Skip to content

Installing for Production

This section outlines how to install CAS Manager in production mode with an external MongoDB and custom Vault. This mode will enable you to re-install CAS Manager and retain your machine information and data.

In this installation mode, CAS Manager supports high availability and scaling beyond a single virtual machine, and is the recommended mode for production and live environments.

Production Mode Deployments

This mode is recommended if you are planning on using CAS Manager in a large scale infrastructure. It should take roughly 2 hours to complete the installation in this mode, and a further 1 hour to install the Cloud Access Connector.

Prerequisite Configurations

To deploy a CAS Manager in Production mode, please follow the steps listed in this section.

Risk of Data Loss

CAS Manager does not do any data migration when updating Vault/MongoDB configuration. Any data stored when CAS Manager is used in Testing mode will not be transferred if the same CAS Manager instance is updated to run in Production mode.

System Requirements and Prerequisite Steps

Before installing CAS Manager please ensure you have read through the system requirements, and configured the necessary prerequisites outlined in the sections below. Failure to do this will result in an unsuccessful installation of CAS Manager.

The following sections outline the process from start to finish, to install CAS Manager in Production Mode. It includes all prerequisite steps.

1. System Requirements

For information on the minimum system requirements for installing CAS Manager in Production mode, see System Requirements.

2. Preparing a Vault Server

The following section outlines how to prepare Vault to be used as a secret manager for CAS Manager.

Reference Steps Only

All configuration steps outlined should be used as a reference only. For specific details, visit the vendor's official documentation and knowledge base.

Configuration Templates

Teradici provides configuration template files and parameters that can be generated and used when configuring your Vault server, see Configuration Templates.

Deploying Vault using Consul

For information on setting up a Vault server using Consul as a storage backend, see HashiCorp's official deployment guide see Vault using Consul. This guide demonstrates how to deploy a Vault in a high availability mode.

HashiCorp's recommendations for a production level deployment of Vault can be found here Production Level Deployment.

Deploying Vault with Integrated Storage (Raft)

HashiCorp's official deployment guide for setting up a Vault server using Integrated Storage (Raft) as a storage backend can be found here Vault with Raft Storage.

2.1 Preparing Vault to be used by CAS Manager

The following steps outline how to prepare Vault to be used by CAS Manager:

  1. Initialize the Vault. For information on initializing the Vault, see Initializing the Vault.
  2. Unseal the Vault. For information on sealing and unsealing the Vault, see Seal/Unseal.
  3. Enable the secrets path expected by CAS Manager by running the following command:
    vault login
    vault secrets enable -path=secret/ kv
    
  4. Create a Vault policy called "casm-policy":
    vault policy write casm-policy - << EOF
    path "secret/data/*" {
      capabilities = ["create", "update", "read", "delete", "list"]
    }
    EOF
    
    The output for this command should be:
    Success! Uploaded policy: casm-policy
    
    You can validate the policy by running the following command:
    vault policy read casm-policy
    
  5. Create a role to be used by CAS Manager by running the following command:
    vault write auth/token/roles/casm-role allowed_policies="casm-policy" period="768h"
    
    This command will create a token role with the casm policy created above. Any token created using this role will be valid for 32 days, if not renewed. If the token is renewed, then its validation period will be reset back to 32 days. This period should be set in accordance with your security guidelines and should be configured to be as low as possible. The output of this command should be:
    Success! Data written to: auth/token/roles/casm-role
    
  6. Create a periodic token to be used by CAS Manager by running the following command:
    vault token create -role=casm-role -orphan
    
    This command will create a periodic token which are useful when the token in question is intended to be used by a long-running process or application. For more information on creating Vault tokens, see Vault Tokens. The output of this command should be:
    Key                  Value
    ---                  -----
    token                <your token is here>
    token_accessor       <your token accessor is here>
    token_duration       768h
    token_renewable      true
    token_policies       ["casm" "default"]
    identity_policies    []
    policies             ["casm" "default"]
    

3. Preparing MongoDB

