Knowledge Base › Troubleshooting › Backing up and restoring your OneSigner configuration

Backing up and restoring your OneSigner configuration

Nov 2, 2026 · 3 views

You will learn how to safely export your OneSigner configuration, database state, and tenant definitions, and how to restore them onto a replacement Windows machine without losing your signing profiles or audit logs.

Prerequisites and File Locations

Before you begin any backup or migration procedure, verify that you have administrative access to the Windows host running your OneSigner service. By default OneSigner keeps its configuration, portal database and logs in its installation folder, C:\OneSigner\app\.

Make sure you note the following standard locations on your file system:

  • Configuration, signing profiles, tenants and license key: C:\OneSigner\app\appsettings.json
  • Signing portal database and files: C:\OneSigner\app\portal.db, plus the portal-docs\ and portal-signed\ folders
  • Signing logs: C:\OneSigner\app\logs\
  • Any source and signed folders your profiles point to, if they live outside the installation folder

Note that OneSigner requires a dedicated Windows machine that stays powered on with your cryptographic hardware token securely plugged in. If you are migrating your entire setup to a new physical machine, ensure your YubiKey, SafeNet, or ePass2003 USB token is physically present and recognized by the new operating system before you attempt a restore.

Exporting Your Configuration and Database Files

Stop the OneSigner service before copying files so the portal database is not written to during the copy. Open an elevated PowerShell prompt and run the following commands to stop the service, archive the data and start the service again.

Stop-Service -Name "OneSignerService"
$backupDir = "C:\OneSignerBackups"
New-Item -ItemType Directory -Force -Path $backupDir
$app = "C:\OneSigner\app"
$items = "appsettings.json","portal.db","portal-docs","portal-signed","logs" |
  ForEach-Object { Join-Path $app $_ } | Where-Object { Test-Path $_ }
Compress-Archive -Path $items -DestinationPath "$backupDir\OneSigner-$(Get-Date -Format 'yyyyMMdd').zip"
Start-Service -Name "OneSignerService"

Verify that the ZIP archive opens and contains appsettings.json. Keep it secure: appsettings.json carries your API tokens and the token PINs saved in your profiles, so store the backup off file shares and out of source control.

For more details on managing multi-tenant environments before you back them up, review the Multi-Tenant Setup: Sign for Many Clients From One Machine guide.

Restoring Files on a New or Existing Machine

When you need to restore your configuration—such as after a hardware failure or when migrating to a new server—follow a strict procedural order. Do not attempt to overwrite active database files while the OneSigner background service is running.

  1. Install the exact same version of OneSigner on the target Windows machine using the standard installer.
  2. Plug in your USB hardware token (YubiKey, SafeNet, or ePass2003) and verify that the cryptographic provider detects your certificate. For hardware token troubleshooting, consult Certificate Not Found.
  3. Stop the background Windows service by running Stop-Service -Name "OneSignerService" in an elevated PowerShell window.
  4. Extract the backup archive into C:\OneSigner\app\, replacing the default appsettings.json.
  5. If you are restoring onto a different machine, note that the license key is bound to the original machine's hardware ID; contact support to move the license to the new machine.
  6. On a different machine, re-enter the token PIN in each signing profile, because saved PINs may not carry over between machines.
  7. Start the service again using Start-Service -Name "OneSignerService".

Validating the Restore and Troubleshooting Common Errors

Once the service has restarted, success is defined as the OneSigner GUI opening successfully, your tenants and signing profiles appearing in the OneSigner configuration app, and test signing operations completing without throwing cryptographic exceptions.

If the service fails to start or reports database corruption errors, check the Windows Event Viewer and the signing logs in C:\OneSigner\app\logs\. Common causes for a failed restore include mismatched application versions between the backup and the newly installed binaries, or missing hardware token drivers on the replacement machine. Ensure your USB token middleware (such as SafeNet Client or YubiKey Smart Card Minidriver) matches the environment where the backup was created.

For further guidance on configuring your environment after a successful restore, refer to the Configuration Guide — Every Tab Explained.