Skip to main content
Version: Developer

Slip-Stream Install Configurations

Overview​

Repeatable deployments need every installed instance to start from the same known configuration. This guide preloads a Kasm Workspaces install with a saved configuration by swapping the default_properties.yaml file in the installation package before install.sh runs. The approach suits CI/CD pipelines, Terraform projects, and other programmatically deployed environments. As a result, partners and system integrators provision consistent, version-controlled deployments without configuring each system by hand.

The default_properties.yaml file uses the same format as a file produced by the Exporting System Configurations mechanism. Administrators can therefore restore the configuration of an existing deployment onto another system.

warning

This feature is intended for partners and system integrators with advanced experience using Kasm Workspaces. Kasm Workspaces contains thousands of interconnected configuration items. Many of these items are internal-facing and are not fully documented. For important implementation concerns, see Configuration Schema Versioning and Details.

Prerequisites​

Before you begin, confirm the following:

  • Access to a target host where you can extract the installation package and run install.sh with sudo.
  • A default_properties.yaml file that defines the configuration to preload. To produce one, follow Exporting System Configurations.
  • A review of the implementation concerns in Configuration Schema Versioning and Details.
  • The release version and storage URL for the Kasm Workspaces installation package.

Solution approach​

This guide progresses through the following phases:

  1. Prepare the installation package and custom configuration.
  2. Swap the default configuration and run the installer.
  3. Template values for repeatable deployments.

Detailed steps​

Prepare the installation package and custom configuration​

  1. Sign in to the target host with an account that can run commands as root.
  2. Produce or locate the default_properties.yaml file that defines your desired configuration. Inspect the default_properties.yaml file shipped in the install package for example usage. That file represents the standard configuration for a default install.

Swap the default configuration and run the installer​

Download and extract the installation package, replace the bundled default_properties.yaml with your custom file, then run the installer. The following commands perform each step in order.

cd /tmp
curl -O https://kasm-static-content.s3.amazonaws.com/kasm_release_1.19.0.tar.gz
tar -xf kasm_release_1.19.0.tar.gz
# Replace default_properties.yaml
cp <custom_config.yaml>  kasm_release/conf/database/seed_data/default_properties.yaml
sudo bash kasm_release/install.sh

The installer ingests the new default_properties.yaml and applies your configuration as it builds the deployment.

Template values for repeatable deployments​

Before the installer ingests default_properties.yaml, it pre-processes the file. Pre-processing replaces special variables with generated values. Templating helps when you construct references between objects through UUIDs, or randomize values that should differ between deployments. The following sections describe each variable type and show a templated config alongside the resultant config.

UUIDs

Template a UUID with the string ${uuid:<some string>}, for example ${uuid:example1}. When the same variable appears multiple times in the YAML, Kasm replaces every occurrence with the same UUID.

Templated Config 
group_settings:
  - description: Allows users to see and edit all attributes of the Kasm application.
    group_id: "${uuid:group:1}"
    group_setting_id: "${uuid:group_setting_id:1}"
    name: administrator
    value: 'False'
    value_type: bool
  - description: Allow audio streaming for a Kasm.
    group_id: "${uuid:group:1}"
    group_setting_id: "${uuid:group_setting_id:2}"
    name: allow_kasm_audio
    value: 'False'
    value_type: bool
groups:
  - description: null
    group_id:  "${uuid:group:1}"
    is_system: false
    name: Internal Administrators
    priority: 1000
    program_data: null
Resultant Config
group_settings:
  - description: Allows users to see and edit all attributes of the Kasm application.
    group_id: "e2fd5c8e-82c2-4841-8ef0-824e30f16055"
    group_setting_id: "e7173013-fad7-4de8-860b-94ee5a70dcbf"
    name: administrator
    value: 'False'
    value_type: bool
  - description: Allow audio streaming for a Kasm.
    group_id: "e2fd5c8e-82c2-4841-8ef0-824e30f16055"
    group_setting_id: "b1c4efbe-ddc4-4ebc-839b-483b2e190873"
    name: allow_kasm_audio
    value: 'False'
    value_type: bool
groups:
  - description: null
    group_id:  "e2fd5c8e-82c2-4841-8ef0-824e30f16055"
    is_system: false
    name: Internal Administrators
    priority: 1000
    program_data: null
DateTime

Generate a datetime object for the current time with the ${datetime:utcnow} variable.

Templated Config

