# Managing Amazon DCV sessions
Managing Amazon DCV sessions

Once the Amazon DCV servers are set up and all your applications are installed, your clients access them through a secured session. Managing these sessions for your client grants them access and sets the parameters for each session.

Before your clients can connect to one, you must create a Amazon DCV session on your Amazon DCV server. Clients can only connect to a Amazon DCV server if there's an active session.

Every Amazon DCV session has the following attributes:
+ **session ID** — Used to identify a specific session on the Amazon DCV server.
+ **Owner** — The Amazon DCV user who created the session. By default, only an owner can connect to the session.

Amazon DCV clients need this information to connect to the session.

**Topics**
+ [

# Understanding Amazon DCV sessions
](managing-sessions-intro.md)
+ [

# Using the Command Line Tool to Manage Sessions
](managing-sessions-cli.md)
+ [

# Starting Amazon DCV sessions
](managing-sessions-start.md)
+ [

# Stopping Amazon DCV sessions
](managing-sessions-lifecycle-stop.md)
+ [

# Viewing Amazon DCV sessions
](managing-sessions-lifecycle-view.md)
+ [

# Managing active Amazon DCV sessions
](managing-running-session.md)
+ [

# Setting session time zone
](managing-session-time-zone.md)
+ [

# Managing screen blanking on Linux
](managing-screen-blanking.md)
+ [

# Taking a screenshot in a Amazon DCV Session
](managing-sessions-lifecycle-screenshot.md)

# Understanding Amazon DCV sessions


Amazon DCV offers two types of sessions—console sessions and virtual sessions. The following table summarizes the differences betweeen the two types of sessions.


| Session type | Support | Multiple sessions | Required permissions | Direct screen capture | GPU-accelerated OpenGL support | 
| --- | --- | --- | --- | --- | --- | 
| Console | Linux, macOS, and Windows Amazon DCV servers | No, only one console session allowed on each server | Only the admin user can start and close sessions | Yes | Yes, without additional software | 
| Virtual | Linux Amazon DCV servers only | Yes, multiple virtual sessions are allowed on a single server | Any user can start and close sessions | No, a dedicated X server (Xdcv), runs for each virtual session. The screen is captured from the X server. | Yes, but requires the DCV-GL package | 

**Note**  
You can't run console and virtual sessions on the same Amazon DCV server at the same time.

## Console sessions


Console sessions are supported on Windows, Linux, and macOS Amazon DCV servers. If you're using a Windows or macOS Amazon DCV server, you can only use console sessions.

Only one console session can be hosted on the Amazon DCV server at a time. Console sessions are created and managed by the Administrator on Windows Amazon DCV servers and the root user on Linux and macOS Amazon DCV servers. 

With console sessions, Amazon DCV directly captures the content of the desktop screen. If the server is configured with a GPU, Amazon DCV console sessions have direct access to the GPU.

## Virtual Sessions


Virtual sessions are supported on Linux Amazon DCV servers only.

You can host multiple virtual sessions on the same Amazon DCV server at the same time. Virtual sessions are created and managed by Amazon DCV users. Amazon DCV users can only manage sessions that they have created. The root user can manage all virtual sessions that are currently running on the Amazon DCV server.

With virtual sessions, Amazon DCV starts an X server instance, `Xdcv`, and runs a desktop environment inside the X server. Amazon DCV starts a new dedicated X server instance for each virtual session. Each virtual session uses the display provided by its X server instance.

**Note**  
While Amazon DCV ensures that each virtual session has an independent `Xdcv` display, many other system resources, including files in the user's home folder, D-Bus services, and devices, are per-user and thus will be shared and accessible across multiple virtual sessions for the same user.   
 You should not run multiple virtual sessions on the same Amazon DCV server for the same user at the same time, unless you have set up your Operating System to mitigate possible concerns about the shared resources. 

If the `dcv-gl` package is installed and licensed, Amazon DCV virtual sessions share access to the server's GPUs. To share hardware-based OpenGL across multiple virtual sessions, you must connect the virtual X server instance to the GPU by configuring the `dcv-gl.conf` file.

# Using the Command Line Tool to Manage Sessions
Using the Command Line Tool

The Amazon DCV server includes a command line tool that can be used to start, stop, and view Amazon DCV sessions.



## Using the command line tool on a Windows Amazon DCV Server


To use the command line tool on a Windows Amazon DCV server, run the commands from the Amazon DCV installation directory or add the Amazon DCV directory to the PATH environment variable. If you add the Amazon DCV directory to the PATH environment variable, you can use the commands from any directory.

