Config

Reference documentation for Tunlr’s configuration

Configuration Sources

Configuration is performed using a JSON/Jsonnet configuration file, environment variables, and command line arguments. Configurations from one source will override previous sources, i.e. environment variables override configuration files, command line arguments override environment variables.

Command Line

Every configuration key can be set using -x <a_config_key1>="a value" -x <a_config_key2>="another value", i.e. -x cli_logLevel=debug -x cli_logFormat=kv. Config values can also be set using JSON, i.e. -x cli='{"logLevel": "debug"}'

Command line values override all other sources.

Environment Variables

Every configuration key can be set using tunlr_config_key=value, i.e. tunlr_cli_logLevel=debug. A special environment variable, tunlr_config can be used to specify a complete JSON/Jsonnet configuration.

Environment Variables override a configuration file.

Configuration File

A configuration file be formatted using JSON or Jsonnet. Underscores in config keys are used to represent nesting, i.e. cli_logLevel represents:

{
  "cli": {
    "logLevel": "debug"
  }
}

Tunlr looks for tunlr.jsonnet by default, ascending the directory tree to find it. See the Jsonnet reference for more information. Configuration files are rendered at startup, allowing you to use dynamic Jsonnet functions to dynamically alter the config, i.e.:

local getRecord(type, name, fallback=null) = std.native('getRecord')(type, name, fallback);
local level = getRecord('txt', 'level.candid.dev');

{
  cli: [
    logLevel: level,
  ],
}

You can view the rendered configuration by running tunlr config.

Configuration Values

`cli`

Configurations for the CLI.

`cli_configPath`

String, path to the configuration file. If a filename without a path is specified, Rot will search parent directories for the filename and use the first one found.

Default: "tunlr.jsonnet"

`cli_configReloadSec`

Number, seconds to periodically reload the config and reload the application, if > 0.

Default: 0

`cli_configWatch`

Boolean, if true then the configPath will be watched for changes. On a change, the application will be reloaded.

Default: false

`cli_logFormat`

String, log format to use for logging: human, kv, or raw.

Default: "human"

`cli_logLevel`

String, log level to use for logging: none, debug, info, or error.

Default: "info"

`cli_logMinStatus`

Number, the minimum status to log for error messages. Used to additionally filter logLevel error. Status roughly map to HTTP status codes:

400 will capture all client and server errors
500 will capture only server errors

Default: 0

`cli_macros`

A map of macros to simplify and template CLI arguments. See Macros for more information.

An example macro looks like this:

{
  "cli": {
    "macro": {
      "mymacro": {
        "argumentsRequired": [
          "argument1"
        ],
        "flags": {
          "d": {
            "usage": "D flag usage!"
          },
        },
        "template": "config",
        "usage": "Mymacro usage!",
      }
    }
  }
}

Default: {}

`cli_macros_[macro]_argumentsRequired`

A list of arguments that are required for the macro.

Default: []

`cli_macros_[macro]_argumentsOptional`

A list of arguments that are optional for the macro.

Default: []

`cli_macros_[macro]_flags`

A map of flags for the macro.

Default: {}

`cli_macros_[macro]_flags_[flag]_default`

A list of strings for the default value of the flag.

Default: []

`cli_macros_[name]_flags_[flag]_options`

A list of strings the flag can be set to.

Default: []

`cli_macros_[name]_flags_[flag]_placeholder`

String, the placeholder name for the flag if it accepts a value.

Default: ""

`cli_macros_[name]_flags_[flag]_usage`

String, the usage instructions for the flag.

Default: ""

`cli_macros_[name]_template`

String, the Go template syntax that will be rendered, appended to the CLI, and ran. The Go template can use these custom functions:

{{ getArg i int f string }}
Get an argument at position i or return fallback f.
{{ getEnv e string f string }}
Get an environment variable e or return fallback f.
{{ getFlag f string }}
Get the flag values for f. For flags with a placeholder, this will be an array of string values, otherwise it will be a boolean.
{{ join s []string sep string }}
Join array s with separator sep.

Default: []

`cli_macros_[name]_usage`

String, the usage documentation for a macro.

Default: ""

`cli_noPaging`

Boolean, disables paging of log output using less.

Default: false

`client`

Configurations for Tunlr in client mode.

