Archive Command

The archive command manages passphrase-encrypted backup bundles (.sigbak files) of the Signotaur server. It is part of the server executable and is run on the server host; it operates directly on the server's configuration, database and certificates.

Use it to take a full backup, check that an existing backup is intact, recover individual files, and (most importantly) migrate or recover Signotaur to another machine.

What Is a .sigbak?

A .sigbak is a single, passphrase-encrypted file containing a complete snapshot of the server state:

  • The server configuration file.
  • A consistent snapshot of the SQLite database.
  • Every CA, managed and self-signed certificate (.pfx) together with its password sidecar (.pwd).
  • A manifest describing the bundle (created date, source hostname, application version, bundle format version, and the file list).
  • key.json: the unsealed AES master key and vector. This is the one portable secret inside the bundle; every other secret stays encrypted exactly as it is on disk.

The bundle is encrypted with AES-256-GCM. The encryption key is derived from your passphrase with PBKDF2-HMAC-SHA256 using 600,000 iterations; the random salt and nonce are stored in the bundle's authenticated header, so any tampering is detected on read.

Because the bundle contains the master key, the passphrase is the only thing protecting every secret in your Signotaur installation. Anyone who obtains both the .sigbak file and its passphrase can recover all of your server's secrets. The passphrase cannot be recovered; if you lose it, the backup is useless. Store it somewhere safe and separate from the bundle.

Because restore re-seals the master key under the destination machine's protection (DPAPI), a .sigbak is the supported way to migrate or recover Signotaur to a new machine; a plain file copy of the data folder will not work. See At-rest encryption for the reasoning.

Sub-Commands

The archive command has four sub-commands:

Sub-command Purpose Writes
archive create Build a new .sigbak backup bundle. The .sigbak file
archive restore Restore a .sigbak onto this host (also the migration path). Config, database and certificates
archive verify Check that a .sigbak is readable and intact. Nothing
archive extract Decrypt a .sigbak into a folder for manual or partial recovery. The decrypted files

Supplying the Passphrase

For every sub-command, the passphrase can be supplied in one of three ways (checked in this order):

  1. The --passphrase <Passphrase> option.
  2. The SIGNOTAUR_BACKUP_PASSPHRASE environment variable.
  3. An interactive hidden prompt (when none of the above is set and the command is run interactively).

In addition, archive create accepts --generate-passphrase, which generates a strong random passphrase, prints it once to the console, and uses it for the backup. When --generate-passphrase is used, both --passphrase and the environment variable are ignored.

A generated passphrase is printed to the console once and is never written to the log file. Capture it immediately; it cannot be recovered.

Passphrase Strength Rules

archive create requires a strong passphrase (the read-side commands accept whatever passphrase the bundle was sealed with). A passphrase is accepted only when it:

  • is at least 16 characters long;
  • includes all four character classes: a lower-case letter, an upper-case letter, a digit and a symbol;
  • uses at least 5 distinct characters;
  • contains no simple sequential run (such as abcd or 1234); and
  • is not on the common-password blocklist (such as password, qwerty, admin).

If you would rather not pick one yourself, use --generate-passphrase.

Archive Create

Builds a passphrase-encrypted .sigbak of the current server state.

Usage

VSoft.Signotaur.Server.exe archive create [options]

Options

  • -o, --output <Path>

    Where to write the .sigbak. If a directory is given, a timestamped file name is generated inside it. If omitted, the file is written to the archives folder under the backups root as Signotaur-<timestamp>.sigbak (the same pool used by scheduled backups, so manual archives are subject to retention and reported as the most recent backup).

  • --passphrase <Passphrase>

    The backup passphrase. If omitted, the SIGNOTAUR_BACKUP_PASSPHRASE environment variable is used, otherwise you are prompted.

  • --generate-passphrase

    Generate a strong random passphrase, print it to the console once, and use it. Overrides --passphrase and the environment variable.

archive create requires the master key to be usable on this machine. If the key cannot be unsealed, the command fails. See At-rest encryption.

Examples

  1. Create a backup, prompting for the passphrase:

    VSoft.Signotaur.Server.exe archive create

  2. Create a backup to a specific path with the passphrase supplied directly:

    VSoft.Signotaur.Server.exe archive create --output D:\Backups\signotaur.sigbak --passphrase "Corr3ct-Horse!Battery"

  3. Create a backup with a generated passphrase (printed once):

    VSoft.Signotaur.Server.exe archive create --generate-passphrase

  4. Create a backup in a scripted/unattended run using the environment variable:

    set SIGNOTAUR_BACKUP_PASSPHRASE=Corr3ct-Horse!Battery
VSoft.Signotaur.Server.exe archive create --output D:\Backups\ --nb

Archive Restore

Restores a .sigbak onto this host. This is also the migration path: restoring a bundle created on another machine re-seals the master key under this machine's protection so all secrets decrypt correctly here.

The Signotaur service must be stopped before restoring (the database file would otherwise be locked). The command takes a pre-restore safety snapshot and automatically rolls back if a destructive write fails part-way.

archive restore overwrites this server's configuration, database and all certificates (CA, managed and web) with the contents of the backup. The command warns you and asks for confirmation: when run interactively you must type yes to proceed; in an unattended run it refuses unless you pass --yes (it cannot prompt and will not overwrite silently). The pre-restore snapshot allows rollback if a write fails, but the current state is replaced.

Usage

VSoft.Signotaur.Server.exe archive restore --input <file.sigbak> [options]