**To use the command line tool from the Amazon DCV installation directory**  
Navigate to the folder where the `dcv.exe` file is located, `C:\Program Files\NICE\DCV\Server\bin\` by default, and open a command prompt window.

Or you can specify the full path when running a command from a different directory.

```
"C:\> Program Files\NICE\DCV\Server\bin\dcv.exe" list-sessions
```

**To add the Amazon DCV directory to the PATH environment variable**

1. In File Explorer, right-click **This PC** and choose **Properties**.

1. Choose **Advanced system settings**.

1. On the **Advanced** tab, choose **Environment Variables**.

1. In the **System variables** section, select the **Path** variable and choose **Edit**.

1. Choose **New** and specify the full path to the `bin` folder in the Amazon DCV installation directory (for example, `C:\Program Files\NICE\DCV\Server\bin\`).

1. Choose **OK** and close the Environment Variables window.

## Using the command line on a Linux Amazon DCV Server


On Linux Amazon DCV servers, the command line tool is automatically configured in the `$PATH` environment variable. You can use the tool from any folder. Open a terminal window and enter the command to run.

## Using the command line on a macOS Amazon DCV Server


On macOS Amazon DCV servers, the command line tool is automatically configured in the `$PATH` environment variable. You can use the tool from any folder. Open a terminal window and enter the command to run.

## Command line tool usage


The following table covers the available command line tool options. This list can be retrieved by using `--help` when calling `dcv`. For more information on how to use each command, pass in `--help` after the command you would like usage information for. For example: `dcv create-session --help`.


| Command | Description | 
| --- | --- | 
|  `create-session`  |  Create a new DCV session  | 
|  `close-session`  |  Close an active DCV session  | 
|  `describe-session`  |  Describe a DCV session  | 
|  `list-sessions`  |  List the active DCV sessions  | 
|  `list-connections`  |  List the client connections for a DCV session  | 
|  `close-connection`  |  Close an active client connection  | 
|  `get-screenshot`  |  Get a screenshot of the DCV console  | 
|  `set-display-layout`  |  Set display layout of an active DCV session  | 
|  `set-name`  |  Set name for a DCV session  | 
|  `set-permissions`  |  Set permissions of an active DCV session  | 
|  `set-storage-root`  |  Set storage root of an active DCV session  | 
|  `reload-licenses`  |  Force reloading the licenses for all the running sessions  | 
|  `get-config`  |  Get server configuration  | 
|  `list-endpoints`  |  List the DCV endpoints  | 
|  `set-config`  |  Set server configuration  | 
|  `version`  |  Show the version of DCV  | 
|  `help`  |  Show help  | 

# Starting Amazon DCV sessions
Starting sessions

When you use the defaults to [install Windows Amazon DCV server](setting-up-installing-wininstall.md), a [console session](managing-sessions-intro.md#managing-sessions-intro-console) is automatically created and active after the server is installed. The default console session is owned by `Administrator` and has a default session ID of `console`. You can use this session or you can [close it](managing-sessions-lifecycle-stop.md) and create a new session.

If you chose to opt out of the automatic console session creation when you installed the Amazon DCV server, you must create one manually. After you install the Amazon DCV server, you can enable or disable the [automatic console session creation](#managing-sessions-start-auto) at any time.

**Note**  
Linux and macOS Amazon DCV servers don't get a default console session after installation.

Assume that you use a floating license on an on-premises or alternative cloud-based server and exceed the maximum number of concurrent sessions that's supported by your license. You might get a `no licenses` error. If you get this error, stop an unused session to release the license and try again.

The Amazon DCV server must be running to start a session. For more information, see [Starting the Amazon DCV Server](manage-start.md).

**Topics**
+ [

## Manually starting console and virtual sessions
](#managing-sessions-start-manual)
+ [

## Enabling Automatic Console Sessions
](#managing-sessions-start-auto)

## Manually starting console and virtual sessions


You can start a Amazon DCV session at any time. You can only run one console session at a time. If you're using a Linux Amazon DCV server, you can run multiple virtual sessions at the same time.

It's good practice to run `dcv list-sessions` before creating a session, especially if you're using Windows Amazon DCV server.

To create a console or virtual session on a Windows, Linux, or macOS Amazon DCV server, use the `dcv create-session` command.

**Topics**
+ [

### Syntax
](#managing-sessions-start-manual-syntax)
+ [

### Options
](#managing-sessions-start-manual-options)
+ [

### Examples
](#managing-sessions-start-manual-examples)

### Syntax


The minimal syntax of the command to start a session is:

```
dcv create-session session_ID
```

The full syntax with all the options is:

```
dcv create-session \
    --type console|virtual \
    --name session_name \
    --user username \
    --owner owner_name \
    --permissions-file /path_to/permissions_file \
    --storage-root /path_to/storage_directory \
    --gl on|off \
    --max-concurrent-clients number_of_clients \
    --init /path_to/init_script \
    session_ID
