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.

Automated Upgrade

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

Administrators have several options to choose from with out to handle replacing existing images.

Flag                                        Description
---------------------------------------------------------------------------------------------------------------
| -h|--help                     | Display this help menu                                                      |
| -L|--proxy-port               | Default Proxy Listening Port                                                |
| -I|--no-images                | Don't seed or pull default Workspaces Images                                |
| -U|--upgrade-images           | Upgrade Images to current set purging previous images                       |
| -K|--add-images               | Ingest the latest images keeping old images in place                        |
| -w|--offline-workspaces       | Path to the tar.gz workspace images offline installer                       |
| -s|--offline-service          | Path to the tar.gz service images offline installer                         |
| -S|--role                     | Role to Upgrade: [app|db|agent|remote_db|guac|proxy]                        |
| -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 Workspaces images                                               |
---------------------------------------------------------------------------------------------------------------

In this example --add-images and --proxy-port is used.

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

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.12.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.

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.11.0/bin/utils/db_backup -f /opt/kasm/backups/kasm_db_backup.tar -p /opt/kasm/1.11.0/

  • Verify the presence and location of the database backup

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

Note

If you are performing an offline upgrade please ensure that you have downloaded and installed versions of docker and docker compose that meet the updated system requirements 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.12.0.d4fd8a.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.11.0/conf/app/api.app.config.yaml

  • Get the existing manager token for use in the subsequent commands.

sudo grep "token" /opt/kasm/1.11.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>

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

grep server_id /opt/kasm/1.11.0/conf/app/agent.app.config.yaml
grep public_hostname /opt/kasm/1.11.0/conf/app/agent.app.config.yaml
sudo vi /opt/kasm/1.12.0/conf/app/agent.app.config.yaml

  • Copy manager_id and server_hostname from the old configuration into the new

grep manager_id /opt/kasm/1.11.0/conf/app/api.app.config.yaml
grep server_hostname /opt/kasm/1.11.0/conf/app/api.app.config.yaml
sudo vi /opt/kasm/1.12.0/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.11.0/conf/nginx/containers.d/* /opt/kasm/1.12.0/conf/nginx/containers.d/

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.12.0/bin/utils/db_restore -f /opt/kasm/backups/kasm_db_backup.tar -p  /opt/kasm/1.12.0

  • Perform an upgrade of the database schema

sudo /opt/kasm/1.12.0/bin/utils/db_upgrade -p /opt/kasm/1.12.0

  • Install The Kasm 1.12.0 Default Images for your platform

    • 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.12.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.12.0/conf/database/seed_data/ workspace_images/default_images_arm64.yaml

For x86 (amd64) platforms:

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

For ARM (arm64) platforms:

sudo /opt/kasm/1.12.0/bin/utils/db_init -s /opt/kasm/1.12.0/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.12.0/bin/utils/db_init -s /opt/kasm/1.12.0/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. The previous steps added the new default workspaces to the upgraded system. Old workspaces should be removed as they are not compatible with new Kasm features.

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

See Default and Custom Docker Images for details.