---
myst:
  html_meta:
    "description lang=en": "Manual and automated upgrade process documentation for Kasm Workspaces single server deployments."
    "keywords": "Kasm, Workspace, Single-server, Single, Server, Upgrade"
    "property=og:locale": "en_US"
---
```{title} Single Server Upgrade
```

# 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.
```

## Automated Upgrade

The automated upgrade script can be used to upgrade a previous installation to {{ release }} .

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

```text
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 {code}`--proxy-port` is used.

`````{tabs}

````{tab} Standard Upgrade

```{parsed-literal}
cd /tmp
curl -O {{ release_url }}
tar -xf {{ release_url.split('/') | last }}
sudo bash kasm_release/upgrade.sh --proxy-port 443
```

````

````{tab} Offline Upgrade x86-64

```{parsed-literal}
cd /tmp
curl -O {{ release_url }}
curl -O {{ amd_service_images_url }}
curl -O {{ amd_workspace_images_url }}
tar -xf {{ release_url.split('/') | last }}
sudo bash kasm_release/upgrade.sh --proxy-port 443 --offline-service /tmp/{{ amd_service_images_url.split('/') | last }}
```

````

````{tab} Offline Upgrade arm64

```{parsed-literal}
cd /tmp
curl -O {{ release_url }}
curl -O {{ arm_service_images_url }}
curl -O {{ arm_workspace_images_url }}
tar -xf {{ release_url.split('/') | last }}
sudo bash kasm_release/upgrade.sh --proxy-port 443 --offline-service /tmp/{{ arm_service_images_url.split('/') | last }}
```

````

`````
### 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.

```{include} image_warning.md
```

**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

```Bash
sudo /opt/kasm/bin/stop
```

- Execute the database backup utility

```{parsed-literal}
sudo mkdir -p /opt/kasm/backups/
sudo bash /opt/kasm/{{ previous_release }}/bin/utils/db_backup -f /opt/kasm/backups/kasm_db_backup.tar -p /opt/kasm/{{ previous_release }}/
```

- Verify the presence and location of the database backup

```Bash
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 {doc}`System Requirements <../install/system_requirements>` for details.
```

- Download and extract the new installation media

```{parsed-literal}
cd /tmp
curl -O {{ release_url }}
tar -xf kasm_release_*.tar.gz
```

- Get the existing database password for use in the subsequent commands.

```{parsed-literal}
sudo grep " password" /opt/kasm/{{ previous_release }}/conf/app/api.app.config.yaml
```

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

```{parsed-literal}
sudo grep "token" /opt/kasm/{{ previous_release }}/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-service <KASM_SERVICE_IMAGES_TAR>`

```Bash
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

```{parsed-literal}
grep server_id /opt/kasm/{{ previous_release }}/conf/app/agent.app.config.yaml
grep public_hostname /opt/kasm/{{ previous_release }}/conf/app/agent.app.config.yaml
sudo vi /opt/kasm/{{ release }}/conf/app/agent.app.config.yaml
```

- Copy **manager_id** and **server_hostname** from the old configuration into the new

```{parsed-literal}
grep manager_id /opt/kasm/{{ previous_release }}/conf/app/api.app.config.yaml
grep server_hostname /opt/kasm/{{ previous_release }}/conf/app/api.app.config.yaml
sudo vi /opt/kasm/{{ release }}/conf/app/api.app.config.yaml
```

- Copy the auto-generated nginx configs for any sessions that may exist on the Agent

```{parsed-literal}
sudo cp /opt/kasm/{{ previous_release }}/conf/nginx/containers.d/* /opt/kasm/{{ release }}/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 

```{parsed-literal}
grep id /opt/kasm/{{ previous_release }}/conf/app/kasmguac.app.config.yaml
/opt/kasm/bin/utils/yq_$(uname -m) -r '.api.auth_token' /opt/kasm/{{ previous_release }}/conf/app/kasmguac.app.config.yaml
sudo vi /opt/kasm/{{ release }}/conf/app/kasmguac.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**

```{parsed-literal}
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.rdp-gateway.registration_token = "<registration_token>"' /opt/kasm/{{ release }}/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**

```{parsed-literal}
sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.rdp-gateway.registration_token = "<registration_token>"' /opt/kasm/{{ release }}/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

```Bash
sudo /opt/kasm/bin/stop
```

- Execute the database restore command

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_restore -f /opt/kasm/backups/kasm_db_backup.tar -p  /opt/kasm/{{ release }}
```

- Perform an upgrade of the database schema

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_upgrade -p /opt/kasm/{{ release }}
```

- (Optional) Install the Kasm {{ release }} 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:

    ```{parsed-literal}
    tar xf <KASM_WORKSPACE_IMAGES_TAR> --strip-components=1 -C /opt/kasm/{{ release }}/conf/database/seed_data/ workspace_images/default_images_amd64.yaml
    ```

    For ARM (arm64) platforms:

    ```{parsed-literal}
    tar xf <KASM_WORKSPACE_IMAGES_TAR> --strip-components=1 -C /opt/kasm/{{ release }}/conf/database/seed_data/ workspace_images/default_images_arm64.yaml
    ```

For x86 (amd64) platforms:

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_init -s /opt/kasm/{{ release }}/conf/database/seed_data/default_images_amd64.yaml
```

For ARM (arm64) platforms:

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_init -s /opt/kasm/{{ release }}/conf/database/seed_data/default_images_arm64.yaml
```

- Start the Kasm services

```Bash
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:

```{parsed-literal}
sudo /opt/kasm/{{ release }}/bin/utils/db_init -s /opt/kasm/{{ release }}/conf/database/seed_data/default_connection_proxies.yaml
```

- Start the Kasm services

```Bash
sudo /opt/kasm/bin/start
```

```{include} upgrade_images.md
```