The following section provides guidelines and best practices involved when preparing and deploying a production MongoDB solution with CAS Manager.

Reference Steps Only

All configuration steps outlined should be used as a reference only. For specific details, visit the vendor's official documentation and knowledge base. For information on the main reference list for MongoDB, see https://docs.mongodb.com/manual/administration/.

Configuration Templates

Teradici provides configuration template files and parameters that can be generated and used when configuring your MongoDB, see Configuration Templates.

Guidelines and Best Practices

The following are some of the guidelines and best practices that Teradici encourages when deploying a MongoDB to work with CAS Manager:

  • Ensure the machine is deployed in a secure subnet with no public facing access.
  • Ensure that the host firewalls are leveraged to control inbound and outbound traffic.
  • MongoDB only needs to be accessible to the CAS Manager and to administrators so it is better to be overly restrictive when granting access, and follow the rules of granting least privilege access.
  • CAS Manager cannot connect to an external MongoDB from behind a proxy.
  • Remote desktop or SSH access to the system should be disallowed altogether if possible - realistically this is highly unlikely - or heavily restricted to essential users only, with a security-conscious configuration (e.g. add certificates for RDP, use passphrase-protected SSH keys and disallow password based authentication, change default SSH port, etc).
  • Keep the host OS patched and update to date to ensure security fixes are deployed.
  • It is best to use the latest stable version of MongoDB to ensure there are as few vulnerabilities, bugs, and issues as possible.
  • It is best to maintain a regular update cadence for both MongoDB and the host machine in order to maintain latest security fixes.
  • It is best to run MongoDB on a Long Term Support variant of Linux (ex, RHEL x86_64 or Ubuntu x86_64) VM.
  • In order to maintain data integrity, it is best to run Mongo with Journaling enabled (enabled by default) in a geographically distributed replica set.
  • Regular backups are also important to ensure CAS Manager can be restored in case of a crash. To keep MongoDB secure, it is important to create the appropriate admin accounts for granting access and ensuring that all communication is done over a secured TLS connect. Details for creating an appropriate service account can be found in the official MongoDB documentaton, as well as:

Installing CAS Manager

The following section outlines how to install CAS Manager. These steps should be performed on the target machine by connecting via SSH or console.

System Requirements and Prerequisite Steps

Before installing CAS Manager please ensure you have read through the system requirements, and configured the necessary prerequisites outlined in the sections above. Failure to do this will result in an unsuccessful installation of CAS Manager.

4. Add CAS Manager Repository

The virtual machine you are adding the repo to must have access to the internet. If it doesn't, you will be unable to download and install the required files.

Run the following command to add the CAS Manager repository:

curl -1sLf \
  'https://dl.teradici.com/502R0tFrirxlgmRy/cas-manager/setup.rpm.sh' \
  | sudo -E distro=el codename=7 bash

5. SELinux Configuration

SELinux policies are required for persistent storage and container logging on CAS Manager. If SELinux policies are not found, data stored in CAS Manager will be lost when the CAS Manager Machine is shut down.

Once configured, and the installation has verified SELinux, all CAS Manager related data will persist when the target machine hosting CAS Manager is re-booted.

  1. To install the SELinux policies and set the basic framework for persistent database and Vault, run the following command:

    sudo yum install -y selinux-policy-base container-selinux
    
  2. To install a specific version of SELinux that has been tested for K3s, run the following command:

    sudo yum install https://github.com/k3s-io/k3s-selinux/releases/download/v0.2.stable.1/k3s-selinux-0.2-1.el7_8.noarch.rpm
    
  3. To install CAS Manager SELinux from the CAS Manager repo, run the following command:

    sudo yum install -y cas-manager-selinux
    

Non-Persistent Storage

If persistent storage is not required, set SELinux to permissive by running setenforce 0 with sudo / as root before beginning the install.

6. Install CAS Manager

Run the following command to install CAS Manager:

sudo yum install -y cas-manager
The installer will install CAS Manager, as well as all external components required. These external components are:

  • k3s
  • A self-signed SSL certificate for HTTPS access