```

**Note**  
The `\` symbol represents the syntax to split a command in multiple lines.

You can also use `dcv create-session --help` to display a quick reference to the syntax.

### Options


The following options can be used with the `dcv create-session` command:

**`--type`**  
This option is supported on Linux Amazon DCV servers only. It specifies the type of session to be created and can be either `console` or `virtual`.  
Type: String  
Allowed values: `console` \$1 `virtual`  
Required: No

**`--name`**  
Specifies a name for the session. Session names can be any string of up to 256 characters. If the string exceeds 256 characters, the command fails. Session names don't need to be unique across running sessions.  
You can change a session's name at any time using the `dcv set-name` command. For more information, see [Managing the session name](managing-session-name.md).  
Type: String  
Required: Yes

**`--user`**  
This option is supported with virtual sessions on Linux Amazon DCV sessions only. This value is the user to be used to create the session. Only the root user can impersonate other users.  
Type: String  
Required: No

**`--owner`**  
Specifies the session owner. Defaults to the currently signed in user if omitted.  
Type: String  
Required: No

**`--permissions-file`**  
Specifies a path to a custom permissions file. Defaults to the server defaults if omitted.  
Type: String  
Required: No

**`--storage-root`**  
Specifies the path to the folder used for session storage.  
You can use `%home%` to specify the home directory of the user who is currently signed in. For example, the following sets the directory for session storage as `c:\Users\username\storage\` for Windows servers or `$HOME/storage/` for Linux servers.  

```
--storage-root %home%/storage/
```
If a specified subdirectory doesn't exist, session storage is disabled.
Type: String  
Required: No

**`--gl`**  
This option is supported with virtual sessions on Linux Amazon DCV sessions only. It overrides the default `dcv-gl` state and can be either `on` or `off`.  
Type: String  
Allowed values: `on` \$1 `off`  
Required: No

**`--max-concurrent-clients`**  
Specifies the maximum number of Amazon DCV clients that are allowed to connect to the session. Defaults to unlimited connections if omitted.  
Type: Integer  
Required: No

**`--init`**  
This option is supported with virtual sessions on Linux Amazon DCV servers only. It specifies the path to a custom `init` script. The script can be used to start a specific desktop environment and launch specific applications automatically when the session starts. The script must be executable. Defaults to a script that starts the default desktop environment if omitted.  
Type: String  
Required: No

**`session ID`**  
Provides an ID for your session at the end of the command.  
Type: String  
Required: Yes

### Examples


**Example 1 - Console session**  
The following command creates a console session owned by `dcv-user` with a unique session ID of `my-session`, and a session name of `my graphics session`. It also specifies a permissions file named `perm-file.txt`.
+ Windows Amazon DCV server

  ```
  C:\> dcv create-session^
      --owner dcv-user^
      --name "my graphics session"^
      --permissions-file perm-file.txt^
      my-session
  ```
+ Linux Amazon DCV server

  ```
  $ sudo dcv create-session \
      --type=console \
      --owner dcv-user \
      --name "my graphics session" \
      --permissions-file perm-file.txt \
      my-session
  ```

**Example 2 - Virtual Session (Linux Amazon DCV servers only)**  
The following command creates a virtual session using the root user to impersonate the intended session owner, `dcv-user`. The session is owned by `dcv-user` even though it is created by the root user

```
$ sudo dcv create-session \
    --owner dcv-user \
    --user dcv-user \
    my-session
