---
myst:
  html_meta:
    "description lang=en": "Allow Kasm Workspaces to automatically record sessions passively"
    "keywords": "Kasm, Session, Recording"
    "property=og:locale": "en_US"
---
```{title} Session Recording
```

```{note}
This feature requires an Enterprise license. Please contact a Kasm Technologies representative for details.
```

# Session Recording

The Session Recording feature allows administrators to record user activities passively for compliance or monitoring purposes. These recordings are initially saved in segments on local storage. Later, they are converted to videos and uploaded to a pre-configured storage bucket.

Session recording is supported on container based workspaces as well as RDP, VNC, and SSH server based workspaces. Containers must be either 1st party Kasm published images, or built upon the 1st party images with 1.15.0 tags or newer. 

```{note}
Session recording is a CPU intensive task and will have an effect on the sizing of Connection Proxies and Agents. Refer to the [Kasm sizing guide](../../how_to/sizing_operations.md) for more information.
```

```{note}
Session recording is not supported on staged sessions. If a user has a group with record_sessions set to True, and selects a workspace that has staged sessions provisioned a fresh on demand session will be provisioned for the user instead.
```

## Configuration

- Log into the Kasm Web UI as an administrator.
- Click **Settings->Global**.
- Configure session recording (see [settings](./settings.md#recording) for more detail):
    - Define **Object Storage Key**
    - Define **Object Storage Secret**
    - Define **Session Recording Upload Location**
    - Modify **Session Recording Bitrate** if desired
    - Modify **Session Recording Framerate** if desired
    - Modify **Session Recording Width** if desired
    - Modify **Session Recording Height** if desired
    - Modify **Session Recording Retention Period** if desired
    - Modify **Session Recording Queue Length** if desired
- Enable session recording for the desired groups:
    - Click **Access Management->Groups**
    - Edit the desired group
    - Click **Settings**
    - Click **Add Setting**
    - Search for **record_sessions** setting and set to True

```{warning}
For container based Workspaces, Workspaces that have sudo or root access enabled will result in the user having enough permissions to subvert the session recording process and prevent those recordings from being uploaded to the cloud.
```

```{tip}
Changes to feature licensing may take up to 10 minutes to be applied since certain requests are cached by the system.
If after applying the license and making all of the above configuration changes sessions are still not being recorded 
check the logs for warning/errors. If Kasm logs that the feature is not licensed wait 10 minutes for the cache to be refreshed and try again.
```

### S3 Policy Configurations

```{include} /guide/s3_policy_configurations.md
```

### S3 Endpoint configuration

By default, the endpoint used for S3 access is `s3.amazonaws.com`. Administrators may desire to specify a custom endpoint in order to support the following use cases.
- A private VPC Endpoint
- AWS Gov Cloud end-points
- Region specific end-points
- AWS S3 Accelerated Endpoints
- S3 Compatible Solutions

To specify a custom endpoint, in the Workspaces settings, format the Session Recording Upload Location path in the following format:
```text
s3://bucket-name@endpoint/folder/{username}/{kasm_id}.mp4
```

The following example configures Kasm to use GCP Cloud Storage (an S3 compliant cloud storage provider) for a session recording storage, where `kasm` is the bucket name, `storage.googleapis.com` is the endpoint name, and the remaining is the path with `{user_id}` replaced by the Kasm user ID, `{image_friendly_name}` replaced by the workspace name, and `{start_date}` is replaced by the date the user started the session.
```text
s3://kasm@storage.googleapis.com/recordings/{user_id}/{image_friendly_name}-{start_date}.mp4
```

```{note}
Some S3 compatible providers will have additional requirements to be compatible. For instance GCP cloud storage also requires the use of [HMAC keys](https://cloud.google.com/storage/docs/authentication/hmackeys) for authentication. Please consult the documentation for the choosen provider to ensure all neccesary configuration is met.
```

#### S3 Session Recording Variable Substitution

The session recording upload location setting provides the ability to specify template variables that are automatically filled in by Kasm when uploading the recording clip. The table below lists each valid template value and an example of what the value looks like.

| Template name       | Example Value                             |
|---------------------|-------------------------------------------|
| kasm_id             | 386b2eef-9bfb-443f-9eb6-6ee3331c38b4      |
| user_id             | 4dabe919-c5e9-4839-9bf3-07675f08a507      |
| username            | admin@kasm.local                          |
| image_id            | 3ea00a8b-7598-408d-8574-dbebc8304ff4      |
| image_friendly_name | windows                                   |
| created_timestamp   | 2023-12-12 21:12:45.386547                |
| created_date        | 2023-12-09                                |
| start_timestamp     | 2023-12-13 20:27:13.853047                |
| start_date          | 2023-12-10                                |
| current_epoch       | 1706554545220 (in millisecond resolution) |

## RDP, VNC, and SSH

The connection proxy, which relies on Guacamole, records RDP, VNC, and SSH sessions in a rolling fashion, breaking the data into 150MB segments. These segments are initially stored in an intermediate format and are later converted into a playable video using the guacenc encoding tool. These are video only recordings, audio from the session, or recording of what the user says into their microphone is not recorded.
If recording is set to true and the system is unable to initiate recording, for instance because the connection_proxy has run out of space, or because the global settings are invalid, then the session is not provisioned for the user to prevent an unrecorded session the administrator intended to be recorded.

### Resource Considerations

It's important to note that session recording involves CPU-intensive video encoding. The number of videos that can be concurrently encoded is controlled by the **Session Recording Queue Length** setting. Each concurrent video encoding process typically utilizes one CPU core. To prevent negative impact on session performance, adequate resources should be allocated to the connection proxy.
Additionally, session recording requires local storage space for the real-time encoding of active sessions. As a general guideline, at least 1GB of local storage should be available for each connected user. The system will prevent new users from connecting if the available local storage falls below 500MB and session recording is required for the connecting user.

### Failure Recovery

In cases where there are interruptions in user connectivity or instances of reconnection, the system will still proceed with the encoding and uploading of pending session recordings. This guarantees that no session data is lost due to these disruptions.
If there are any problems with the upload process, the recorded files will be retained on local storage. The system will continue to attempt to upload these files periodically. The duration for which these files will be locally retained is controlled by the **Session Recording Retention Period** setting.

## Viewing Session Recordings

```{note}
Users will need the **SESSIONS_VIEW** group permission to view the **session history** page.
Users will need the **SESSION_RECORDINGS_VIEW** group permission to be able to view the session recordings on the **session history** page. 
```

There is a new administration page under **Sessions->History** that displays a history of all past sessions. 

```{figure} /images/session_recording/session_history_view.webp
:align: center
**Session History**
```

This is also where users can view the recordings for each session. If session recordings are available there is a side arrow for that session row that will expand to allow selecting either a download or a view option.

```{figure} /images/session_recording/recording_view_download_options.webp
:align: center
**View and Download options**
```

Clicking the download button will zip up and download all clips for that session. For the **Download All** option to work the s3 bucket must be configured for CORS. See the section on setting up s3 bucket CORS configuration below.

A log similar to `User admin@kasm.local downloaded entire session: 10307f51fd2749f3a84a7aaa2f81d26e` will be generated whenever a User downloads all recordings for a session. This allows an administrator to track when recordings are downloaded.

```{figure} /images/session_recording/session_recording_download_all.webp
:align: center
**Download All**
```

When clicking on the preview (eye) icon the user is taken to a screen that lists all the clips for the session along with thumbnails, a download button (small cloud icon with a down arrow next to the clip number) for each individual clip, and a video playback window. For the Download button to work the s3 bucket must be configured for CORS. See the section on setting up s3 bucket CORS configuration below. 

Clicking on the video player window will initiate playback of the selected clip. 

A log similar to `User admin@kasm.local played 10307f51fd2749f3a84a7aaa2f81d26e video: s3://kasm_session_recordings@storage.googleapis.com/recordings/admin@kasm.local/2023-12-08/10307f51-fd27-49f3-a84a-7aaa2f81d26e.1702066120.mp4` will be generated whenever a User plays a recording for a session. This allows an administrator to track when recordings are viewed.

Clicking the download button will allow the user to download the individual clip that is selected.

A log similar to `User admin@kasm.local downloaded 10307f51fd2749f3a84a7aaa2f81d26e video: s3://kasm_session_recordings@storage.googleapis.com/recordings/admin@kasm.local/2023-12-08/10307f51-fd27-49f3-a84a-7aaa2f81d26e.1702066120.mp4` will be generated whenever a User plays a recording for a session. This allows an administrator to track when recordings are viewed.

```{figure} /images/session_recording/session_recording_preview.webp
:align: center
**Preview**
```

## S3 CORS configuration

When utilizing the download options for the recording clips there are CORS settings on the s3 bucket that have to be configured. Two providers are covered here, Amazon S3, and GCP cloud storage.

### Amazon S3

Select the Amazon S3 bucket that will be used for storing session recordings. Select the permissions tab and scroll down until you see the *Cross-origin resource sharing (CORS)* section click edit and configure it as below replacing https://kasm.acme.com with the appropriate origin (the Kasm domain).

```{figure} /images/session_recording/session_recording_amazon_s3_CORS_permissions.webp
:align: center
**Amazon S3 Bucket Permissions**
```

```{figure} /images/session_recording/session_recording_amazon_s3_CORS.webp
:align: center
**Amazon S3 Bucket CORS permissions**
```

```{code-block} json
:caption: '**CORS configuration**'

[
    {
        "AllowedHeaders": [
            "*"
        ],
        "AllowedMethods": [
            "GET",
            "PUT",
            "POST",
            "DELETE"
        ],
        "AllowedOrigins": [
            "https://kasm.acme.com"
        ],
        "ExposeHeaders": []
    }
]
```

### GCP Cloud Storage

Like Amazon S3 GCP cloud storage buckets need to have CORS configuration applied for Kasm to be able to provide the download access for recording clips. GCP only supports bucket CORS configuration through the commandline gcloud client. Download and install the [gcloud client](https://cloud.google.com/sdk/docs/install) follow the instructions to apply a [CORS configuration](https://cloud.google.com/storage/docs/using-cors#command-line) the following is an example configuration that should work when replacing https://kasm.acme.com with the Kasm domain of the installation.

```{code-block} json
:caption: '**CORS configuration**'

[
    {
      "origin": ["https://kasm.acme.com"],
      "method": ["GET", "PUT", "POST", "DELETE"]
    }
]
```