tlstunnel - TLS reverse proxy
tlstunnel [options...]
tlstunnel is a TLS reverse proxy with support for automatic TLS certificate retrieval via the ACME protocol.
-h, -help
Show help message and quit.
-config <path>
Path to the configuration file.
The config file has one directive per line. Directives have a name, followed by parameters separated by space characters. Directives may have children in blocks delimited by "{" and "}". Lines beginning with "#" are comments.
tlstunnel will reload the config file when it receives the HUP signal.
Example:
frontend
example.org:443 {
backend localhost:8080
}
The following directives are supported:
frontend <address>... { ... }
Addresses to listen on for incoming TLS connections.
Each address is in the form <name>:<port>. The name may be omitted to match all hosts. The name can contain a wildcard, but only to represent the first label of the hostname (e.g. *.example.org works, matches foo.example.org but doesn’t match foo.bar.example.org).
The frontend directive supports the following sub-directives:
listen <address>...
Additional addresses to listen on.
backend <uri>...
Backend to forward incoming connections to.
The following URIs are supported:
•
[tcp://]<host>:<port> connects to a TCP
server
• tls://<host>:<port> connects to a
TLS over TCP server
• unix://<path> connects to a Unix
socket
The +proxy suffix can be added to the URI scheme to forward connection metadata via the PROXY protocol.
tls { ... }
Customise frontend-specific TLS configuration.
The tls directive supports the following sub-directives:
load <cert> <key>
Load certificates and private keys from PEM files.
This disables automatic TLS.
protocol <name>...
List of supported application-layer protocols.
The first protocol which is also supported by the client is negociated. The backend can inspect the negotiated protocol via the PROXY protocol.
The protocols will be advertised via the TLS ALPN extension. See the IANA registry for a list of protocol names: https://www.iana.org/assignments/tls-extensiontype-values/tls-extensiontype-values.xhtml#alpn-protocol-ids
For instance, for an HTTP server supporting HTTP/1 and HTTP/2:
protocol h2 http/1.1 http/1.0
tls { ... }
Customise global TLS configuration.
The tls directive supports the following sub-directives:
acme_ca <url>
ACME Certificate Authority endpoint.
email <address>
The email address to use when creating or selecting an existing ACME server account
on_demand { ... }
Enable on-demand TLS.
When enabled, a TLS handshake may trigger maintenance for the relevant certificate. If no existing certificate is available, a new certificate is obtained and the connection is blocked until it’s available. If an existing certificate is available, the certificate is renewed in the background if necessary.
Warning: to prevent abuse, you should specify a validate_command sub-directive.
The on_demand directive supports the following optional sub-directives:
validate_command command [arguments...]
Command to run before an on-demand certificate is obtained. If the command returns a non-zero exit status, the request is denied.
The environment will contain a TLSTUNNEL_NAME variable with the domain name to be validated.
/etc/tlstunnel/config
Default configuration file location.
/var/lib/tlstunnel
State files such as certificates are stored in this directory.
Maintained by Simon Ser <[email protected]>, who is assisted by other open-source contributors. For more information about tlstunnel development, see <https://git.sr.ht/˜emersion/tlstunnel>.