Single Server Upgrade

Warning

When running any upgrade please ensure there are no active Kasm Workspaces sessions running. On large deployments this will likely require a maintenance window.

Note

While not required, making a backup using a VM snapshot or other method of the server is recommended as a precaution to provide a recovery point if something goes wrong.

Install Files
Installer

Contents

URL

SHA256

Installer Bundle

https://kasm-static-content.s3.amazonaws.com/kasm_release_1.16.1.98d6fa.tar.gz

096b27e3219b98a8e5faef2b36ccb58a0944a8f0e9b27933ce475335f745433a

Offline AMD Images

Contents

URL

SHA256

Services

https://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_amd64_1.16.1.98d6fa.tar.gz

e8d87b47ba74fa63efc2f417848ebeda2eda3d75b65914c2e9823d173b068b94

Workspaces

https://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_amd64_1.16.1.98d6fa.tar.gz

1b8575df087cf2db87da5bb2d23de341b41887313cd90134f353304072975248

Plugin

https://kasm-static-content.s3.amazonaws.com/kasm_release_plugin_images_amd64_1.16.1.98d6fa.tar.gz

673f29b8fef433e2919fe87e42fc6ccf71e9d5b6a4832bf2b382d635a58be793

Offline ARM Images

Contents

URL

SHA256

Services

https://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_arm64_1.16.1.98d6fa.tar.gz

0d00edd30607d5ba95e277dfb098cf26216a80b71ea3e586ecbed90118c01e51

Workspaces

https://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_arm64_1.16.1.98d6fa.tar.gz

20d4483066075aebc918b7a9e20ba0d344db651e556c6e45a1d35cbabcbe322b

Plugin

https://kasm-static-content.s3.amazonaws.com/kasm_release_plugin_images_arm64_1.16.1.98d6fa.tar.gz

a7425211836f71f4ea26713ea8488266a75fcccd5e1f269f8948ece77125d62b

Automated Upgrade

The automated upgrade script can be used to upgrade a previous installation to 1.16.1 .

Administrators have several options to choose from when running the automated upgrade script:

Flag                                        Description
---------------------------------------------------------------------------------------------------------------
| -h|--help                     | Display this help menu                                                      |
| -L|--proxy-port               | Default Proxy Listening Port                                                |
| -s|--offline-service          | Path to the tar.gz service images offline installer                         |
| -x|--offline-plugin           | Path to the tar.gz plugin images offline installer                          |
| -S|--role                     | Role to Upgrade: [app|db|agent|remote_db|guac|proxy]                        |
| -p|--public-hostname          | Agent/Component <IP/Hostname> used to register with deployment.             |
| -g|--database-master-user     | Database master username required for remote DB                             |
| -G|--database-master-password | Database master password required for remote DB                             |
| -q|--db-hostname              | Database Hostname needed when upgrading agent and pulling images            |
| -T|--db-port                  | Database port needed when upgrading agent and pulling images (default 5432) |
| -Q|--db-password              | Database Password needed when upgrading agent and pulling images            |
| -b|--no-check-disk            | Do not check disk space                                                     |
| -n|--api-hostname             | Set API server hostname                                                     |
| -A|--enable-lossless          | Enable lossless streaming option (1.12 and above)                           |
| -O|--use-rolling-images       | Use rolling Service images                                                  |
| -k|--registration-token       | Register a component with an existing deployment.                           |
| --skip-egress                 | Do not install egress network plugin or dependancies                        |
---------------------------------------------------------------------------------------------------------------

In this example --proxy-port is used.

cd /tmp
curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.16.1.98d6fa.tar.gz
tar -xf kasm_release_1.16.1.98d6fa.tar.gz
sudo bash kasm_release/upgrade.sh --proxy-port 443

Automatic Upgrade Troubleshooting

The upgrade.sh script creates a log file as it runs, this file is removed upon completion of a successful upgrade. However, if something does go wrong the logfile will be available from the directory the upgrade.sh script was executed from in the format kasm_upgrade_${TIMESTAMP}.log. This file will be important for diagnosing the error that caused the upgrade to fail and will be requested when submitting a support ticket with Kasm Technologies.

