Skip to main content
Version: Developer

Multi-server upgrade

caution

For long-running systems: this release requires a minimum Docker version of v25.0.5. If necessary prior to Kasm upgrade, please upgrade Docker following their instructions for your distribution. Although the Kasm installer will install Docker as a missing dependency, it will not upgrade or update Docker. A detailed explanation and instructions are available in the the Kasm support article.

caution

Before any upgrade, confirm that no active Kasm Workspaces sessions are running. On large deployments, this usually requires a maintenance window.

note

A backup is not required, but a VM snapshot or other backup of the servers in the installation is recommended as a precaution, to provide a recovery point if something goes wrong.

note

Starting in 1.19.0, the default installation uses rolling images to deliver ongoing security fixes and updates. For static images with manual update control, pass the -f or --use-static-images argument during the installation or upgrade process.

sudo bash kasm_release/install.sh -f

or

sudo bash kasm_release/upgrade.sh -f

Refer to Rolling Image Management for more information about rolling images.

Install Files
ContentsURLSHA256
Installer Bundlehttps://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0.tar.gz7b801cb0579a7867df46b6da873fe8dd631db07d4c05349e5bd1aea27130c37d
ContentsURLSHA256
Serviceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_amd64_1.19.0.tar.gzc8697a7d6db6d6c2cd685cf431977e79bb4adfa35d91d6fab455e70f4441e46d
Workspaceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_amd64_1.19.0.tar.gz2338ed95653cf37b41c32c4202c38b507fd94a745dc81a303402e20f292486da
Network Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_network_plugin_images_amd64_1.5.tar.gzbd13ce71737cebf2e7559c01c2dbff657a52505c771fce450a32bed36ef3056d
Logging Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_logging_plugin_images_amd64_1.1.tar.gzfe5d1d6d1acd42ea89e15e375d0d6719f9d6cbf1f9c6943c4fda901a3d529135
ContentsURLSHA256
Serviceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_service_images_arm64_1.19.0.tar.gzf7975cecf89fc5b1e3886c09178047e7d6f092344ab15f9babfdeaeeb8d01801
Workspaceshttps://kasm-static-content.s3.amazonaws.com/kasm_release_workspace_images_arm64_1.19.0.tar.gz5ee92ebac22c7399694c9a7eef4d0baddc98c315c2d78848fa3a757d66bcd2c4
Network Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_network_plugin_images_arm64_1.5.tar.gz59d23f6765f26be86a00fed31b38873d36f9b7b7ecf608a2efb270d969621ae6
Logging Pluginhttps://kasm-static-content.s3.amazonaws.com/kasm_release_logging_plugin_images_arm64_1.1.tar.gz1d720994c141fe9743b566ea2affeee77759e272ad777d0257ed6a089dd3b802
caution

Starting in Kasm Workspaces 1.17.0, the following configuration files changed locations.

Old locationNew location
/opt/kasm/current/conf/app/agent.app.config.yaml/opt/kasm/current/conf/app/agent/agent.app.config.yaml
/opt/kasm/current/conf/app/api.app.config.yaml/opt/kasm/current/conf/app/api/api.app.config.yaml
/opt/kasm/current/conf/app/kasmguac.app.config.yaml/opt/kasm/current/conf/app/guac/kasmguac.app.config.yaml
/opt/kasm/current/conf/app/passthrough.app.config.yaml/opt/kasm/current/conf/app/rdp_gateway/passthrough.app.config.yaml
/opt/kasm/current/conf/app/rdpproxy.ini/opt/kasm/current/conf/app/rdp_gateway/rdpproxy.ini
/opt/kasm/current/conf/app/rdp_https_gateway.app.config.yaml/opt/kasm/current/conf/app/rdp_https_gateway/rdp_https_gateway.app.config.yaml
/opt/kasm/current/conf/app/rdpgw.yaml/opt/kasm/current/conf/app/rdp_https_gateway/rdpgw.yaml

Observability prerequisites for 1.20.0 upgrades​

Observability prerequisites​

Before upgrading a multi-server deployment to 1.20.0, complete these prerequisites:

  1. Open TCP 4317 on the app/all node from all remote nodes (agent, db, guac, proxy roles). This port is used by remote OTel Collectors to forward telemetry to the central collector. For cloud deployments, add an inbound firewall rule for TCP 4317 from the remote nodes' IP addresses or subnets. Do not expose this port to the internet.

  2. Token coordination: The OTel bearer token must match across all nodes. The upgrade script on the app node generates a token automatically. After upgrading the app node, retrieve the token:

