--- myst: html_meta: "description lang=en": "How to configure user dashboard entries for connecting to Containers, Servers, Server Pools, and Web Links." "keywords": "Kasm, Workspaces, Images, Configuration, Dashboard Items" "property=og:locale": "en_US" --- ```{title} Workspaces ``` # Workspaces Kasm Workspaces allows administrators to define workspaces that users can use to access a desktop, a single application, or another webpage. There are four types of workspaces that can be defined in Kasm Workspaces. Those are: **Containers**, **Servers**, **Server Pools**, and **Links** ## Add Edit Workspaces From the Workspaces menu you can edit existing Workspaces or add new Workspaces. Each Workspace has a number of properties, the following properties are common for each Workspace type. ```{eval-rst} +----------------------------------+-----------------------------------------------------------------------------------+ | **Name** | **Description** | +----------------------------------+-----------------------------------------------------------------------------------+ | Workspace Type | The type of Workspace, options are Container, Server, Server Pool and Link. | +----------------------------------+-----------------------------------------------------------------------------------+ | Friendly Name | Workspace name shown to user. | +----------------------------------+-----------------------------------------------------------------------------------+ | Description | Description of Workspace. | +----------------------------------+-----------------------------------------------------------------------------------+ | Thumbnail URL | (Optional) URL of Workspace icon. | +----------------------------------+-----------------------------------------------------------------------------------+ | Enabled | The Workspace is enabled for use. If unchecked the Workspace | | | will not be available for users to provision. For Container type Worksapaces | | | Agents will not be given instructions to download Images that are disabled. | +----------------------------------+-----------------------------------------------------------------------------------+ | Categories | (Optional) Define a list of categories the Workspace belongs to. These categories | | | will be displayed on the Workspaces dashboard for uses to select. The first | | | category listed is the one displayed for the Workspace when looking at a list of | | | all Workspaces. | +----------------------------------+-----------------------------------------------------------------------------------+ | Hide Workspace on Dashboard | Do not show the Workspace as available on the user dashboard. | +----------------------------------+-----------------------------------------------------------------------------------+ | Notes | (Optional) A free form field used for taking notes about the Workspace. | | | This is only displayed when editing or viewing a Workspace configuration. | | | This is a great way to let other admins know about anything specific | | | to this Workspace. | +----------------------------------+-----------------------------------------------------------------------------------+ ``` ```{note} The Workspaces are by default added to the all users group. This behavior can be changed with the [Add Workspaces To Default Group](settings) server setting. ``` (Workspaces_Containers)= ## Containers **Containers** are what have been traditionally referred to as images in the Kasm Workspaces ecosystem. These are Linux docker images that have applications installed, that are then provision by docker as containers and streamed to the user over KasmVNC. See {doc}`Images ` for more details on available default docker images and creating custom docker images. Attributes that are specific to **Container** type Workspaces are below: ```{eval-rst} +----------------------------------+-----------------------------------------------------------------------------------+ | **Name** | **Description** | +----------------------------------+-----------------------------------------------------------------------------------+ | Docker Image | The Docker Image and tag. | +----------------------------------+-----------------------------------------------------------------------------------+ | Cores | Amount of CPU cores allocated per Workspace. | +----------------------------------+-----------------------------------------------------------------------------------+ | Memory | Amount of Memory allocated per Workspace, in megabytes. | +----------------------------------+-----------------------------------------------------------------------------------+ | GPU Count | When the session is created, the system will map in this many GPUs into the | | | the container. See `Agent Settings `_. | +----------------------------------+-----------------------------------------------------------------------------------+ | CPU Allocation Method | Sets the CPU Allocation Method for the Workspace. Selecting **Inherit** will cause| | | the Workspace to use the Global Setting **Default CPU Allocation Method**. | | | See :ref:`cpu-resource-allocation` for more details. | +----------------------------------+-----------------------------------------------------------------------------------+ | Docker Registry | The docker registry to pull the docker images from | | | For Docker Hub use https://index.docker.io/v1/ | | | Leave this option blank if you intend to use local | | | images built directly on the Agent server. | +----------------------------------+-----------------------------------------------------------------------------------+ | Docker Registry Username | (Optional) Username. | +----------------------------------+-----------------------------------------------------------------------------------+ | Docker Registry Password | (Optional) Password. | +----------------------------------+-----------------------------------------------------------------------------------+ | Hash | (Optional) hash of docker image. | +----------------------------------+-----------------------------------------------------------------------------------+ | Persistent Profile Path | (Optional) Absolute path of the location to store | | | user's persistent profile. See | | | `Persistent Profiles <../how_to/persistent_profiles.html>`_ | | | for more details. | +----------------------------------+-----------------------------------------------------------------------------------+ | Volume Mappings | (Optional) Json data for | | | `Volume Mappings <..guide//persistent_data/volume_mapping.html>`_. | +----------------------------------+-----------------------------------------------------------------------------------+ | Docker Run Config Override | (Optional) Json data for specifying additional | | | docker run arguments, see `Docker Run Config`_ for more info. | +----------------------------------+-----------------------------------------------------------------------------------+ | Docker Exec Config | (Optional) Json data for specifying commands | | | to be executed when a Workspace container is started or resumed. | | | See the `Docker Exec Config`_ for details. | +----------------------------------+-----------------------------------------------------------------------------------+ | Web Filter Policy | Enables web filtering and sets the | | | :doc:`Web Filter Policy <../../guide/web_filtering>` to be used. Policies can | | | also be set via Group Settings. Policies assigned to Workspaces take priority over| | | those defined via Group Settings. Selecting **Inherit** will instruct the system | | | to use a policy if defined on a Group Setting. Selecting **Force Disabled** will | | | instruct the system to not use a policy even if one is defined in a Group Setting.| +----------------------------------+-----------------------------------------------------------------------------------+ | Allow Network Selection | When enabled, users will be presented with a dropdown of available docker | | | networks when creating a session. The list of available networks can be | | | limited if **Restrict Workspace to Docker Network** is configured. | +----------------------------------+-----------------------------------------------------------------------------------+ | Restrict Workspace to Docker | (Optional) Instances of this Workspace will only | | Network | be created on agent servers with this docker | | | network. | +----------------------------------+-----------------------------------------------------------------------------------+ | Restrict Workspace to Kasm Agent | (Optional) Instances of this Workspace will only | | | be created on this agent server. | +----------------------------------+-----------------------------------------------------------------------------------+ | Restrict Workspace to Deployment | (Optional) Instances of this Workspace will only | | Zone | be created on Agents within the selected | | | :term:`Deployment Zone`. | +----------------------------------+-----------------------------------------------------------------------------------+ | Session Time Limit | The amount of time (in seconds) before a session will automatically expire. | | | A countdown timer will be displayed to the user. | +----------------------------------+-----------------------------------------------------------------------------------+ ``` ### Docker Exec Config The Docker Exec configurations allow administrators to configure custom commands to be executed when a user creates or resumes a Kasm. This JSON dictionary configuration accepts three top-level keys **first_launch**, **go**, and **assign**. - first_launch : This command is executed after the session is launched. - go : This command is executed when the user requests to create or resume a session via the /go url. If the session doesn't exist yet, and will be created for the first time, the **first_launch** command will take priority. If the user is assigned a {doc}`Staged Session ` as part of the request, the **assign** command will take priority. - assign : This command is executed when the user is assigned a {doc}`Staged Session ` via direct request, the /go url, or via {code}`request_kasm` api The following example demonstrates how to use the Docker Exec Config for the default **kasmweb/chrome** Image for a seamless browser isolation configuration. See [Browser Isolation](browser_isolation) for more details. ```Javascript { "first_launch": { "cmd": "bash -c 'google-chrome --start-maximized \"$KASM_URL\"'", "environment": { "LAUNCH_URL": "" } }, "go": { "cmd": "bash -c 'google-chrome --start-maximized \"$KASM_URL\"'" }, "assign": { "cmd": "bash -c 'google-chrome --start-maximized \"$KASM_URL\"'" } } ``` (docker-run-config)= ### Docker Run Config The Docker Run Config Override setting may be used by administrators to pass custom docker run options when the session container is created. Many items that can be invoked by the `docker run` commandline tool can be defined in the json structure mirroring the keyword arguments defined in the docker python API `Container.run` function. Detailed specs can be found in the [Docker SDK for Python Documentation](https://docker-py.readthedocs.io/en/stable/containers.html#docker.models.containers.ContainerCollection.run) #### Examples **Setting environment variables.** ```Javascript { "environment": { "FOO": "BAR", "BIN" : "BAZ" } } ``` **Setting the container hostname.** ```Javascript { "hostname": "HOST-123" } ``` **Setting the user. see {doc}`Running as root <../how_to/running_as_root>` for more details** ```Javascript { "user": "root" } ``` **Mapping in devices.** ```Javascript { "devices": [ "/dev/input/event0:/dev/input/event0:rwm", "/dev/net/tun:/dev/net/tun:rwm" ] } ``` **Adjusting security options.** ```Javascript { "security_opt": [ "seccomp=unconfined" ] } ``` **Adjusting the size of /dev/shm.** ```Javascript { "shm_size" : "4g" } ``` **Running the container as privileged.** ```Javascript { "privileged" : true } ``` **Adding / Removing Linux Kernel capabilities.** ```Javascript { "cap_add" : ["SYS_ADMIN", "MKNOD"], "cap_drop" : ["SYS_RESOURCE"] } ``` ## Links **Links** are a way to define another webpage that will be presented in the workspaces dashboard for users to access. This could be a company website like time sheet tracking or a ticketing system, or an external website such as Google Drive or microsoft OneDrive. Attributes that are specific to **Link** type Workspaces are below: ```{eval-rst} +----------------------------------+-----------------------------------------------------------------------------------+ | **Name** | **Description** | +----------------------------------+-----------------------------------------------------------------------------------+ | URL | The URL to direct the user to when clicking on this Workspace in the dashboard. | +----------------------------------+-----------------------------------------------------------------------------------+ ``` ## Servers **Servers** are workspaces intended to define a single physical or virtual server. This server can be connected to from Kasm Workspaces via KasmVNC or RDP. Attributes that are specific to **Server** type Workspaces are below: ```{eval-rst} +----------------------------------+-----------------------------------------------------------------------------------+ | **Name** | **Description** | +----------------------------------+-----------------------------------------------------------------------------------+ | Server | Dropdown to select the defined Server entity to use for this Workspace. | +----------------------------------+-----------------------------------------------------------------------------------+ | Session Time Limit | The amount of time (in seconds) before a session will automatically expire. | | | A countdown timer will be displayed to the user. | +----------------------------------+-----------------------------------------------------------------------------------+ ``` ## Server Pools **Server Pools** are groups of **Servers** that are to be treated equally be Kasm Workspaces. These server instances don't need to be identical but Kasm Workspaces will treat each server in a **Server Pool** as interchangeable. For instance, you may have a Windows server that has Microsoft Office installed, and have a Linux Ubuntu server with LibreOffice installed Kasm workspaces will use which ever of the servers is available when a user requests a server form this server pool. Attributes that are specific to **Server Pool** type Workspaces are below: ```{eval-rst} +----------------------------------+-----------------------------------------------------------------------------------+ | **Name** | **Description** | +----------------------------------+-----------------------------------------------------------------------------------+ | Pool | Dropdown to select the defined Server Pool entity to use for this Workspace. | +----------------------------------+-----------------------------------------------------------------------------------+ | Session Time Limit | The amount of time (in seconds) before a session will automatically expire. | | | A countdown timer will be displayed to the user. | +----------------------------------+-----------------------------------------------------------------------------------+ ```