Devolutions Gateway configuration on Linux

Installing and running Devolutions Gateway on Linux is quick and easy, provided that several prerequisites are met. Ubuntu 22.04 LTS was used to demonstrate the installation and configuration.

Devolutions Server or Devolutions Cloud is required for the configuration as well as a Devolutions Gateway license.

Install Devolutions Gateway

1. Navigate to the Devolutions Gateway GitHub Release page and download the .deb file of the latest release.
2. Input the following using the command-line: wget https://github.com/Devolutions/devolutions-gateway/releases/download/v2024.3.2/devolutions-gateway_2024.3.2.0_amd64.deb

   
3. Install the package using the dpkg utility: sudo dpkg -i devolutions-gateway_2024.3.2.0_amd64.deb

   

   The configuration and binary packages are in the following locations:

   • Configuration: /etc/devolutions-gateway
   • Binary: /usr/bin/devolutions-gateway

Update Devolutions Gateway

To update Devolutions Gateway on Linux download the latest package as explained in the previous section and run the installation command. The package will install over the existing installation and preserve configurations.

Install the PowerShell gateway module

It is recommended to use the PowerShell gateway module to configure and manage the Devolutions Gateway instance on Linux.

1. Install PowerShell with this command:

   source /etc/os-release
   wget -q https://packages.microsoft.com/config/ubuntu/$VERSION_ID/packages-microsoft-prod.deb
   sudo dpkg -i packages-microsoft-prod.deb
   rm packages-microsoft-prod.deb
   sudo apt-get update
   sudo apt-get install -y powershell

2. Install the Devolutions Gateway PowerShell module:

   Install-Module -Name DevolutionsGateway
   Import-Module -Name DevolutionsGateway

Once installed the Devolutions Gateway configuration can be started, stopped, viewed or modified.

Configure certificates

Proper trust of certificates between systems is key to making Devolutions Gateway work. Functionalities such as WebSockets used in web dashboard views of RDP, SSH, etc., require a properly trusted certificate. A certificate from an official authority such as Let's Encrypt would be ideal for most production systems. Self-signed certificates, such as the example shown below, may be generated but require additional configuration for trust. You may generate certificates on any system and use them within Devolutions Gateway if it adheres to the certificate requirements.

Generate a LetsEncrypt certificate on Ubuntu 22.04 LTS via Certbot

One option is to generate a LetsEncrypt certificate with the Certbot utility. To install the latest version, you may use the snap package manager. Depending on the Ubuntu distribution, the default APT repositories may not contain the latest version of the software. In this example, the domain verification is used with Cloudflare as the DNS provider.

1. The example below demonstrates running Certbot installed and running as the root user, but Devolutions Gateway as a different user.

   sudo snap install certbot --classic
   sudo snap set certbot trust-plugin-with-root=ok
   sudo snap install certbot-dns-cloudflare

2. When using Cloudflare, generate either a user or account-scoped API token, using the Edit zone DNS template. Once you have the API token, create the containing folder and corresponding .ini file to contain the API token.

   sudo install -d -m 0700 /root/.secrets
   sudo nano /root/.secrets/cloudflare.ini
   sudo chmod 0600 /root/.secrets/cloudflare.ini

3. Request a certificate for your Devolutions Gateway domain using the Cloudflare DNS plugin. Replace the gateway.mydomain.com value below with your own domain.

   certbot certonly --dns-cloudflare --dns-cloudflare-credentials /root/.secrets/cloudflare.ini -d gateway.mydomain.com --cert-name gateway

4. Modify your gateway.json configuration file to add the following lines and use the newly generated certificate, using the Devolutions Gateway PowerShell module. The commands below modify the TlsCertificateFile, TlsPrivateKeyFile, and Listeners configuration variables.

   Import-Module DevolutionsGateway
   Set-DGatewayConfig -TlsCertificateFile "/etc/letsencrypt/live/gateway/fullchain.pem" -TlsPrivateKeyFile "/etc/letsencrypt/live/gateway/privkey.pem" -Listeners @(
   @{
           "InternalUrl" = "tcp://*:8181"
           "ExternalUrl" = "tcp://*:8181"
       }
       @{
           "InternalUrl" = "https://*:7171"
           "ExternalUrl" = "https://*:7171"
       }
   )

