Devolutions Gateway

A blazing fast relay server adaptable to different protocols and desired levels of traffic inspection.

Install

From our website (recommended)

You can download either the Devolutions Server Management Console or the offline Windows Installer from the official Devolutions website. Only releases that have successfully passed our quality assurance team's acceptance testing are accessible through this channel.

From GitHub

Signed binaries and installers for all versions can be conveniently obtained from the GitHub releases page. It's important to note that these are made available immediately, without going through the acceptance testing process of our quality assurance team.

From sources

Ensure that you have the Rust toolchain installed, then clone this repository and run:

cargo install --path ./devolutions-gateway

Configuration

Devolutions Gateway is configured using a JSON document. The recommended way to modify this document is to use the PowerShell module, but it is nonetheless possible to modify it manually or by any other means that are convenient for you.

The file containing this JSON document must be named gateway.json and exist under the following path, depending on your platform:

Platform	Path
Windows	%ProgramData%\Devolutions\Gateway\
Linux	/etc/devolutions-gateway/
macOS (Darwin)	/Library/Application Support/devolutions-gateway/

This path may be overridden using the DGATEWAY_CONFIG_PATH environment variable.

A default template with minimal options is generated at this location on startup if the file doesn't exist yet.

Stable options are:

• Id (UUID): This Gateway's UUID.

• Hostname (String): This Gateway's hostname (used when inferring external URLs).

• ProvisionerPublicKeyFile (FilePath): Path to the provisioner public key which is used to verify tokens without any specific restriction.

• ProvisionerPrivateKeyFile (FilePath): Path to the provisioner private key which is used to generate session tokens when using the standalone web application.

• SubProvisionerPublicKey (Object): A JSON object describing the sub provisioner public key which may only be used to verify tokens when establishing a session.

  The schema is:

  • Id (UUID): The key ID for this subkey.

  • Value (String): The binary-to-text-encoded key data.

  • Format (String): The format used for the key data.

    Possible values:

    • Spki (default)
    • Rsa

  • Encoding (String): The binary-to-text encoding used for the key data.

    Possible values:

    • Multibase (default)
    • Base64
    • Base64Pad
    • Base64Url
    • Base64UrlPad

• DelegationPrivateKeyFile (FilePath): Path to the delegation private key which is used to decipher sensitive data from tokens.

• TlsCertificateSource (String): Source for the TLS certificate.

  Possible values:

  • External (default): Retrieve a certificate stored on the file system. See the options TlsCertificateFile, TlsPrivateKeyFile and TlsPrivateKeyPassword.

  • System: Retrieve the certificate managed by the system certificate store. See the options TlsCertificateSubjectName, TlsCertificateStoreName and TlsCertificateStoreLocation.

• TlsCertificateSubjectName (String): Subject name of the certificate to use for TLS when using system source.

• TlsCertificateStoreName (String): Name of the System Certificate Store to use for TLS (default is My).

• TlsCertificateStoreLocation (String): Location of the System Certificate Store to use for TLS.

  Possible values:

  • CurrentUser (default)
  • CurrentService
  • LocalMachine

• TlsCertificateFile (FilePath): Path to the certificate to use for TLS.

• TlsPrivateKeyFile (FilePath): Path to the private key to use for TLS.

• TlsPrivateKeyPassword (String): Password to use for decrypting the TLS private key.

  It's important to understand that using this option in order to use an encrypted private key does not inherently enhance security beyond using a plain, unencrypted private key. In fact, storing the password in plain text within the configuration file is discouraged because it provides minimal security advantages over the unencrypted private key. If an unauthorized person gains access to both the configuration file and the private key, they can easily retrieve the password, making it as vulnerable as an unencrypted private key. To bolster security, consider additional measures like securing access to the files or using the system certificate store (see TlsCertificateSource option).

• Listeners (Array): Array of listener URLs.

  Each element has the following schema:

  • InternalUrl (URL): Internal URL for this listener, a socket bound to the specified address (IP address, and port number) will be created.

  • ExternalUrl (URL): External URL for this listener, accessing this URL from outside should ultimately redirect to the service. This holds no meaning for the service itself, but the value will be advertised by the GET /jet/diagnostics/configuration HTTP endpoint. This route can be used by other systems to automatically discover the remaining access URLs.

  For both values, host segment may be abridged with *.

  When used in internal URLs, * will cause two listeners to be created with * expanded into:

  • the IPv4 wildcard bind address 0.0.0.0, for listening to any IPv4 address, and
  • the IPv6 wildcard bind address [::], for listening to any IPv6 address.

  When used in external URLs, * will be expanded into the value of Hostname.

• Subscriber (Object): Subscriber API configuration.

  • Url (URL): HTTP URL where notification messages are to be sent.
  • Token (String): bearer token to use when making HTTP requests.

• RecordingPath (FilePath): Path to the recordings folder.

