Standalone Remote Database

Admins may wish to use a Managed Database Service such as RDS and Elasticache or have a separate PostgreSQL Database and Redis server from their Kasm installation.

This guide provides instructions on how to initialize the database server from a remote machine and then install the Kasm WebApp.

Requirements

  • Remote PostgreSQL server supports PostgreSQL version 12.

  • Remote PostgreSQL either already has a User “kasmapp” in the database “kasm” OR you have SuperUser credentials on the database.

  • Remote Redis server supports Redis version 5.

  • Machine executing initialization and the Web App server can both connect to the PostgreSQL Database (default port TCP/5432)

  • Web App servers can connect to Redis Server (default port TCP/6379)

  • Remote PostgreSQL must support the UUID-OSSP Extension. The Kasm installer will attempt to create the extension, if it is not already enabled.

Important

If you are using the Azure Database for PosgreSQL PaaS, you will need to enable the UUID-OSSP extension from the Azure portal prior to following the below steps. In the Azure portal, navigate to your Postgres database, go to Server Parameters, search for azure.extensions, hit the drop-down and check th box next to UUID-OSSP. Hit the Save button to apply the change. Wait for the change to apply, this can take a few minutes.

When performing an installation

Initializing PostgreSQL Server

  • This can be done from anywhere, but since the script will install docker and other Kasm prerequisites it may be easiest to run the remote DB install from the future Kasm Web App server.

  • Download latest version of Kasm Workspaces to /tmp

  • Extract package and initialize the Database.

cd /tmp

curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.16.1.98d6fa.tar.gz

tar -xf kasm_release*.tar.gz

sudo bash kasm_release/install.sh \
--accept-eula \
--role init_remote_db \
--db-hostname [DATABASE_HOSTNAME] \
--db-password [DATABASE_KASMAPP_USER_PASSWORD] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--db-master-user [DATABASE_SUPERUSER_USERNAME] \
--db-master-password [DATABASE_SUPERUSER_PASSWORD]

Note

If the Database already has the User “kasmapp” and database “kasm” created you may omit the -g and -G parameters. The DATABASE_USERNAME and DATABASE_NAME are optional and only required if not using the default kasm/kasmapp settings.

Installing Kasm Web App

  • Download latest version of Kasm Workspaces to /tmp

  • Extract package and initialize the Database.

cd /tmp

tar -xf kasm_release*.tar.gz

sudo bash kasm_release/install.sh \
--role app \
--db-hostname [DATABASE_HOSTNAME] \
--db-password [DATABASE_KASMAPP_USER_PASSWORD] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--redis-hostname [REDIS_HOSTNAME] \
--redis-password [REDIS_PASSWORD]

Note

If you are using Redis on Elasticache you will need to set [REDIS_PASSWORD] to "".

Backing up the PostgreSQL Server

  • This script should be run from a Kasm Web App server.

If you are backing up a standalone remote database for Kasm Workspaces 1.10.0 we will need to use the backup script that is included with the 1.16.1 release as the one included with 1.10.0 did not support a remote standalone database:

  • Download the latest version of Kasm Workspaces to /tmp

  • Extract package and run the backup script

    • If necessary, use the --exclude-logs flag or -l to exclude log data from the backup

cd /tmp

tar -xf kasm_release*.tar.gz

sudo bash kasm_release/bin/utils/db_backup \
--backup-file [DESIRED_BACKUP_FILE_LOCATION] \
--database-hostname [DATABASE_HOSTNAME] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--path [PATH_TO_KASM_INSTALL]

If you are backing up a standalone remote database for Kasm Workspaces 1.11.0 or newer then use the existing db_backup script:

sudo bash /opt/kasm/bin/utils/db_backup -v --backup-file [DESIRED_BACKUP_FILE_LOCATION] -q [DATABASE_HOSTNAME] --path [PATH_TO_KASM_INSTALL]

  • The backup will be present at the location specified with –backup-file

Restoring the PostgreSQL server from a backup

  • This script should be ran from a Kasm Web App server or during a Kasm Workspaces upgrade from the server that ran the database clean install step.

  • You will need SuperUser credentials on the database.

  • Make sure that All Kasm Web App and Agent servers have their services stopped.

sudo bash /opt/kasm/1.16.1/bin/utils/db_restore \
--backup-file [LOCATION_OF_BACKUP_FILE] \
--database-hostname [DATABASE_HOSTNAME] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--path /opt/kasm/1.16.1 \
--database-master-user [DATABASE_MASTER_USER] \
--database-master-password [DATABASE_MASTER_USER_PASSWORD]

  • After the restore is complete restart all Kasm Web App and Agent services.

When performing an upgrade

Important

Before performing an upgrade ensure all Kasm Workspaces Containers/Sessions are stopped on all hosts in your deployment. sudo /opt/kasm/bin/stop Also ensure the “Automatically Enable Agents” is enabled under settings in the Admin Dashboard. These instructions are for upgrading from Kasm Workspaces >= 1.11.0 to 1.16.1.

Upgrading Kasm Web App

Database migration

Note