Installer Health Check

Towards the end of the installation, the installer will check the CAS Manager's health status. This health check is part of the installation process. This health check takes about 15 minutes to complete.

If the installation appears unhealthy you should generate a support bundle and send this to Teradici for investigation. For more information on generating a support bundle, see Support Bundle. For more information on monitoring and assessing the health status of CAS Manager, see Health Status.

Once the installation has been successful you should see the following message: Alt Text

Generated Credentials

The installer will automatically generate a password. This password is important as it will be required when accessing the Admin Console. This password can be found in the temp-creds.txt file which is located at /opt/teradici/casm/temp-creds.txt. This location will be displayed in the CLI window once the the installation has been successful, as seen in the image above.

7. Proxy Configuration

If the proxy environment variables were not set before installing CAS Manager, please see the System Requirements section for the steps involved in setting these variables. If you have already set your proxy configuration prior to installing CAS Manager, you do not need to run the command below.

If you have installed CAS Manager and have not configured the environment variables for the proxy, follow the steps below:

  1. From the CAS Manager virtual machine set the environment variables HTTPS_PROXY, HTTP_PROXY, ALL_PROXY and NO_PROXY in the /etc/environment file.
  2. Establish a new ssh/shell session.
  3. Configure CAS Manager to use the proxy configuration by running the following command:
    sudo /usr/local/bin/cas-manager update -–enable-proxy
    

Vault Server Configuration

The following section outlines how to update CAS Manager to use the Vault server you prepared in the steps above.

8. Updating CAS Manager to use Vault

The following steps outline how to update CAS Manager to use Vault:

  1. SSH to the target machine where you installed CAS Manager.
  2. Create a file that contains the following data:
    {
            "vault-type": "vault",
            "vault-url": "https://<vault_address>",
            "vault-token": "<vault_token>",
            "vault-skip-verify-cert": false,
            "vault-secret-path": "secret/data"
    }
    
  3. Replace the following place holders with your own values:
    • vault_address: IP address or domain name of the Vault server.
    • vault_token: The access token generated on the Vault server that will be used by CAS Manager to access the Vault.
  4. Run the following command to update CAS Manager to use Vault:
    sudo /usr/local/bin/cas-manager update --config-file path-to-your-config-file
    
    After running this command, CAS Manager will validate the configuration by attempting to query the Vault's health status. If the request is successful, then CAS Manager will update to use this Vault configuration. The update command should only take a few minutes to complete. To verify that the connection to the Vault is healthy, run the following command:
sudo /usr/local/bin/cas-manager diagnose --health

[2021-01-25T22:49:02Z]  INFO .. Connections:
[2021-01-25T22:49:02Z]  INFO .... Vault=Healthy

[2021-01-26T01:47:10Z]  INFO .. Connections:
[2021-01-26T01:47:10Z] ERROR .... Vault=Vault service is unreachable
[2021-01-26T01:47:10Z] ERROR .. Overall Health=CAS Manager is in Unhealthy state because Vault is unhealthy

8.1 Connecting a Vault server with Self-Signed TLS Certificates

The following steps outline how to connect a Vault server that uses self-signed TLS certificates:

  1. Create a file called vault-config.json that contains the following:
    {
            "vault-type": "vault",
            "vault-url": "https://<vault_address>",
            "vault-token": "<vault_token>",
            "vault-ca-cert-file": "<vault_ca_cert_file>",
            "vault-skip-verify-cert": false,
            "vault-secret-path": "secret/data"
    }
    
  2. Replace the following place holders with your own values:
    • vault_address (string): IP address or domain name of the Vault server.
    • vault_token (string): The access token generated on the Vault server that will be used by CAS Manager to access the Vault.
    • vault_ca_cert_file (string): The path to the file containing the CA certificate for your self-signed certificate.
  3. Run the following command to update CAS Manager to use Vault:
    sudo /usr/local/bin/cas-manager update --config-file path-to-your-config-file
    
  4. If you want to skip certificate verification, include "vault-skip-verify-cert":true in your configuration file. Please note that this is not secure and is not recommended for production use cases.