5. Before you can restart Devolutions Gateway to use the new certificate, you must allow the user running Devolutions Gateway to read the certificate files. This assumes your user is named devolutions and that the certificate is named gateway. You are giving traversal rights to the directories and read rights to the certificate files themselves.

   sudo setfacl -R -m u:devolutions:x /etc/letsencrypt/live
   sudo setfacl -R -m u:devolutions:x /etc/letsencrypt/live/gateway
   sudo setfacl -R -m u:devolutions:x /etc/letsencrypt/archive
   sudo setfacl -R -m u:devolutions:x /etc/letsencrypt/archive/gateway
   sudo setfacl -m u:devolutions:r /etc/letsencrypt/live/gateway/fullchain.pem
   sudo setfacl -m u:devolutions:r /etc/letsencrypt/live/gateway/privkey.pem
   sudo setfacl -m u:devolutions:r /etc/letsencrypt/archive/gateway/fullchain*.pem
   sudo setfacl -m u:devolutions:r /etc/letsencrypt/archive/gateway/privkey*.pem
   
   # Reconfigure to add a deploy hook
   sudo certbot reconfigure --cert-name gateway --deploy-hook "sudo setfacl -m u:devolutions:r /etc/letsencrypt/archive/gateway/fullchain*.pem; sudo setfacl -m u:devolutions:r /etc/letsencrypt/archive/gateway/privkey*.pem; systemctl restart devolutions-gateway.service"

6. Restart Devolutions Gateway using either the systemctl command or the Devolutions Gateway PowerShell module.

   # Restart Gateway using systemctl
   systemctl restart devolutions-gateway.service

   # Restart Gateway using the Devolutions Gateway PowerShell module, assuming it is run in a pwsh shell.
   Import-Module DevolutionsGateway; Restart-DGateway

Renew LetsEncrypt certificate

By default, with the Snap installation method, a systemd timer is used (instead of a cron job), which runs twice a day (though only renews a certificate within 30 days of its expiration). To force a renewal, you can use the command below.

sudo certbot renew
# To perform a renewal dry run and force a restart of the service, you can use the following command:
# sudo certbot renew --dry-run --run-deploy-hooks

Generate a self-signed certificate on Ubuntu 22.04 LTS via OpenSSL

Using the OpenSSL utility, generate a certificate directly from the command line. The certificate then needs to be placed directly into the configuration directory /etc/devolutions-gateway.

sudo openssl req -x509 -subj "/C=CA/ST=Quebec/L=Lavaltrie/O=Devolutions/CN=ubuntu-2204" -addext "subjectAltName = IP:10.10.0.20" -addext "extendedKeyUsage = serverAuth" -nodes -days 365 -newkey rsa:2048 -keyout /etc/devolutions-gateway/server.key -out /etc/devolutions-gateway/server.crt

The certificate request will look different for every configuration.

Note that the certificate must include a Subject Alternative Name (SAN) extension with either a DNS name or an IP address, and it should also contain the Extended Key Usage (EKU) extension with the Server Authentication purpose (serverAuth). This is required because modern operating systems and browsers, including Google Chrome and macOS, will reject certificates that are missing a SAN or the appropriate EKU, even if the Common Name (CN) is set. It’s possible to relax this requirement by setting the TlsVerifyStrict option to false if necessary, but this is not recommended.

Customization options	Explanation
req	Create and process certificate requests including self-signed certificates in PKCS#10 format.
-x509	Output a self-signed certificate.
-subj	Define the certificate subject on the command-line. There must be no spaces between sections /C - Country in 2-digit code such as “CA” for Canada or “US” for United States. /ST - State or Province, such as Quebec or California. /L - Locality, such as Lavaltrie or Sacramento. /O - Organization, such as Devolutions or Microsoft. /CN - Common name, here ubuntu-2204 (as shown via the hostname command).
-addext	To add a Subject Alternate Name (SAN), you can use this parameter to define either an IP or DNS entry. "subjectAltName = IP:10.10.0.20" "subjectAltName = DNS:ubuntu-2204"
-nodes	Do not encrypt the created private key.
-days	The number of days the certificate is valid.
-newkey	Define the algorithm and bit size, here rsa:2048 is used.
-keyout	The location to create the private key file.
-out	The location to create the public key file.