```

**Example 3 - Virtual Session (Linux Amazon DCV servers only)**  
The following command creates a virtual session owned by the user who creates it:

```
$ dcv create-session my-session
```

## Enabling Automatic Console Sessions


Enabling an automatic console session ensures that a console session is automatically created each time that the Amazon DCV server starts. The automatic console session is owned by the Amazon DCV user specified by the `owner` configuration parameter. Its session ID is always `console`.

Other parameters affecting automatic console sessions are `max-concurrent-clients`, `permissions-file`, and `storage-root`. For more information about these parameters, see [`session-management/automatic-console-session` Parameters](config-param-ref.md#session_management_automatic_console_session).

**Note**  
Amazon DCV doesn't support automatic virtual sessions.

------
#### [ Windows Amazon DCV server ]

**To enable an automatic console session on a Windows Amazon DCV server**

1. Open the Windows Registry Editor.

1. Navigate to the **HKEY\$1USERS\$1S-1-5-18\$1Software\$1GSettings\$1com\$1nicesoftware\$1dcv\$1session-management** key.

1. Create a `create-session` parameter:

   1. In the navigation pane, open the context (right-click) menu for the **session-management** key and choose **New**, **DWORD (32-bit) Value**.

   1. For **Name**, enter `create-session` and press **Enter**.

   1. Open the **create-session** parameter. For **Value data**, enter `1`, and choose **OK**.

1. Navigate to the **HKEY\$1USERS\$1S-1-5-18\$1Software\$1GSettings\$1com\$1nicesoftware\$1dcv\$1session-management/automatic-console-session** key.

1. Create an `owner` parameter:

   1. In the navigation pane, open the context (right-click) menu for the **automatic-console-session** key and choose **New**, **String Value**.

   1. For **Name**, enter `owner` and press **Enter**.

   1. Open the **owner** parameter. For **Value data**, enter the session owner's name and choose **OK**.

1. Choose **OK** and close the Windows Registry Editor.

1. [Stop](manage-stop.md) and [restart](manage-start.md) the Amazon DCV server.

------
#### [ Linux Amazon DCV server ]

**To enable an automatic console session on a Linux Amazon DCV server**

1. Navigate to `/etc/dcv/` and open the `dcv.conf` with your preferred text editor.

1. Add the `create-session` and `owner` parameters to the `[session-management/automatic-console-session]` section using the following format:

   ```
   [session-management]
   create-session = true
   
   [session-management/automatic-console-session]
   owner="session-owner"
   ```

1. Save and close the file.

1. [Stop](manage-stop.md) and [restart](manage-start.md) the Amazon DCV server.

------
#### [ macOS Amazon DCV server ]

**To enable an automatic console session on a macOS Amazon DCV server**

1. Navigate to `/etc/dcv/` and open the `dcv.conf` with your preferred text editor.

1. Add the `create-session` and `owner` parameters to the `[session-management/automatic-console-session]` section using the following format:

   ```
   [session-management]
   create-session = true
   
   [session-management/automatic-console-session]
   owner="session-owner"
   ```

1. Save and close the file.

1. [Stop](manage-stop.md) and [restart](manage-start.md) the Amazon DCV server.

------

# Stopping Amazon DCV sessions
Stopping Sessions

A console session can only be stopped by the administrator on Windows Amazon DCV servers, and the root user on Linux and macOS Amazon DCV servers. A virtual session on a Linux Amazon DCV server can only be stopped by the root user or the Amazon DCV user who created it. 

**Note**  
Stopping a session closes all of the applications that are running in the session.

To stop a console or virtual session on a Windows, Linux, or macOS Amazon DCV server, use the `dcv close-session` command and specify the unique session ID.

**Topics**
+ [

## Syntax
](#managing-sessions-lifecycle-stop-syntax)
+ [

## Example
](#example)

## Syntax


```
dcv close-session session-id
```

## Example


For example, the following command stops a session with the unique ID of `my-session`.

```
dcv close-session my-session
```

# Viewing Amazon DCV sessions
Viewing sessions

The administrator on a Windows Amazon DCV server or the root user on a Linux Amazon DCV server can view all active sessions that are running on the server. Amazon DCV users can only view sessions that they have created.



**Topics**
+ [

## Viewing all active sessions
](#list-all)
+ [

## Viewing a specific active session
](#view-specific)

## Viewing all active sessions


To list the active console or virtual sessions on a Windows or Linux Amazon DCV server, use the `dcv list-sessions` command.

**Topics**
+ [

### Syntax
](#list-all-syntax)
+ [

### Output
](#output)

### Syntax


```
dcv list-sessions
```

### Output


The command returns a list of active sessions in the following format.

```
Session: session-id (owner:session-owner type:virtual|console name:'my session')
```

## Viewing a specific active session


To view information about a session, use the `dcv describe-session` command and specify the unique session ID.

**Topics**
+ [

### Syntax
](#view-specific-syntax)
+ [

### Output
](#output)

### Syntax


```
$ dcv describe-session session_id
```

### Output


In the following example output, the `display-layout` element indicates that the session's display layout is set to use two 800x600 screens. Of these, the second screen is offset to x=800 (to the right) of the first screen.

```
Session: test
  owner: session-id
  name: session-name
  x display: :1
  x authority: /run/user/1009/dcv/test.xauth
  display layout: 800x600+0+0,800x600+800+0
