Build an install or upgrade command

Overview

The Kasm Workspaces installer and upgrader accept several dozen flags, and the right set depends on the role, whether the install is offline, and how observability is deployed. This page builds the command for you. Choose the script and role, select the flags you need, fill in values, and copy the result into the install guide's download and extract steps.

Everything on this page runs in your browser. Values you type are never sent anywhere. Passwords you leave empty appear as placeholders in angle brackets.

Prerequisites

• The release package downloaded and extracted to /tmp on the target host, as shown in the single-server or multi-server installation guides.
• For upgrades, the current install stopped with sudo /opt/kasm/bin/stop, and a plan for the 1.20.0 observability prerequisites.

note

The generated command appears directly below the steps and updates as you change the form. It uses long flag names with one flag per line, so it can be pasted into a change ticket or a runbook. Select One line, no line continuations for a single line that pastes cleanly into a terminal. For the meaning of each observability flag, see Observability configuration. For the full upgrade procedure, see Single-server upgrade or Multi-server upgrade.

Detailed steps

1. Optionally pick a preset under Start from a preset. Presets mirror the single-server and multi-server installation guides, common observability scenarios, and the 1.20.0 upgrade paths. Hostnames and paths are examples to replace, and passwords are left for you to fill in.
2. Select Script: install.sh for a new host, upgrade.sh for an existing install.
3. Select Role. Single-server deployments use all. Multi-server deployments run the wizard once per role.
4. Select the flags you need in each group and fill in their values. Groups that do not apply to the selected role are hidden. Select Show flags for every role to list them anyway.
5. Read the Fix before running and Review before running boxes. The first lists flags the selected role requires, marked required in the flag list, and combinations the installer rejects or that cancel each other out, such as --skip-otel together with any observability flag. The second lists choices that lose data or leave a node misconfigured, such as an upgrade of the database role without --backup-logs-file.
6. Copy the generated command and run it from the directory that holds kasm_release/.

Start from a presetBlank commandSingle server, standardSingle server, offline (air-gapped)Single server, custom port and certificateDatabase roleDedicated ClickHouse roleWeb App roleDocker Agent roleConnection Proxy roleDedicated Kasm Proxy roleStandalone PostgreSQL initializationYour own OTel Collector, no local ClickHouseExternal managed ClickHouse, tenant databaseForward telemetry to a SIEM or Grafana CloudRemote node with verified collector TLSObservability disabledSingle server upgrade with logs table backupDatabase role upgrade with logs table backupChange ClickHouse retentionEnable observability on an opted-out agentTurn on verified collector TLS on a proxy

Scriptinstall.sh (new install)upgrade.sh (upgrade an existing install)

Roleall (single server)app (Web App)db (Database)init_remote_db (standalone PostgreSQL)agent (Docker Agent)guac (Connection Proxy)proxy (Dedicated Kasm Proxy)clickhouse (dedicated ClickHouse)

OptionsShow flags for every roleOne line, no line continuations

Generated install.sh command

sudo bash kasm_release/install.sh

General14 flags

--accept-eula-e

Accept the End User License Agreement without prompting.

--verbose-v

Verbose output.

--install-profile-V

Installation profile from kasm_release/profiles: noninteractive or hardened.

--proxy-port-L

Port the proxy listens on. The default is 443.

--admin-password-P

Initial admin@kasm.local password.

--user-password-U

Initial user@kasm.local password.

--activation-key-file-a

License activation key file to apply during install.

--server-zone-z

Zone name this server belongs to.

--agent-registration-hostname-m

Hostname or IP of the Web App that agents register with and send heartbeats to. On the agent role this is the Web App the agent joins.

--no-start-D

Do not start services when the install finishes.

--ssl-public-cert

Copy this public SSL certificate into place during install.

--ssl-private-key

Copy this private SSL key into place during install.

--default-registry-url-y

Default Workspaces Registry URL.

--guac-cluster-size

Connection Proxy cluster size. 0 selects automatic sizing.

Database5 flags

--db-password-Q

Password of the Kasm database user.

--database-user-c

Kasm database user name.

--database-name-j

Kasm database name.

--no-db-ssl-t

Disable SSL on the database connection.

--no-db-init-d

Skip database initialization.

Offline install5 flags

--offline-service-s

Path to the service images offline tar.gz.

--offline-workspaces-w

Path to the workspace images offline tar.gz.

--offline-network-plugin-x

Path to the network plugin images offline tar.gz.

--offline-logger-plugin

Path to the logger plugin images offline tar.gz.

--install-depends

Force dependency installation even during an offline install.

Images6 flags

--default-images-W

Seed and download the default Workspaces images.

--use-static-images-f

Use static, version-pinned service images. Recommended for new installs and initial-build upgrades.

--use-rolling-images-O

Use rolling service images.

--use-tag-F

Specific tag for service images. Defaults to the build date.

--enable-lossless-A

Enable the lossless streaming option.

--skip-v4l2loopback-X

Skip v4l2loopback installation (webcam passthrough).

Observability6 flags

--skip-otel

Do not install the OTel Collector or ClickHouse. Sticky across upgrades until --enable-otel is passed.

--otel-token

Bearer token for inter-collector authentication. Generated on the app or all node when omitted, and required on every remote node.

--otel-collector-endpoint

Use a custom OTLP collector instead of the bundled one.

--otel-forward-endpoint

Forward all telemetry to this OTLP/HTTP endpoint in parallel.

--otel-forward-token

Bearer token for the forward endpoint.

--otel-trace-sample-percentage

Percent of non-error, non-slow traces kept. The default is 10.

ClickHouse8 flags

--no-clickhouse

Do not install the bundled ClickHouse and configure no external replacement. Telemetry is not stored.

--clickhouse-endpoint

Native-interface DSN of a dedicated or external ClickHouse for the collector.

--clickhouse-http-endpoint

HTTPS URL of the same ClickHouse for Kasm UI reports and logs. Required together with --clickhouse-endpoint.

--clickhouse-database

ClickHouse database name. The default is kasm_otel.

--clickhouse-username

Writer user name. The default is kasm_otel.

--clickhouse-password

Writer password. Sets the server password on the clickhouse role and the connect password on app.

--clickhouse-reader-username

Read-only user name the API uses for reports and logs. The default is kasm_otel_ro.

--clickhouse-reader-password

Read-only password. Sets the server password on the clickhouse role and the connect password on app.

Retention4 flags

--otel-logs-retention-days

General log retention in days. The default is 30.

--otel-audit-logs-retention-days

Audit log retention in days. The default is 365.

--otel-traces-retention-days

Trace retention in days. The default is 7.

--otel-metrics-retention-days

Metrics retention in days. The default is 90.

Checks and dependencies9 flags

--skip-connection-test-N

Skip the database, API, OTel Collector, and ClickHouse connectivity checks.

--no-check-ports-B

Do not check for open ports.

--no-check-disk-b

Do not check disk space.

--no-swap-check-H

Disable the swapfile check.

--swap-size-J

Create a swapfile of this many megabytes when none exists.

--skip-egress

Do not install the egress network plugin or its dependencies.

--skip-custom-rclone

Install the stock Rclone plugin without modification.

--enable-epel

Enable the EPEL repository for packages missing from the default RHEL repositories.

--ignore-dep-failures

Continue when optional dependencies fail to install.