Egress

Kasm Workspaces allows for the Kasm Administrator to define an Egress Provider, which contains a collection of Egress Gateways that can be selected upon Workspace launch to tunnel all of a Workspace’s network traffic.

Administrators may use the Egress feature to grant access to secure environments via a VPN or have Kasm traffic be routed through a location geographically separated from the Kasm Deployment.

Egress Providers can be mapped to a Workspace, User or Group in order to allow for a user to select an Egress Gateway when launching their Kasm Workspace.

An Egress Credential can also be created on a Workspace, Group or User which allows for the Credential to be used when making a connection to the Egress Gateway. These may be a Username and Password for an OpenVPN Provider, a Private Key for Wireguard.

The following is an example of the new Egress Selection menu presented when a User launches a Workspace:

../_images/egress_selection.webp — **Egress Launch Selection**

Gateway Selection Behavior

Egress Providers and Egress Credentials can be applied to Users, Groups and Workspaces.

When users attempt to launch a Kasm they will be presented with a list of available Gateways. Gateways are only shown if they are enabled and there is credential for the same Provider mapped to the selected Workspace, the User or any of the User’s groups.

A Credential can be paired with a Gateway even if they are mapped to different resources. For instance the User “user@kasm.local” can use a Gateway attached to “All Users” group with a credential attached to “user@kasm.local”.

The first matching, enabled credential in a list credentials sorted by their egress_credential_id will be automatically selected to be used when a user specifies an Egress Gateway when launching a Workspace. Manually specifying an Egress Credential on Workspace launch is not currently supported.

If a Credential has Limit Active Connections enabled and the number of concurrent connections using that credential has reached the limit it will not be available to be used on a new Egress credential until a Kasm Session using the credential have ended.

Configuration

In this example we will be configuring an OpenVPN provider, but Wireguard is also supported.

Creating Provider and Gateways

Log into the Kasm Web UI as an administrator
Click Infrastructure -> Egress
Click Add

../_images/egress_provider_form.webp — **Egress Provider Form**

Name	Description
Enabled	Enable or disable this configuration
Name	The Unique Name for the Egress Provider
Egress Provider Type	The type of Egress Provider Configuration
Enable New Managed Gateways	(Managed Egress Provider Only) When enabled any new Egress Gateways sent by the Egress Plugin Service will be automatically enabled.

Fill out the form and click Save
A list of all Egress Providers is shown.

../_images/egress_provider_list.webp — **Egress Provider List**

Click the arrow menu on the OpenVPN Provider and Select Edit
Select the Egress Gateway tab and click Add

../_images/egress_gateway_form.webp — **Egress Gateway Form**

Name	Description
Enabled	Enable or Disable this configuration.
Name	The Unique Name for the Egress Gateway
Country	The Country for the Egress Gateway
City	The City for the Egress Gateway
Config	The Egress Gateway Config (OpenVPN, Wireguard or Custom)

Note

For Wireguard Configurations the PrivateKey value in Config is set by the Egress Credential.

Assigning Provider and Credentials

Provider Assignments and Credential creation can be done on Users, Groups and Workspaces. In this example we will be performing an Assignment on the User user@kasm.local.

Log in to the Kasm Web UI as Administrator
Click Access Management -> Users
Click the arrow menu on user@kasm.local and select Edit.
Click on the Egress tab and select Add

../_images/egress_provider_mapping_form.webp — **Egress Provider Mapping Form**

Name	Description
Enabled	Enable or Disable this configuration.
Egress Provider	The name of the Egress Provider to Map.
Allow All Gateways	When Enabled, all Egress Gateways in the selected Provider will be mapped. Disabling requires that the Admin specify which gateways to map in the Selected Gateways field.
Selected Gateways	When Allow All Gateways is enabled this setting sets the gateways that apply to this mapping.

Fill out the form and click Save
Click on the Egress Credential tab.

../_images/egress_credential_form.webp — **Egress Credentials Form**

Name	Description
Enabled	Enable or Disable this configuration.
Egress Provider	The name of the Egress Provider for this Credential.
Name	The name of this Egress Credential.
Username	The Username for the Egress Credential (OpenVPN Provider)
Password	The Password for the Egress Credential (OpenVPN Provider)
Private Key	The Wireguard Private Key for the Egress Credential (Wireguard Provider)
Custom Credential	The Custom Credential for the Egress Credential (Custom Provider)
Allow All Gateways	When Enabled, the Credential will apply to all Egress Gateways in the selected Provider. Disabling requires that the Admin specify which gateways to map in the Selected Gateways setting.
Selected Gateways	When Allow All Gateways is enabled, this sets the gateways that this Credential can be used with.
Limit Active Connections	When Enabled, the number of concurrent connections that this Egress Credential can be used in is limited to the setting in Active Connection Limit.
Active Connection Limit	When Limit Active Connections is enabled, this value sets the maximum number concurrent connections the credential can be used in.

