Skip to content

Installing CAS Manager - External Configuration

This section outlines how to install CAS Manager and to configure an external database and secret storage. If you have already installed CAS Manager with the default configuration you can skip this section.

With this configuration CAS Manager supports high availability and scaling beyond a single virtual machine.

Installation Time

Installing and configuring CAS Manager to run with an external database and secret storage should take roughly 2 hours to complete. It should take a further 1 hour to install the Connector.

Data Migration

CAS Manager does not do any data migration when configuring your database and secret storage application. Any data stored when CAS Manager is used with the default database and secret storage configuration, will not be transferred if the same CAS Manager instance is re-configured to run with an external database and secret storage.

Preparing the CAS Manager Virtual Machine

The following section outlines how to prepare the system requirements, firewall configurations and proxy configurations on the CAS Manager virtual machine:

System Requirements

You need to prepare a virtual machine that has the following requirements:

  • Operating System: RHEL 8 and Rocky Linux 8.
  • Minimum 8 GB RAM
  • 4 CPU
  • 60 GB Storage: If you are using LVM and /var is mounted on a separate volume, that volume must have 30GB or more in order for the installation to succeed and for CAS Manager to function properly.

Firewall Configuration

You must ensure your firewall is established and configured properly. Ensure port 443 is enabled in the firewall rules for the VM that CAS Manager is running on.

Configure the firewall that the virtual network CAS Manager is running by following the commands below:

  1. Login to the CAS Manager VM by ssh from a bash shell as root.
  2. Check and confirm if firewalld is active by running the following command:
    sudo systemctl status firewalld
    
  3. If firewalld is active, follow the steps outlined below for firewall configuration. If firewalld is inactive, and your organization does not require firewall on the CAS Manager VM, then skip the firewall configuration steps below and proceed to the remaining steps.

  4. Run the following commands to configure the firewall:

sudo firewall-cmd --permanent --add-port=6443/tcp # virtual network flannel

sudo firewall-cmd --permanent --zone=trusted --add-source=10.42.0.0/16 # This subnet is for the pods

sudo firewall-cmd --permanent --zone=trusted --add-source=10.43.0.0/16 # This subnet is for the services

sudo firewall-cmd --reload

Proxy Configuration Variables

If HTTP/HTTPS proxy is used, then HTTP_PROXY, HTTPS_PROXY and NO_PROXY must be set. For NO_PROXY, specific IP addresses or domain names of service that are internal must be added. IP address ranges like "10.0.0.0/8" will not work; exact IP addresses or domain names must be used for NO_PROXY for the traffic to be routed through the proxy to work properly. The outlined variables need to be set in the /etc/environment file.

The following steps outline how to modify this file to add these variables:

  1. Run the following command to edit the /etc/environment/ file in vi. You could also use vim or nano:
    sudo vi /etc/environment
    
  2. Update the file to include the following environment variables.
    HTTPS_PROXY="http://hostname_of_proxy:port"
    HTTP_PROXY="http://hostname_of_proxy:port"
    NO_PROXY=[list of all host names that should not go through the proxy, such as: localhost, 127.0.0.1, 0.0.0.0, ip_address_of_mongo]
    ALL_PROXY="http://hostname_of_proxy:port"
    https_proxy="http://hostname_of_proxy:port"
    http_proxy="http://hostname_of_proxy:port"
    no_proxy==[list of all host names that should not go through the proxy, such as: localhost, 127.0.0.1, 0.0.0.0, ip_address_of_mongo]
    all_proxy="http://hostname_of_proxy:port"
    
  3. Save the file. Once you install CAS Manager you can configure it to use the proxy configuration. From this new terminal, proceed with the installation steps. The proxy configuration will be implemented when CAS Manager is installed.

Cloud Access Software Registration Code

Once you have a Cloud Access Software subscription Teradici will email a registration code to you. To contact sales and enquire about attaining a Cloud Access Software subscription, see Contact Sales.

By default, CAS Manager will install a database and secret storage on the same virtual machine. If you plan to use an external database and secret storage, which Teradici recommends for scaling, continue with the steps outlined below to prepare the external database and secret store.

Preparing an External Database and Secret Storage

The following sections outline how to prepare a secret storage application and MongoDB that can be configured to work with CAS Manager.

Verified Versions

The table below outlines the versions of MongoDB and Vault that are verified with CAS Manager:

CAS Manager Version Vault Version MongoDB Version
21.03 1.4.2 4.0.8
21.07 1.7.1 4.2.14
21.10 1.7.1 4.2.14

Preparing a Secret Storage Application

It is possible to use either Hashicorp Vault or Azure Key Vault, depending on your environment and needs, for secret and key encryption and storage with CAS Manager. Once you have successfully installed CAS Manager you will need to configure CAS Manager to use the defined secret store. Please be aware that you can only configure one secret storage option with CAS Manager.

The sections below outline the prerequisite steps required to prepare these secret stores:

You can't configure the secret storage application to work with CAS Manager until you have successfully installed CAS Manager. Please complete the installation and then perform the required configurations.

Preparing an External Database

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

Reference Instructions for MongoDB and Vault Configuration

For detailed deployment instructions on installing and configuring MongoDB and Vault in a single virtual machine to be used by CAS Manager, see the following KB article. This KB article outlines in detail how to install and configure an instance of MongoDB and an instance of Vault on the same virtual machine. This KB article should be used in conjunction with the installation steps outlined in this section.

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/.

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 up 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 above. Failure to do this will result in an unsuccessful installation of CAS Manager.

