Skip to content

Latest commit

 

History

History
193 lines (157 loc) · 7.96 KB

uhppoted-tunnel-toml.md

File metadata and controls

193 lines (157 loc) · 7.96 KB
Raw

uhppoted-tunnel.toml

uhppoted-tunnel.toml is a TOML file that defines the default configuration for uhppoted-tunnel.

The file is intended to allow simple and maintainable configuration for systems running multiple uhppoted-tunnel services and provides a base configuration which can be overridden by command line arguments when necessary e.g. for running a tunnel in console mode.

A sample uhppoted-tunnel.toml is included in the examples.

A uhppoted-tunnel.toml file comprises:

  • a defaults section which defines the base configuration for all uhppoted-tunnels
  • service specific sections that customise the base configuration for a particular uhppoted-tunnel (typically by defining the in and out connectors)

Running an instance of uhppoted-tunnel with the --config flag selects the service specific section to use, e.g.

uhppoted-tunnel --config "#client" ...

will run with the [client] section from the default uhppoted-tunnel.toml file.

uhppoted-tunnel --config "/etc/uhppoted/tunnel-special.toml#client" ...

will run with the [client] section from the /etc/uhppoted/tunnel-special.toml#client file.

Notes

  1. The daemonize command supports the --config argument on the command line and will configure the uhppoted-tunnel daemon/service to run with the specified TOML file/section, e.g.
sudo ./uhppoted-tunnel daemonize --config "#client"
  1. Command line arguments override any settings in the the TOML file, allowing uhppoted-tunnel to be easily run with custom configurations for e.g. testing and debugging:
./uhppoted-tunnel --config "#client" --debug --console --out udp/broadcast:192.168.1.255:60005 --udp-timeout 15s
  1. uhppoted-tunnel is configured on start only - changes to a TOML file will not take effect until the service/instance is restarted.

[defaults] section

The [defaults] section in the TOML sets the base configuration for instances of uhppoted-tunnel. The settings defined in the [defaults] section can be individually overriden in service specific sections, e.g.

[defaults]
lockfile = ""
max-retries = 32
max-retry-delay = "5m"
udp-timeout = "5s"
interfaces = { "in" = "en3", "out" = "" }
rate-limit = 1
rate-limit-burst = 120
...

Settings

Attribute Description Default value
in IN connector that accepts external requests None
out OUT connector that dispatches received requests None
interfaces IN and OUT connector network interfaces None
lockfile lockfile used to prevent running multiple copies of the service auto-generated
max-retries Maximum number of times to retry failed connection. -1 (retry forever)
max-retry-delay Maximum delay between retrying failed connections 5m
udp-timeout Maximum delay between retrying failed connections 5s
ca-cert (TLS only) File path for CA certificate PEM file ./ca.cert
cert (TLS only) File path for client/server certificate PEM file ./client.cert or ./server.cert
key (TLS only) File path for client/server key PEM file ./client.key or ./server.key
client-auth (TLS only) Mandates client authentication false
authorisation (Tailscale only) Tailscale authorisation method TS_AUTHKEY environment variable
html (HTTP only) Folder with HTML ./html
log-level Sets the logging level (debug, info, warn or error) info./html
console Runs in console mode i.e. logs to console false
debug Enables display of low-level UDP messages false
label Service label used to distinguish multiple tunnesl on a machine None
rate-limit Average request rate limit (requests/second) 1
rate-limit-burst Burst request rate limit (requests) 120

Service specific sections

A service specific section defines the custom configuration (typically at least the IN and OUT connectors) for a particular service/instance of uhppoted-tunnel, e.g.:

...

[client]
in = "tcp/client:127.0.0.1:12345"
out = "udp/broadcast:192.168.1.255:60000"
udp-timeout = "1s"
log-level = "warn"
label = "qwerty"
...

The section name is specified in the --config command line argument preceded by a #, e.g.

./uhppoted-tunnel --config "#client"

Tailscale authorisation

By default connections to a Tailscale tailnet will use the authorisation key in the TS_AUTHKEY environment variable. If the environment variable is not defined or is blank then you will be prompted with an authorisation URL. Alternative authorisation methods can be configured using the authorisation TOML configuration file key:

  1. A different environment variable can specified using the env:<variable name> syntax, e.g.
[tailscale-server]
...
authorisation = "env:TS_WORKSHOP"
...

This is an alternative to using a reusable authorisation key in the TS_AUTHKEY environment variable when running two or more tunnels on the same machine.

  1. The authorisation key can specified directly using the authkey:<key> syntax, e.g.
[tailscale-server]
...
authorisation = "authkey:tskey-auth-xxxxxxxxxxxx-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
...
  1. Authorisation can be done using an OAuth2 client ID created on the the Tailscale admin console.
[tailscale-server]
...
authorisation = "oauth2:.credentials.workship"
...

The credentials is a JSON file that contains the OAuth2 credentials for the OAuth2 client, e.g.

{ 
    "tailscale": {
        "oauth2": {
            "client-id": "xxxxxxxxxxxx",
            "client-secret": "tskey-client-xxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
            "auth-url": "https://api.tailscale.com/api/v2/oauth/token",
            "tailnet": "qwerty@uiop.com",
            "tag": "development",
            "key-expiry": 300
        }
    }
}
  • The client-id and client-secret are the keys generated when creating the OAuth2 client on the Tailscale admin console.
  • The tailnet is the user or organisation account name (not the tailnet DNS name) but can be defaulted to a '-' since the API keys are organisation/client specific.

Please note that connections authorised using OAuth2 are required to be tagged and the keys do not expire, but can be expired manually on the Tailscale console.

Sample TOML file

[defaults]
lockfile = ""
max-retries = 32
max-retry-delay = "5m"
udp-timeout = "5s"
interfaces = { "in" = "en3", "out" = "" }

[host]
in = "udp/listen:0.0.0.0:60000"
out = "tcp/server:0.0.0.0:12345"
lockfile = "/tmp/uhppoted-tunnel-host.pid"
label = "uiop"

[client]
in = "tcp/client::lo0:127.0.0.1:12345"
out = "udp/broadcast:192.168.1.255:60000"
udp-timeout = "1s"
log-level = "info"
label = "qwerty"
...
...