Step 1: Prepare the NICE DCV servers
You must have a fleet of NICE DCV servers with which you intend to use Session Manager. For more information about installing NICE DCV servers, see Installing the NICE DCV server in the NICE DCV Administrator Guide.
On Linux NICE DCV servers, Session Manager uses a local service user named dcvsmagent. This user is automatically created when the Session Manager Agent is installed. You must grant this service user administrator privileges for NICE DCV so that it can perform actions on behalf of other users. To grant the Session Manager service user administrator privileges, do the following:
To add the local service user for Linux NICE DCV servers 1. Open /etc/dcv/dcv.conf using your preferred text editor.
2. Add the administrators parameter to the [security] section and specify the Session Manager user. For example:
[security]
administrators=["dcvsmagent"]
3. Save and close the file.
4. Stop and restart the NICE DCV server.
Session Manager is only able to create NICE DCV sessions on behalf of users that already exist on the NICE DCV server. If a request is made to create a session for a user that doesn't exist, the request fails.
Therefore, you must ensure that each intended end user has a valid system user on the NICE DCV server.
Tip
If you intend to use multiple Broker hosts or NICE DCV servers with Agents, we recommend that you configure only one Broker and one NICE DCV server with an Agent by performing the following steps, creating Amazon Machine Images (AMI) of the hosts with the completed
Step 2: Set up the Broker
configurations, and then using the AMIs to launch the remaining Brokers and NICE DCV servers.
Alternatively, you can use AWS Systems Manager to run the commands on multiple instances remotely.
Step 2: Set up the NICE DCV Session Manager Broker
The Broker must be installed on a Linux host. For more information about the supported Linux distributions, see NICE DCV Session Manager requirements (p. 3). Install the Broker on a host that is separate from the Agent and the NICE DCV server host. The host can be installed on a different private network, but it must be able to connect to and communicate with the Agent.
To install and start the Broker
1. Connect to the host on which you intend to install the Broker.
2. The packages are digitally signed with a secure GPG signature. To allow the package manager to verify the package signature, you must import the NICE GPG key. Run the following command to import the NICE GPG key.
• Amazon Linux 2, RHEL 7.x, RHEL 8.x and CentOS 7.x and CentOS 8.x
$ sudo rpm --import https://d1uj6qtbmh3dt5.cloudfront.net/NICE-GPG-KEY
• Ubuntu 18.04 and Ubuntu 20.04
$ sudo apt-key add https://d1uj6qtbmh3dt5.cloudfront.net/NICE-GPG-KEY 3. Download the installation package.
• Amazon Linux 2, RHEL 7.x, and CentOS 7.x
$ wget https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerBrokers/nice-dcv-session-manager-broker-2022.0.341-1.el7.noarch.rpm
• RHEL 8.x and CentOS 8.x
$ wget https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerBrokers/nice-dcv-session-manager-broker-2022.0.341-1.el8.noarch.rpm
• Ubuntu 18.04
$ wget https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerBrokers/nice-dcv-session-manager-broker-2022.0.341-1_all.ubuntu1804.deb
• Ubuntu 20.04
$ wget https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerBrokers/nice-dcv-session-manager-broker-2022.0.341-1_all.ubuntu2004.deb
4. Install the package.
• Amazon Linux 2, RHEL 7.x, and CentOS 7.x
$ sudo yum install -y nice-dcv-session-manager-broker-2022.0.341-1.el7.noarch.rpm
Step 3: Set up the Agent
• RHEL 8.x and CentOS 8.x
$ sudo yum install -y nice-dcv-session-manager-broker-2022.0.341-1.el8.noarch.rpm
• Ubuntu 18.04
$ sudo apt install -y nice-dcv-session-manager-broker-2022.0.341-1_all.ubuntu1804.deb
• Ubuntu 20.04
$ sudo apt install -y nice-dcv-session-manager-broker-2022.0.341-1_all.ubuntu2004.deb 5. Check that the default Java environment version is 11
$ java -version
If not, you can explicitly set the Java home directory that the Broker will use to target the right Java version. This is done setting the parameter broker-java-home in the Broker configuration file. For more information, see Broker Configuration File.
6. Start the Broker service and ensure that it starts automatically every time the instance starts.
$ sudo systemctl start session-manager-broker && sudo systemctl enable dcv-session-manager-broker
7. Place a copy of the Broker's self-signed certificate in your user directory. You'll need it when you install the Agents in the next step.
sudo cp /var/lib/dcvsmbroker/security/dcvsmbroker_ca.pem $HOME
Step 3: Set up the NICE DCV Session Manager Agent
The Agent must be installed on all of the NICE DCV server hosts in the fleet. The Agent can be installed on both Windows and Linux servers. For more information about the supported operating systems, see NICE DCV Session Manager requirements (p. 3).
Prerequisites
The NICE DCV server must be installed on the host before installing the Agent.
Linux host Note
The Session Manager Agent is available for the following Linux distributions and architectures:
• Amazon Linux 2 (64-bit x86 and 64-bit ARM)
• RHEL 7.x and CentOS 7.x (64-bit x86 and 64-bit ARM)
• RHEL 8.x and CentOS 8.x (64-bit x86 and 64-bit ARM)
• Ubuntu 18.04 and Ubuntu 20.04 (64-bit x86 and 64-bit ARM)
• SUSE Linux Enterprise 12 and SUSE Linux Enterprise 15 (64-bit x86 only)
Step 3: Set up the Agent
The following instructions are for installing the Agent on 64-bit x86 hosts. To install the Agent on 64-bit ARM hosts, for Amazon Linux, RHEL, and Centos, replace x86_64 with aarch64, and for Ubuntu, replace amd64 with arm64.
To install the Agent on a Linux host
1. The packages are digitally signed with a secure GPG signature. To allow the package manager to verify the package signature, you must import the NICE GPG key. Run the following command to import the NICE GPG key.
• Amazon Linux 2, RHEL, CentOS, and SUSE Linux Enterprise
$ sudo rpm --import https://d1uj6qtbmh3dt5.cloudfront.net/NICE-GPG-KEY
• Ubuntu
$ wget https://d1uj6qtbmh3dt5.cloudfront.net/NICE-GPG-KEY
$ gpg --import NICE-GPG-KEY 2. Download the installation package.
• Amazon Linux 2, RHEL 7.x, and CentOS 7.x
$ wget https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerAgents/nice-dcv-session-manager-agent-2022.0.520-1.el7.x86_64.rpm
• RHEL 8.x and CentOS 8.x
$ wget https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerAgents/nice-dcv-session-manager-agent-2022.0.520-1.el8.x86_64.rpm
• Ubuntu 18.04
$ wget https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerAgents/nice-dcv-session-manager-agent_2022.0.520-1_amd64.ubuntu1804.deb
• Ubuntu 20.04
$ wget https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerAgents/nice-dcv-session-manager-agent_2022.0.520-1_amd64.ubuntu2004.deb
• SUSE Linux Enterprise 12
$ curl -O https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerAgents/nice-dcv-session-manager-agent-2022.0.520-1.sles12.x86_64.rpm
• SUSE Linux Enterprise 15
$ curl -O https://d1uj6qtbmh3dt5.cloudfront.net/2022.0/SessionManagerAgents/nice-dcv-session-manager-agent-2022.0.520-1.sles15.x86_64.rpm
3. Install the package.
• Amazon Linux 2, RHEL 7.x, and CentOS 7.x
$ sudo yum install -y nice-dcv-session-manager-agent-2022.0.520-1.el7.x86_64.rpm
Step 3: Set up the Agent
• RHEL 8.x and CentOS 8.x
$ sudo yum install -y nice-dcv-session-manager-agent-2022.0.520-1.el8.x86_64.rpm
• Ubuntu 18.04
$ sudo apt install ./nice-dcv-session-manager-agent_2022.0.520-1_amd64.ubuntu1804.deb
• Ubuntu 20.04
$ sudo apt install ./nice-dcv-session-manager-agent_2022.0.520-1_amd64.ubuntu2004.deb
• SUSE Linux Enterprise 12
$ sudo zypper install nice-dcv-session-manager-agent-2022.0.520-1.sles12.x86_64.rpm
• SUSE Linux Enterprise 15
$ sudo zypper install nice-dcv-session-manager-agent-2022.0.520-1.sles15.x86_64.rpm
4. Place a copy of the Broker's self-signed certificate (that you copied in the previous step) in the /etc/dcv-session-manager-agent/ directory on the Agent.
5. Open /etc/dcv-session-manager-agent/agent.conf using your preferred text editor and do the following.
• For broker_host, specify the DNS name of the host on which the Broker is installed.
Important
If the Broker is running on an Amazon EC2 instance, for broker_host you must specify the instance's private Ipv4 address.
• (Optional) For broker_port, specify the port over which to communicate with the Broker.
By default the Agent and the Broker communicate over port 8445. Only change this if you need to use a different port. If you do change it, ensure that the Broker is configured to use the same port.
• For ca_file, specify the full path the certificate file that you copied in the previous step. For example:
ca_file = '/etc/dcv-session-manager-agent/broker_cert.pem'
Alternatively, if you want to disable TLS verification, set tls_strict to false.
6. Save and close the file.
7. Run the following command to start the Agent.
$ sudo systemctl start dcv-session-manager-agent
Windows host
To install the Agent on a Windows host 1. Download the Agent installer.
2. Run the installer. On the Welcome screen, choose Next.
Step 4: Configure the NICE DCV server
3. On the EULA screen, carefully read the license agreement, and if you agree, select I accept the terms and choose Next.
4. To begin the installation, choose Install.
5. Place a copy of the Broker's self-signed certificate (that you copied in the previous step) in the C:\Program Files\NICE\DCVSessionManagerAgent\conf\ folder on the Agent.
6. Open C:\Program Files\NICE\DCVSessionManagerAgent\conf\agent.conf using your preferred text editor, and then do the following:
• For broker_host, specify the DNS name of the host on which the Broker is installed.
Important
If the Broker is running on an Amazon EC2 instance, for broker_host you must specify the instance's private IPv4 address.
• (Optional) For broker_port, specify the port over which to communicate with the Broker.
By default the Agent and the Broker communicate over port 8445. Only change this if you need to use a different port. If you do change it, ensure that the Broker is configured to use the same port.
• For ca_file, specify the full path the certificate file that you copied in the previous step. For example:
ca_file = 'C:\Program Files\NICE\DCVSessionManagerAgent\conf\broker_cert.pem' Alternatively, if you want to disable TLS verification, set tls_strict to false.
7. Save and close the file.
8. Stop and restart the Agent service for the changes to take effect. Run the following commands at the command prompt.
C:\> sc stop DcvSessionManagerAgentService C:\> sc start DcvSessionManagerAgentService
Step 4: Configure the NICE DCV server to use the Broker as the authentication server
Configure the NICE DCV server to use the Broker as the external authentication server for validating client connection tokens. You must also configure the NICE DCV server to trust the Broker's self-signed CA.
Linux NICE DCV server
To add the local service user for Linux NICE DCV servers 1. Open /etc/dcv/dcv.conf using your preferred text editor.
2. Add the ca-file and auth-token-verifier parameters to the [security] section.
For ca-file, specify the path to the Broker's self-signed CA that you copied to the host in the previous step.
For auth-token-verifier, specify the URL for the token verifier on the Broker in the following format:
https://broker_ip_or_dns:port/agent/validate-authentication-token. Specify the port used for Broker-Agent communication, which is
Step 5: Verify the installations
8445 by default. If you are running the Broker on an Amazon EC2 instance, you must use the private DNS or private IP address.
For example
[security]
ca-file="/etc/dcv-session-manager-agent/broker_cert.pem"
auth-token-verifier="https://my-sm-broker.com:8445/agent/validate-authentication-token"
3. Save and close the file.
4. Stop and restart the NICE DCV server. For more information, see Stopping the NICE DCV Server and Starting the NICE DCV Server in the NICE DCV Administrator Guide.
Windows NICE DCV server
On Windows NICE DCV servers
1. Open the Windows Registry Editor and navigate to the HKEY_USERS/S-1-5-18/Software/
GSettings/com/nicesoftware/dcv/security/ key.
2. Open the ca-file parameter. For Value data, specify the path to the Broker's self-signed CA that you copied to the host in the previous step.
Note
If the parameter does not exist, create a new string parameter and name it ca-file.
3. Open the auth-token-verifier parameter. For Value data, specify the URL for the token verifier on the Broker in the following format: https://broker_ip_or_dns:port/agent/
validate-authentication-token. Specify the port used for Broker-Agent communication, which is 8445 by default. If you are running the Broker on an Amazon EC2 instance, you must use the private DNS or private IP address.
Note
If the parameter does not exist, create a new string parameter and name it auth-token-verifier.
4. Choose OK and close the Windows Registry Editor.
5. Stop and restart the NICE DCV server. For more information, see Stopping the NICE DCV Server and Starting the NICE DCV Server in the NICE DCV Administrator Guide.
Step 5: Verify the installations
Topics
• Verify the Agent (p. 11)
• Verify the Broker (p. 12)
Verify the Agent
After you have installed the Broker and the Agent, make sure that the Agent is running and that it's able to connect to the Broker.
Linux Agent host
The command to run depends on the version.
Verify the Broker
• Since version 2022.0
From the Agent host, run the following command:
$ grep 'sessionsUpdateResponse' /var/log/dcv-session-manager-agent/agent.log | tail -1 | grep -o success
• Versions prior to 2022.0
From the Agent host, run the following command, and specify the current year, month, and day.
$ grep 'sessionsUpdateResponse' /var/log/dcv-session-manager-agent/agent.log.yyyy-mm-dd | tail -1 | grep -o success
For example
$ grep 'sessionsUpdateResponse' /var/log/dcv-session-manager-agent/agent.log.2020-11-19 | tail -1 | grep -o success
If the Agent is running and it's able to connect to the broker, the command should return success.
If the command returns different output, inspect the Agent log file for more information. The log files are located here: /var/log/dcv-session-manager-agent/.
Windows Agent host
Open the Agent log file, which is located in C:\ProgramData\NICE\DCVSessionManagerAgent\log.
If the log file includes a line similar to the one below, the Agent is running and it's able to connect to the Broker.
2020-11-02 12:38:03,996919 INFO ThreadId(05) dcvsessionmanageragent::agent:Processing broker message "{\n \"sessionsUpdateResponse\" : {\n \"requestId\" :
\"69c24a3f5f6d4f6f83ffbb9f7dc6a3f4\",\n \"result\" : {\n \"success\" : true\n }\n }\n}"
If your log file doesn’t have a similar line, inspect the log file for errors.
Verify the Broker
After you have installed the Broker and Agent, make sure that your Broker is running and that it's reachable from your users and front-end applications.
From a computer that should be able to reach the Broker, run the following command:
$ curl -X GET https://broker_host_ip:port/sessionConnectionData/aSession/aOwner --insecure
If the verification is successful, the Broker returns the following:
{ "error": "No authorization header"
}
Scaling Session Manager
Configuring NICE DCV Session Manager
This section explains how to perform advanced configuration for Session Manager.
Topics
• Scaling Session Manager (p. 13)
• Using tags to target NICE DCV servers (p. 17)
• Configuring an external authorization server (p. 18)
• Configuring broker persistence (p. 21)
• Integrating with the NICE DCV Connection Gateway (p. 23)
• Integrating with Amazon CloudWatch (p. 26)
Scaling Session Manager
To enable high availability and improve performance, you can configure Session Manager to use multiple Agents and Brokers. If you do intend to use multiple Agents and Brokers, we recommend that you install and configure only one Agent and Broker host, create Amazon Machines Images (AMI) from those hosts, and then launch the remaining hosts from the AMIs.
By default, Session Manager supports the use of multiple Agents without any additional configuration.
However, if you intend to use multiple Brokers, you must use a load balancer to balance the traffic between the frontend client and the Brokers, and between the Brokers and the Agents. Load balancer setup and configuration is entirely owned and managed by you.
The following section explains how to configure Session Manager to use multiple hosts with an Application Load Balancer.
Steps