Trust the self-signed certificate on Ubuntu

The TLS certificate has two purposes:

1. Secures the management API;
2. Secures any client-to-Gateway tunnel in which gateway can inspect or filter traffic (websites, Gateway Tunnel, SCP/SFTP, etc.). For opaque protocols such as RDP or SSH, Devolutions Gateway simply forwards already-encrypted bytes, but the certificate is still required for gateway health checks and future features.

Once the self-signed certificate is created the certificate within the Ubuntu system will need to be trusted. To trust system-wide use the following set of commands:

cd /etc/devolutions-gateway
sudo apt-get install -y ca-certificates
sudo cp server.crt /usr/local/share/ca-certificates
sudo update-ca-certificates

The ca-certificates may already be installed. By running the update-ca-certificates command a symlink will be created in /etc/ssl/certs to the copied certificate file in /usr/local/share/ca-certificates.

If this is done in Firefox multiple trust errors will appear as the browser does not use the system-wide certificate store. Their documentation offers a few solutions to this.

Trust the self-signed certificate on Windows

After the self-signed certificate is created it will need to be trusted on Devolutions Server. The server.crt and server.key files will need to be transferred to the Windows system; or copy and paste the contents into files (i.e. sudo cat server.crt in Ubuntu and copy that into a text file on Windows).

Skip this section if Devolutions Server is not running on Windows.

1. Copy the public key to Windows (in the example, C:\Gateway is a temporary location): sudo cat server.crt

1. Copy the content into a server.crt file.

   
2. Copy private key to Windows: sudo cat server.key

   
3. Copy the content into a server.key file.

   
4. Create a PFX file using the Windows certutil command-line tool. For this to work, the key file must be named the same as the crt file, only differing in extension: certutil -mergepfx server.crt server.pfx

   
5. Import the PFX file into the Trusted Root Certification Authorities Certificate Store.

   1. Double-click the server.pfx file to start the import wizard and choose Local Machine.
   2. Click Next and accept the prompt.

      
   3. Click Next.

      
   4. Enter the password that you entered with the certutil command.

      • Optionally: choose to Mark this key as exportable.

      
   5. Choose the option Place all certificates in the following store.
   6. Select Trusted Root Certification Authorities with the Browse... button.
   7. Click Next.

      
   8. Click Finish to complete the import.

Open Ubuntu firewall ports

If the Linux system uses UFW (Uncomplicated Firewall) to manage iptable-based firewall, perform the following commands to open the necessary ports:

sudo ufw status
sudo ufw allow 7171
sudo ufw allow 8181
sudo ufw status

Modify the Devolutions Gateway configuration

The default configuration of a gateway contained in the /etc/devolutions-gateway/gateway.json file needs the certificate directives added (the InternalUrl will need to use HTTPS):

{
  "Id": "YOUR-UNIQUE-GUID",
  "ProvisionerPublicKeyFile": "provisioner.pem",
  "ProvisionerPrivateKeyFile": null,
  "Listeners": [
    {
      "InternalUrl": "tcp://:8181",
      "ExternalUrl": "tcp://:8181"
    },
    {
      "InternalUrl": "http://:7171",
      "ExternalUrl": "https://:7171"
    }
  ]
}

Modify the above file to reflect the following, assuming that both server.crt and server.key are in the same directory as gateway.json (using the built-in file editor Nano is recommended):

{
  "Id": "YOUR-UNIQUE-GUID",
  "ProvisionerPublicKeyFile": "provisioner.pem",
  "ProvisionerPrivateKeyFile": null,
  "TlsCertificateFile": "server.crt",
  "TlsPrivateKeyFile": "server.key",
  "Listeners": [
    {
      "InternalUrl": "tcp://:8181",
      "ExternalUrl": "tcp://:8181"
    },
    {
      "InternalUrl": "https://:7171",
      "ExternalUrl": "https://:7171"
    }
  ]
}