Now that the Egress Provider and Credential are assigned to this user, they may select the Egress Gateway when launching a Container Workspace.

Implementation

The egress implementation in Kasm Workspaces relies on a Docker network plugin that fully manages container’s network setup, including creating the necessary network interfaces, configuring IP tables rules, and establishing VPN connections.

The primary source of information about the setup status is the implementation logs located at /var/log/kasm-sidecar/network-sidecar.log. These logs are also accessible in the admin panel under the Diagnostics->Logging section and contain details about the creation of network interfaces, IP tables rules and VPN connections.

Logs related to Docker engine calls by the plugin are stored in /var/log/kasm-sidecar/plugin.log. These logs provide insight into the interactions between the Kasm sidecar and the Docker engine and can help verify that a container is connected through the plugin.

The plugin stores all container-related files, including all used configuration files, which can be found at /var/run/kasm-sidecar/$container_namespace. The network namespace name of the container can be identified from the network-sidecar.log logs.

Tip

A quick way to query a container namespace is by using the following command: docker inspect -f '{{.NetworkSettings.SandboxKey}}' $container_name | grep -o -E "[a-h0-9]+$".

Troubleshooting

Whenever a session container fails to connect to an egress gateway, the user will be shown an error message.

../_images/egress_error_status.png — **Egress error message**

While the container will continuously attempt to connect to the egress gateway upon reloading, the following guidelines can be used for troubleshooting:

Check the plugin status:

Run docker plugin ls to verify that the plugin is running and enabled.
Check the plugin logs:

Review the logs at /var/log/kasm-sidecar/network-sidecar.log for any errors or warnings related to the network or VPN connection setup.
Check the used VPN configuration file:

Verify that the VPN configuration file used by the plugin is correct and that the VPN connection was established. The file can be found in /var/run/kasm-sidecar/$container_namespace/$vpn, ie: /var/run/kasm-sidecar/b8a8cbe7c027/wg/wg.conf.
Check that kasm_proxy is connected to the plugin’s network:

Run docker exec -it kasm_proxy ip a to confirm that the kasm_proxy container is connected to the plugin’s network bridge. The interface name should follow the pattern k-p-p-*.
Check the container network interface:

Run docker exec -it kasm_proxy ip a to confirm that a network interface connected to the plugin’s network bridge has been created for the container. The interface name should follow the pattern k-p-p-*.
Check the container route table:

Run docker exec -it kasm_proxy ip route to verify that the container’s route table includes the routes using the plugin’s network interface, ie:
```
default via 172.20.0.1 dev k-p-1389f8
172.20.0.0/16 dev k-p-1389f8 proto kernel scope link src 172.20.0.3
```

Check the container hostname resolution:

The container’s /etc/hosts file should include an entry corresponding to the KASM_API_HOST environment variable defined within the container. An example of a correct setup is:

> docker exec -it $CONTAINER_NAME env | grep KASM_API_HOST
KASM_API_HOST=proxy

> docker exec -it $CONTAINER_NAME cat /etc/hosts
fe00::0     ip6-localnet
ff00::0     ip6-mcastprefix
ff02::1     ip6-allnodes
ff02::2     ip6-allrouters
172.20.0.2  proxy
172.20.0.3  505c32d766d9

Check the container IP tables rules:

Run nsenter --net=$container_namespace iptables -L -v -n to verify that the container’s IP tables rules include the necessary rules. An example of a correct setup is:

Chain INPUT (policy ACCEPT 0 packets, 0 bytes)
pkts    bytes   target     prot opt in          out     source               destination
   131K    ACCEPT     0    --  k-p-1389f8  *       172.20.0.2           0.0.0.0/0 # <-- kasm_proxy IP address
 4534K   ACCEPT     0    --  lo          *       0.0.0.0/0            0.0.0.0/0
     0       ACCEPT     0    --  tun0        *       0.0.0.0/0            0.0.0.0/0
    7620    ACCEPT     0    --  wg          *       0.0.0.0/0            0.0.0.0/0
     0       ACCEPT     0    --  *           *       172.20.0.0/16        0.0.0.0/0 # <-- kasm_sidecar_network IP range
    9644    ACCEPT     0    --  *           *       XXX.XXX.XX.XX        0.0.0.0/0 # <-- VPN server IP

Chain OUTPUT (policy ACCEPT 0 packets, 0 bytes)
pkts    bytes   target     prot opt in     out     source               destination
    16678   ACCEPT     6    --  *      k-p-1389f8   0.0.0.0/0            172.20.0.2           tcp dpt:443 # <-- kasm_proxy IP address
 4534K   ACCEPT     0    --  *      lo           0.0.0.0/0            0.0.0.0/0
     0       ACCEPT     0    --  *      tun0         0.0.0.0/0            0.0.0.0/0
    2340    ACCEPT     0    --  *      wg           0.0.0.0/0            0.0.0.0/0
  4567K   ACCEPT     0    --  *      *            0.0.0.0/0            172.20.0.0/16 # <-- kasm_sidecar_network IP range
    4464    ACCEPT     0    --  *      *            0.0.0.0/0            XXX.XXX.XX.XX # <-- VPN server IP