`client_allowedNetworks`

List of strings representing IPv4 and IPv6 networks that requests must originate from. This check is performed on the Tunlr server, clients will never see requests that do not match these networks.

Default: []

`client_httpHeaderFilters`

List of strings representing HTTP header filters that must be present for a client request to be tunneld. This check is performed on the Tunlr server, clients will never see requests that do not match these headers.

The header format is a list of comma separated filters. Within the list, filters are OR, within a comma separated string, filters are AND:

{
  "client": {
    "httpHeaderFilters": [
      "Authorization=^Bearer .*$,MySecretHeader",
      "Authorization=^Basic",
    ],
  }
}

In this example, the request must match one of these conditions:

Contain the header Authorization with a value that starts with Bearer , and contain the header MySecretHeader with any value.
Contain the header Authorization with a value that starts with Basic.

Default: []

`client_hostname`

String, a hostname to request from the server. Server must be configured to allow client hostname requests. If the server does not allow requests, or the hostname is taken, the server will return a randomized hostname.

Default: ""

`client_jwt`

String, a JWT used for authenticating to a Tunlr server.

Default: ""

`client_password`

String, a password used for authenticating to a Tunlr server.

Default: ""

`client_serverAddresses`

List of server addresses to use. Tunlr will randomize the list and attempt to connect to each one.

Default: []

`client_serverList`

String, a URL to download a server list from. The server list file should list the server addresses separated by a newline, i.e.:

https://123.tunlr.link
https://456.tunlr.link:3000

Tunlr will copy these addresses into client_serverAddreses.

Default: "https://tunlr.dev/servers.txt"

`client_targets`

Targets is a map of target names to target configurations. See Guides > Client for more information.

Default: {}

`client_targets_[target]_path`

String, the path to the target. Targets support these path types:

http:// for HTTP targets.
https:// for HTTPS targets.
Other path types default to local directories

Default: ""

`client_username`

String, a username used for authenticating to a Tunlr server.

Default: ""

`httpClient`

Configurations for the global HTTP client.

`httpClient_noSystemCA`

Boolean, if true, Tunlr will not use the system certificate authorities. All certificate authorities must be specified using httpClient_tlsCABase64 or httpClient_tlsCAPath or no HTTPS URLs will be trusted.

Default: false

`httpClient_tlsCABase64`

String, base64 encoded PEM certificate used by Tunlr’s HTTP client to validate HTTPS endpoints. If this or tlsCAPath are not specified, Tunlr will only use the system CA certificates to validate certificates.

Default: ""

`httpClient_tlsCAPath`

String, path to a PEM certificate used by Tunlr’s HTTP client to validate HTTPS endpoints. If this or tlsCABase64 are not specified, Tunlr will only use the system CA certificates to validate certificates.

Default: ""

`httpClient_tlsCertificatesBase64`

List of base64 encoded PEM certificate strings used by Tunlr’s HTTP client to perform TLS Client authentication.

Default: ""

`httpClient_tlsCertificatesPath`

List of path strings to PEM certificates used by Tunlr’s HTTP client to perform TLS Client authentication.

Default: ""

`httpClient_tlsKeysBase64`

List of base64 encoded PEM key strings used by Tunlr’s HTTP client to perform TLS Client authentication.

Default: ""

`httpClient_tlsKeysPath`

List of path strings to PEM keys used by Tunlr’s HTTP client to perform TLS Client authentication.

Default: ""

`httpClient_tlsCAPath`

Default: ""

`httpClient_tlsSkipVerify`

Boolean, configures Tunlr’s HTTP client to skip TLS verification for HTTPS endpoints. Use with caution.

Default: false

`httpClient_timeoutDialSec`

Number, default seconds to wait for HTTP requests to connect. 0 disables the timeout.

Default: 10

`httpClient_timeoutTLSHandshakeSec`

Number, default seconds to wait for HTTP requests to negotiate TLS. 0 disables the timeout.

Default: 10

`httpServer`

Configurations for the HTTP server.

`httpServer_listenAddress`

String, the listen address and port number for the service.

Default: ":5000"

`httpServer_rateLimitKey`

String, a HTTP header key that can be provided using x-rate-limit-key to bypass rate limiting.

Default: ""

`httpServer_rateLimitPatterns`

