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. 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.

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.