users:
  - created: '${datetime:utcnow}'
    password_set_date: '${datetime:utcnow}'
    pw_hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    realm: local
    salt: 6614c4ba-6c49-4f50-8d9a-ce82de5ac852
    user_id: 11bf8e0a-e08c-4c1b-81ad-518447d75b49
    username: admin@kasm.local
Resultant Config
users:
  - created: '2023-02-05 02:41:43.729155'
    password_set_date: '2023-02-05 02:41:43.729155'
    pw_hash: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    realm: local
    salt: 6614c4ba-6c49-4f50-8d9a-ce82de5ac852
    user_id: 11bf8e0a-e08c-4c1b-81ad-518447d75b49
    username: admin@kasm.local
Random Tokens

Generate a random string token with the ${random_token:<some string>} variable, for example ${random_token:manager_token}.

Templated Config
settings:
  - category: manager
    description: An authentication token used in the communication between Kasm Agents and the Manager API server.
    name: token
    sanitize: false
    services_restart: manager
    title: Token
    value: "${random_token:manager_token}"
    value_type: password
Resultant Config
settings:
  - category: manager
    description: An authentication token used in the communication between Kasm Agents and the Manager API server.
    name: token
    sanitize: false
    services_restart: manager
    title: Token
    value: "2RZGPY1LUPOph4fmU1kU"
    value_type: password
RSA Keys

Generate RSA public and private keys with the variables ${rsa:<some string>:private} and ${rsa:<some string>:public}.

Templated Config
settings:
  - category: auth
    description: Private Key used to sign request between Kasm components.
    name: api_private_key
    sanitize: true
    services_restart: null
    title: API Private Key
    value: "${rsa:1:private}"
    value_type: multiline_string
  - category: auth
    description: Public key used by Kasm components to validate internal API calls.
    name: api_public_cert
    sanitize: false
    services_restart: null
    title: API Public Cert
    value: "${rsa:1:public}"
    value_type: multiline_string
Resultant Config
settings:
  - category: auth
    description: Private Key used to sign request between Kasm components.
    name: api_private_key
    sanitize: true
    services_restart: null
    title: API Private Key
    value: "-----BEGIN PRIVATE KEY-----
        MIIJRAIBADANBgkqhkiG9w0BAQEFAASCCS4wggkqAgEAAoICAQDPS/VMFDiHcmYc
        ...
        F0QQggEL0azu+RPZkg2KV2ZqawkFbGeGdhnPbluvmFUZHS0qzs1xbefludeVe9aR
        568UxTAiTOowDRY45zwugW52VdBFASdc3w6z/DzPgD2FfI46ZQPzJD4ariJOMlSY
        ZszdhrNDulOoIsp0Adm/nKtXrT8JJca5
        -----END PRIVATE KEY-----"
    value_type: multiline_string
  - category: auth
    description: Public key used by Kasm components to validate internal API calls.
    name: api_public_cert
    sanitize: false
    services_restart: null
    title: API Public Cert
    value: "-----BEGIN PUBLIC KEY-----
        MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEAoQu+DCpu6IMVRJBlrxn5
        /SLIzggFi72fkLTuXTi7gGPCtGMV/5QLJnRjcAAYo9zJoFhob268qcK69FMRD3B
        nJ//C3zSW5pWvzh5HdRINrjmdZKgCpudEeXYpd/KpIulHzoWLJuiizEM/jlFpJcB
        ...
        89c22kgSOtyQGFJXQLQeFIqyak3fQ2guJ/ZbdJP6CeNJfjLdKFm9RE4bHuuqr2Bt
        /deSoQfXUXUUZbWf40jqprYTIuaidwBHus8KirY5LAxlDz9RVHvGQHrYq3hRMHcD
        XLnh226+sKxRSxxdXLwFLyMCAwEAAQ==
        -----END PUBLIC KEY-----"
    value_type: multiline_string

Common troubleshooting steps​

  • The installer applies the default configuration instead of yours. Confirm that you copied the custom file to kasm_release/conf/database/seed_data/default_properties.yaml before running install.sh. Verify the path matches the extracted package directory.
  • Templated variables remain literal in the running deployment. Pre-processing replaces variables only in default_properties.yaml. Confirm the variable syntax exactly, for example ${uuid:example1} or ${random_token:manager_token}.
  • References between objects do not link correctly. Pre-processing replaces every occurrence of the same UUID variable with one value. Confirm that related objects reference the identical variable string, such as ${uuid:group:1}.
  • The configuration fails to import on a different version. Schema differences between versions can break an import. Review Configuration Schema Versioning and Details and export from a matching version.