The database migration commands should be run once from the Kasm Web App with access to the remote database. Any additional Kasm Web App server does not need to execute database migrations again.

  • Stop all services:

sudo /opt/kasm/bin/stop

  • Grab and extract the installer for 1.16.1:

cd /tmp

curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.16.1.98d6fa.tar.gz

tar -xf kasm_release*.tar.gz

  • Generate a database backup:

Important

If necessary, use the --exclude-logs flag or -l to exclude log data from the backup. Note that this will result in an empty logs interface after the upgrade.

sudo mkdir -p /opt/kasm/backups/

sudo bash kasm_release/bin/utils/db_backup \
--backup-file /opt/kasm/backups/1.16.0_backup.tar \
--database-hostname [DATABASE_HOSTNAME] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--path /opt/kasm/current

  • Log into your PostgreSQL server as the master user and remove the database/user:

drop database if exists kasm;
drop user if exists kasmapp;

  • Init the empty DB, restore our backup, and upgrade the database:

sudo bash kasm_release/install.sh \
--accept-eula \
--role init_remote_db \
--db-hostname [DATABASE_HOSTNAME] \
--db-password [DATABASE_KASMAPP_USER_PASSWORD] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--db-master-user [DATABASE_MASTER_USER] \
--db-master-password [DATABASE_MASTER_USER_PASSWORD]

sudo bash /opt/kasm/1.16.1/bin/utils/db_restore \
--backup-file /opt/kasm/backups/1.16.0_backup.tar \
--database-hostname [DATABASE_HOSTNAME] \
--path /opt/kasm/1.16.1 \
--database-master-user [DATABASE_MASTER_USER] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--database-master-password [DATABASE_MASTER_USER_PASSWORD]

sudo bash /opt/kasm/1.16.1/bin/utils/db_upgrade \
--database-hostname [DATABASE_HOSTNAME] \
--path /opt/kasm/1.16.1

  • Seed the new images for this installation:

sudo /opt/kasm/1.16.1/bin/utils/db_init \
--database-hostname [DATABASE_HOSTNAME] \
--seed-file /opt/kasm/1.16.1/conf/database/seed_data/default_images_amd64.yaml

Kasm Web App upgrade

  • Run a clean install of 1.16.1:

sudo bash kasm_release/install.sh \
--role app \
--no-start \
--db-hostname [DATABASE_HOSTNAME] \
--db-password [DATABASE_KASMAPP_USER_PASSWORD] \
--database-user [DATABASE_USERNAME] \
--database-name [DATABASE_NAME] \
--redis-password [REDIS_PASSWORD] \
--redis-hostname [REDIS_HOSTNAME] \
--skip-connection-test

  • Update config information:

export MANAGER_ID=$(/opt/kasm/bin/utils/yq_$(uname -m) '.manager.manager_id' /opt/kasm/1.16.0/conf/app/api.app.config.yaml)

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.manager.manager_id = "'${MANAGER_ID}'"' /opt/kasm/1.16.1/conf/app/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/{{ previous_release }}/docker/docker-compose.yaml  /opt/kasm/{{ release }}/docker/docker-compose.yaml

  • Start the Kasm Web App:

sudo /opt/kasm/bin/start

Upgrading Kasm Agent

  • Stop all services:

sudo /opt/kasm/bin/stop

  • Grab and extract the installer for 1.16.1:

cd /tmp

curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.16.1.98d6fa.tar.gz

tar -xf kasm_release*.tar.gz

  • Execute a clean install:

sudo bash kasm_release/install.sh \
--role agent \
--no-start \
--public-hostname [AGENT_HOSTNAME] \
--manager-hostname [MANAGER_HOSTNAME] \
--manager-token [MANAGER_TOKEN]

  • Update config information:

export SERVER_ID=$(/opt/kasm/bin/utils/yq_$(uname -m) '.agent.server_id' /opt/kasm/1.16.0/conf/app/agent.app.config.yaml)

sudo /opt/kasm/bin/utils/yq_$(uname -m) -i '.agent.server_id = "'${SERVER_ID}'"' /opt/kasm/1.16.1/conf/app/agent.app.config.yaml

  • Copy the auto-generated nginx configs for any sessions that may exists on the Agent:

/opt/kasm/1.16.0/conf/nginx/containers.d/* /opt/kasm/1.16.1/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.16.0/docker/docker-compose.yaml  /opt/kasm/1.16.1/docker/docker-compose.yaml

diff /opt/kasm/1.16.0/conf/app/agent.app.config.yaml  /opt/kasm/1.16.1/conf/app/agent.app.config.yaml

  • Start the Kasm Agent:

sudo /opt/kasm/bin/start

Upgrading/Adding the Guac Role

Note

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.

  • On a new server Grab and extract the installer for 1.16.1:

cd /tmp

curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.16.1.98d6fa.tar.gz

tar -xf kasm_release*.tar.gz

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

  • Execute a clean install:

sudo bash kasm_release/install.sh \
--role guac \
--api-hostname [API_HOSTNAME] \
--public-hostname [GUAC_SERVER_HOSTNAME] \
--registration-token [COMPONENT_REGISTRATION_TOKEN]