Restart Devolutions Gateway

With the new configuration in place restart Devolutions Gateway. This can be done with the systemctl command:

sudo systemctl restart devolutions-gateway.service
sudo systemctl status devolutions-gateway.service

Alternatively the Stop-DGateway and Start-DGateway PowerShell commands can also be used.

Connect Devolutions Gateway to Devolutions Server

Copy the Public Key from Devolutions Server to Devolutions Gateway Linux

1. Log into the Devolutions Server web console and navigate to Administration – Devolutions Gateway.
2. Click the More button and choose the Download public key option.

   
3. Copy the contents of the downloaded gateway_public_key.pem file on Windows.

   
4. Replace the contents of the /etc/devolutions-gateway/provisioner.pem (the Nano utility is recommended) file with the copied contents from Windows.

   
5. Restart Devolutions Gateway with the command sudo systemctl restart devolutions-gateway.service.

   

Configure Devolutions Gateway in Devolutions Server

Go to the Devolutions Server web interface where the newly configured Linux Devolutions Gateway will be added.

Skip this section if you are installing Devolutions Gateway with Devolutions Cloud.

1. Log into the Devolutions Server web console and navigate to Administration – Devolutions Gateway.
2. Click the Add (+) button.
3. Select Gateway.

1. Enter the following (this will change depending on the configuration).

   1. Name: Linux Gateway
   2. Devolutions Gateway URL: https://10.10.0.20:7171
   3. TCP Hostname: Ubuntu-2204
2. Click Save.

   

   Click the More options menu for the gateway and choose the Publish revocation list option if the revocation list is out of date.

Resolve hosts in Ubuntu

The Linux-hosted Devolutions Gateway system must be able to resolve the addresses that are requested by Devolutions Server. The simplest method for testing is to modify the hosts file.

Connect to the following system:

• Hostname: it-help-dc
• Fully-Qualified Domain Name (FQDN): it-help-dc.ad.it-help.ninja
• IP Address: 10.10.0.3

Open the hosts file for editing sudo nano /etc/hosts to add the host in Ubuntu.

Open a web-based RDP session

The gateway can now to connect to hosts. Since the it-help-dc host was added as resolvable to Ubuntu, it can be used to connect in a web-based session.

Web-based sessions require an active gateway configured for the entry and the user launching will require an assigned Remote Desktop Manager Team edition license or Devolutions Launcher license.

Additionally, if changes have been made to license assignments, logging out and back in may be needed to see the option to launch the web-based connection.

1. In the Devolutions Server web UI click on Add. Select an RDP session entry.
2. Click Continue.

1. Enter a Name and Host which must be resolvable by the Linux Devolutions Gateway install.
2. Click Add.

   
3. Enter or link any necessary credentials to the RDP session and click Add.

   
4. Under the VPN/Tunnel/Gateway tab choose Devolutions Gateway as the VPN type.
5. Set the Connect option to Always connect.
6. Choose the correct gateway.
7. Click Add.

   
8. Click Open in web client.

   

Open a Remote Desktop Manager RDP session

If the entry is already configured from within the Devolutions Server web interface it can be launched from Remote Desktop Manager when connected to the Devolutions Server workspace.

Skip this section if you are installing Devolutions Gateway with Devolutions Cloud.

When creating a new entry from Remote Desktop Manager the process is similar to that of Devolutions Server.

1. In Remote Desktop Manager, click on New entry. Select an RDP session entry.
2. Click on Select.

   
3. Enter a Name and Host which must be resolvable by the Linux Devolutions Gateway install.
4. Enter or link any necessary credentials to the RDP session.

   
5. Set the Connect option to Always connect.
6. Under the VPN/Tunnel/Gateway tab choose Devolutions Gateway as the VPN type.

   
7. Go to the Settings (Devolutions Gateway) sub-tab.
8. Choose the desired Devolutions Gateway.
9. Click Add.

   
10. Click on the Open session button.

    By hovering over the title bar a tooltip will appear and show that the RDP is connected via Devolutions Gateway.