Command line reference

The management service binary is also a command line tool. Most of what it can do from a terminal is also available from the SuperAdmin interface, but a few tasks, notably restoring onto a brand new node, exist only here.

This page documents the commands that handle secrets and the ones that update the software. For the rest, run the binary with --help, or a subcommand with --help, which prints the current flags for the version you actually have installed.

Supplying a secret without leaking it

Several commands need a password or a passphrase. Passing one as a command line argument puts it in the process table, where every other account on the machine can read it with ps or out of /proc/<pid>/cmdline for as long as the command runs. That matters here more than usual: the backup passphrase is the only thing sealing this installation's encryption key inside the archive, so somebody holding both the archive and the passphrase holds the whole configuration database in the clear.

Every command below therefore accepts the same three ways of supplying a secret, and resolves them in this order:

1. The flag, for example --passphrase. Accepted for compatibility with scripts that already use it, but visible in the process table. Prefer one of the other two.
2. A file, for example --passphrase-file /run/secrets/backup-pass. The contents are read as the secret, with a trailing newline stripped. Give the file mode 0600 and let it be owned by the account running the command.
3. An interactive prompt, used when neither of the above is given. The terminal echo is switched off while you type. This is the right choice for a human at a keyboard, and it is the default.

If none of the three is available, for instance when the command runs from cron with no terminal attached, it fails with a clear message rather than proceeding without the secret. Environment variables prefixed with SS_ are also read by the configuration layer, so SS_PASSPHRASE works as well.

backup

Exports the current configuration into a ZIP archive.

Flag	Meaning
-d, --destdir	Destination directory. Created if it does not exist. Required.
-p, --passphrase	The passphrase that protects the archive. See above.
--passphrase-file	Read that passphrase from a file instead.

The passphrase is what allows the archive to be restored on a different node. It is never stored anywhere: an archive whose passphrase has been lost can only be restored back onto the same installation it came from.

The archive is written mode 0600 inside a directory created mode 0700, so no other local account can read it.

ss-webrest backup --destdir /var/backups/syncplify --passphrase-file /run/secrets/backup-pass

initfrombak

Initializes a brand new node from an existing backup archive. This is how a cluster member is rebuilt, and how an installation is moved to different hardware.

Flag	Meaning
--bakfile	Path to the backup archive to restore. Required.
--bakpass	The passphrase that archive was exported with. See above.
--bakpass-file	Read that passphrase from a file instead.
--saname	Username of the SuperAdmin to create. Required; sa is the usual answer.
--sapass	Password for that SuperAdmin. See above.
--sapass-file	Read that password from a file instead.
--saemail	Email address for that SuperAdmin. Required.
--nodename	Name for this node. Optional.

Two secrets are involved here, and they are different things: --bakpass unseals the archive, while --sapass is the password of the administrator account being created. Both take the file and prompt forms.

ss-webrest initfrombak \
  --bakfile /var/backups/syncplify/backup-1754006400.zip \
  --bakpass-file /run/secrets/backup-pass \
  --saname sa --saemail admin@example.com \
  --sapass-file /run/secrets/sa-pass \
  --nodename node2

TIP

Delete the secret files once the command has finished. They are only needed for the duration of the run.

importusers

Creates user accounts in bulk from a file: Syncplify's own CSV, or an export from Cerberus FTP Server, SFTPGo or FileZilla Server, password hashes included. It has a page of its own: Importing users and migrating from other servers.

version

Prints the version of the binary and exits. --json prints one object with the name, version, build date, commit, operating system and architecture instead. The setup program uses the bare form to refuse replacing a newer version with an older one.

ss-webrest version

update

The command line side of Keeping the server current. Every subcommand works on the node it runs on; when the Web/REST service is running, apply and cancel hand the request to it, so the node drains and, in a cluster, claims the update lease exactly as from the console. When the service is stopped, apply runs the updater directly.

update status

Shows the update standing of this node: the running version and its components, what the release channel offers, the maintenance standing, the update policy, an update waiting or in progress, the outcome of the last update, and in a cluster the standing of every member.

update check

Reads the release channel and reports what it offers, downloading nothing.

Flag	Meaning
--base-url	Release channel root URL. Default: the policy's mirror, else the Syncplify release channel.

update apply

Stages the release and applies it, at the next idle moment by default.

Flag	Meaning
--now	Drain, wait the grace period for open transfers, terminate the sessions that remain, and apply.
--version	The exact version to apply. Default: the channel's current version.
--base-url	Release channel root URL, as for check.
--consent-unverified	Apply even though the maintenance standing could not be verified, taking full responsibility. It never overrides a verified refusal.
--acknowledge-offline-peers	In a cluster, update this node even though members are offline.
--force-rollback	Allow a version below the one installed on this node: a deliberate rollback through the channel.

ss-webrest update apply --now

update cancel

Cancels an update waiting on this node. The node accepts new connections again and the staged release is kept.

update acknowledge

Acknowledges the failed or rolled back outcome of the last update on this node, so the SuperAdmin console, the sign in screen and the Dashboard stop asking for attention. The record stays in the state file and in the notifications. It works with the service stopped; the running service sees it at its next look.

update cluster

Starts a rolling update of the whole cluster, one node at a time: peers by node ID first, this node last. --now makes each node drain, wait the grace period and terminate what remains instead of waiting for an idle moment. The pass refuses to start while a member is offline, mid update or failed, and stops at the first failure.

update rollback

Restores the previous version from the rollback slots beside the installed binaries (Web/REST, worker and SyngoDB as a set), reconciles the service definitions and restarts the services. Run it with the services stopped. It refuses when the SyngoDB data layout changed since, because restoring the previous server over a migrated store would be unsafe.

The setup program

Running the setup program of a newer version on an existing installation updates it through the very same updater: ss-setup install. It refuses to replace a newer version the server installed on its own; --allow-downgrade installs the older version deliberately. --silent still refuses when the maintenance standing could not be verified.

dbcred

Manages the password this installation uses to reach its own database, which is kept in .ssrv-database.cred. See Protected files on a node for what that file is and why it has to be backed up.

Setup runs these for you. The only reason to run one by hand is that setup told you it could not.

dbcred rotate

Retires the built in password on an installation that still uses it: generates a password for this node, changes it on the database, and checks that the new one works before recording it. An installation that already has a password of its own is left alone, so running it twice is harmless.

It takes no flags.

ss-webrest dbcred rotate

WARNING

Stop the Web/REST service and every worker service first, and start them again afterwards. Those services keep the password they connected with in memory, so one still holding the old password loses its database the next time it has to authenticate. This is why the installer does it at the point in an update where everything is already stopped.

The command is safe to interrupt. Whichever side of the change it is cut short on, the node still opens its database the next time it starts.

dbcred provision

Flag	Meaning
--initfile	Path to the SyncplifyDB initialization file to write the password hash into. Required.

Used by setup while it is creating a database, before that database exists. It writes the hash of the generated password into the initialization file so the database is built with it. There is no reason to run this against an installation that is already running; use dbcred rotate instead.