- The difference between virtual and and console session types
- Dynamic Console Sessions
- Overview
- Linux
- Windows
- Connect to a specific DCV session
- Allow different users to connect into DCV
- Windows
- Dynamically set NICE DCV session permissions at logon
- Windows
- Create and test a dummy session
- Linux
- Console session without Physical Monitor
- Linux
- Idle timeout period
- Overview
- Linux server
- Windows server
- Web client
- Set the display layout for a running Session
- NICE DCV Gateway integrated with DCV SM
- Overview
- Configuring the DCV SM Broker
- Configuring the DCV Gateway
- Register the DCV Servers under DCV SM Broker
- DCV Session Manager CLI
The difference between virtual and and console session types
NICE DCV offer two types of sessions: console and virtual. Lets check all differences:
- OS support:
- Console: Linux and Windows NICE DCV servers
- Virtual: Just Linux
- Multiple sessions:
- Console: Just one
- Virtual: Multiple consoles
- Permissions:
- Console: Just privileged user (admin) can start and close
- Virtual: Any user can start and close
- Direct screen capture:
- Console: Yes
- Virtual: No
- GPU-accelerated OpenGL support:
- Console: Yes, without any extra package
- Virtual: Yes, but requires the DCV-GL package
Important notes:
- You can not run virtual and console types in the same NICE DCV server.
- Virtual consoles will run each one in a dedicated Xdcv display, but there are other resources that will share same configuration files, like: User’s home folder, D-Bus services, and devices connected in that user. So is expected that you run one virtual console per user, or you can get problems.
Dynamic Console Sessions
Overview
The standard approach for NICE DCV console sessions is to have a session created statically for a specific user. In some cases it is preferred to enable users to connect to NICE DCV and dynamically be able to use the DCV Console Session.
To implement this we automatically create a console sessions for a specific standard user and set the maximal number of connection to the DCV console session to 1 so no other user can connect and allow all users to connect to the session in the permissions file.
Below are the steps to enable Dynamic DCV Sessions on Windows and Linux NICE DCV Servers.
Linux
In /etc/dcv/dcv.conf
we apply the following settings:
# In /etc/dcv/dcv.conf in the session management section we apply the following settings
[session-management]
# Specify the maximum number of concurrent clients per session. Limit to 1 in this case.
max-concurrent-clients = 1
# Property "create-session" requests to automatically create a console session
# (with ID "console") at DCV startup.
create-session = true
[session-management/automatic-console-session]
# Property "owner" specifies the username of the owner of the automatically
# created "console" session. You can set this to a standard service user.
owner = "centos"
# owner = "ubuntu"
[connectivity]
# Property "idle-timeout" specifies a timeout in minutes after which
# a client that does not send keyboard or mouse events is considered idle
# and hence disconnected. Default is 60 minutes.
# You can adapt this setting to your needs to free the console session e.g. after 30 minutes.
# idle-timeout=30
# Number of seconds to warn via notification before idle-timeout
# idle-timeout-warning=300
# Whether the clients are disconnected on OS session lock
# Enable this to force client disconnection when the remote OS session is locked.
# You can set the OS auto lock to be shorter than the idle-timeout so that connections
# are closed automatically (idle time default is 60 minutes)
disconnect-on-lock=true
# The following setting should be enabled by default which controls whether to
# lock the OS session when the last client connection ends
# [security]
# os-auto-lock = true
You can check more details here: https://docs.aws.amazon.com/dcv/latest/adminguide/config-param-ref.html#session_management
In /etc/dcv/default.perm
we allow all users to connect. More details can be found in https://docs.aws.amazon.com/dcv/latest/adminguide/security-authorization-file-create.html
; In /etc/dcv/default.perm in the permissions section we apply the following setting to allow all users
; Permissions can be adjusted for the respective purposes, builtin enables all permissions
[permissions]
%any% allow builtin
After one user has connected the following users will see a message similar to this:
![](https://www.ni-sp.com/wp-content/uploads/2024/05/image-8.png)
Windows
Here are the settings to enable dynamic console session for NICE DCV on Windows configuring the NICE DCV Server.
# Set the maximum number of concurrent clients per session to 1
New-ItemProperty -Path "HKEY_USERS\S-1-5-18\Software\GSettings\com\nicesoftware\dcv\session-management" `
-Name "max-concurrent-clients" -PropertyType DWord -Value 1 -Force
# Enable automatic creation of a console session at DCV startup
New-ItemProperty -Path "HKEY_USERS\S-1-5-18\Software\GSettings\com\nicesoftware\dcv\session-management" `
-Name "create-session" -PropertyType DWord -Value 1 -Force
# Set the owner of the automatically created "console" session, e.g. Administrator
New-ItemProperty -Path "HKEY_USERS\S-1-5-18\Software\GSettings\com\nicesoftware\dcv\session-management\automatic-console-session" `
-Name "owner" -PropertyType String -Value "Administrator" -Force
# Set the idle timeout (in minutes) after which a client is considered idle and disconnected
# New-ItemProperty -Path "HKEY_USERS\S-1-5-18\Software\GSettings\com\nicesoftware\dcv\connectivity" `
-Name "idle-timeout" -PropertyType DWord -Value 30 -Force
# Set the number of seconds to warn via notification before idle timeout, e.g. 5 minutes
# New-ItemProperty -Path "HKEY_USERS\S-1-5-18\Software\GSettings\com\nicesoftware\dcv\connectivity" `
-Name "idle-timeout-warning" -PropertyType DWord -Value 300 -Force
# Enable client disconnection when the remote OS session is locked
New-ItemProperty -Path "HKEY_USERS\S-1-5-18\Software\GSettings\com\nicesoftware\dcv\connectivity" `
-Name "disconnect-on-lock" -PropertyType DWord -Value 1 -Force
# Enable locking the OS session when the last client connection ends, default is enabled
# New-ItemProperty -Path "HKEY_USERS\S-1-5-18\Software\GSettings\com\nicesoftware\dcv\security" `
-Name "os-auto-lock" -PropertyType DWord -Value 1 -Force
To allow all users to connect we specify in the default.perm file using Powershell with Admin rights:
$filePath = "C:\Program Files\NICE\DCV\Server\conf\default.perm"
$fileContent = @"
; In /etc/dcv/default.perm in the permissions section we apply the following setting to allow all users
; Permissions can be adjusted for the respective purposes, builtin enables all permissions
[permissions]
%any% allow builtin
"@
New-Item -ItemType File -Path $filePath -Force
Set-Content -Path $filePath -Value $fileContent
After one user has connected the following users will see a message similar to this:
![](https://www.ni-sp.com/wp-content/uploads/2024/05/image-10.png)
More information about NICE DCV. For a managed approach to DCV session management NICE DCV Session Manager is the right solution including the NICE DCV Connection Gateway Proxy integration in case of interest.
Connect to a specific DCV session
When running multiple DCV sessions on one server you can specify in the DCV client to which session you would like to connect to by adding “#session_name” – e.g. #session3 in the example below:
![](https://www.ni-sp.com/wp-content/uploads/2021/02/image-4.png)
This also is possible in the DCV web client by specifying the session name in the URL like e.g. https://dcv.ni-sp.com#session3.
Allow different users to connect into DCV
Windows
DCV on Windows by default starts one session, this session has an “owner”.
The default owner proposed at installation time is Administrator
. You can change it during installation time or afterwards in the registry.
By default only the owner can connect to that session. If you want multiple users to be able to connect to the session, you have to change the DCV session permissions. From the DCV admin guide:
“The default permissions file is used for all sessions if you do not specify a custom permissions file when creating a session. The default permissions file grants only the session owner full access to all features.“
“You can customize the default permissions file to include custom authorizations. The default permissions file is located at C:\Program Files\NICE\DCV\Server\conf\default.perm
on Windows NICE DCV servers.”
You can configure a group (e.g. osgroup:YOUR_GROUP) or allow all users (%any%) to connect in default.perm:
[groups]
mygroup1=dom\user1, user2
[aliases]
; create permission alias
file-management=file-upload, file-download, clipboard-management
[permissions]
; Example to allow all users to connect
%any% allow builtin
; Example to allow users from osgroup YOUR_GROUP to connect
osgroup:YOUR_GROUP allow builtin
; allow the predefined mygroup to connect
group:mygroup1 allow builtin
The following features can be configured in the permissions file which allows for fine-granular permission control e.g. related to file transfer, cut&paste, USB devices, … :
builtin — All features.
display — Receive visual data from the NICE DCV server.
clipboard-copy — Copy data from the NICE DCV server to the client clipboard.
clipboard-paste — Paste data from the client clipboard to the NICE DCV server.
file-download — Download files from the session storage.
file-upload — Upload files to the session storage.
mouse — Input from the client pointer to the NICE DCV server.
keyboard — Input from the client keyboard to the NICE DCV server.
keyboard-sas — Use the secure attention sequence (CTRL+Alt+Del). Requires the keyboard
feature. Supported on version DCV 2017.3 and later.
touch — Use native touch events. Supported on version DCV 2017.3 and later. Not supported on Linux NICE DCV servers.
stylus — Input from specialized USB devices, such as 3D pointing devices or graphic tablets.
usb — Read the smart card from the client.
pointer — View NICE DCV server mouse position events and pointer shapes. Supported on version DCV 2017.3 and later.
audio-out — Play back NICE DCV server audio on the client.
audio-in — Insert audio from the client to the NICE DCV server.
printer — Print PDFs or XPS files from the NICE DCV server to the client.
smartcard — Read the smart card from the client.
Dynamically set NICE DCV session permissions at logon
Windows
Andrew from the DCV team has created a great guide how to set NICE DCV permissions at Windows login which applies to on-prem use cases similar to AWS based use cases of NICE DCV.
Create and test a dummy session
Linux
Sometimes it can be useful to test a session containing only a Window manager and a specific application or a terminal.
This allows the user to check in case there are session creation issues related to the specific session environment in use (typically gnome or KDE).In order to create a test dummy session, you need to create an init script init.sh for the user, containing something as:
#!/bin/sh
metacity &
xterm
This will start the metacity window manager and launch an xterm, as soon as the xterm process is terminated the session will also terminate.
Then you need to make sure that the init script is executable:
chmod a+x init.sh
To create the session with the specified init script from the user shell, run this command:
dcv create-session dummy --init init.sh
To create a session for another user as superuser you can run this command instead:
sudo dcv create-session test --user USER --owner USER --init init.sh
Finally, you can launch a test application such as dcvgltest or glxgears to verify that the OpenGL is correctly working.
Then you can check the session created with the command:
dcv list-sessions
Console session without Physical Monitor
Linux
For virtual sessions there is no way to login with a different user than the one for which the session was created.
To make the console session work, we could try the following setup to disable the physical monitor attached to the server in the xorg.conf file.
Add this option to the “Device” section corresponding to the GPU card in use in the /etc/X11/xorg.conf
configuration file:
Option "UseDisplayDevice" "none"
then restart the X server with:
sudo init 3
sudo init 5
or the equivalent commands for systemctl:
sudo systemctl isolate multi-user.target
sudo systemctl isolate graphical.target
Then create a console session with the command:
sudo dcv create-session console --owner USER
To authenticate, you will need to pass credentials for the system user USER.
Idle timeout period
Overview
You can configure NICE DCV to disconnect idle clients.
There are certain actions that will reset the idle disconnect timeout period. They are list below.
- Moving the mouse
- Pressing the mouse buttons or moving the mouse wheel
- Pressing any key on the keyboard
- Touching the touchscreen (if enabled)
- Using the stylus (if enabled)
- Using the gamepad (if enabled)
- Streaming with the webcam (if enabled)
- Any file storage operation such as uploading files, creating directories, downloading files, or listing items
Linux server
- Edit the file
/etc/dcv/dcv.conf
- Look for the code below and change the value to zero if you do not want disconnect, or any value greater than zero in minutes.
[connectivity]
idle-timeout=timeout_in_minutes - You can also set warnings about timeout X seconds before it happens editing this config:
[connectivity]
idle-timeout-warning=seconds_before_idle_timeout
- Then you need to restart the DCV session.
Windows server
- Open the Windows Registry Editor
- Open the
HKEY_USERS/S-1-5-18/Software/GSettings/com/nicesoftware/dcv/connectivity/
key and select theidle-timeout
parameter. If the parameter does not exist, you can createNew, DWORD (32-bit) value
withidle-timeout
name.
Note: the value must be in minutes - You can also set warnings about timeout X seconds before it happens editing the
HKEY_USERS/S-1-5-18/Software/GSettings/com/nicesoftware/dcv/connectivity/
key and select theidle-timeout-warning
parameter. If the parameter does not exist, you can createNew, DWORD (32-bit) value
withidle-timeout-warning
name.
Note: the value must be in seconds
Web client
The timeout of the sessions created through a web browser is controlled by the file:
${NICE_ROOT}/WEBAPP/WEB-INF/web.xml
Search and modify the following portion (timeout is given in minutes):
<session-config>
<session-timeout>30</session-timeout> <!-- time in minutes -->
</session-config>
Set the display layout for a running Session
With the below command you can set the display layout for a running session:
dcv set-display-layout --session session-id display-layout-descriptor
If you specify more than one screen, separate the screen descriptors by a comma. For example, suppose these two screens:
- Screen 1: 1920×1080 resolution offset to x=0, y=0
- Screen 2: 800×600 resolution offset to x=1920, y=0 so that it appears to the right of screen 1.
The parameter will be:
1920x1080+0+0,800x600+1920+0
It means:
![](https://www.ni-sp.com/wp-content/uploads/2024/05/Captura-de-Tela-2024-05-07-as-15.26.15.png)
Another example:
- Screen 1: 1920×1080 resolution offset to x=0, y=0
- Screen 2: 1920×1080 resolution offset to x=1920, y=0 so that it appears to the right of screen 1.
- Screen 3: 1024×768 resolution offset to x=-1024, y=0 so that it appears to the left of screen 1.
1920x1080+0+0,1920x1080+1920+0,1024x768-1024+0
![](https://www.ni-sp.com/wp-content/uploads/2024/05/Captura-de-Tela-2024-05-07-as-15.27.05.png)
Those examples were inspired in NICE DCV official doc.
NICE DCV Gateway integrated with DCV SM
Overview
With NICE DCV Gateway you can create and endpoint outside of your DCV Server infrastructure and redirect the traffic to the right DCV Server, if there is more than one. To have the DCV Gateway working, we need to follow 3 basic steps:
- Configuring the DCV SM Broker to be DCV Gateway resolver
- Configuring the DCV Gateway to look to the broker as resolver
- Register all DCV Servers under DCV SM Broker
Important notes:
- The Session Manager will assign a DCV Server for a new session.
- The session needs to be mapped by the DCV SM Broker to the right DCV Server.
- The DCV SM Broker will authenticate the user.
Configuring the DCV SM Broker
First we need to configure the DCV SM Broker to be the Resolver of DCV Gateway. The DCV SM Broekr will authenticate the users. This means that DCV Gateway will use the resolver to find the DCV Server sessions.
Please edit the file /etc/dcv-session-manager-broker/session-manager-broker.properties
and uncomment and configure these lines:
enable-gateway = true
gateway-to-broker-connector-bind-host = 0.0.0.0
gateway-to-broker-connector-https-port = 8449
Important: make sure that 8449 port is not being used.
You can restart the DCV SM Broker service:
sudo systemctl restart dcv-session-manager-broker
Configuring the DCV Gateway
Then we need to configure the DCV Gateway to use DCV SM Broker as Resolver.
Please edit the file /etc/dcv-connection-gateway/dcv-connection-gateway.conf
and configure the [resolver]
entry:
[gateway]
web-listen-endpoints = ["0.0.0.0:8447"]
quic-listen-endpoints = ["0.0.0.0:8447"]
cert-file = "/etc/dcv-connection-gateway/dcv_gateway_cert.pem"
cert-key-file = "/etc/dcv-connection-gateway/dcv_gateway_key.pem"
[resolver]
url = "https://dcvsmbroker:8449"
[web-resources]
url = "https://localhost:9001"
The 8449 port means that DCV Gateway will look for dcvsmbroker
dns name and try to connect into the port 8449. And the ports 8447 means that the DCV Gateway will listen the TCP and UDP protocols and forward the traffic to the right DCV Server.
You also need to change the DCV Gateway certificates. You need to copy from the Broker server the files /var/lib/dcvsmbroker/security/dcvsmbroker_ca.pem
and /var/lib/dcvsmbroker/security/dcvsmbroker_ca.key
to /etc/dcv-connection-gateway/dcv_gateway_cert.pem
and /etc/dcv-connection-gateway/dcv_gateway_key.pem
(or the right place if you did different configuration in the dcv-connection-gateway.conf
file).
Register the DCV Servers under DCV SM Broker
We need to register all DCV SM Agents under the Broker service. For that we will use the command dcv-session-manager-broker
.
If you never did it, you will see an empty DNS mapping list:
~# dcv-session-manager-broker describe-server-dns-mappings
Using system default Java runtime
Available server - DNS names mappings:
[ ]
Now we need to create a JSON file that contains the DNS mapping. Let’s create it under /tmp/dns_broker_mapping.json
with the content below:
[
{
"ServerIdType": "Id",
"ServerId": "127.0.0.1",
"DnsNames":
{
"InternalDnsName": "dcvserver"
}
}
]
- The ServerIdType will be Id: The Session Manager Agent creates a new UUID every time the hostname or the ip address changes.
- The ServerId is an unique identifier for DCV Servers.
- The InternalDnsName is the DNS name that will be used by DCV Gateway to connect into DCV Server
Then you need to make to change the user owner to dcvsmbroker
:
chown dcvsmbroker:dcvsmbroker /tmp/dns_broker_mapping.json
Now we can import the DNS mapping to the Broker service with the command dcv-session-manager-broker register-server-dns-mappings –file-path=/tmp/dns_broker_mapping.json, as the example below.
root@dcv-install-gw:~# dcv-session-manager-broker register-server-dns-mappings --file-path=/tmp/dns_broker_mapping.json
Using system default Java runtime
Successfully loaded 1 server id - dns name mappings from file /tmp/dns_broker_mapping.json
Now you can check the registered Agents with this command:
~# dcv-session-manager-broker describe-server-dns-mappings
Using system default Java runtime
Available server - DNS names mappings:
[ {
"ServerIdType" : "Id",
"ServerId" : "127.0.0.1",
"DnsNames" : {
"InternalDnsName" : "dcvserver"
}
} ]
Note: If you have multiple DCV Servers, you need to have a JSON mapping file like this:
[
{
"ServerIdType": "Id",
"ServerId": "127.0.0.1",
"DnsNames": {
"InternalDnsName": "dcvserver"
}
},
{
"ServerIdType": "Id",
"ServerId": "1.2.3.4",
"DnsNames": {
"InternalDnsName": "dcvserver2"
}
},
{
"ServerIdType": "Id",
"ServerId": "192.168.1.2",
"DnsNames": {
"InternalDnsName": "dcvserver3"
}
}
]
DCV Session Manager CLI
Before use the DCV SM CLI, you need to get the Agent API credentials that will be used to DCV SM CLI talk with the DCV Agent. To get the credentials, please execute in the Broker server:
~# dcv-session-manager-broker register-api-client --client-name EF
Using system default Java runtime
client-id: 1fc15078-66b2-415d-8fb8-ae51af034b70
client-password: MGVmYzcyNzQtOWYzYy00NDZkLThmMjctYTczMGE1NGEyYmM2
Then open your DCV SM CLI config file conf/dcvsmcli.conf and set all the config like this:
[output]
# The formatting style for command output.
output-format = json
# Turn on debug logging
# debug = true
[security]
# Disable SSL certificates verification.
no-verify-ssl = true
# CA certificate bundle to use when verifying SSL certificates.
# ca-bundle = ca-bundle.pem
[authentication]
# hostname of the authentication server used to request the token
auth-server-url = https://brokerip:brokerport/oauth2/token?grant_type=client_credentials
# The client ID
client-id = 1fc15078-66b2-415d-8fb8-ae51af034b70
# The client password
client-password = MGVmYzcyNzQtOWYzYy00NDZkLThmMjctYTczMGE1NGEyYmM2
[broker]
# hostname or IP of the broker. This parameter is mandatory.
url = https://brokerip:brokerport
The brokerip is the DCV SM Broker server IP (in our example will be 127.0.0.1). The brokerport is what you configured in the variable client-to-broker-connector-https-port in the file /etc/dcv-session-manager-broker/session-manager-broker.properties
(in our example will be 8448).
To test, let’s execute this command to describe the sessions:
~# ./dcvsm describe-sessions
WARNING : Validation of SSL certificates is disabled
{
"request_id": "46e1c957-ea5e-4bf6-a959-9bbf107a6e36",
"sessions": [
{
"id": "console",
"owner": "ubuntu",
"server": {
"id": "ZGN2LWluc3RhbGwtZ3ctMTg4LjI0NS44MS45MC04YTc0MDQwZjAwZDk0MmM3YjU4ZTgxZjhkNDVmZTk3Yg==",
"ip": "1.2.3.4",
"hostname": "dcvserver",
"default_dns_name": "static.1.2.3.4.clients.your-server.com.",
"port": "8443",
"endpoints": [
{
"ip_address": "0.0.0.0",
"port": 8443,
"web_url_path": "/",
"protocol": "HTTP"
},
{
"ip_address": "::",
"port": 8443,
"web_url_path": "/",
"protocol": "HTTP"
}
],
"web_url_path": "/",
"version": "2023.1.17701",
"session_manager_agent_version": "2023.1.0",
"availability": "UNAVAILABLE",
"unavailability_reason": "SERVER_FULL",
"console_session_count": 1,
"virtual_session_count": 0,
"tags": [
{
"key": "dcv:max-virtual-sessions",
"value": "-1"
},
{
"key": "dcv:max-concurrent-sessions-per-user",
"value": "1"
},
{
"key": "dcv:os-family",
"value": "linux"
}
]
},
"type": "CONSOLE",
"state": "READY",
"creation_time": "2024-09-03T09:04:51.148000+00:00",
"num_of_connections": 0,
"storage_root": ""
}
]
}
You can see all other command executing:
root@dcv-install-gw:~/nice-dcv-session-manager-cli-1.1.0-140# ./dcvsm --help
Usage: dcvsm [OPTIONS] COMMAND [ARGS]...
NICE DCV Session Manager CLI
Options:
--conf TEXT Name of the configuration file to read the
configuration parameters
--broker-url TEXT The URL of the broker
--debug Specify to enable the debug mode. By default is
disabled
--no-verify-ssl Specify to disable the verification of SSL
certification. By default is enabled
--output-format TEXT Specify the format of the output
--ca-bundle TEXT Specifies the path to a custom certificate bundle (a
file with a .pem extension) of CA to use when
establishing SSL/TLS connections
--auth-server TEXT URL of the authentication server used to request the
token
--version Show the version and exit.
-h, --help Show this message and exit.
Commands:
close-servers Closes one or more NICE DCV servers.
create-session Creates a new NICE DCV session.
delete-session Deletes the specified NICE DCV session.
describe-servers Describes one or more NICE DCV servers.
describe-sessions Describes one or more NICE DCV sessions.
get-session-connection-data Gets connection data for a specific NICE DCV
session.
get-session-screenshots Gets screenshots of one or more NICE DCV
sessions.
open-servers Opens one or more NICE DCV servers.
update-session-permissions Updates the user permissions for a specific
NICE DCV session.