Skip to main content
Version: Developer

Single-server upgrade

caution

For long-running systems, this release requires a minimum Docker version of v25.0.5. If necessary, upgrade Docker before the Kasm upgrade, following the instructions for your distribution. Although the Kasm installer will install Docker as a missing dependency, it will not upgrade or update Docker. For a detailed explanation and instructions, see 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 server 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​

Before upgrading a single-server deployment to 1.20.0, review these items:

  1. Offline installs: Pre-pull two new container images before running the upgrade:

    docker pull otel/opentelemetry-collector-contrib:0.160.0
    docker pull clickhouse/clickhouse-server:24.12-alpine

    On the all role, kasm_clickhouse is bundled on the same host. No dedicated ClickHouse node is needed.

  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> to also write a separate tar holding only the logs table, as shown in the caution under Automated upgrade. See Review breaking changes and prepare the environment.

Token coordination, the TCP 4317 firewall rule, and inter-collector TLS verification apply only to multi-server deployments.

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

Automated upgrade​

The automated upgrade script upgrades a previous installation to 1.19.0. Administrators have several options when running the automated upgrade 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

In this example --proxy-port is used.

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 upgrade command 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 --proxy-port 443 \
  --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.

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 --proxy-port 443

Troubleshooting an Automated Upgrade​

The upgrade.sh script creates a log file as it runs, and removes it on a successful upgrade. If something goes wrong, the log file is available in the directory the script was run from, in the format kasm_upgrade_${TIMESTAMP}.log. This file is important for diagnosing the error that caused the upgrade to fail, and Kasm Technologies requests it when you submit a support ticket.

Manual upgrade​

Kasm Technologies recommends installing a separate instance of the application, migrating the data, and performing a cutover of the application. Read through the entire process before you start.

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.

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.

Create a database backup​

Back up the existing Kasm database. The backup serves as a recovery point and also migrates existing data to the latest version.

  • Stop existing Kasm Services
sudo /opt/kasm/bin/stop
  • Execute 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 kasm_share and kasm_redis containers
sudo docker container rm kasm_share
sudo docker container rm kasm_redis
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
  • 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

Perform a clean install​

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 -D -Q <DATABASE_PASSWORD> -M <MANAGER_TOKEN>

Modify the configuration files​

  • 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 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
  • 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/

  • 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

Restore the database​

Restore and update the database from the prior version.

  • Ensure all Kasm services are stopped
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
sudo /opt/kasm/1.19.0/bin/utils/db_upgrade -p /opt/kasm/1.19.0

  • (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

Add connection proxy settings to the database​

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

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

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.