Options

  • -i, --input <Path> (required)

    The .sigbak file to restore.

  • --passphrase <Passphrase>

    The backup passphrase. If omitted, the SIGNOTAUR_BACKUP_PASSPHRASE environment variable is used, otherwise you are prompted.

  • -y, --yes

    Skip the interactive overwrite confirmation. Required for unattended/scripted runs, which cannot prompt. Has no effect on the safety snapshot (see --force).

  • --force

    Continue even if the pre-restore safety snapshot cannot be written. Use with caution; without the snapshot there is no automatic rollback. This is separate from --yes: --force relaxes the snapshot safety, it does not confirm the overwrite.

Examples

  1. Restore a backup (service stopped):

    VSoft.Signotaur.Server.exe archive restore --input D:\Backups\signotaur.sigbak

  2. Restore in a scripted run using the environment variable (--yes confirms the overwrite, which an unattended run cannot do interactively):

    set SIGNOTAUR_BACKUP_PASSPHRASE=Corr3ct-Horse!Battery
VSoft.Signotaur.Server.exe archive restore --input D:\Backups\signotaur.sigbak --yes --nb

Archive Verify

Checks, without changing anything, that a .sigbak opens with the supplied passphrase and is intact (its authentication tag verifies), then prints the bundle manifest. This is the "are my backups good?" command.

Usage

VSoft.Signotaur.Server.exe archive verify --input <file.sigbak> [options]

Options

  • -i, --input <Path> (required)

    The .sigbak file to verify.

  • --passphrase <Passphrase>

    The backup passphrase. If omitted, the SIGNOTAUR_BACKUP_PASSPHRASE environment variable is used, otherwise you are prompted.

The output reports the created date, source hostname, application version, bundle format version, and the list of files in the bundle.

Example

VSoft.Signotaur.Server.exe archive verify --input D:\Backups\signotaur.sigbak

Archive Extract

Decrypts a .sigbak into a folder for manual or partial recovery, without touching the live server. By design, the plaintext master key (key.json) is not written unless you explicitly ask for it.

Usage

VSoft.Signotaur.Server.exe archive extract --input <file.sigbak> --to <dir> [options]

Options

  • -i, --input <Path> (required)

    The .sigbak file to extract.

  • -t, --to <Dir> (required)

    The destination directory for the extracted files.

  • --passphrase <Passphrase>

    The backup passphrase. If omitted, the SIGNOTAUR_BACKUP_PASSPHRASE environment variable is used, otherwise you are prompted.

  • --include-key

    Also write key.json, the plaintext master key. When this is used the destination directory is ACL-locked and a warning is logged. Only use this when you understand the consequences.

  • --force

    Extract even if the destination directory is not empty.

Example

VSoft.Signotaur.Server.exe archive extract --input D:\Backups\signotaur.sigbak --to D:\Recovery

Global Options

Every archive sub-command also accepts:

  • --nb

    Hide the startup banner. Useful in scripted or unattended runs.

  • --theme <Theme>

    Specifies the console colour theme. Options are: General (default, suitable for most consoles), Dark (optimized for dark backgrounds), Light (optimized for light backgrounds), or None (disables colours). The default is General. Use Light on a white-background terminal so the output and banner stay readable.

  • --nc, --no-colour, --no-color

    Disables coloured output entirely. This is useful for CI/CD environments, log files, or systems that don't support ANSI colour codes. Alternatively, you can set the NO_COLOR environment variable to any non-empty value to achieve the same effect (following the no-color.org standard).

Migrating to a New Host

Because the master key is bound to the machine that sealed it, you cannot move Signotaur by copying the data folder. Use archive instead:

  1. On the original (source) host, create a backup:

    VSoft.Signotaur.Server.exe archive create --output D:\Migration\signotaur.sigbak

    Record the passphrase securely.

  2. Copy the .sigbak file to the new (destination) host.

  3. On the destination host, stop the Signotaur service, then restore:

    VSoft.Signotaur.Server.exe archive restore --input D:\Migration\signotaur.sigbak

    Restore re-seals the master key under the destination machine's DPAPI, so all secrets, certificates and database content decrypt correctly on the new machine.

  4. Start the Signotaur service on the destination host.

Run archive verify on the copied bundle before you decommission the source host, to confirm the bundle transferred intact and the passphrase is correct.

Troubleshooting

  • "the backup passphrase is too weak": archive create rejected the passphrase against the strength rules. Choose a stronger passphrase, or use --generate-passphrase.

  • Wrong passphrase on restore/verify/extract: if the passphrase does not match the one the bundle was created with, the bundle cannot be decrypted and the command fails. There is no recovery from a lost passphrase; the backup is unusable without it.

  • Tampered or corrupt bundle: the bundle's AES-256-GCM authentication tag is verified on read. If the file has been altered or truncated, decryption fails with an integrity error. Restore from a known-good .sigbak (use archive verify to find one).

  • Service still running on restore: archive restore refuses to run while the database is locked by the live server. Stop the Signotaur service first, then retry.

  • Master key unusable on archive create: create requires the master key to be usable on this machine. If the key was sealed on a different host (for example, the data folder was copied rather than restored), the command fails. See At-rest encryption for how to recover, including using archive restore on the new host.

See Also

  • At-rest encryption - How Signotaur protects secrets at rest, and why migration goes through archive.
  • Backup Settings - Scheduling automatic .sigbak backups and configuring the backup passphrase.