Manual Upgrade

Kasm Tech recommends installing a separate instance of the application, migrating the data and performing a cutover of the application.

Please read through the entire process before getting started.

Warning

The Kasm Workspaces 1.16.1 upgrade will optionally 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 if selecting the options to seed new images.

Component Registration Token

The Component Registration Token is used during the upgrade process to register new components that were not present on earlier versions of Kasm Workspaces.

Login to the Workspaces UI as an administrator. Retrieve the value of Component Registration Token from the Global Settings.

Create a Database Backup

Backup the existing Kasm database. This can be saved for later recovery, but will also be used to migrate existing data to the latest version.

  • 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.16.0/bin/utils/db_backup -f /opt/kasm/backups/kasm_db_backup.tar -p /opt/kasm/1.16.0/
  • Verify the presence and location of the database backup

sudo ls -al /opt/kasm/backups/kasm_db_backup.tar

Note

When performing an offline upgrade please ensure that versions of docker and docker compose that meet the updated system requirements have been downloaded and installed see System Requirements for details.

  • Download and extract the new installation media

cd /tmp
curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.16.1.98d6fa.tar.gz
tar -xf kasm_release_*.tar.gz
  • Get the existing database password for use in the subsequent commands.

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

sudo grep "token" /opt/kasm/1.16.0/conf/app/agent.app.config.yaml

Perform a clean install

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

    • When performing an offline update add these flags --offline-workspaces <KASM_WORKSPACE_IMAGES_TAR> --offline-service <KASM_SERVICE_IMAGES_TAR> --offline-plugin <KASM_PLUGIN_IMAGES_TAR>

sudo bash kasm_release/install.sh -D -Q <DATABASE_PASSWORD> -M <MANAGER_TOKEN>

Modify Configs

  • Copy the server_id and the public_hostname properties from the old agent to the new

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.agent.server_id = load("/opt/kasm/1.16.0/conf/app/agent.app.config.yaml").agent.server_id' /opt/kasm/1.16.1/conf/app/agent.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.agent.public_hostname = load("/opt/kasm/1.16.0/conf/app/agent.app.config.yaml").agent.public_hostname' /opt/kasm/1.16.1/conf/app/agent.app.config.yaml
  • Copy manager_id and server_hostname from the old configuration into the new

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.server.server_hostname = load("/opt/kasm/1.16.0/conf/app/api.app.config.yaml").server.server_hostname' /opt/kasm/1.16.1/conf/app/api.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.manager.manager_id = load("/opt/kasm/1.16.0/conf/app/api.app.config.yaml").manager.manager_id' /opt/kasm/1.16.1/conf/app/api.app.config.yaml
  • Copy the auto-generated nginx configs for any sessions that may exist on the Agent