Map of paths and rate limits. Rate limits are configured as count-duration-status, e.g. 5-1h means 5 requests every 1 hour. Status is an HTTP status code, the rate limiter will apply if the response is greater than the status code, e.g. 5-1h-400 will apply if the response status code is > 400. If the rate limit is an empty string (""), it will be disabled for that path.

Default: Run tunlr config | tunlr jq .http.rateLimitPatterns

`httpServer_tlsClientCABase64`

String, base64 encoded PEM CA certificate for validating TLS clients. Setting this will enable/require TLS authentication from all HTTP clients.

Default: ""

`httpServer_tlsClientCAPath`

String, path to a PEM CA certificate for validating TLS clients. Setting this will enable/require TLS authentication from all HTTP clients.

Default: ""

`httpServer_tlsCertificateBase64`

String, base64 encoded PEM certificate for HTTPS.

Default: ""

`httpServer_tlsCertificatePath`

String, path to a PEM certificate for HTTPS.

Default: ""

`httpServer_tlsKeyBase64`

String, base64 encoded PEM key for HTTPS.

Default: ""

`httpServer_tlsKeyPath`

String, path to a PEM key for HTTPS.

Default: ""

`httpServer_timeoutReadHeaderSec`

Number, default seconds to wait reading a request header from an HTTP client. 0 disables the timeout.

Default: 60

`httpServer_timeoutReadSec`

Number, default seconds to wait reading a request from an HTTP client. 0 disables the timeout.

Default: 60

`httpServer_timeoutWriteSec`

Number, default seconds to wait writing to a response to a HTTP client. 0 disables the timeout.

Default: 300

`httpServer_xForwardedTrustedCIDRs`

A list of subnets or CIDRs that will be trusted for sending X-Forwarded-For headers. If an IP address in the X-Forwarded-For header matches one of these subnets, the client IP will be the left most address before the matched IP. This should be the host or network of a trusted proxies like NGINX or Traefik.

Default: ""

`jsonnet`

Configuration toggles for disabling Jsonnet Native Functions. Some of these functions are disabled by default–namely anything that could perform an external call, like running a command, or performing HTTP or DNS requests. These should only be enabled for Jsonnet files you trust, as they could lead to data exfiltration or worse.

`jsonnet_disableGetArch`

Disable the getArch function.

Default: false

`jsonnet_disableGetCmd`

Disable the getCmd function.

Default: true

`jsonnet_disableGetConfig`

Disable the getConfig function.

Default: false

`jsonnet_disableGetEnv`

Disable the getEnv function.

Default: false

`jsonnet_disableGetFile`

Disable the getFile function.

Default: false

`jsonnet_disableGetFileHTTP`

Disable the getFileHTTP function.

Default: true

`jsonnet_disableGetOS`

Disable the getOS function.

Default: false

`jsonnet_disableGetPath`

Disable the getPath function.

Default: false

`jsonnet_disableGetRecord`

Disable the getRecord function.

Default: true

`licenseKey`

String, the Tunlr license key provided to your organization.

Default: ""

`rpc`

License Required

This requires a Server License

Configure the RPC connections between Tunlr servers.

`rpc_cacheRequestsExpiration`

String, the duration to cache RPC request IDs. Setting this too low may cause duplicate request replies.

Default: "1m"

`rpc_cacheServicesExpiration`

String, the duration to cache RPC service names. Setting this too low may cause excessive RPC broadcasts, and too high may cause requests to be routed to offline nodes.

Default: "1m"

`rpc_findRequestTick`

String, the duration to wait before checking for replies to find requests. This should be set to the minimum end-to-end latency between RPC nodes.

Default: "100ms"

`rpc_findRequestTimeout`

String, the duration to wait for a find request reply. This should be set to the maximum end-to-end latency between RPC nodes.

Default: "10s"

`rpc_id`

String, the unique ID of this node. An ID will be generated if one is not provided.

Default: ""

`rpc_listenAddress`

String, the listen address for TCP/TLS RPC traffic.

Default: ":2000"

`rpc_nodeAddresses`

List of node addresses in the form of host:port to connect as a client. Nodes can fully mesh without duplication–they will disconnect from nodes they are already connected to.

Default: []

`rpc_nodeKeepaliveMiss`