In case of issues not caused by a VPN misconfiguration (as described by steps 4-8), the following script can be used to restart the plugin:

Warning

Before running the script, ensure that no workspaces using the egress feature are running on the agent where the plugin is being restarted.

# disconnect kasm_proxy from the plugin network
plugin_name=$(docker network inspect kasm_sidecar_network --format '{{.Driver}}')
docker network disconnect kasm_sidecar_network kasm_proxy

# restart the plugin
docker network rm kasm_sidecar_network
docker plugin disable $plugin_name
docker plugin enable $plugin_name

# reconnect kasm_proxy to the plugin network
docker network create -d $plugin_name kasm_sidecar_network
docker network connect kasm_sidecar_network kasm_proxy

Managed Egress Providers

Kasm allows for Licenses to be purchased that grant a number of connections to a Managed Egress Provider.

When a license that grants the use of an Managed Egress Provider is applied to the Kasm Workspaces deployment, Kasm Workspaces automatically reaches out to the Kasm Egress Plugin Service to obtain a list of Egress Accounts and Egress Providers and adds them to the Kasm Deployment.

For example the following screenshot is of the Egress Providers section on a deployment that has a License applied that grants 5 connections to the PureVPN Managed Egress Provider.

../_images/managed_egress_provider_list.webp — **Egress Provider List Containing PureVPN Managed Egress Provider**

../_images/managed_egress_provider_details.webp — **Egress Provider Details for PureVPN Managed Egress Provider**

Using these Managed Egress Providers is as simple as mapping them to a User, Group, or Workspace.

Note

Managed Egress providers do not require the creation of Egress Credentials, they only require mapping the Egress Provider to a User Group or Workspace.

../_images/managed_egress_provider_mapping.webp — **PureVPN Managed Egress Provider Mapped to the “All Users” Group**

Egress Plugin System Info

When a license is added that grants connections for a Managed Egress Provider, it creates a “Egress Plugins” Tab in Diagnostics->System Info, which contains summarized information about all the Egress Plugins for all the Licenses on the Kasm Workspaces Deployment.

Listed below are the fields in the Egress Plugins table:

Name	Description
Egress Plugin ID	The ID of the Egress Plugin.
Accounts	The number of Managed Egress Accounts currently provisioned on this Kasm Workspaces Deployment for this Plugin.
Allowed Connections	The total number of allowed connections permitted by all the licenses on the Kasm Workspaces Deployment for this Plugin
Remaining Connections	The number of remaining available connections for this plugin. This is based on the number of accounts provisioned on the system and the the number of Workspaces sessions currently using an Egress Connection.

Egress Plugin License Info

Information about the Managed Egress Providers granted by an individual license can be viewed by logging into the Kasm Workspaces Admin UI and navigating to Diagnostics->System Info->Licenses and then selecting the “View” button on an individual license and then scrolling to the “Egress Plugins” section.

The first entry is a table containing a list of the Egress Plugins granted by the license:

Name	Description
Egress Plugin ID	The ID of the Egress Plugin.
Accounts	The number of Managed Egress Accounts currently provisioned on this Kasm Workspaces Deployment for this Plugin on this License.
Allowed Connections	The total number of allowed connections permitted by this license on the Kasm Workspaces Deployment for this Plugin.
Remaining Connections	The number of remaining available connections for this Plugin on this License. This is based on the number of accounts provisioned on this system and the number of Workspaces sessions currently using an Egress connection.

Next are a number of fields that show Egress Plugin information for the License:

Name	Description
Is License Valid	The License validity according to the Egress Plugin Service.
Is Entitlement Valid	The License Entitlement validity according to the Egress Plugin Service.
Next Egress Plugin Check In	The next time Kasm Workspaces will attempt to query the Egress Plugin Service to update Managed Egress Accounts and Managed Egress Providers for this License.
Last Egress Plugin Check In	The last time this License was checked in to the Egress Plugin Service.

Managed Egress Provider Info

When a license is added that grants access to Managed Egress providers, additional information about the Egress Providers can be found by logging into Kasm Administrator UI, navigating to Infrastructure->Egress and selecting Edit on a Managed Egress Provider and then navigating to Details and then scrolling down to the Egress Plugins section.

The section contains the following:

Name	Description
Is Managed	Wether the Egress Provider is managed by an Egress Plugin.
Egress Plugin ID	The ID of the Egress Plugin that Manages this Egress Provider.
Egress Plugin Account Count	The number of Managed Egress Accounts currently provisioned on this Kasm Workspaces Deployment for this Managed Egress Provider.
Egress Plugin Active Connections	The number Kasm Connections currently using this Manage Egress Provider
Egress Plugin Remaining Connections	The number of remaining available connections for this Managed Egress. This is based on the number of accounts provisioned on this system and the number of active connections.