For AI agents: the complete documentation index is available at https://www.jumpserver.com/docs/llms.txt, the full documentation bundle is available at https://www.jumpserver.com/docs/llms-full.txt, and this page is available as Markdown at https://www.jumpserver.com/docs/operations/backup-restore.md.
🎉 JumpServer v5.1.1 is available. See what's new →
  • v5

    • Backup & Restore

    JumpServer data is split into two parts:

    • Database data: users, assets, accounts, authorizations, operation logs, and command records.
    • Static files: session recordings, uploaded files, system logs, certificates, and component registration keys.

    Back up both parts together. A database-only backup restores the platform but leaves recordings orphaned, and a static-file-only backup cannot be indexed without the matching database.

    Back up the database

    Run the backup on any one node of the deployment:

    ./jmsctl.sh backup_db

    The backup file and the active configuration are written to the persistence directory, /data/jumpserver/db_backup by default. The file name contains the version and timestamp, for example jumpserver-v5.0.0-2026-10-28_10:00:00.dump for PostgreSQL or the matching .sql file for MySQL and MariaDB.

    Restore the database

    Stop the services, then restore the backup file on one node:

    ./jmsctl.sh stop
./jmsctl.sh restore_db /data/jumpserver/db_backup/jumpserver-v5.0.0-2026-10-28_10:00:00.dump
./jmsctl.sh start

    When restoring into a different environment, the database engine and version must match the source, and SECRET_KEY and BOOTSTRAP_TOKEN must have the same values as in the source environment. Otherwise encrypted fields cannot be decrypted and components cannot register with Core.

    Back up static files

    Static files are stored under VOLUME_DIR, /data/jumpserver by default:

    ├── core/data/logs      # system logs
├── core/data/media     # session recordings and uploads
├── core/data/certs     # certificates
├── db_backup           # database backups and saved configuration
├── koko/data           # component logs and keys
├── nginx/data/logs     # web access logs
├── postgresql/data     # built-in PostgreSQL data files
└── redis/data          # built-in Redis data files

    Copy the directories you need to a backup target, for example the recordings:

    rsync -avh /data/jumpserver/core/data/media/replay/ /backup/jumpserver/replay_backup/
    Note

    In a two-node deployment, keep core/data on shared storage (NFS) or use object storage for recordings, so that both nodes read the same files. Back up the shared location once, not per node.

    External storage

    If recordings are stored in an object storage service, or session commands are stored in Elasticsearch, back those services up with their own tooling. The JumpServer database backup does not include external object or index data. Keep the database backup and the external storage snapshot from the same point in time.

    Restore checklist

    1. Confirm that the target version and database engine match the backup.
    2. Restore the files under VOLUME_DIR first.
    3. Restore the database with ./jmsctl.sh restore_db.
    4. Start the services and check ./jmsctl.sh status and /api/health/.
    5. Open an existing session recording and an account secret to confirm that the data and encryption keys match.