Vault Token Auto-Renewal

CAS Manager does not renew the Vault token automatically. It is the admin's responsibility to keep the Vault token alive. To enable auto-renewal on a renewable Vault token, create an automated process by running the following commands:

  1. Set the following shell variables:
    VAULT_ADDR="https://<your vault url>"
    VAULT_CACERT="<path to ca cert file, if necessary>"
    VAULT_TOKEN="<your vault token>"
    
  2. Run the following command to enable the token to renew itself:
    curl \
      --request POST \
      --header "X-Vault-Token: $VAULT_TOKEN" \
      --cacert $VAULT_CACERT \
      $VAULT_ADDR/v1/auth/token/renew-self
    

In the above example, we created a an automated process that triggers the Vault token to renew itself. This process can be installed on any Linux machine that can reach the Vault server. If installed on the CAS Manager VM, the process will stop automatically renewing the token if the CAS Manager VM is retired. This is useful in production to make sure that the token is only alive as long as it is needed.

More information on renewing Vault tokens see Vault Token Renewal.

Vault Data Migration

CAS Manager does not do any data migration between different Vault configurations. If CAS Manager is updated to use a new Vault configuration, it will no longer be able to access the data from the previous configuration. If the admin user's password had been updated using a prior Vault configuration, you will no longer be able to login. To fix this, do one of the following:

  • If you have access to the old Vault, migrate the data from the old Vault to the new Vault.
  • Find the key that CAS Manager is using to look for the admin password in the Vault and then manually store the password in the Vault at that location. To find the key, stream the logs for the secretmgmt service by running the following command:
    /usr/local/bin/kubectl logs -l app=secretmgmt -f
    
    Log in to CAS Manager using the adminUser account and look for the log that includes the route /internal/secrets/admin-XXX. The password is expected to be at <secret path>/admin-XXX in the Vault, where secret path is the path defined by "vault-secret-path" in your CAS Manager config-file.
  • Update to use a new MongoDB, or drop the standaloneAdmins collection in your MongoDB. WARNING: this will cause you to lose all of your CAS Manager data.

MongoDB Configuration

The following section outlines how to configure CAS Manager to use the MongoDB you prepared in the steps above.

9. Updating CAS Manager to use MongoDB

The following section outlines how to update CAS Manager to use MongoDB:

  1. SSH to your target machine where you installed CAS Manager.
  2. Create a file that contains the following data:

    {
      "db-connection-string": "mongodb://<username>:<password>@<address>/<db_name>",
      "db-enable-tls": true,
      "db-skip-verify-cert": false
    }
    

    URL Encoding

    If the username or password contain any of the following special characters: /, ?, #, [], @, %, those characters must be converted using URL encoding in the MongoDB connection string. For example, if you defined user 'casmuser' with password 'Password%' in MongoDB, then in CAS Manager the db-connection-string for MongoDB would look like this:

    mongodb://casmuser:Password%25@ip_of_mongodb:27017/name_of_mongodb
    
    If you require more characters to be encoded, or want to test encoding or decoding your data, see https://www.urlencoder.org/.

  3. Replace the following place holders with your own values:

    • username: Username of the MongoDB user that CAS Manager will authenticate MongoDB requests.
    • password: Password for the MongoDB user referenced in "username".
    • address: Address to the MongoDB server.
    • db_name: Name of the MongoDB database that CAS Manager will use. Note that if no db name is specified, the db named "test" will be used.
  4. Run the following command to update CAS Manager to use MongoDB:
    sudo /usr/local/bin/cas-manager update --config-file path-to-your-config-file
    

"MongoDB Database Name

If no database name is provided as part of the connection string, a default name "test" will be used instead, for example:

db-connection-string:"mongodb://user:pass@mongo:27017/ will result in the creation of a database with the name "test".

If you provided a database name then that will be used, for example:

db-connection-string:"mongodb://user:pass@mongo:27017/casm_db will result in "casm_db" being used as the name.