sudo cp /opt/kasm/1.16.0/conf/nginx/containers.d/* /opt/kasm/1.16.1/conf/nginx/containers.d/
  • Copy the id and the token properties from the old connection_proxy to the new

    • The token field of kasmguac.app.config.yaml has been renamed to auth_token in the Kasm Workspaces 1.13.0 release

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.kasmguac.id = load("/opt/kasm/1.16.0/conf/app/kasmguac.app.config.yaml").kasmguac.id' /opt/kasm/1.16.1/conf/app/kasmguac.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.api.auth_token = load("/opt/kasm/1.16.0/conf/app/kasmguac.app.config.yaml").api.auth_token' /opt/kasm/1.16.1/conf/app/kasmguac.app.config.yaml
  • Copy the id and the auth_token properties from the old rdp_gateway to the new

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.api.auth_token = load("/opt/kasm/1.16.0/conf/app/passthrough.app.config.yaml").api.auth_token' /opt/kasm/1.16.1/conf/app/passthrough.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.rdp-gateway.id = load("/opt/kasm/1.16.0/conf/app/passthrough.app.config.yaml").rdp-gateway.id' /opt/kasm/1.16.1/conf/app/passthrough.app.config.yaml
  • Copy the id and the auth_token properties from the old rdp_https_gateway to the new

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.api.auth_token = load("/opt/kasm/1.16.0/conf/app/rdp_https_gateway.app.config.yaml").api.auth_token' /opt/kasm/1.16.1/conf/app/rdp_https_gateway.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.rdp-gateway.id = load("/opt/kasm/1.16.0/conf/app/rdp_https_gateway.app.config.yaml").rdp-gateway.id' /opt/kasm/1.16.1/conf/app/rdp_https_gateway.app.config.yaml

In Kasm Workspaces version 1.16.0 The Kasm RDP Gateway service was added, when upgrading from any Kasm Workspaces version <= 1.15.0 to any Kasm Workspaces version >= 1.16.0 please perform the below steps to register the new services:

  • Set the registration_token for the rdp_gateway using the Component Registration Token retrieved from the UI earlier.

    • Replace <registration_token> below with the Component Registration Token

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.rdp-gateway.registration_token = "<registration_token>"' /opt/kasm/1.16.1/conf/app/passthrough.app.config.yaml
  • Set the registration_token for the rdp_https_gateway using the Component Registration Token retrieved from the UI earlier.

    • Replace <registration_token> below with the Component Registration Token

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.rdp-gateway.registration_token = "<registration_token>"' /opt/kasm/1.16.1/conf/app/rdp_https_gateway.app.config.yaml

Restoring 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.16.1/bin/utils/db_restore -f /opt/kasm/backups/kasm_db_backup.tar -p  /opt/kasm/1.16.1
  • Perform an upgrade of the database schema

sudo /opt/kasm/1.16.1/bin/utils/db_upgrade -p /opt/kasm/1.16.1
  • (Optional) Install the Kasm 1.16.1 default images for the platform

    • With Kasm Workspaces 1.13.0 and newer the Kasm team recommends using the Workspaces Registry to install Workspaces rather than seeding the images during the installation.

    • Seeding workspaces is still needed when doing an offline Kasm installation as the official Kasm Workspaces Registry will be unavailable.

    • If doing an offline upgrade first extract the default image seed data from the workspace images tar.

      For x86 (amd64) platforms:

      tar xf <KASM_WORKSPACE_IMAGES_TAR> --strip-components=1 -C /opt/kasm/1.16.1/conf/database/seed_data/ workspace_images/default_images_amd64.yaml

      For ARM (arm64) platforms:

      tar xf <KASM_WORKSPACE_IMAGES_TAR> --strip-components=1 -C /opt/kasm/1.16.1/conf/database/seed_data/ workspace_images/default_images_arm64.yaml

For x86 (amd64) platforms:

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

For ARM (arm64) platforms:

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

sudo /opt/kasm/bin/start

Add Connection Proxy Settings to Database

When upgrading from a version <= 1.11.0 to >= 1.12.0 add connection proxy settings to the database:

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

sudo /opt/kasm/bin/start

Update Custom Workspaces

Each release, the Kasm Technologies team updates the default workspaces with new features and security updates. Old workspaces should be removed as they may not be compatible with new Kasm features.

Note

Kasm Workspaces 1.13.0 and newer utilize a Workspaces Registry to install new Workspaces after upgrade. Upon logging into Kasm Workspaces for the first time after the upgrade the administrator will have the opportunity to add the default Kasm Workspaces registry if the administrator has not already configured it.

Workspaces from prior releases may contain incompatible features and are not guaranteed to work. Kasm recommends that the administrator utilize the registry to add the latest compatible Workspaces for the installed version.

Kasm recommends rebuilding any custom Workspaces using the appropriately tagged Docker image (e.g : kasmweb/core-ubuntu-focal:1.16.1 ) see creating custom Kasm images for more information.

See Default and Custom Docker Images for details.

For existing Workspaces officially supported by Kasm, it is possible to edit the Workspace configuration and change the tag to the new version of Kasm Workspaces, this will preserve configuration and group settings that may already have been added. It will take a few minutes for the Kasm Agent to download the new Workspace during which time it will be unavailable.