Multi Server Upgrade

Please read through the entire process before getting started.

Issues can be reported on the Kasm Workspaces Issues Page

Warning

The Kasm Workspaces 1.10.0 upgrade will install a new set of default desktop and application images. Please ensure 50GB of free space is available on the Kasm server ( or Agent role server for multi-server installations) prior to upgrading.

  • Stop all Kasm Services on all Servers

sudo /opt/kasm/bin/stop

Upgrade Database Server Role

Create a Database Backup

  • Stop existing Kasm Services

sudo /opt/kasm/bin/stop
  • Execute the database backup utility

sudo mkdir -p /opt/kasm/backups/
sudo bash /opt/kasm/1.9.0/bin/utils/db_backup -f /opt/kasm/backups/kasm_db_backup.tar -p /opt/kasm/1.9.0/
  • Download and extract the new installation media

cd /tmp/
curl -O <release url>
tar -xf kasm_release_*.tar.gz
  • Get the existing database password for use in the subsequent commands.

sudo grep " password" /opt/kasm/1.9.0/conf/app/api.app.config.yaml
  • Get the existing redis password for use in the subsequent commands.

sudo grep "redis_password" /opt/kasm/1.9.0/conf/app/api.app.config.yaml

Perform a clean install

Perform a clean install of the Database Role Services

  • Install kasm from the release media downloaded in the prior steps.

sudo bash kasm_release/install.sh -S db -D -Q <DATABASE_PASSWORD> -R <REDIS_PASSWORD>

Restore and upgrade the database

Restore and update the database from the prior version

  • Ensure all Kasm services are stopped

sudo /opt/kasm/bin/stop
  • Execute the database restore command

sudo /opt/kasm/1.10.0/bin/utils/db_restore -f /opt/kasm/backups/kasm_db_backup.tar -p  /opt/kasm/1.10.0/
  • Perform an upgrade of the database schema

sudo /opt/kasm/1.10.0/bin/utils/db_upgrade -p /opt/kasm/1.10.0
  • Advanced: Review the contents of the existing configs to ensure any custom docker settings are migrated to the new configuration.

diff /opt/kasm/1.9.0/docker/docker-compose.yaml  /opt/kasm/1.10.0/docker/docker-compose.yaml
  • Install The Kasm 1.10.0 Default Images for your platform

For x86 (amd64) platforms:

sudo /opt/kasm/1.10.0/bin/utils/db_init -s /opt/kasm/1.10.0/conf/database/seed_data/default_images_amd64.yaml

For ARM (arm64) platforms:

sudo /opt/kasm/1.10.0/bin/utils/db_init -s /opt/kasm/1.10.0/conf/database/seed_data/default_images_arm64.yaml
  • Start the Kasm services

sudo /opt/kasm/bin/start

Upgrade Web App Server Role

  • Stop existing Kasm Services

sudo /opt/kasm/bin/stop
  • Download and extract the new installation media

cd /tmp/
curl -O <release url>
tar -xf kasm_release_*.tar.gz
  • Install kasm from the release media downloaded in the prior steps.

sudo bash kasm_release/install.sh -S app -D -q <DATABASE_HOSTNAME> -Q <DATABASE_PASSWORD> -R [REDIS_PASSWORD]
  • Copy manager_id and server_hostname from the old configuration into the new

grep manager_id /opt/kasm/1.9.0/conf/app/api.app.config.yaml
grep server_hostname /opt/kasm/1.9.0/conf/app/api.app.config.yaml
sudo vi /opt/kasm/1.10.0/conf/app/api.app.config.yaml
  • Advanced: Review the contents of the existing configs to ensure any custom docker settings are migrated to the new configuration.

diff /opt/kasm/1.9.0/docker/docker-compose.yaml  /opt/kasm/1.10.0/docker/docker-compose.yaml
  • Start the Kasm services

sudo /opt/kasm/bin/start

Upgrade Agent Server Role

  • Ensure all Kasm services are stopped

sudo /opt/kasm/bin/stop
  • Download and extract the new installation media

cd /tmp/
curl -O <release url>
tar -xf kasm_release_*.tar.gz
  • Get the existing manager token for use in the subsequent commands.

sudo grep "token" /opt/kasm/1.9.0/conf/app/agent.app.config.yaml
  • Install kasm from the release media downloaded in the prior steps.

sudo bash kasm_release/install.sh -S agent -D -p <AGENT_HOSTNAME> -m <MANAGER_HOSTNAME> -M <MANAGER_TOKEN>
  • Copy the server_id and the public_hostname properties from the old agent to the new

grep server_id /opt/kasm/1.9.0/conf/app/agent.app.config.yaml
grep public_hostname /opt/kasm/1.9.0/conf/app/agent.app.config.yaml
sudo vi /opt/kasm/1.10.0/conf/app/agent.app.config.yaml
  • Copy the auto-generated nginx configs for any sessions that may exists on the Agent

sudo cp /opt/kasm/1.9.0/conf/nginx/containers.d/* /opt/kasm/1.10.0/conf/nginx/containers.d/
  • Advanced: Review the contents of the existing configs to ensure any custom docker settings are migrated to the new configuration.

diff /opt/kasm/1.9.0/docker/docker-compose.yaml  /opt/kasm/1.10.0/docker/docker-compose.yaml
diff /opt/kasm/1.9.0/conf/app/agent.app.config.yaml  /opt/kasm/1.10.0/conf/app/agent.app.config.yaml
  • Start the Kasm services

sudo /opt/kasm/bin/start
  • Verify the Agent Service is properly checking into the Manager Service. Log into the UI as an Administrator. Select Agents and verify the Agent is listed with a Last Reported time of less than 1 minute. If the agent has not checked in, it likely can’t resolve or connect to [AGENT_HOSTNAME]:443 . Inspect the logs for details.

sudo tail -f /opt/kasm/current/log/agent.log

Update Custom Images

Each release, the Kasm Technologies team updates the default images with new features and security updates. The previous steps added the new default images to the upgraded system. Old images should be removed as they are not compatible with new Kasm features.

If you are running custom images, rebuild each image using the the latest image. (e.g : kasmweb/core-ubuntu-bionic:1.10.0 ) , and create a new Image entry in the Kasm UI. Do not re-use existing Image entries for custom images.

See Default and Custom Images for details.