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/upgrade-maintenance.md.
🎉 JumpServer v5.1.1 is available. See what's new →
  • v5

    • Upgrade & Maintenance

    JumpServer releases new versions regularly. Upgrading keeps the platform on supported components and security fixes, while routine maintenance keeps the database, storage, and logs from degrading over time. This page covers the upgrade path, the preparation steps, the upgrade commands, and the recurring tasks an operator should schedule.

    Supported upgrade path

    Upgrade along the following path to avoid incompatible schema changes:

    • v2 to v3: the two versions differ significantly. Read the upgrade notes before starting.
    • v3 to v4: first upgrade to the latest v3 release, then to v4.
    • v4 to v5: database migrations roll forward continuously, so any v4 release can be upgraded to v5. For early v4 releases, upgrade to the latest v4 release first.

    The detailed step-by-step upgrade for both installation types is in the Upgrade guide.

    Before the upgrade

    1. Read the release notes of the target version for behavior changes and new requirements; pay attention to the database and Redis version requirements.
    2. Schedule a maintenance window. Upgrading stops the services and interrupts active sessions.
    3. Back up the database and static files. See Backup & Restore.
    4. Confirm that DOMAINS contains the domain or IP address users open in the browser. A missing trusted host is the usual cause of 400 and 403 responses after an upgrade.
    5. Keep the current packages and configuration backup until the new version has been verified.

    Upgrade an offline installation

    cd /opt
tar -xf jumpserver-ce-<version>-x86_64.tar.gz
cd jumpserver-ce-<version>-x86_64
./jmsctl.sh upgrade
./jmsctl.sh start

    For the enterprise offline package, use the jumpserver-ee-<version>-x86_64 package and the same commands.

    Upgrade an online installation

    Download the installer package for the target version, extract it, then upgrade:

    cd /opt
tar -xf jumpserver-installer-<version>.tar.gz
cd jumpserver-installer-<version>
./jmsctl.sh upgrade
./jmsctl.sh start

    After the upgrade

    • Run ./jmsctl.sh status and confirm that all expected containers are running.
    • Open /api/health/ and the web UI, then log in as a normal user.
    • Check the version shown in the UI and in the startup output.
    • Test one connection, one recording playback, and one account secret to confirm that the data survived the migration.
    • Watch the Core and protocol component logs for errors for a few minutes.
    • Upgrade the other node in a high-availability pair after the first node is healthy.

    Routine maintenance

    TaskFrequencyNotes
    Database and static file backupDailyCopy backups off the host; verify restore regularly
    Disk usage of VOLUME_DIRWeeklyRecordings and logs grow quickly; increase storage or move recordings to object storage
    Log reviewWeeklyCheck Core, KoKo, and web logs for repeated errors
    Certificate renewalBefore expiryConfigure HTTPS and renew under config/nginx/cert
    License validityBefore expiryEnterprise licenses expire; import a new license in System Settings
    Patch and version updatesPer releaseFollow the upgrade path above

    Local cleanup of login, operation, and file-transfer records is configured under System Settings > System Tasks > Regular clean-up. Recordings and commands written to external storage are not affected by that page. See System Tasks and Storage.