grep -oP '(?<=token: \")[^\"]+' /opt/kasm/current/conf/otel/otel-collector-config.yaml

Pass this token to each remote node upgrade with --otel-token <token>.

  1. Offline installs: Pre-pull two new container images:
docker pull otel/opentelemetry-collector-contrib:0.160.0
docker pull clickhouse/clickhouse-server:24.12-alpine

In a multi-server deployment kasm_clickhouse runs on its own dedicated clickhouse role node — a required role, the same as the Database Server (it is bundled on the node only in a single-server all install). Upgrade it with upgrade.sh -S clickhouse. See Dedicated ClickHouse role.

  1. (Optional) Verified TLS on the inter-collector hop: the 4317 hop is bearer-token authenticated and TLS-encrypted by default, without certificate verification. If the app/all node uses a CA-signed certificate whose SANs cover the exact hostname passed as --otel-collector-hostname, pass --otel-collector-verify-tls (public CA) or --otel-collector-ca-cert <path> (private/corporate CA) when upgrading each remote node (agent, guac, proxy) to turn on verification for that hop. The choice persists across future upgrades automatically; pass --otel-collector-no-verify-tls on a later upgrade.sh run to turn it back off. See Configure custom TLS certificates.

  2. PostgreSQL logs table: The schema migration drops the logs table and does not migrate its contents to ClickHouse. The pre-upgrade backup at /opt/kasm/backups/kasm_db_backup.tar is the only surviving copy of that table. Pass --backup-logs-file <absolute path> when upgrading the db or remote_db role to also write a separate tar holding only the logs table. The command is shown in the caution under Upgrade script.

For the complete observability upgrade procedure and migration guide, see Observability migration.

Manual upgrade​

Read through the entire process before you start. Report issues on the Kasm Workspaces issues page.

Retrieve the component registration token​

The Component Registration Token registers new components during the upgrade that were not present in earlier versions of Kasm Workspaces. Log in to the Workspaces UI as an administrator and retrieve the value of Component Registration Token from the global settings.

warning

The Kasm Workspaces 1.19.0 upgrade optionally installs a new set of default desktop and application images. Ensure 50 GB of free space is available on the Kasm server (or Agent role server for multi-server installations) before upgrading if you select the options to seed new images.

  • Stop all Kasm Services on all Servers
sudo /opt/kasm/bin/stop

Upgrade the database server role​

First, create a database backup.

  • Confirm that Kasm services are stopped on all hosts. Database corruption can occur when Kasm services are still connected to the database as it goes down.
note

For a standalone remote database, see Backing up the PostgreSQL server.

sudo /opt/kasm/bin/stop
  • Run the database backup utility.
note

If the /opt/kasm/backups directory already exists, note that the permissions changed in 1.18.0. Run:

sudo chown -R 70:70 /opt/kasm/backups

If the directory does not exist, create it and adjust the permissions:

sudo mkdir -p /opt/kasm/backups/
sudo chown -R 70:70 /opt/kasm/backups
sudo bash /opt/kasm/1.18.1/bin/utils/db_backup -f /opt/kasm/backups/kasm_db_backup.tar -p /opt/kasm/1.18.1/
  • Verify the presence and location of the database backup
sudo ls -al /opt/kasm/backups/kasm_db_backup.tar
  • Remove the kasm_redis container
sudo docker container rm kasm_redis
  • Download and extract the new installation media
cd /tmp/ \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz
note

For an offline upgrade, confirm that versions of Docker and Docker Compose that meet the updated system requirements are downloaded and installed. See System requirements for details.

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

Perform a clean install of the database role services​

note

For a standalone remote database, see Initializing the PostgreSQL server.

  • 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>
sudo bash kasm_release/install.sh -S db -D -Q <DATABASE_PASSWORD>

Restore and upgrade the database​

Restore and update the database from the prior version.

  • Confirm that all Kasm services are stopped on all hosts.
note

For a standalone remote database, see Restoring the PostgreSQL server from a backup.

sudo systemctl stop kasm
  • Execute the database restore command
sudo /opt/kasm/1.19.0/bin/utils/db_restore -f /opt/kasm/backups/kasm_db_backup.tar -p  /opt/kasm/1.19.0/
  • Perform an upgrade of the database schema
note

For a standalone remote database, see Standalone remote database.

