Skip to main content
Version: Developer

Back up, restore, and secure the Kasm Workspaces database

Overview​

Kasm Workspaces stores deployment data in a PostgreSQL database, so the platform is only as recoverable as its most recent backup. This guide shows administrators how to back up that database, restore it on the same or a replacement server, and rotate the database password without leaving services misconfigured. Following these procedures protects deployment data against loss, supports audit and security requirements, and gives operations teams a tested recovery path. The result is a database that you can confidently restore and re-secure when an incident or compliance review demands it.

Prerequisites​

  • A running Kasm Workspaces deployment that uses the bundled PostgreSQL database.
  • Shell access with sudo privileges on the server that holds the Database role.
  • Shell access with sudo privileges on the server that holds the Web App role for password changes.
  • The Kasm release archive that matches the installed version, required only for restore on a replacement server.
  • A maintenance window for password changes, because the change interrupts service.

Solution approach​

This guide progresses through the following phases:

  1. Back up the PostgreSQL database.
  2. Restore the database from a backup.
  3. Change the database password.

Detailed steps​

Back up the PostgreSQL database​

The following command backs up the Kasm PostgreSQL data and all configuration files into a single archive. Run it on the server that holds the Database role.

# This places the backup at /tmp/backup.tar
sudo docker exec kasm_db pg_dump -U kasmapp -F t kasm > /tmp/backup.tar
Automate backups for historical retention

Schedule this command as a cron job, for example daily, and include the date in the archive filename to keep historical backups. Write the archive to a directory backed by an NFS mount so the backups live off the server.

Restore the database from a backup​

The following steps restore the database from a backup archive. The example assumes the target server holds only the Database role, but the same process works on a server where all roles are installed.

  1. Download and unpack the same Kasm version that runs on the primary database server.

    cd /tmp
    curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0.tar.gz
    tar -xf kasm_release*.tar.gz

  2. Install only the database component.

    sudo bash kasm_release/install.sh -b

  3. Copy the backup archive into the kasm_db container.

    sudo docker cp backup.tar kasm_db:/tmp/backup.tar

  4. Restore the database from the archive.

    sudo docker exec kasm_db pg_restore -d kasm /tmp/backup.tar -c -U kasmapp
Update the database address after restoring to a new server

When you restore to a different server, update the database IP address or hostname referenced by all API and Manager systems. Several methods avoid manual edits on every component. Use a hostname and change the IP address in your DNS record, ideally with a five-minute TTL, because propagation can otherwise take up to an hour. Alternatively, use a virtual IP address if a router or firewall sits between the database servers and the Manager and API components. As a final option, use NGINX with layer 4 load balancing and define a single backend server in the upstream block.

Change the database password​

Administrators may need to rotate the password that the Kasm API service uses to connect to the database. The following steps update the password for the kasmapp user in PostgreSQL and the password that the Kasm API uses when it connects.

Password changes interrupt service

Changing the PostgreSQL password requires a restart of Kasm services and causes a temporary service interruption. Perform this change during a maintenance window.

  1. On the server that holds the Database role, change the password for the kasmapp user. Replace new_password with your chosen value, and ensure it does not contain $, ', or " characters.

    sudo docker exec -it kasm_db psql -U kasmapp -d kasm -c "ALTER ROLE kasmapp WITH PASSWORD 'new_password';"

  2. On the server that holds the Web App role, stop the Kasm services.

    sudo systemctl stop kasm

  3. Edit the API app configuration, and replace the value on the line that starts with password: with your new password.

    sudo vi /opt/kasm/current/conf/app/api/api.app.config.yaml

  4. Start the Kasm services on the Web App server.

    sudo systemctl start kasm

Common troubleshooting steps​

  • The restore fails with a version mismatch. Confirm that the installed Kasm version on the target server matches the version that produced the backup. Download the matching release archive before you restart the restore.
  • API or Manager components cannot reach the database after a restore. Verify the database IP address or hostname on every API and Manager system. Update DNS, the virtual IP, or the NGINX upstream definition as described in the restore caution.
  • Services fail to start after a password change. Confirm that the password in api.app.config.yaml matches the value set on the kasmapp role, and that it contains no $, ', or " characters.
  • The password command reports a permission error. Run the command on the server that holds the Database role, and confirm that the kasm_db container is running.