tlstunnel(1)

✨ tlstunnel(1) — bestie, it's a TLS reverse proxy ✨

okay so you're reading the General Commands Manual page for tlstunnel(1), and honestly? It's giving quiet infrastructure icon 💅. Let's get into it.

🌸 NAME 🌸

tlstunnel — TLS reverse proxy. That's the whole name, bestie.

🦋 SYNOPSIS 🦋

tlstunnel [options...]

💖 DESCRIPTION 💖

tlstunnel is a TLS reverse proxy with support for automatic TLS certificate retrieval via the ACME protocol. Lowkey magical, fr fr.

🎀 OPTIONS 🎀

• -h, -help — Show help message and quit. Cute, quick, iconic.
• -config <path> — Path to the configuration file. Yes, this is the one you point at your config file.

🌈 CONFIG 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. Yes bestie, signal-based reload, we love to see it.

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.
      • The backend directive supports the following sub-directives:
        • tls_certfp sha-256 <fingerprint> — Instead of using CAs to check the TLS certificate provided by the backend, check that the certificate matches the provided fingerprint. This can be used to connect to servers with a self-signed certificate, for instance.
          • The fingerprint of a certificate can be obtained via openssl(1):

openssl x509 -fingerprint -sha256 -noout <certificate>

• proxy_version <version> — PROXY protocol version to use, if +proxy is specified. The supported versions are 1 and 2. If not specified, the PROXY version used defaults to version 2.

• 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. The certificate must be valid for the names specified in listen addresses, if any.
    • client_auth <type> <cert> — Configures client authentication.
      • The available verification types are the following: request, require, verify, require_and_verify. They are defined here: https://pkg.go.dev/crypto/tls#ClientAuthType.
      • The certificate must be a PEM file and is used as a CA to validate client certificates.
• protocol <name>... — List of supported application-layer protocols.
  • The first protocol which is also supported by the client is negotiated. 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.

• acme_dns_command command [arguments...] — Configure the ACME DNS challenge using the specified command.
  • The command must implement deploy_challenge and clean_challenge as specified by dehydrated's hooks: https://github.com/dehydrated-io/dehydrated
• acme_dns_update <address> — Configure the ACME DNS challenge using the specified DNS UPDATE server.
  • The DNS server must implement DNS UPDATE as specified by RFC 2136.
• load <cert> <key> — Load certificates and private keys from PEM files.

🌟 FILES 🌟

• /etc/tlstunnel/config — Default configuration file location.
• /var/lib/tlstunnel — State files such as certificates are stored in this directory.

👑 AUTHORS 👑

Maintained by Simon Ser <contact@emersion.fr>, who is assisted by other open-source contributors. For more information about tlstunnel development, see <https://codeberg.org/emersion/tlstunnel>.

---

xoxo bestie 💖 that's the whole page: tlstunnel(1) from the General Commands Manual, dated 2026-10-14. periodt ✨