1. 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.

To access the scripts to configure and add the RHEL repository, select the Downloads and Scripts option here from the CAS Manager support site.

Rocky Linux Repository

To force the specific repository for Rocky Linux 8, run the following command:

curl -1sLf https://dl.teradici.com/<RepositoryAccessToken>/cas-manager/cfg/setup/bash.rpm.sh | sudo -E distro=el codename=8 bash

You can get the Repository Access Token by selecting the Downloads and Scripts option here from the CAS Manager support site. Copy the token in the download script and replace in the command above.

Run the following command to confirm teradici-cas-manager repos were added into yum repo.

yum repolist --enabled teradici-cas-manager*

The output from this command should list the repo id, names as outlined in the example below:

repo id                                             repo name
teradici-cas-manager-beta                           teradici-cas-manager-beta
teradici-cas-manager-beta-noarch                    teradici-cas-manager-beta-noarch
teradici-cas-manager-beta-source                    teradici-cas-manager-beta-source

2. 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. Run the following commands to install and SELinux:

  1. Run the following command to install the SELinux policies and set the basic framework for persistent database and Vault:
    sudo yum install -y selinux-policy-base container-selinux
    
  2. Run the following command to install a specific version of SELinux that has been tested for K3s:
    sudo yum install -y https://github.com/k3s-io/k3s-selinux/releases/download/v0.2.stable.1/k3s-selinux-0.2-1.el7_8.noarch.rpm
    
  3. Run the following command to install SELinux from the CAS Manager repo:
    sudo yum install -y cas-manager-selinux
    

3. 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

The installation process takes 5-10 minutes to complete, depending on your network connection speed and other environment variables. During this process, CAS Manager is running a health check every 15 seconds to confirm that all required services are deployed and running successfully before reporting that the installation is complete.

Once the installation has been successful you should see a message stating CAS Manager installation complete. The IP address of your CAS Manager instance will also be displayed. The CAS Manager version that has been installed will also be displayed.

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.

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.

Generated Self-Signed Certificates

The installer will automatically generate several certificates to ensure that internal communication within the CAS Manager and communication to the CAS Manager itself are done over encrypted TLS connections. These certificates will be automatically generated as needed when CAS Manager is initially installed or when upgrades are done. If for whatever reason you do not wish to upgrade, certificates will need to be periodically renewed, see TLS Certificates for steps on how to do this.

4. Configure CAS Manager to use Proxy

The following section outlines the steps involved in enabling the proxy configuration with CAS Manager:

  1. If the proxy environment variables were not set before installing CAS Manager, please see the Proxy Configuration Variables section above for the steps involved in setting these variables. If you already have these variables set, continue to step 2.
  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 configure -–enable-proxy

5. Configure CAS Manager to use a Secret Storage Application

Once you have successfully installed CAS Manager you must configure it to use the secret store you prepared in the prerequisite steps prior to installing CAS Manager. You need to have prepared the selected secret storage application before installing CAS Manager, as outlined in the Preparing a Secret Storage Application section above. For information on how to configure CAS Manager to work with these secret stores, see the following sections based on what type of secret storage you prepared:

6. Configure CAS Manager to use MongoDB

Once you have successfully installed CAS Manager you must configure it to use the external MongoDB you prepared in the prerequisite steps prior to installing CAS Manager.

The following section outlines how to configure 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 configure CAS Manager to use MongoDB:
    sudo /usr/local/bin/cas-manager configure --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 be configured to use this MongoDB. The configure 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

Configuration Templates

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

6.1 Connecting a MongoDB with Self-Signed TLS Certificates

CAS Manager allows for the option to provide a database connection string, a flag 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. This is only recommended during proof-of-concept testing. In this mode, TLS must be enabled and certificate validation must be carried out. A server certificate signed by a public Certificate Authority is also highly recommended.

Tested on CentOS Only

The following steps have been tested on CentOS. These steps may not work, or work differently, on different systems.

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:
    • "db-connection-string": Follow the same guidelines as mentioned above.
    • "db-ca-cert-file": 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.
  4. Run the following command to configure CAS Manager to use MongoDB:
    sudo /usr/local/bin/cas-manager configure --config-file path-to-your-config-file
    
  5. 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:
    {
        "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": true
    }
    

7. Accessing the Admin Console

The following section outlines how to access and unlock the CAS 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.The initial password can be found 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.

8. CAS Manager Yum Repo Management

By default, CAS Manager will install any updates that are available, when you update all managed packages with the following command:

yum upgrade

or

yum update

This system wide update will include any new CAS Manager version updates. If you do not want this system wide update, the CAS Manager repo(s) should be disabled once installation is complete. The following section outlines how to lock the CAS Manager in the Yum repo.

Locking CAS Manager version in the yum repo

The following command will lock the CAS Manager version in the yum repo:

sudo yum config-manager --set-disabled teradici-cas-manager*

You can confirm the settings by running the following command:

yum repolist teradici-cas-manager*

The output from this command should list the repo id, names and their status, as outlined in the example below:

repo id                                         repo name                                       status
teradici-cas-manager                            teradici-cas-manager                            disabled
teradici-cas-manager-noarch                     teradici-cas-manager-noarch                     disabled
teradici-cas-manager-source                     teradici-cas-manager-source                     disabled

Installing the Connector

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