sudo /opt/kasm/1.19.0/bin/utils/db_upgrade -p /opt/kasm/1.19.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.18.1/docker/docker-compose.yaml  /opt/kasm/1.19.0/docker/docker-compose.yaml

  • (Optional) Install the Kasm 1.19.0 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.19.0/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.19.0/conf/database/seed_data/ workspace_images/default_images_arm64.yaml

For x86 (amd64) platforms:

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

For ARM (arm64) platforms:

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

Upgrade the Webapp server role​

  • Stop existing Kasm Services
sudo /opt/kasm/bin/stop
  • Remove the kasm_share container
sudo docker container rm kasm_share
  • Download and extract the new installation media
cd /tmp/ \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_*-latest.tar.gz
note

For an offline upgrade, confirm that versions of Docker and Docker Compose that meet the updated system requirements are downloaded and installed. See System requirements for details.

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

    • When performing an offline update add this flag --offline-service <KASM_SERVICE_IMAGES_TAR>
sudo bash kasm_release/install.sh -S app -D -q <DATABASE_HOSTNAME> -Q <DATABASE_PASSWORD>
  • 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.18.1/conf/app/api/api.app.config.yaml").server.server_hostname' /opt/kasm/1.19.0/conf/app/api/api.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.manager.manager_id = load("/opt/kasm/1.18.1/conf/app/api/api.app.config.yaml").manager.manager_id' /opt/kasm/1.19.0/conf/app/api/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.18.1/docker/docker-compose.yaml  /opt/kasm/1.19.0/docker/docker-compose.yaml
  • Start the Kasm services
sudo systemctl start kasm

Upgrade the Docker Agent server role​

  • Ensure all Kasm services are stopped
sudo /opt/kasm/bin/stop
  • Get the existing manager token for use in the subsequent commands.
sudo grep "token" /opt/kasm/1.18.1/conf/app/agent/agent.app.config.yaml
note

For an offline upgrade, confirm that versions of Docker and Docker Compose that meet the updated system requirements are downloaded and installed. See System requirements for details.

  • Install kasm.
cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& 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
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.agent.server_id = load("/opt/kasm/1.18.1/conf/app/agent/agent.app.config.yaml").agent.server_id' /opt/kasm/1.19.0/conf/app/agent/agent.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.agent.public_hostname = load("/opt/kasm/1.18.1/conf/app/agent/agent.app.config.yaml").agent.public_hostname' /opt/kasm/1.19.0/conf/app/agent/agent.app.config.yaml
  • Copy the auto-generated nginx configs for any sessions that may exist on the Agent