Number, maximum number of keepalive misses from a node before it is considered dead.

Default: 3

`rpc_nodeKeepaliveTick`

String, the duration to wait before issuing a keepalive.

Default: "5s"

`rpc_nodeRetryMax`

String, the maximum amount of time to wait before retrying a connection to a node listed in rpc_nodeAddresses.

Default: "10s"

`rpc_nodeRetryMin`

String, the minimum amount of time to wait before retrying a connection to a node listed in rpc_nodeAddresses.

Default: "100ms"

`rpc_tlsCABase64`

String, a base64 encoded string of the certificate authority used to establish mutal TLS (mTLS). Required.

Default: ""

`rpc_tlsCABase64`

String, a base64 encoded string of the certificate authority used to establish mutal TLS (mTLS).

Default: ""

`server`

License Required

This requires a Server License

Configurations for Tunlr in server mode.

`server_allowClientHostnames`

Boolean, allows clients to request hostnames.

Default: false

`server_clientKeepaliveSec`

Number, maximum number of seconds to send periodic keepalives to clients. The exact keepalive interval is randomized to limit timing attacks.

Default: 60 (1 minute)

`server_clientLifetimeSec`

Number, maximum number of seconds a client can be connected to a Tunlr server. Clients can always reconnect, but they may receive a new hostname if server_allowClientHostnames is false. Combine this with httpServer_rateLimitPatterns to limit how many times a client can connect a Tunlr server.

Default: 1200 (20 minutes)

`server_clientTimeoutSec`

Number, seconds to wait without a response before a client is considered dead and removed from the Tunlr server.

Default: 600 (10 minutes)

`server_domain`

String, the domain to generate certificates from. If not specified, will use the domain of the server’s hostname.

Default: ""

`server_hostnameTemplate`

String, the hostname template to use for generating hostnames for clients. Use Go templating. The default template will use the sub JWT claim if provided or generate a 14 character Nanoid. All names generated will be converted to lowercase and stripped of any non-alphaneumeric character, including -.

Default: "{{ if eq (index . "sub") nil }}{{ nanoid 14 }}{{ else }}{{ .sub }}{{ end }}"

`server_jwtExpiresSec`

Number, seconds until JWTs signed by Tunlr server expire.

Default: 86400 (one day)

`server_jwtPrivateKey`

String, a JWT private key used to sign JWTs. Can be generated using tunlr keys. If one is not provided, a random one will be generated, however JWTs will be invalidated everytime Tunlr restarts.

Default: ""

`server_jwtPublicKeys`

List of strings containing JWT public keys to use for JWT authentication.

Default: []

`server_maxClients`

Number, maximum number of clients a server can support. When new clients try to connect after this limit is reached, they will receive an error and will connect to other servers if configured.

Setting 0 means the Tunlr server can support an unlimited number of clients.

Default: 0

`server_maxRequestSizeKB`

Number, the maximum request size that can be sent to this server in kilobytes. Requests sent to this server over this limit will receive an error response and not be proxied.

Setting 0 means there is no limit.

Default: 0

`server_maxResponseSizeKB`

Number, the maximum response size that can be received by this server in kilobytes. Responses sent to this server over this limit will receive an error response and not be proxied.

Setting 0 means there is no limit.

Default: 0

`server_requireAuthClient`

Boolean, require clients to be authenticated via JWT or staticUsernames

Default: true

`server_requestTimeoutSec`

Number, the number of seconds to wait for a request to complete (from client request to tunlr client response).

Default: 60

`server_systemClientKey`

String, a secret key to access the /api/v1/system/client?key=<server_systemClientKey> endpoint. This endpoint returns details about the client, such as headers and the remote address. The endpoint is not enabled if this key is unset. Useful for debugging.

Default: ""

`server_systemMetricsKey`

String, a secret key to access the /api/v1/system/metrics?key=<server_systemMetricsKey> endpoint. This endpoint returns Prometheus-style scrape metrics. The endpoint is not enabled if this key is unset

Default: ""

`server_tunnelHTTPS`

Boolean, returns https:// hostname schemes to clients when true. If false, clients will see http:// hostname schemes.

Default: false

`server_tunnelPort`

Number, the port number appended to client hostnames. Defaults to httpServer_listenAddress.

Default: 5000