# Managing active Amazon DCV sessions
<a name="managing-running-session"></a>

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
<a name="managing-session-storage"></a>

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
<a name="managing-session-storage-syntax"></a>

```
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
<a name="managing-session-storage-options"></a>

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
<a name="session-storage-example"></a>

**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
<a name="managing-session-perms"></a>

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
<a name="managing-session-perms-syntax"></a>

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

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

## Options
<a name="managing-session-perms-options"></a>

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
<a name="session-perms-example"></a>

**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
<a name="managing-session-display"></a>

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
<a name="display-restrict"></a>

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
<a name="dislay-set"></a>

**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
<a name="dislay-view"></a>

**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
<a name="managing-session-name"></a>

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
<a name="managing-session-name-syntax"></a>

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

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

## Options
<a name="managing-session-name-options"></a>

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
<a name="example"></a>

**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
<a name="stop-idle-sessions"></a>

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.