```

You can also include the `--json` (or `-j`) option to force the command to return the output in JSON format. The JSON output provides additional details about the session. 

```
$ dcv describe-session session-id --json
```

The following is example JSON output.

```
{
  "id" : "session-id",
  "owner" : "dcvuser",
  "name" : "session-name",
  "num-of-connections" : 0,
  "creation-time" : "2020-03-02T16:08:50Z",
  "last-disconnection-time" : "",
  "licenses" : [
    {
      "product" : "dcv",
      "status" : "licensed",
      "check-timestamp" : "2020-03-02T16:08:50Z",
      "expiration-date" : "2020-03-29T00:00:00Z"
    },
    {
      "product" : "dcv-gl",
      "status" : "licensed",
      "check-timestamp" : "2020-03-02T16:08:50Z",
      "expiration-date" : "2020-03-29T00:00:00Z"
    }
  ],
  "storage-root" : "",
  "type" : "virtual",
  "x11-display" : ":2",
  "x11-authority" : "/run/user/1009/dcv/vsession.xauth",
  "display-layout" : [
    {
      "width" : 800,
      "height" : 600,
      "x" : 0,
      "y" : 0
    },
    {
      "width" : 800,
      "height" : 600,
      "x" : 800,
      "y" : 0
    }
  ]
}
```

# Managing active Amazon DCV sessions
Managing active sessions

After a client is logged in and begins using a DCV session, the session is considered active. While a session is active, you can still perform certain management tasks. This section provides the information you need about managing the parameters of these sessions while they are still in use by the client. 

**Topics**
+ [Managing session storage](managing-session-storage.md)
+ [Managing session authorization](managing-session-perms.md)
+ [Managing the session display layout](managing-session-display.md)
+ [

# Managing the session name
](managing-session-name.md)
+ [

# Finding and stopping idle sessions
](stop-idle-sessions.md)

# Managing Amazon DCV Session storage
Managing session storage

Session storage is a directory on the Amazon DCV server that clients can access when they are connected to a Amazon DCV session.

If session storage is enabled on the Amazon DCV server, you can use the `dcv set-storage-root` command to specify the directory on the server to be used for session storage. For more information about enabling session storage on the Amazon DCV server, see [Enabling session storage](manage-storage.md).

To set the session storage path, use the `dcv set-storage-root` command and specify the session ID and the path to the directory to use.

**Topics**
+ [

## Syntax
](#managing-session-storage-syntax)
+ [

## Options
](#managing-session-storage-options)
+ [

## Examples
](#session-storage-example)

## Syntax


```
dcv set-storage-root --session session_id /path_to/directory
```

For the directory path, you can use `%home%` to specify the home directory of the user who is currently signed in. For example, the `%home%/storage/` path resolves to `c:\Users\username\storage\` on Windows servers. It resolves to `$HOME/storage/` on Linux servers. 

**Note**  
The `storage-root` value must be an absolute path on macOS.

## Options


The following options can be used with the `dcv set-storage-root` command

**`--session`**  
The session ID for which to specify the storage directory.  
Type: String  
Required: Yes

## Examples


**Windows Amazon DCV server example**  
The following example sets to storage path to `c:\session-storage` for a session with a session ID of `my-session`.

```
C:\> dcv set-storage-root --session my-session c:\session-storage
```

**Linux Amazon DCV server example**  
The following example sets to storage path to a directory named `session-storage` in the current user's home directory, for a session with a session ID of `my-session`.

```
$ dcv set-storage-root --session my-session %home%/session-storage/
```

# Managing Amazon DCV Session authorization
Managing session authorization

Authorization is used to grant or deny Amazon DCV clients permissions to specific Amazon DCV features. Typically, authorization is configured when a Amazon DCV session is started. However, it's possible to edit the permissions for a running session. For more information about Amazon DCV authorization, see [Configuring Amazon DCV authorization](security-authorization.md).

To modify the permissions for a running session, use the `dcv set-permissions` command.

**Topics**
+ [

## Syntax
](#managing-session-perms-syntax)
+ [

## Options
](#managing-session-perms-options)
+ [

## Examples
](#session-perms-example)

## Syntax


```
dcv set-permissions --session session-id --none | --reset-builtin | --file /path_to/permissions_file
```

You must specify either `--none`, `--reset-builtin`, or `--file`.

## Options


The following options can be used with the `dcv set-permissions` command.

**--session**  
Specifies the ID of the session to set the permissions for.

**--reset-builtin**  
Resets the session's permissions to the default session permissions. The default permissions grants only the session owner full access to all features.

**--none**  
Revokes all permissions for the session.

**--file**  
Specifies the path to a custom permissions file. If the specified file is empty, all permissions are revoked. For more information about creating a custom permissions file, see [Understanding permissions files](security-authorization-file-create.md).

## Examples


**Example 1—Revoking all permissions**  
The following example revokes all client permissions for a session with an ID of `my-session`.

```
C:\> dcv set-permissions --session my-session --none
```

**Example 2—Specifying custom permissions**  
The following example specifies a custom permissions file that's named `perm-file.txt` for a session with an ID of `my-session`. This file is located in the `c:\dcv\` directory. 

```
C:\> dcv set-permissions --session my-session --file c:\dcv\perm-file.txt
```

**Example 3—Resetting the permissions**  
The following example resets the permissions to the defaults for a session with an ID of `my-session`.

```
C:\> dcv set-permissions --session my-session --reset-builtin
```

# Managing the Amazon DCV Session display layout
Managing the session display layout

You can set the display layout for a running Amazon DCV session. The display layout specifies the default configuration that's used when clients connect to the session. However, clients can manually override the layout using the Amazon DCV client settings or the native operating system display settings. 

If the host server's hardware and software configuration doesn't support the specified resolution or the number of screens, the Amazon DCV server doesn't apply the specified display layout.

Amazon DCV can configure a resolution according to the settings and the server system configuration.
+ Web client resolution is limited by default to 1920x1080 (from web-client-max-head-resolution server setting).
+ Native clients are limited by default to 4096x2160 (from max-head-resolution).

Note that the available resolutions and number of monitors depend on the configuration of the server, make sure to follow the [prerequisites guide](https://docs.aws.amazon.com/dcv/latest/adminguide/setting-up-installing.html) to properly setup the system environment and drivers for best performance.

**Note**  
For native clients, up to a maximum of four monitors can be used.   
For web clients, up to a maximum of two monitors can be used.  
Higher resolutions or more than the maximum number of monitors are not supported in any configuration.

**Topics**
+ [

## Accessing the display layout
](#display-restrict)
+ [

## Setting the display layout
](#dislay-set)
+ [

## Viewing the display layout
](#dislay-view)

## Accessing the display layout


You can configure the Amazon DCV server to prevent clients from requesting display layouts that are outside of a specified range. To restrict display layout changes, configure the following Amazon DCV server parameters.
+ [`enable-client-resize`](config-param-ref.md#paramref.display.enable-client-resize)—To prevent clients from changing the display layout, set this parameter to `false`.
+ [`min-head-resolution`](config-param-ref.md#paramref.display.min-head-resolution) and [`max-head-resolution`](config-param-ref.md#paramref.display.max-head-resolution)—Specifies the minimum and maximum allowed resolutions respectively.
+ [`web-client-max-head-resolution`](config-param-ref.md#paramref.display.web-client-max-head-resolution)—Specifies the maximum allowed resolution for web browser clients. The `max-head-resolution` limitation is applied on top of `web-client-max-head-resolution` limitation. By default, the maximum resolution for web browser clients is 1920x1080. Specifying a higher resolution might cause performance issues, depending on the web browser and specifications of the client computer.
+ [`max-num-heads`](config-param-ref.md#paramref.display.max-num-heads)—Specifies the maximum number of displays.
+ `max-layout-area`— Specifies the maximum number of pixels allowed for the screen area. Requests with the total screen area (expressed in pixels) exceeds the specified value are ignored.

For more information about these parameters, see [`display` Parameters](config-param-ref.md#display) in the Parameter Reference.

## Setting the display layout


**To configure the display layout for a running Amazon DCV session**  
Use the `dcv set-display-layout` command and specify the session to set the display layout and the display layout descriptor for.

```
dcv set-display-layout --session session-id display-layout-descriptor
```

The display layout descriptor specifies the number of displays and the resolution and position offset for each display. The description must be specified in the following format:

```
widthxheight+|-x-position-offset+|-y-position-offset
```

If you specify more than one screen, separate the screen descriptors by a comma. The screen position offsets specify the position of the top-left corner of the screen relative to screen 1. If you don't specify a position offset for a screen, it defaults to x=0 and y=0.

**Important**  
If you're specifying more than one screen, ensure that you properly set the position offset for each screen to avoid screen overlaps.

For example, the following display layout descriptor specifies two screens:
+ Screen 1: 1920x1080 resolution offset to x=0, y=0
+ Screen 2: 800x600 resolution offset to x=1920, y=0 so that it appears to the right of screen 1.

![\[Screen layout with two screens.\]](http://docs.aws.amazon.com/dcv/latest/adminguide/images/eg2.png)


```
1920x1080+0+0,800x600+1920+0
```

The following display layout descriptor specifies three screens. 
+ Screen 1: 1920x1080 resolution offset to x=0, y=0
+ Screen 2: 1920x1080 resolution offset to x=1920, y=0 so that it appears to the right of screen 1.
+ Screen 3: 1024x768 resolution offset to x=-1024, y=0 so that it appears to the left of screen 1.

![\[Screen layout with three screens.\]](http://docs.aws.amazon.com/dcv/latest/adminguide/images/eg1.png)


```
1920x1080+0+0,1920x1080+1920+0,1024x768-1024+0
```

## Viewing the display layout


**To view the display layout for a session**  
Use the `dcv describe-session` command and review the `display layout` element in the output. For more information, see [Viewing Amazon DCV sessions](managing-sessions-lifecycle-view.md).

# Managing the session name


You can change the name of a running session at any time. You can use the specific name of session to quickly identify a session based on its name. Session names don't need to be unique across running sessions.

To change the name of a running session, use the `dcv set-name` command. 

**Topics**
+ [

## Syntax
](#managing-session-name-syntax)
+ [

## Options
](#managing-session-name-options)
+ [

## Examples
](#example)

## Syntax


```
$ dcv set-name --session session_id --none |--name "session-name"
```

You must specify either `--name` or `--none`.

## Options


The following options can be used with the `dset-name` command.

**`--session`**  
The ID of the session to set the name for.   
Type: String  
Required: Yes

**`--name`**  
The name to assign the session. Only specify this option if you want to assign a name to session. If you want to remove a name, omit this paramater. The session name can be up to 256 characters long. It can consist of letters, numbers, and special characters. If the specified string exceeds 256 characters, the command fails.  
Type: String  
Required: No

**`--none`**  
Specify this parameter to remove an existing name from a session. If you don't want to remove the session name, omit this option.  
Required: No

## Examples


**Example 1—Changing a session's name**  
The following example sets the name of a session with an ID of `my-session` to `my graphics session`.

```
$ dcv set-name --session my-session --name "my graphics sessions"
```

**Example 2—Removing a session's name**  
The following example removes the name of a session with an ID of `my-session`.

```
$ dcv set-name --session my-session --none
```

# Finding and stopping idle sessions


You can identify idle Amazon DCV sessions using the `dcv describe-sessions` CLI command with the `-j` command option. Specifying the `-j` option configures the command to return the output in JSON format, which provides additional details about the session.

For example, the following command returns information about a session named `my-session`.

```
$ dcv describe-session my-session -j
```

Output:

```
{
    "id" : "my-session",
    "owner" : "dcvuser",
    "x11-display" : ":1",
    "x11-authority" : "/run/user/1009/dcv/test3.xauth",
    "num-of-connections" : 1,
    "creation-time" : "2019-05-13T13:21:19.262883Z",
    "last-disconnection-time" : "2019-05-14T12:32:14.357567Z",
    "licensing-mode" : "DEMO",
    "licenses" : [
        {
            "product" : "dcv",
            "status" : "LICENSED",
            "check-timestamp" : "2019-05-14T12:35:40Z",
            "expiration-date" : "2019-05-29T00:00:00Z"
        },
        {
            "product" : "dcv-gl",
            "status" : "LICENSED",
            "check-timestamp" : "2019-05-14T12:35:40Z",
            "expiration-date" : "2019-05-29T00:00:00Z"
        }
    ]
}
```

In the command output, the `num-of-connections` parameter indicates the number of active client connections. A value of `0` indicates that there are no active client connections, and that the session is currently idle. You can also use the `last-disconnection-time` parameter to determine when the session last had an active client connection. 

You can create a script or cron job that uses this information to identify idle sessions. Then you can stop using them by using the [`dcv close-session`](managing-sessions-lifecycle-stop.md) command.

**Note**  
Stopping a session closes all of the applications that are running in the session.

# Setting session time zone


DCV allows session owners and users to set the time zone of their session to reflect either the location of the DCV Server or their current location.

 If only individual users in a session are required to have this feature, you will need to set the centralized parameter for all users first and then adjust individuals’ permissions separately by creating a custom permissions file at [Adding permissions](security-authorization-file-create-permission.md). 

**Note**  
This feature is not available on Linux virtual sessions.

**Note**  
On macOS, time zone redirection is applied after login.

**Enabling time zone redirection**  
You can enable and disable this feature for all users on a specific session.

1. Modify the [`enable-timezone-redirection`](config-param-ref.md#paramref.redirection.enable-timezone-redirection) parameter to one of the following values:
   + `always-on`: Time Zone Redirection is always enabled.

     The feature will be turned on and the session displays the time zone information of the client. The user will not be able to turn the feature off.
   + `always-off`: Time Zone Redirection is always disabled.

     The feature will be turned off and the session displays its own time zone information. The user will not be able to turn the feature on.
   + `client-decides`: Time Zone Redirection is turned on by default.

     The session will have the feature enabled, display the client time zone, and the user will have the option to disable it allowing the server time zone to be displayed.
**Note**  
This setting is the standard default setting.

1. Restart any affected sessions for your changes to appear.

# Managing screen blanking on Linux


For Console sessions on a Linux server, DCV blanks the local screen by default when at least one remote user is connected to the server, and restores the output (also locking the screen) upon disconnection of the last remote user.

This prevents user in the physical proximity of a server to see the screen and interact with the remote session using the input devices connected to the host. This may be undesirable for privacy reasons or local laws compliance when remotely working on console sessions. Local input is prevented by disabling the physically connected devices such as the keyboard and the mouse. Input devices are disabled as soon as they are plugged in or when found to be enabled. Analogously, input devices are enabled back when no remote user is connected, thus permitting local log in and interaction.

**Disabling screen blanking and input blocking**  
Screen blanking can be disabled using the following procedure:

1. Navigate to `/etc/dcv/` and open the `dcv.conf` file with your preferred text editor.

1. Locate the `disable-local-console parameter` in the `[display/linux]` section. To permit locally connected displays to stay active and show the ongoing remote session, and permit interaction through locally connected devices set `disable-local-console=false`. The default value is `true` (i.e.: screen blanking and input blocking active). If there's no `disable-local-console` parameter in the `[display/linux]` section, add it manually using the following format:

   ```
    [display/linux]
    disable-local-console=false|true
   ```

1. Save and close the file.

1. [Stop](manage-stop.md) and [restart](manage-start.md) the Amazon DCV server.

**Preventing selected input devices from being disabled**  
Specific devices can be set to remain enabled.

 Input devices whose name starts with `DCV ` (please pay attention to the space after the name) will never be disabled irrespective of the value of the `display-local-console` setting. To rename input devices, refer to this guide: [Enable Stylus](enable-stylus.md). 

# Taking a screenshot in a Amazon DCV Session
Taking a screenshot

You can use the `dcv get-screenshot` command to take a screenshot of the desktop for the running session. 

## Syntax


```
dcv get-screenshot --max-width pixels --max-height pixels --format JPEG|PNG --primary --json --output /path_to/destination session_name
```

## Options


**`--max-width`**  
Specifies the maximum width, in pixels, of the screenshot. If you don't specify a width or a height, the screenshot uses the session's display resolution. If you specify a height only, the width is automatically scaled to maintain the aspect ratio.  
Type: Integer  
Required: No

**`--max-height`**  
Specifies the maximum height, in pixels, of the screenshot. If you don't specify a width or height, the screenshot uses the session's display resolution. If you specify a width only, the height is automatically scaled to maintain the aspect ratio.  
Type: Integer  
Required: No

**`--format`**  
The file format of the screenshot. Currently, only the `JPEG` and `PNG` formats are supported. If you specify conflicting file types for the `--format` and `--output` options, the value specified for `--format` takes priority. For example, if you specify `--format JPEG` and `--output myfile.png`, Amazon DCV creates a JPEG image file.  
Type: String  
Allowed values: `JPEG` \$1 `PNG`  
Required: No

**`--primary`**  
Indicates whether to get a screenshot of the primary display only. To get a screenshot of the primary display only, specify `--primary`. To get a screenshot of all displays, omit this option. If you choose to get a screenshot of all of the displays, all of the displays are combined into a single screenshot.  
Required: No

**`--json`, `-j`**  
Indicates whether to deliver the output in JSON format encoded in base64. To get JSON output, specify `--json`. Otherwise, omit it.  
Required: No

**`--output`, `-o`**  
Specifies the destination path, file name, and file type for the screenshot. For example, for Windows, specify `c:\directory\filename.format`, and for Linux, specify `/directory/filename.format`. The format must be `.png` or `.jpeg`. If you specify conflicting file types for the `--format` and `--output` options, the value specified for `--format` takes priority. For example, if you specify `--format JPEG` and `--output myfile.png`, Amazon DCV creates a JPEG image file.  
Type: String  
Required: no

## Examples


**Example 1**  
The following example command gets a screenshot of a session that's named `my-session`. The screenshot uses the resolution of the server.

```
dcv get-screenshot --output myscreenshot.png my-session
```

**Example 2**  
The following example command takes a screenshot that's `200` pixels wide by `100` pixels high. It takes it of a session that's named `my-session`. It saves the screenshot in the current directory with the file name `myscreenshot.png`.

```
dcv get-screenshot --max-width 200 --max-height 100 --output myscreenshot.png my-session
```

**Example 3**  
The following example command takes a screenshot of a session that's named `my-session`. The screenshot is only of the primary display. It saves the file in the current directory and names the screenshot `myscreenshot.png`.

```
dcv get-screenshot --primary --output myscreenshot.jpeg my-session
```

**Example 4**  
The following example command gets a screenshot of a session that's named `my-session`. The command outputs the file encoded in base64 and in JSON format.

```
dcv get-screenshot --json --format png my-session
```