sudo cp /opt/kasm/1.18.1/conf/nginx/containers.d/* /opt/kasm/1.19.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.18.1/docker/docker-compose.yaml  /opt/kasm/1.19.0/docker/docker-compose.yaml
diff /opt/kasm/1.18.1/conf/app/agent/agent.app.config.yaml  /opt/kasm/1.19.0/conf/app/agent/agent.app.config.yaml
  • Start the Kasm services
sudo systemctl start kasm
  • 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

(Optional) Install the Connection Proxy server role​

The Connection Proxy role is new in Workspaces 1.12.0. This service is used to connect to VM/Hardware running RDP, VNC, or SSH. If these capabilities are not needed, this role does not need to be installed.

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

  • Download and extract the new installation media
cd /tmp/ \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_*-latest.tar.gz

  • Install the Connection Proxy role 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>
    • Replace <SERVICE_REGISTRATION_TOKEN> below with the Component Registration Token
sudo bash kasm_release/install.sh --role guac --api-hostname [MANAGER_HOSTNAME] --public-hostname [CONNECTION_PROXY_HOSTNAME] --registration-token [SERVICE_REGISTRATION_TOKEN] -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.18.1/conf/app/guac/kasmguac.app.config.yaml").kasmguac.id' /opt/kasm/1.19.0/conf/app/guac/kasmguac.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.api.auth_token = load("/opt/kasm/1.18.1/conf/app/guac/kasmguac.app.config.yaml").api.auth_token' /opt/kasm/1.19.0/conf/app/guac/kasmguac.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.api.public_jwt_cert = load("/opt/kasm/1.18.1/conf/app/guac/kasmguac.app.config.yaml").api.public_jwt_cert' /opt/kasm/1.19.0/conf/app/guac/kasmguac.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i 'del(.kasmguac.registration_token)' /opt/kasm/1.19.0/conf/app/guac/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.18.1/conf/app/rdp_gateway/passthrough.app.config.yaml").api.auth_token' /opt/kasm/1.19.0/conf/app/rdp_gateway/passthrough.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.rdp-gateway.id = load("/opt/kasm/1.18.1/conf/app/rdp_gateway/passthrough.app.config.yaml").rdp-gateway.id' /opt/kasm/1.19.0/conf/app/rdp_gateway/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.18.1/conf/app/rdp_https_gateway/rdp_https_gateway.app.config.yaml").api.auth_token' /opt/kasm/1.19.0/conf/app/rdp_https_gateway/rdp_https_gateway.app.config.yaml
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.rdp-gateway.id = load("/opt/kasm/1.18.1/conf/app/rdp_https_gateway/rdp_https_gateway.app.config.yaml").rdp-gateway.id' /opt/kasm/1.19.0/conf/app/rdp_https_gateway/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.19.0/conf/app/rdp_gateway/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.19.0/conf/app/rdp_https_gateway/rdp_https_gateway.app.config.yaml
sudo systemctl start kasm

Upgrade script​

Since Kasm Workspaces version 1.11.0, an automated upgrade script is included with the installation package under kasm_release/upgrade.sh.

For enterprise and complex environments it is recommended to use the manual upgrade process to ensure against data loss.

note

Before you start the upgrade, confirm that the Web App servers are stopped. When they are left running, database corruption can occur on the Web App servers.

sudo /opt/kasm/bin/stop

The upgrade script can be found in the installation package under kasm_release/upgrade.sh.

These instructions assume there are 3 servers with the app, db, and agent roles.

Back up the PostgreSQL logs table before you upgrade

The 1.20.0 schema migration drops the PostgreSQL logs table. Its contents are not migrated to ClickHouse, and after the upgrade the only copy is the pre-upgrade backup. Add --backup-logs-file to the db or remote_db role upgrade command, because that host holds the table, to write a standalone pg_dump tar archive of that table at a path you choose. Add --backup-file-name to choose where the full database backup is written. Both paths must be absolute.

sudo bash kasm_release/upgrade.sh --role db \
  --backup-file-name /opt/kasm/backups/kasm_db_backup.tar \
  --backup-logs-file /opt/kasm/backups/kasm_logs_backup.tar

Confirm both files exist before you remove the previous release directory:

sudo ls -al /opt/kasm/backups/

Restore the logs archive into a separate PostgreSQL database with pg_restore when you need to query the old history. For the ClickHouse equivalents of the old columns, see Migrate downstream consumers from PostgreSQL logs to ClickHouse.

Login to the db server and execute:

cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/upgrade.sh --role db

Login to the agent server and execute:

cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/upgrade.sh --role agent

Login to the Web App server and execute:

cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/upgrade.sh --role app

Log in to the connection proxy server and run the following:

note

The Component Registration Token is available in the global server settings of the Kasm Workspaces deployment.

cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/upgrade.sh --role guac --registration-token [COMPONENT_REGISTRATION_TOKEN]

Login to the dedicated proxy server and execute:

In this example we assume the proxy domain is proxy.example.com and the Web App hosting the API server is located at workspaces.example.com.

cd /tmp \
&& curl --fail-early \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.tar.gz \
    -fO https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0-latest.sha256sum \
&& sha256sum --check --ignore-missing kasm_release_1.19.0-latest.sha256sum \
&& tar -xf kasm_release_1.19.0-latest.tar.gz \
&& sudo bash kasm_release/upgrade.sh --role proxy --api-hostname workspaces.kasmweb.com

Here are the available helper flags for the upgrade.sh script:

FlagDescription
-h or --helpDisplay this help menu
-L or --proxy-portDefault Proxy Listening Port
-s or --offline-servicePath to the tar.gz service images offline installer
-x or --offline-network-pluginPath to the tar.gz network plugin offline installer
--offline-logger-pluginPath to the tar.gz logger plugin offline installer
-S or --roleRole to Upgrade: [app|db|agent|remote_db|guac|proxy|clickhouse]
-p or --public-hostnameAgent/Component <IP/Hostname> used to register with deployment.
-g or --database-master-userDatabase master username required for remote DB
-G or --database-master-passwordDatabase master password required for remote DB
-q or --db-hostnameDatabase Hostname needed when upgrading agent and pulling images
-T or --db-portDatabase port needed when upgrading agent and pulling images (default 5432)
-Q or --db-passwordDatabase Password needed when upgrading agent and pulling images
-b or --no-check-diskDo not check disk space
-N or --skip-connection-testSkip the pre-upgrade OTel and ClickHouse connectivity checks
--backup-file-nameAbsolute path of the pre-upgrade database backup tar (default /opt/kasm/backups/kasm_db_backup.tar). The restore step reads the same path.
--backup-logs-fileAbsolute path of an additional tar holding only the PostgreSQL logs table, taken before the schema migration drops it (all, db, and remote_db roles)
-n or --api-hostnameSet API server hostname
-A or --enable-losslessEnable lossless streaming option (1.12 and above)
-O or --use-rolling-imagesUse rolling Service images
-f or --use-static-imagesUse static versioned Service images
-F or --use-tagUse a specific tag for service images. Default to build date.
-k or --registration-tokenRegister a component with an existing deployment.
--skip-egressDo not install egress network plugin or dependencies
--skip-otelDo not install the OTel Collector or ClickHouse (recovered if previously skipped)
--enable-otelInstall the OTel Collector and ClickHouse even if the previous install skipped them
--otel-tokenBearer token for OTel inter-collector authentication (recovered if omitted)
--otel-db-monitor-passwordPassword for the kasm_otel_monitor database role (recovered if omitted)
--otel-collector-endpointCustom OTLP collector replacing the bundled one (recovered if omitted)
--clickhouse-endpointExternal ClickHouse native-interface DSN for the collector (recovered if omitted)
--clickhouse-http-endpointExternal ClickHouse HTTP URL for Kasm UI reports and logs (recovered if omitted)
--clickhouse-usernameUsername for the external ClickHouse database (recovered if omitted)
--clickhouse-databaseClickHouse database name (recovered if omitted, default kasm_otel)
--clickhouse-passwordClickHouse password: server password on the clickhouse role, connect password on app (recovered if omitted)
--clickhouse-reader-usernameClickHouse read-only username the API uses for reports and logs (recovered if omitted, default kasm_otel_ro)
--clickhouse-reader-passwordClickHouse read-only password the API uses for reports and logs (recovered if omitted)
--no-clickhouseSkip bundled ClickHouse with no external replacement (recovered if omitted)
--otel-forward-endpointForward all telemetry to this OTLP/HTTP endpoint (recovered if omitted)
--otel-forward-tokenBearer token for --otel-forward-endpoint authentication (recovered if omitted)
--otel-trace-sample-percentagePercent of non-error, non-slow traces kept (recovered if omitted, default 10)
--otel-logs-retention-daysGeneral log retention in days (default 30)
--otel-audit-logs-retention-daysAudit log retention in days (default 365)
--otel-traces-retention-daysTrace retention in days (default 7)
--otel-metrics-retention-daysMetrics retention in days (default 90)
--otel-collector-hostnameHostname of the central OTel collector (required for distributed remote roles)
--otel-collector-verify-tlsVerify the central collector certificate on the 4317 hop (recovered if omitted)
--otel-collector-ca-certCA certificate for that verification, implies --otel-collector-verify-tls (recovered if omitted)
--otel-collector-no-verify-tlsClear a recovered verify-tls choice, restoring encrypt-only TLS on that node
--ignore-dep-failuresContinue installation even if optional dependencies fail to install
--enable-epelEnable EPEL repo to install packages not in default RHEL repos

Troubleshooting an Automated Upgrade​

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.

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 use a Workspaces Registry to install new Workspaces after an upgrade. When the administrator logs into Kasm Workspaces for the first time after the upgrade, Kasm offers to add the default Workspaces Registry if it is not already configured.

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

Kasm Workspaces 1.20.0 cannot start Workspace images made for 1.19 or earlier

Workspace images made for Kasm Workspaces 1.20.0 have a com.kasmweb.kasm_version label. When someone tries to start a session, Kasm blocks the image if:

  • it has no com.kasmweb.kasm_version label, or the label shows an older version
  • it is not marked as a Kasm image (it has no com.kasmweb.image label)
  • the agent that holds it does not report its image labels, for example an agent that has not been upgraded to 1.20.0

The user sees this message: "Workspace image (name) is not compatible with this Kasm release and cannot be launched. Please contact an Administrator". The API server log shows why the image was blocked. Look for a line that starts with Launch refused for image.

Before users start sessions on the upgraded deployment:

  • Switch every container Workspace to a 1.20.0 image tag.
  • Rebuild custom images from a 1.20.0 kasmweb/core-* base image.
  • Upgrade every agent to 1.20.0.

Kasm recommends rebuilding any custom Workspaces using the appropriately tagged Docker image (e.g : kasmweb/core-ubuntu-jammy:1.19.0 ) 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.