After running this command, CAS Manager will validate the configuration by attempting to query the MongoDB server. If the request is successful, then CAS Manager will update to use this MongoDB configuration. The update command should only take a few minutes to complete.

Here's an example of creating a user for the CAS Manager Database "casm""

use casm_db
db.createUser(
  {
    user: "casmanager",
    pwd: passwordPrompt(), // or cleartext password
    roles: [ {db: "casm_db", role:"readWrite"} ], // user only needs readWrite Access to casm DB,
    authenticationRestrictions: [
        {
          clientSource: [
            "<CASM-IP>", // IP address of the CASM Host
            "10.42.0.0/24" // Subnet for the CASM pods
          ],
          serverAddress: ["<MongoDB IP>"] // IP for the MongoDB server
        }
     ],
  }
)

The connection string for this user would be:

mongodb://casmanager:<password>@<MongoDB IP>/casm_db

  • CAS Manager allows for the option to provide a database connection string, a flags to enable/disable TLS , a flag to enabled/disable TLS cert validation, and also provide a custom Certificate Authority certificate for the MongoDB Server certificate, but this is only recommend during proof-of-concept testing. In production, TLS must be enabled and certificate validation must be carried out. A server certificate signed by a public Certificate Authority is also highly recommended.

9.1 Connecting a MongoDB with Self-Signed TLS Certificates

CAS Manager allows for the option to provide a database connection string, a flags to enable/disable TLS , a flag to enabled/disable TLS cert validation, and also provide a custom Certificate Authority certificate for the MongoDB Server certificate, but this is only recommend during proof-of-concept testing. In production, TLS must be enabled and cert validation must be done. A server certificate signed by a public Certificate Authority is also highly recommended.

The following steps outline how to connect a MongoDB that uses self-signed TLS certificates:

  1. SSH to your target machine where you installed CAS Manager.
  2. Create a file that contains the following data:
    {
        "db-connection-string": "mongodb://<username>:<password>@<address>/<db_name>",
        "db-enable-tls": true,
        "db-ca-cert-file": "/path/to/mongo/TLS/custom/certificate/authority",
        "db-skip-verify-cert": false
    }
    
  3. Replace the following place holders with your own values:
  4. "db-connection-string" (string): Follow the same guidelines as mentioned above.
  5. "db-ca-cert-file" (string): Path to MongoDB's custom Certificate Authority's public certificate, in PEM format, if one is used. This is only required to validate self-signed certificates or certificates signed by a non-public Certificate Authority.
  6. Run the following command to update CAS Manager to use MongoDB:
    sudo /usr/local/bin/cas-manager update --config-file path-to-your-config-file
    
  7. If you want to skip certificate verification, include "db-skip-verify-cert": true in your configuration file. Please note that this is not secure and is not recommended for production use cases.

10. Accessing the Admin Console

The following section outlines how to access and unlock the Admin Console.

  1. Open a web browser and go to https://{public-or-private-ip-address-of-cas-manager}. This is the external IP address of the target machine that CAS Manager has been installed on. You will be presented with the CAS Manager login page. Alt Text
  2. Use the following credentials to begin setting up the admin user:
    • username: adminUser
    • password: The password generated by the installer. This password can be found in the temp-creds.txt file which is located at /opt/teradici/casm/temp-creds.txt. You can run the following command to view the password:
      sudo cat /opt/teradici/casm/temp-creds.txt
      
  3. Upon successful login, you will be required to immediately change this password. The new password will be stored in the Vault. Do not change the configuration to connect to a different Vault after resetting the password. Alt Text After updating the password you will be able to use CAS Manager as the adminUser user.

To unlock the Admin Console enter your Cloud Access Software registration code into the Unlock dialog that appears when you first log-in. CAS Manager will verify the registration code and then create a new deployment on your behalf. For further information on using the Admin Console, see Admin Console.

Installing the Cloud Access Connector

Once you have installed the CAS Manager you can install Cloud Access Connector(s) by following the instructions outlined in the Installing the Cloud Access Connector section.