> For the complete documentation index, see [llms.txt](https://docs.devolutions.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.devolutions.net/gateway/getting-started/devolutions-gateway-configuration-on-linux.md). # 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. {% hint style="warning" %} Devolutions Server or Devolutions Cloud is required for the configuration as well as a Devolutions Gateway license. {% endhint %} ### Install Devolutions Gateway 1. Navigate to the [Devolutions Gateway GitHub Release](https://github.com/Devolutions/devolutions-gateway/releases/) 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` ![](https://cdnweb.devolutions.net/docs/DGW0027_2024_3.png) 3. Install the package using the `dpkg` utility: `sudo dpkg -i devolutions-gateway_2024.3.2.0_amd64.deb` ![](https://cdnweb.devolutions.net/docs/DGW0028_2024_3.png)

The configuration and binary packages are in the following locations:

### 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: ```powershell 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: ```powershell 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. ```shell 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. ```shell 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. ```shell 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. ```powershell 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. ```shell 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. ```shell # Restart Gateway using systemctl systemctl restart devolutions-gateway.service ``` ```powershell # 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**. ![](https://cdnweb.devolutions.net/docs/DGW0029_2024_3.png) ```powershell 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 optionsExplanation
reqCreate and process certificate requests including self-signed certificates in PKCS#10 format.
-x509Output 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"
-nodesDo not encrypt the created private key.
-daysThe number of days the certificate is valid.
-newkeyDefine the algorithm and bit size, here rsa:2048 is used.
-keyoutThe location to create the private key file.
-outThe 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: ```powershell cd /etc/devolutions-gateway sudo apt-get install -y ca-certificates sudo cp server.crt /usr/local/share/ca-certificates sudo update-ca-certificates ``` ![](https://cdnweb.devolutions.net/docs/DGW0030_2024_3.png) 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**. ![](https://cdnweb.devolutions.net/docs/DGW0031_2024_3.png) {% hint style="warning" %} If this is done in Firefox multiple trust errors will appear as the browser does not use the system-wide certificate store. Their [documentation](https://support.mozilla.org/en-US/kb/setting-certificate-authorities-firefox) offers a few solutions to this. {% endhint %} #### 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). {% hint style="warning" %} Skip this section if Devolutions Server is not running on Windows. {% endhint %} 1\. Copy the public key to Windows (in the example, **C:\Gateway** is a temporary location):\ `sudo cat server.crt` ![](https://cdnweb.devolutions.net/docs/DGW0032_2024_3.png) 2. Copy the content into a **server.crt** file. ![](https://cdnweb.devolutions.net/docs/DGW0064_2024_3.png) 3. Copy private key to Windows:\ `sudo cat server.key` ![](https://cdnweb.devolutions.net/docs/DGW0034_2024_3.png) 4. Copy the content into a **server.key** file. ![](https://cdnweb.devolutions.net/docs/DGW0065_2024_3.png) 5. 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` ![](https://cdnweb.devolutions.net/docs/DGW0036_2024_3.png) 6. Import the PFX file into the [Trusted Root Certification Authorities Certificate Store](https://learn.microsoft.com/en-us/windows-hardware/drivers/install/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. ![](https://cdnweb.devolutions.net/docs/DGW0037_2024_3.png) 3. Click ***Next***. ![](https://cdnweb.devolutions.net/docs/DGW0038_2024_3.png) 4. Enter the password that you entered with the `certutil` command. * Optionally: choose to ***Mark this key as exportable***. ![](https://cdnweb.devolutions.net/docs/DGW0039_2024_3.png) 5. Choose the option ***Place all certificates in the following store***. 6. Select ***Trusted Root Certification Authorities*** with the ***Browse...*** button. 7. Click ***Next***. ![](https://cdnweb.devolutions.net/docs/DGW0040_2024_3.png) 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: ```powershell sudo ufw status sudo ufw allow 7171 sudo ufw allow 8181 sudo ufw status ``` ![](https://cdnweb.devolutions.net/docs/DGW0041_2024_3.png) ### 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): ```powershell { "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): ```powershell { "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" } ] } ``` ![](https://cdnweb.devolutions.net/docs/DGW0042_2024_3.png) #### Restart Devolutions Gateway With the new configuration in place restart Devolutions Gateway. This can be done with the `systemctl` command: ```powershell sudo systemctl restart devolutions-gateway.service sudo systemctl status devolutions-gateway.service ``` ![](https://cdnweb.devolutions.net/docs/DGW0046_2024_3.png) 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. ![](https://cdnweb.devolutions.net/docs/DGW0049_2024_3.png) 3. Copy the contents of the downloaded **gateway\_public\_key.pem** file on Windows. ![](https://cdnweb.devolutions.net/docs/DGW0066_2024_3.png) 4. Replace the contents of the **/etc/devolutions-gateway/provisioner.pem** (the Nano utility is recommended) file with the copied contents from Windows. ![](https://cdnweb.devolutions.net/docs/DGW0045_2024_3.png) 5. Restart Devolutions Gateway with the command `sudo systemctl restart devolutions-gateway.service`. ![](https://cdnweb.devolutions.net/docs/DGW0046_2024_3.png) #### Configure Devolutions Gateway in Devolutions Server Go to the Devolutions Server web interface where the newly configured Linux Devolutions Gateway will be added. {% hint style="warning" %} Skip this section if you are installing Devolutions Gateway with Devolutions Cloud. {% endhint %} 1. Log into the Devolutions Server web console and navigate to ***Administration*** – ***Devolutions Gateway***. 2. Click the ***Add*** (***+***) button. 3. Select ***Gateway***. ![](https://cdnweb.devolutions.net/docs/DGW0047_2024_3.png) 4. 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` 5. Click ***Save***. ![](https://cdnweb.devolutions.net/docs/DGW0050_2024_3.png)

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

![](https://cdnweb.devolutions.net/docs/DGW0048_2024_3.png) ### 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. ![](https://cdnweb.devolutions.net/docs/DGW0052_2024_3.png) ### 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. {% hint style="info" %} 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. {% endhint %} 1. In the Devolutions Server web UI click on ***Add***. Select an ***RDP*** session entry. 2. Click ***Continue***. ![](https://cdnweb.devolutions.net/docs/DGW0053_2024_3.png) 3. Enter a ***Name*** and ***Host*** which must be resolvable by the Linux Devolutions Gateway install. 4. Click ***Add***. ![](https://cdnweb.devolutions.net/docs/DGW0054_2024_3.png) 5. Enter or link any necessary credentials to the RDP session and click ***Add***. ![](https://cdnweb.devolutions.net/docs/DGW0055_2024_3.png) 6. Under the ***VPN/Tunnel/Gateway*** tab choose Devolutions Gateway as the VPN type. 7. Set the ***Connect*** option to ***Always connect***. 8. Choose the correct gateway. 9. Click ***Add***. ![](https://cdnweb.devolutions.net/docs/DGW0056_2024_3.png) 10. Click ***Open in web client***. ![](https://cdnweb.devolutions.net/docs/DGW0069_2024_3.png) ### 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. {% hint style="warning" %} Skip this section if you are installing Devolutions Gateway with Devolutions Cloud. {% endhint %} 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***. ![](https://cdnweb.devolutions.net/docs/DGW0058_2024_3.png) 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. ![](https://cdnweb.devolutions.net/docs/DGW0067_2024_3.png) 5. Set the ***Connect*** option to ***Always connect***. 6. Under the ***VPN/Tunnel/Gateway*** tab choose Devolutions Gateway as the VPN type. ![](https://cdnweb.devolutions.net/docs/DGW0068_2024_3.png) 7. Go to the ***Settings (Devolutions Gateway)*** sub-tab. 8. Choose the desired Devolutions Gateway. 9. Click ***Add***. ![](https://cdnweb.devolutions.net/docs/DGW0061_2024_3.png) 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.

![](https://cdnweb.devolutions.net/docs/DGW0062_2024_3.png) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.devolutions.net/gateway/getting-started/devolutions-gateway-configuration-on-linux.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.