Proxy settings

If you are going to use RADKit behind an HTTP proxy (eg. from a lab, an extranet/vendor site, …) here are a few things you should know.

Note

This page is not about accessing devices remotely through RADKit’s HTTP/SOCKS proxy forwarder feature. If that is what you’re looking for, please head to Port forwarding, SOCKS5 & HTTP proxy instead.

Proxy support in RADKit 

History:

RADKit 1.2 and earlier used to rely solely on the http_proxy, wss_proxy and no_proxy environment variables.
In RADKit 1.3, proxy configuration was moved to the new settings subsystem (see Settings management and Settings reference for details).
Since RADKit 1.6.x, proxy support has been extended to allow for proxy exclusion through settings, as well as falling back to standard environment variables. Users now have the choice between using RADKit Settings for their proxy configuration, or taking it straight from the environment, or even a mix of both.
Experimental support for system proxies on Windows and macOS was added in 1.6.0 but was removed in 1.6.5. It has been decommissioned in favor of the improved proxy derivation logic described later in this document.

Compatibility:

Transparent proxies (like those in place on the Cisco corporate, non-lab network) should not require any particular configuration. Note however, that proxies that perform man-in-the middle interception of HTTPS traffic will not be able to decrypt RADKit traffic.
Non-transparent proxies, like proxy.esl.cisco.com for labs or proxy-wsa.esl.cisco.com for extranet (see the Extranet Proxy User Guide), need to be configured as described in this document.
Proxy authentication is supported, but only with Basic HTTP authentication (e.g. NTLM/Kerberos is not supported).
Proxies that use the HTTPS scheme (TLS from client to proxy) are not supported; TLS connections in RADKit must be established end-to-end over an HTTP CONNECT call.

Scopes 

Separate proxy settings are available for different scopes of HTTP(S) connections. Within each scope, the same proxy settings are used for all protocols/schemes (http, https, ws, wss).

Cloud client proxy 

cloud_client.proxy.* in RADKit Client and RADKit Service (see cloud_client.proxy.url);
used for connections to RADKit Cloud and other cloud services such as Cisco CXD;
also used for direct cloud-less RPC connections from Client to Service.

Control proxy 

control.proxy.* in RADKit Control (see control.proxy.url);
used for direct connections from the Control CLI/API to a Service;
if you’re unsure whether you need this, you probably don’t need to worry about it.

Devices proxy 

service.devices_proxy.* in RADKit Service (see service.devices_proxy.url);
used for HTTP(S)/Swagger connections from RADKit Service to network devices;
experimental – subject to change as we plan to introduce per-device proxy settings in a future release*;
if you’re unsure whether you need this, you probably don’t need to worry about it.

Proxy settings 

The following settings govern the use of an HTTP proxy in RADKit within one of the scopes described previously:

url: The HTTP URL to the proxy, e.g. http://proxy.esl.cisco.com:80. If left empty, RADKit will check fall_back_to_environment (see Derivation logic below for details).
username, password: The username and password for Basic authentication to the proxy, if required.
no_proxy: Added in 1.6.5; not supported for devices proxy. A comma-separated list of hosts, domains and/or IP addresses (can be mixed) that should not be accessed through the proxy. Wildcards and CIDR masks are accepted, e.g. *.cisco.com, 127.0.0.0/8 or 127.*. A single asterisk * excludes all hosts and IP addresses from proxying.
fall_back_to_environment: Added in 1.6.0. If True, and url is not specified, proxy configuration will be derived from environment variables (see Derivation logic below for details). If set to False, proxy settings in the environment will be ignored. Default: True for cloud and control proxy, False for devices proxy.

Derivation logic 

To decide whether to use a proxy when accessing a given URL, RADKit walks through the following steps in order, stopping at the first match:

Retrieve proxy configuration from the relevant settings section (Cloud Client, Devices, Control):
- If no_proxy is configured and the host portion of the URL matches the proxy exclusion list: do not use a proxy for this connection.
- If url is configured: use its value as the proxy for this connection.
If fall_back_to_environment is True, check proxy-related environment variables:
- If NO_PROXY is present and the host portion of the URL matches the proxy exclusion list: do not use a proxy for this connection.
- If <scheme>_PROXY is present (where <scheme> is for instance HTTPS for a URL that starts with https://...): use its value as the proxy for this connection.
- If ALL_PROXY is present: use its value as the proxy for this connection.
- If <scheme>_PROXY is present for another scheme than the one in the given URL: use its value as the proxy for this connection (checked in order: http, https, ws, wss).
Do not use a proxy for this connection.

When proxy configuration is taken from the environment:

<scheme>_PROXY_USER[NAME] and <scheme>_PROXY_PASS[WORD] are checked for username and password for Basic authentication, where <scheme> is the scheme that was selected in the logic shown above;
uppercase and lowercase values are supported (e.g. HTTPS_PROXY or https_proxy), but if both are present and have different values, that is considered a misconfiguration and a warning will be printed in the log.

Configuration examples 

Note

The CLI examples below are for macOS/Linux. For more information on how to manage environment variables on Windows, please refer to this section.

System environment variable 

$ export HTTPS_PROXY="http://proxy.example.com:80"
$ radkit-client
$ radkit-service run

RADKit environment variable 

$ export RADKIT_CLOUD_CLIENT_PROXY_URL="http://proxy.example.com:80"
$ radkit-client
$ radkit-service run

CLI setting 

$ radkit-client --setting cloud_client.proxy.url "http://proxy.example.com:80"
$ radkit-service --setting cloud_client.proxy.url "http://proxy.example.com:80" run

TOML setting 

Under your home directory, create a file called .radkit/client/settings.toml for the Client or .radkit/service/settings.toml for the Service, containing:

[cloud_client.proxy]
url="http://proxy.example.com:80"

If you want to be able to perform SSO-based login in the RADKit Client or SSO-based enrollment in the RADKit Service, you will need to have access to a web browser that can open connections to the outside world. The SSO operations can be performed in a browser that is on a different machine than the one RADKit Client or Service is running on.

On the Client, this is done by passing open_browser=False to sso_login() and copy-pasting the URL that is returned. The RADKit Client only needs connectivity to the RADKit Cloud. The web browser must be able to reach both the RADKit Cloud and the SSO login page.

Likewise, the RADKit Service only needs connectivity to the RADKit Cloud. The web browser must be able to reach the Service WebUI (to trigger SSO-based enrollment), the RADKit Cloud and the SSO login page.