• Ngrok (Object): JSON object describing the ngrok configuration for ingress listeners.

  • AuthToken (String): Specifies the authentication token used to connect to the ngrok service.

  • HeartbeatInterval (Integer): How often the service should heartbeat to the ngrok servers defined as a number in seconds.

  • HeartbeatTolerance (Integer): Reconnect the agent tunnel session if the server does not respond to a heartbeat within this tolerance defined as a number in seconds.

  • Metadata (String): Opaque, user-supplied string that will be returned as part of the ngrok API response to the list online sessions resource for all tunnels started by Devolutions Gateway service.

  • ServerAddr (URL): This is the URL of the ngrok server to connect to. You should only set this if you are using a custom ingress URL.

  • Tunnels (Map): A map of ngrok tunnels. The key is the name of the tunnel and value is a JSON object whose schema depends on tunnel protocol.

    Common options are:

    • AllowCidrs (Array): Array of CIDRs, rejects connections that do not match the given CIDRs.
    • DenyCidrs (Array): Array of CIDRS, rejects connections that match the given CIDRs and allows all other CIDRs.
    • Metadata (String): Arbitrary user-defined metadata that will appear in the ngrok service API when listing tunnel sessions.

    Other options for an HTTP tunnel are:

    • Proto (String): MUST be set to http.
    • Domain (String): The domain to request, as registered in the ngrok dashboard.
    • Metadata (String): Arbitrary user-defined metadata that will appear in the ngrok service API when listing tunnel sessions.
    • CircuitBreaker (Ratio): Reject requests when 5XX responses exceed this ratio.
    • Compression (Boolean): Enable gzip compression for HTTP responses.

    Other options for a TCP tunnel are:

    • Proto (String): MUST be set to tcp.
    • RemoteAddr (String): Bind the remote TCP address and port, as registered in the ngrok dashboard.

    Note that in order to accept connections from outside, you must at least configure AllowCidrs. The most permissive CIDR is the "zero-address" 0.0.0.0/0, and defines an IP block containing all possible IP addresses.

• WebApp (Object): JSON object describing the standalone web application configuration.

  • Enabled (Boolean): Whether to enable or disable the standalone web application. When enabled, the ProvisionerPrivateKeyFile option must be set.

  • Authentication (String): The authentication method for accessing the web application.

    Possible values:

    • Custom: Requires a username/password pair.
    • None: Disable authentication, anyone can access the web application.

  • AppTokenMaximumLifetime (Integer): The maximum lifetime granted to web application tokens defined as a number in seconds (default is 28800 for 8 hours).

  • LoginLimitRate (Integer): The maximum number of login requests for a given username/IP pair over a minute (default is 10).

  • UsersFile (FilePath): Path to the users file which holds the list of users authorized to access the web application when using the Custom authentication method (default is users.txt).

    For each line such as <user>:<hash>:

    • <user>: The name of the user.

    • <hash>: Hash of the password in the PHC string format. Currently, the only supported hash algorithm is Argon2. It’s possible to use the online tool argon2.online to generate a hash.

    Blank lines and lines starting by # are ignored.

  • StaticRootPath (FilePath): Path to the static files for the standalone web application. This is an advanced option which should typically not be changed.

• VerbosityProfile (String): Logging verbosity profile (pre-defined tracing directives).

  Possible values:

  • Default (default): The default profile.
  • Debug: Recommended profile for developers.
  • Tls: Verbose logging for TLS troubleshooting.
  • All: Extra-verbose profile, showing all traces.
  • Quiet: Only show warnings and errors.

Troubleshooting

Connection from Microsoft Windows 7/8/8.1/Server 2008/Server 2012 clients

1. For Window 7 and Windows Server 2008: Install latest updates. Make sure to install the update that adds support for TLS 1.1 and TLS 1.2. This is not required for newer Windows editions - they support TLS 1.1 and TLS 1.2 by default.

2. Add following cipher suites to the SSL Cipher Suite order:

   • TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256;
   • TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384.

   To add cipher suites, use the group policy setting SSL Cipher Suite Order under Computer Configuration > Administrative Templates > Network > SSL Configuration Settings. TLS Cipher Suites in Windows 7.

Redirection to Microsoft Windows 7/8/8.1/Server 2008/Server 2012 server

Unfortunately, Microsoft Windows 7/8/8.1/Server 2008/Server 2012 machines cannot accept connections from rustls client. Support for required cipher suits was not implemented until Windows 10.

NoCipherSuitesInCommon error on Windows with a custom SChannel configuration

If you tried to to explicitly enable hashing algorithms like SHA256 in registry keys under HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Hashes, it turns out that this will… disable them, even if you set Enabled to 1. For example, if the only hashing algorithm that is not explicitly set is SHA1, the SChannel client only advertises SHA1, which is not supported anymore by default.

See this page from Microsoft documentation to learn how to properly configure SChannel.

Knowledge base

Read more on our knowledge base.

Cookbook

See COOKBOOK.md.

Continuous Integration and Delivery

See the dedicated README.md file in the workflows directory.