Protected files on a node
Two files in the data directory hold material that nothing else on the machine should be able to read. Both are created automatically, both are mode 0600 on Unix and restricted to the service account on Windows, and neither is ever included in a backup archive.
On Linux the data directory is /opt/Syncplify/Server/data; on Windows it is C:\ProgramData\Syncplify\Server.
| File | Holds |
|---|---|
.ssrv-installation.key | The key that encrypts every secret this installation stores |
.ssrv-database.cred | The password this installation uses to reach its own database |
CAUTION
Back these two files up separately, and store them somewhere other than alongside your backup archives. They are deliberately not in the archives, which is what makes a stolen backup useless on its own; the flip side is that losing them is not something a backup can undo for you.
The database credential
Every installation reaches its own database as a service account. Until version 8.1.0 the password for that account was a constant, identical on every installation ever shipped, and compiled into the program itself. Anyone with a copy of the software could read it out, and in SyncplifyDB a service account is administrator equivalent, so that was rather more than read access to the data.
From 8.1.0, every installation has a random password of its own, kept in .ssrv-database.cred. Nothing is shared with any other installation, and a password recovered from one is worth nothing against another.
On a new installation
Setup generates the password while it is creating the database, so the database is built with it and the built in password is never used at all.
On an existing installation
Updating to 8.1.0 or later retires the built in password automatically. The update generates a password for this node, changes it on the database, and checks that the new one works before recording it as the one to use.
It happens at the one point in the update where every service that holds a database password has been stopped and none has started again yet, which is why it is done by the installer and not by the software at startup.
You do not have to do anything, and there is nothing to plan around. The step is also safe to interrupt: whether the update is cut short before the change reaches the database or after it, the node still opens its database the next time it starts.
If it could not be done
Retiring the built in password is deliberately allowed to fail without failing the installation, because the built in password still works and a node that cannot rotate is a node that behaves exactly like every previous version. If it fails, setup says so and the update completes normally.
You can retry it later, but only with every Syncplify service stopped:
ss-webrest dbcred rotateWARNING
Do not run that command while the Web/REST or worker services are running. Those services keep the password they connected with in memory, so a service still holding the old one loses its database the next time it has to authenticate again. Stop them, run the command, then start them.
An installation that already has a password of its own is left alone, so running it more than once is harmless.
If the file is lost
This is the one thing worth understanding about the change, because the answer is different before and after the built in password has been retired.
On a node that has not retired it yet, the software tries the credential file first and the built in password second, so a node whose file has been lost or damaged still starts. It writes a warning to the log every time it does:
the database refused this node's own credential and the connection was opened with the shared one every copy of the product knows
If you see that line, the node is running and serving normally, but its database is once again reachable by anyone who can read the program. Restore the file from wherever you keep it, or contact support.
On a node that has retired it, the built in password no longer opens that database, which is the entire point of retiring it. The file is then the only copy of the password, and a node that loses it cannot reach its database at all until the file is restored.
CAUTION
This is why .ssrv-database.cred has to be backed up, and backed up somewhere other than alongside your backup archives. It is not a file you can regenerate, and no backup archive contains it.
TIP
A separate break glass administrator account exists on the database and is unaffected by any of this. It is there precisely so that Syncplify can help you recover an installation after an event that would otherwise be unrecoverable, including this one.