---
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                         |
| -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.                           |
| --slim-images                 | Use slim alpine based service containers                                    |
---------------------------------------------------------------------------------------------------------------
```

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

**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
grep token /opt/kasm/{{ previous_release }}/conf/app/kasmguac.app.config.yaml
sudo vi /opt/kasm/{{ release }}/conf/app/kasmguac.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
```