diff --git a/Makefile b/Makefile index f1b493a4ed..ad99a7ed74 100644 --- a/Makefile +++ b/Makefile @@ -12,7 +12,7 @@ ghostunnel.man: ghostunnel # Man page for docs docs/MANPAGE.md: ghostunnel - ./ghostunnel --help-man | pandoc --from man --to markdown > $@ + ./ghostunnel --help-custom-man | pandoc --wrap=preserve --from man --to markdown > $@ # Test binary with coverage instrumentation ghostunnel.test: $(SOURCE_FILES) diff --git a/README.md b/README.md index 8e52520b91..755f468f93 100644 --- a/README.md +++ b/README.md @@ -146,12 +146,12 @@ example, both the listen and target flags can also accept paths to UNIX domain sockets as their argument. To set allowed clients, you must specify at least one of `--allow-all`, -`--allow-cn`, `--allow-ou`, `--allow-dns` or `--allow-uri`. All checks are made -against the certificate of the client. Multiple flags are treated as a logical -disjunction (OR), meaning clients can connect as long as any of the flags -matches (see [ACCESS-FLAGS](docs/ACCESS-FLAGS.md) for more information). In -this example, we assume that the CN of the client cert we want to accept -connections from is `client`. +`--allow-cn`, `--allow-ou`, `--allow-dns`, `--allow-uri` or `--alow-policy`. All +checks are made against the certificate of the client. Multiple flags are +treated as a logical disjunction (OR), meaning clients can connect as long as +any of the flags matches. See [ACCESS-FLAGS](docs/ACCESS-FLAGS.md) for more +information. In this example, we assume that the CN of the client cert we want +to accept connections from is `client`. Start a backend server: @@ -182,6 +182,11 @@ Ghostunnel and forward the connections to the insecure backend. This is an example for how to launch Ghostunnel in client mode, listening on `localhost:8080` and proxying requests to a TLS server on `localhost:8443`. +By default, Ghostunnel in client mode verifies targets based on the hostname. +Various access control flags exist to perform additional verification on top of +the regular hostname verification. See [ACCESS-FLAGS](docs/ACCESS-FLAGS.md) for +more information. + Start a backend TLS server: openssl s_server \ @@ -355,4 +360,12 @@ this option. ### Landlock Support -Ghostunnel can use [Landlock](https://landlock.io) to limit process privileges on Linux. Landlock is enabled by default (in best-effort mode) on v1.9.0 or later. On Ghostunnel v1.8.x, Landlock can enabled using the `--use-landlock` flag. When enabled, Ghostunnel will limit its access to files and sockets based on the flags passed at startup. Note that Landlock does not work with PKCS#11 modules and is disabled if PKCS#11 is used (as PKCS#11 modules are opaque to us we can't craft workable Landlock rules for them). +Ghostunnel can use [Landlock](https://landlock.io) to limit process privileges +on Linux. Landlock is enabled by default (in best-effort mode) on v1.9.0 or +later. On Ghostunnel v1.8.x, Landlock can enabled using the `--use-landlock` +flag. On Ghostunnel v1.9.x and later, Landlock can be disabled using +`--disable-landlock` if necessary (not recommended). When enabled, Ghostunnel +will limit its access to files and sockets based on the flags passed at +startup. Note that Landlock does not work with PKCS#11 modules and is disabled +if PKCS#11 is used (as PKCS#11 modules are opaque to us we can't craft workable + Landlock rules for them). diff --git a/doc.go b/doc.go index 0c126dc3aa..ca1c568c54 100644 --- a/doc.go +++ b/doc.go @@ -16,9 +16,9 @@ import ( var manPageTemplate = `{{define "FormatFlags"}}\ {{range .Flags}}\ {{if not .Hidden}}\ -.TP -\fB{{if .Short}}-{{.Short|Char}}, {{end}}--{{.Name}}{{if not .IsBoolFlag}}={{.FormatPlaceHolder}}{{end}}\\fR +\fB{{if .Short}}-{{.Short|Char}}, {{end}}--{{.Name}}{{if not .IsBoolFlag}}={{.FormatPlaceHolder}}{{end}}\fR {{.Help}} +.PP {{end}}\ {{end}}\ {{end}}\ @@ -28,9 +28,9 @@ var manPageTemplate = `{{define "FormatFlags"}}\ {{end}}\ {{define "FormatCommands"}}\ {{range .FlattenedCommands}}\ -{{if not .Hidden}}\ +{{if not .Hidden}} .SS -\fB{{.FullCommand}}{{template "FormatCommand" .}}\\fR +\fB{{.FullCommand}}{{template "FormatCommand" .}}\fR .PP {{.Help}} {{template "FormatFlags" .}}\ @@ -38,14 +38,15 @@ var manPageTemplate = `{{define "FormatFlags"}}\ {{end}}\ {{end}}\ {{define "FormatUsage"}}\ -{{template "FormatCommand" .}}{{if .Commands}} [ ...]{{end}}\\fR -{{end}}\ +{{template "FormatCommand" .}}{{if .Commands}} [ ...]{{end}}\fR +{{end}} .TH {{.App.Name}} 1 {{.App.Version}} "{{.App.Author}}" .SH "NAME" {{.App.Name}} .SH "SYNOPSIS" +\fB{{.App.Name}}{{template "FormatUsage" .App}}\fR .TP -\fB{{.App.Name}}{{template "FormatUsage" .App}} + .SH "DESCRIPTION" {{.App.Help}} @@ -57,68 +58,173 @@ a TCP domain/port or a UNIX domain socket. Ghostunnel in client mode accepts a TLS-secured service. For a more in-depth explanation, please see the README.md file (and docs -folder) that shipped with ghostunnel or view the latest docs on +folder) that shipped with Ghostunnel or view the latest docs on github.com/ghostunnel/ghostunnel. .SH "CERTIFICATES & PRIVATE KEYS" -Ghostunnel accepts certificates in multiple different file formats. +Ghostunnel supports multiple methods for loading certificates and private keys. +File-based formats: +.RS The \fB--keystore\fR flag can take a PKCS#12 keystore or a combined PEM file with the certificate chain and private key as input (format is auto-detected). The \fB--cert\fR and \fB--key\fR flags can be used to load a certificate chain and key from separate PEM files (instead of a combined one). +.RE + +SPIFFE Workload API: +.RS +Ghostunnel can retrieve certificates and root CAs from the SPIFFE Workload API +using the \fB--use-workload-api\fR flag. This enables automatic certificate +rotation and is useful in service mesh deployments. The Workload API socket +location can be specified via the \fBSPIFFE_ENDPOINT_SOCKET\fR environment +variable or the \fB--use-workload-api-addr\fR flag. +.RE + +ACME (Automatic Certificate Management): +.RS +In server mode, Ghostunnel can automatically obtain and renew public TLS +certificates using the ACME protocol (e.g., Let's Encrypt). Use +\fB--auto-acme-cert\fR with \fB--auto-acme-email\fR and +\fB--auto-acme-agree-to-tos\fR. This requires Ghostunnel to be accessible on +a public interface (tcp/443) with valid DNS records. The ACME CA URL can be +specified with \fB--auto-acme-ca\fR (defaults to Let's Encrypt). +.RE + +PKCS#11 (Hardware Security Modules): +.RS +Private keys can be stored in PKCS#11-compatible hardware security modules +(HSMs). Use \fB--cert\fR to specify the certificate chain file, and +\fB--pkcs11-module\fR, \fB--pkcs11-token-label\fR, and \fB--pkcs11-pin\fR to +configure the HSM. PKCS#11 options can also be set via environment variables +(\fBPKCS11_MODULE\fR, \fBPKCS11_TOKEN_LABEL\fR, \fBPKCS11_PIN\fR). +.RE + +Keychain (macOS/Windows): +.RS +On macOS and Windows, Ghostunnel can load certificates from the system keychain +using \fB--keychain-identity\fR (by subject CN/serial) or \fB--keychain-issuer\fR +(by issuer CN). On macOS, \fB--keychain-require-token\fR can be used to +require certificates from physical tokens (e.g., Touch ID MacBooks). +.RE -Ghostunnel also supports loading identities from the macOS keychain and having -private keys backed by PKCS#11 modules, see the documentation on GitHub for -examples. - -In server mode, Ghostunnel supports automatically obtaining and renewing a -public TLS certificate using the ACME protocol. This requires either Ghostunnel -to listen on tcp/443 on a public interface, or somehow a public tcp/443 -interface needs to be forwarded to Ghostunnel's server listening port -(e.g. - systemd socket, iptables, etc.). The URL to the ACME CA can be specified -using the \fB--auto-acme-ca=\fR flag. If not specified, Ghostunnel defaults -to using Let's Encrypt. .SH "EXAMPLE: SERVER MODE" Start a ghostunnel in server mode to proxy connections from localhost:8443 to localhost:8080, while only allowing connections from client certificates with CN=client: +.nf ghostunnel server \\ --listen localhost:8443 \\ --target localhost:8080 \\ --keystore server-keystore.p12 \\ --cacert cacert.pem \\ --allow-cn client +.fi To set allowed clients, you must specify at least one of \fB--allow-all\fR, -\fB--allow-cn\fR, \fB--allow-ou\fR, \fB--allow-dns\fR or \fB--allow-uri\fR. All -checks are made against the certificate of the client. Multiple flags are -treated as a logical disjunction (OR), meaning clients can connect as long as -any of the flags match. To disable requiring client certificates, use -\fB--disable-authentication\fR. +\fB--allow-cn\fR, \fB--allow-ou\fR, \fB--allow-dns\fR, \fB--allow-uri\fR, or +\fB--allow-policy\fR. All checks are made against the certificate of the client. +Multiple flags are treated as a logical disjunction (OR), meaning clients can +connect as long as any of the flags match. To disable requiring client +certificates, use \fB--disable-authentication\fR. + .SH "EXAMPLE: CLIENT MODE" Start a ghostunnel in client mode to proxy connections from localhost:8080 to localhost:8443, doing only hostname verification to validate the server certificate: +.nf ghostunnel client \\ --listen localhost:8080 \\ --target localhost:8443 \\ --cert client-cert.pem \\ --key client-key.pem \\ --cacert cacert.pem +.fi Use \fB--override-server-name\fR to overrides the server name used for hostname verification. Various access control flags exist to perform additional verification (on top of the regular hostname verification) of server -certificates, such as \fB--verify-cn\fR, \fB--verify-ou\fR, \fB--verify-dns\fR -and \fB--verify-uri\fR. Multiple flags are treated as a logical disjunction -(OR), meaning clients will connect to the server as long as any of the flags -match, assuming that hostname verification was also successful. To disable -sending client certificates, use \fB--disable-authentication\fR. +certificates, such as \fB--verify-cn\fR, \fB--verify-ou\fR, \fB--verify-dns\fR, +\fB--verify-uri\fR, or \fB--verify-policy\fR. Multiple flags are treated as a +logical disjunction (OR), meaning clients will connect to the server as long as +any of the flags match, assuming that hostname verification was also successful. +To disable sending client certificates, use \fB--disable-authentication\fR. + +.SH "EXAMPLE: UNIX SOCKETS" +Ghostunnel supports UNIX domain sockets for both listening and forwarding: + +.nf +# Server mode with UNIX socket +ghostunnel server \\ + --listen unix:/var/run/ghostunnel.sock \\ + --target unix:/var/run/backend.sock \\ + --keystore server-keystore.p12 \\ + --cacert cacert.pem \\ + --allow-cn client + +# Client mode with UNIX socket listener +ghostunnel client \\ + --listen unix:/var/run/client.sock \\ + --target localhost:8443 \\ + --keystore client-keystore.p12 \\ + --cacert cacert.pem +.fi + +UNIX sockets provide secure local communication without network exposure. + +.SH "EXAMPLE: STATUS AND METRICS" +Enable status and metrics endpoints for monitoring and health checks: + +.nf +ghostunnel server \\ + --listen localhost:8443 \\ + --target localhost:8080 \\ + --keystore server-keystore.p12 \\ + --cacert cacert.pem \\ + --allow-cn client \\ + --status localhost:6060 +.fi + +Access status and metrics: +.nf +# Status information (JSON) +curl --cacert cacert.pem https://localhost:6060/_status + +# Metrics (Prometheus format) +curl --cacert cacert.pem https://localhost:6060/_metrics/prometheus + +# Metrics (JSON format) +curl --cacert cacert.pem https://localhost:6060/_metrics/json +.fi + +The status port can also use HTTP by prefixing with "http://" (e.g., +\fB--status http://localhost:6060\fR). Profiling endpoints can be enabled +with \fB--enable-pprof\fR. + +.SH "EXAMPLE: MULTIPLE ACCESS CONTROL FLAGS" +Multiple access control flags can be combined using OR logic: + +.nf +ghostunnel server \\ + --listen localhost:8443 \\ + --target localhost:8080 \\ + --keystore server-keystore.p12 \\ + --cacert cacert.pem \\ + --allow-cn client1 \\ + --allow-cn client2 \\ + --allow-ou developers \\ + --allow-uri spiffe://example.com/* +.fi + +Clients matching any of the specified criteria (CN=client1 or CN=client2 or +OU=developers or URI matching spiffe://example.com/*) will be allowed to +connect. The same OR logic applies to client mode verification flags +(\fB--verify-cn\fR, \fB--verify-ou\fR, \fB--verify-dns\fR, \fB--verify-uri\fR). + .SH "OPTIONS" {{template "FormatFlags" .App}}\ -{{if .App.Commands}}\ +{{if .App.Commands}} .SH "COMMANDS" {{template "FormatCommands" .App}}\ {{end}}\ diff --git a/docs/MANPAGE.md b/docs/MANPAGE.md index 02ff6b25c5..c0b0a3868b 100644 --- a/docs/MANPAGE.md +++ b/docs/MANPAGE.md @@ -6,295 +6,256 @@ ghostunnel **ghostunnel \[\\] \ \[\ \...\]** -: # DESCRIPTION +# DESCRIPTION -A simple SSL/TLS proxy with mutual authentication for securing non-TLS -services. +A simple SSL/TLS proxy with mutual authentication for securing non-TLS services. -# OPTIONS - -**\--help** - -: Show context-sensitive help (also try \--help-long and \--help-man). - -**\--keystore=PATH** - -: Path to keystore (combined PEM with cert/key, or PKCS12 keystore). - -**\--cert=PATH** - -: Path to certificate (PEM with certificate chain). - -**\--key=PATH** +Ghostunnel supports two modes, client mode and server mode. Ghostunnel in server mode runs in front of a backend server and accepts TLS-secured connections, which are then proxied to the (insecure) backend. A backend can be a TCP domain/port or a UNIX domain socket. Ghostunnel in client mode accepts (insecure) connections through a TCP or UNIX domain socket and proxies them to a TLS-secured service. -: Path to certificate private key (PEM with private key). +For a more in-depth explanation, please see the README.md file (and docs folder) that shipped with Ghostunnel or view the latest docs on github.com/ghostunnel/ghostunnel. -**\--storepass=PASS** +# CERTIFICATES & PRIVATE KEYS -: Password for keystore (if using PKCS keystore, optional). +Ghostunnel supports multiple methods for loading certificates and private keys. -**\--cacert=CACERT** +File-based formats: -: Path to CA bundle file (PEM/X509). Uses system trust store by - default. +> The **\--keystore** flag can take a PKCS#12 keystore or a combined PEM file with the certificate chain and private key as input (format is auto-detected). The **\--cert** and **\--key** flags can be used to load a certificate chain and key from separate PEM files (instead of a combined one). -**\--use-workload-api** +SPIFFE Workload API: -: If true, certificate and root CAs are retrieved via the SPIFFE - Workload API +> Ghostunnel can retrieve certificates and root CAs from the SPIFFE Workload API using the **\--use-workload-api** flag. This enables automatic certificate rotation and is useful in service mesh deployments. The Workload API socket location can be specified via the **SPIFFE_ENDPOINT_SOCKET** environment variable or the **\--use-workload-api-addr** flag. -**\--use-workload-api-addr=ADDR** +ACME (Automatic Certificate Management): -: If set, certificates and root CAs are retrieved via the SPIFFE - Workload API at the specified address (implies \--use-workload-api) +> In server mode, Ghostunnel can automatically obtain and renew public TLS certificates using the ACME protocol (e.g., Let\'s Encrypt). Use **\--auto-acme-cert** with **\--auto-acme-email** and **\--auto-acme-agree-to-tos**. This requires Ghostunnel to be accessible on a public interface (tcp/443) with valid DNS records. The ACME CA URL can be specified with **\--auto-acme-ca** (defaults to Let\'s Encrypt). -**\--timed-reload=DURATION** +PKCS#11 (Hardware Security Modules): -: Reload keystores every given interval (e.g. 300s), refresh - listener/client on changes. +> Private keys can be stored in PKCS#11-compatible hardware security modules (HSMs). Use **\--cert** to specify the certificate chain file, and **\--pkcs11-module**, **\--pkcs11-token-label**, and **\--pkcs11-pin** to configure the HSM. PKCS#11 options can also be set via environment variables (**PKCS11_MODULE**, **PKCS11_TOKEN_LABEL**, **PKCS11_PIN**). -**\--shutdown-timeout=5m** +Keychain (macOS/Windows): -: Process shutdown timeout. Terminates after timeout even if - connections still open. +> On macOS and Windows, Ghostunnel can load certificates from the system keychain using **\--keychain-identity** (by subject CN/serial) or **\--keychain-issuer** (by issuer CN). On macOS, **\--keychain-require-token** can be used to require certificates from physical tokens (e.g., Touch ID MacBooks). -**\--connect-timeout=10s** +# EXAMPLE: SERVER MODE -: Timeout for establishing connections, handshakes. +Start a ghostunnel in server mode to proxy connections from localhost:8443 to localhost:8080, while only allowing connections from client certificates with CN=client: -**\--close-timeout=10s** + ghostunnel server \ + --listen localhost:8443 \ + --target localhost:8080 \ + --keystore server-keystore.p12 \ + --cacert cacert.pem \ + --allow-cn client -: Timeout for closing connections when one side terminates. +To set allowed clients, you must specify at least one of **\--allow-all**, **\--allow-cn**, **\--allow-ou**, **\--allow-dns**, **\--allow-uri**, or **\--allow-policy**. All checks are made against the certificate of the client. Multiple flags are treated as a logical disjunction (OR), meaning clients can connect as long as any of the flags match. To disable requiring client certificates, use **\--disable-authentication**. -**\--max-conn-lifetime=0s** +# EXAMPLE: CLIENT MODE -: Maximum lifetime for connections post handshake, no matter what. - Zero means infinite. +Start a ghostunnel in client mode to proxy connections from localhost:8080 to localhost:8443, doing only hostname verification to validate the server certificate: -**\--max-concurrent-conns=0** + ghostunnel client \ + --listen localhost:8080 \ + --target localhost:8443 \ + --cert client-cert.pem \ + --key client-key.pem \ + --cacert cacert.pem -: Maximum number of concurrent connections to handle in the proxy. - Zero means infinite. +Use **\--override-server-name** to overrides the server name used for hostname verification. Various access control flags exist to perform additional verification (on top of the regular hostname verification) of server certificates, such as **\--verify-cn**, **\--verify-ou**, **\--verify-dns**, **\--verify-uri**, or **\--verify-policy**. Multiple flags are treated as a logical disjunction (OR), meaning clients will connect to the server as long as any of the flags match, assuming that hostname verification was also successful. To disable sending client certificates, use **\--disable-authentication**. -**\--metrics-graphite=ADDR** +# EXAMPLE: UNIX SOCKETS -: Collect metrics and report them to the given graphite instance (raw - TCP). +Ghostunnel supports UNIX domain sockets for both listening and forwarding: -**\--metrics-url=URL** + # Server mode with UNIX socket + ghostunnel server \ + --listen unix:/var/run/ghostunnel.sock \ + --target unix:/var/run/backend.sock \ + --keystore server-keystore.p12 \ + --cacert cacert.pem \ + --allow-cn client -: Collect metrics and POST them periodically to the given URL (via - HTTP/JSON). + # Client mode with UNIX socket listener + ghostunnel client \ + --listen unix:/var/run/client.sock \ + --target localhost:8443 \ + --keystore client-keystore.p12 \ + --cacert cacert.pem -**\--metrics-prefix=PREFIX** +UNIX sockets provide secure local communication without network exposure. -: Set prefix string for all reported metrics (default: ghostunnel). +# EXAMPLE: STATUS AND METRICS -**\--metrics-interval=30s** +Enable status and metrics endpoints for monitoring and health checks: -: Collect (and post/send) metrics every specified interval. + ghostunnel server \ + --listen localhost:8443 \ + --target localhost:8080 \ + --keystore server-keystore.p12 \ + --cacert cacert.pem \ + --allow-cn client \ + --status localhost:6060 -**\--status=ADDR** +Access status and metrics: -: Enable serving /\_status and /\_metrics on given HOST:PORT (or - unix:SOCKET). + # Status information (JSON) + curl --cacert cacert.pem https://localhost:6060/_status -**\--enable-pprof** + # Metrics (Prometheus format) + curl --cacert cacert.pem https://localhost:6060/_metrics/prometheus -: Enable serving /debug/pprof endpoints alongside /\_status (for - profiling). + # Metrics (JSON format) + curl --cacert cacert.pem https://localhost:6060/_metrics/json -**\--enable-shutdown** +The status port can also use HTTP by prefixing with \"http://\" (e.g., **\--status http://localhost:6060**). Profiling endpoints can be enabled with **\--enable-pprof**. -: Enable serving a /\_shutdown endpoint alongside /\_status to allow - terminating via HTTP. +# EXAMPLE: MULTIPLE ACCESS CONTROL FLAGS -**\--quiet=** +Multiple access control flags can be combined using OR logic: -: Silence log messages (can be all, conns, conn-errs, handshake-errs; - repeat flag for more than one) + ghostunnel server \ + --listen localhost:8443 \ + --target localhost:8080 \ + --keystore server-keystore.p12 \ + --cacert cacert.pem \ + --allow-cn client1 \ + --allow-cn client2 \ + --allow-ou developers \ + --allow-uri spiffe://example.com/* -**\--syslog** +Clients matching any of the specified criteria (CN=client1 or CN=client2 or OU=developers or URI matching spiffe://example.com/\*) will be allowed to connect. The same OR logic applies to client mode verification flags (**\--verify-cn**, **\--verify-ou**, **\--verify-dns**, **\--verify-uri**). -: Send logs to syslog instead of stderr. - -**\--keychain-identity=CN** - -: Use local keychain identity with given serial/common name (instead - of keystore file). +# OPTIONS -**\--keychain-issuer=CN** +**\--help** Show context-sensitive help (also try \--help-long and \--help-man). -: Use local keychain identity with given issuer name (instead of - keystore file). +**\--keystore=PATH** Path to keystore (combined PEM with cert/key, or PKCS12 keystore). -**\--keychain-require-token** +**\--cert=PATH** Path to certificate (PEM with certificate chain). -: Require keychain identity to be from a physical token (sets \'access - group\' to \'token\'). +**\--key=PATH** Path to certificate private key (PEM with private key). -**\--pkcs11-module=PATH** +**\--storepass=PASS** Password for keystore (if using PKCS keystore, optional). -: Path to PKCS11 module (SO) file (optional). +**\--cacert=CACERT** Path to CA bundle file (PEM/X509). Uses system trust store by default. -**\--pkcs11-token-label=LABEL** +**\--use-workload-api** If true, certificate and root CAs are retrieved via the SPIFFE Workload API -: Token label for slot/key in PKCS11 module (optional). +**\--use-workload-api-addr=ADDR** If set, certificates and root CAs are retrieved via the SPIFFE Workload API at the specified address (implies \--use-workload-api) -**\--pkcs11-pin=PIN** +**\--timed-reload=DURATION** Reload keystores every given interval (e.g. 300s), refresh listener/client on changes. -: PIN code for slot/key in PKCS11 module (optional). +**\--shutdown-timeout=5m** Process shutdown timeout. Terminates after timeout even if connections still open. -**\--version** +**\--connect-timeout=10s** Timeout for establishing connections, handshakes. -: Show application version. +**\--close-timeout=1s** Timeout for closing connections when one side terminates. Zero means immediate closure. -# COMMANDS +**\--max-conn-lifetime=0s** Maximum lifetime for connections post handshake, no matter what. Zero means infinite. -## **help \[\\...\]** +**\--max-concurrent-conns=0** Maximum number of concurrent connections to handle in the proxy. Zero means infinite. -Show help. +**\--metrics-graphite=ADDR** Collect metrics and report them to the given graphite instance (raw TCP). -## **server \--listen=ADDR \--target=ADDR \[\\]** +**\--metrics-url=URL** Collect metrics and POST them periodically to the given URL (via HTTP/JSON). -Server mode (TLS listener -\> plain TCP/UNIX target). +**\--metrics-prefix=PREFIX** Set prefix string for all reported metrics (default: ghostunnel). -**\--listen=ADDR** +**\--metrics-interval=30s** Collect (and post/send) metrics every specified interval. -: Address and port to listen on (can be HOST:PORT, unix:PATH, - systemd:NAME or launchd:NAME). +**\--status=ADDR** Enable serving /\_status and /\_metrics on given HOST:PORT (or unix:SOCKET). -**\--target=ADDR** +**\--enable-pprof** Enable serving /debug/pprof endpoints alongside /\_status (for profiling). -: Address to forward connections to (can be HOST:PORT or unix:PATH). +**\--enable-shutdown** Enable serving a /\_shutdown endpoint alongside /\_status to allow terminating via HTTP. -**\--target-status=\"\"** +**\--quiet=** Silence log messages (can be all, conns, conn-errs, handshake-errs; repeat flag for more than one) -: Address to target for status checking downstream healthchecks. - Defaults to a TCP healthcheck if this flag is not passed. +**\--skip-resolve** Skip resolving target host on startup (useful to start Ghostunnel before network is up). -**\--proxy-protocol** +**\--syslog** Send logs to syslog instead of stderr. -: Enable PROXY protocol v2 to signal connection info to backend +**\--keychain-identity=CN** Use local keychain identity with given serial/common name (instead of keystore file). -**\--unsafe-target** +**\--keychain-issuer=CN** Use local keychain identity with given issuer name (instead of keystore file). -: If set, does not limit target to localhost, 127.0.0.1, \[::1\], or - UNIX sockets. +**\--keychain-require-token** Require keychain identity to be from a physical token (sets \'access group\' to \'token\'). -**\--allow-all** +**\--pkcs11-module=PATH** Path to PKCS11 module (SO) file (optional). -: Allow all clients, do not check client cert subject. +**\--pkcs11-token-label=LABEL** Token label for slot/key in PKCS11 module (optional). -**\--allow-cn=CN** +**\--pkcs11-pin=PIN** PIN code for slot/key in PKCS11 module (optional). -: Allow clients with given common name (can be repeated). +**\--version** Show application version. -**\--allow-ou=OU** +# COMMANDS -: Allow clients with given organizational unit name (can be repeated). +## **help \[\\...\]** -**\--allow-dns=DNS** +Show help. -: Allow clients with given DNS subject alternative name (can be - repeated). +## **server \--listen=ADDR \--target=ADDR \[\\]** -**\--allow-uri=URI** +Server mode (TLS listener -\> plain TCP/UNIX target). **\--listen=ADDR** Address and port to listen on (can be HOST:PORT, unix:PATH, systemd:NAME or launchd:NAME). -: Allow clients with given URI subject alternative name (can be - repeated). +**\--target=ADDR** Address to forward connections to (can be HOST:PORT or unix:PATH). -**\--allow-policy=BUNDLE** +**\--target-status=\"\"** Address to target for status checking downstream healthchecks. Defaults to a TCP healthcheck if this flag is not passed. -: Allow passing the location of an OPA bundle. +**\--proxy-protocol** Enable PROXY protocol v2 to signal connection info to backend -**\--allow-query=QUERY** +**\--unsafe-target** If set, does not limit target to localhost, 127.0.0.1, \[::1\], or UNIX sockets. -: Allow defining a query to validate against the client certificate - and the rego policy. +**\--allow-all** Allow all clients, do not check client cert subject. -**\--disable-authentication** +**\--allow-cn=CN** Allow clients with given common name (can be repeated). -: Disable client authentication, no client certificate will be - required. +**\--allow-ou=OU** Allow clients with given organizational unit name (can be repeated). -**\--auto-acme-cert=FQDN** +**\--allow-dns=DNS** Allow clients with given DNS subject alternative name (can be repeated). -: Automatically obtain a certificate via ACME for the specified FQDN +**\--allow-uri=URI** Allow clients with given URI subject alternative name (can be repeated). -**\--auto-acme-email=EMAIL** +**\--allow-policy=BUNDLE** Allow passing the location of an OPA bundle. -: Email address associated with all ACME requests +**\--allow-query=QUERY** Allow defining a query to validate against the client certificate and the Rego policy. -**\--auto-acme-agree-to-tos** +**\--disable-authentication** Disable client authentication, no client certificate will be required. -: Agree to the Terms of Service of the ACME CA +**\--auto-acme-cert=FQDN** Automatically obtain a certificate via ACME for the specified FQDN -**\--auto-acme-ca=https://some-acme-ca.example.com/** +**\--auto-acme-email=EMAIL** Email address associated with all ACME requests -: Specify the URL to the ACME CA. Defaults to Let\'s Encrypt if not - specified. +**\--auto-acme-agree-to-tos** Agree to the Terms of Service of the ACME CA -**\--auto-acme-testca=https://testing.some-acme-ca.example.com/** +**\--auto-acme-ca=https://some-acme-ca.example.com/** Specify the URL to the ACME CA. Defaults to Let\'s Encrypt if not specified. -: Specify the URL to the ACME CA\'s Test/Staging environment. If set, - all requests will go to this CA and \--auto-acme-ca will be ignored. +**\--auto-acme-testca=https://testing.some-acme-ca.example.com/** Specify the URL to the ACME CA\'s Test/Staging environment. If set, all requests will go to this CA and \--auto-acme-ca will be ignored. ## **client \--listen=ADDR \--target=ADDR \[\\]** -Client mode (plain TCP/UNIX listener -\> TLS target). - -**\--listen=ADDR** - -: Address and port to listen on (can be HOST:PORT, unix:PATH, - systemd:NAME or launchd:NAME). - -**\--target=ADDR** - -: Address to forward connections to (must be HOST:PORT). - -**\--unsafe-listen** - -: If set, does not limit listen to localhost, 127.0.0.1, \[::1\], or - UNIX sockets. - -**\--override-server-name=NAME** - -: If set, overrides the server name used for hostname verification. - -**\--proxy=URL** - -: If set, connect to target over given proxy (HTTP CONNECT or SOCKS5). - Must be a proxy URL. - -**\--verify-cn=CN** - -: Allow servers with given common name (can be repeated). - -**\--verify-ou=OU** +Client mode (plain TCP/UNIX listener -\> TLS target). **\--listen=ADDR** Address and port to listen on (can be HOST:PORT, unix:PATH, systemd:NAME or launchd:NAME). -: Allow servers with given organizational unit name (can be repeated). +**\--target=ADDR** Address to forward connections to (must be HOST:PORT). -**\--verify-dns=DNS** +**\--unsafe-listen** If set, does not limit listen to localhost, 127.0.0.1, \[::1\], or UNIX sockets. -: Allow servers with given DNS subject alternative name (can be - repeated). +**\--override-server-name=NAME** If set, overrides the server name used for hostname verification. -**\--verify-uri=URI** +**\--proxy=URL** If set, connect to target over given proxy (HTTP CONNECT or SOCKS5). Must be a proxy URL. -: Allow servers with given URI subject alternative name (can be - repeated). +**\--verify-cn=CN** Allow servers with given common name (can be repeated). -**\--verify-policy=BUNDLE** +**\--verify-ou=OU** Allow servers with given organizational unit name (can be repeated). -: Allow passing the location of an OPA bundle. +**\--verify-dns=DNS** Allow servers with given DNS subject alternative name (can be repeated). -**\--verify-query=QUERY** +**\--verify-uri=URI** Allow servers with given URI subject alternative name (can be repeated). -: Allow defining a query to validate against the client certificate - and the rego policy. +**\--verify-policy=BUNDLE** Allow passing the location of an OPA bundle. -**\--disable-authentication** +**\--verify-query=QUERY** Allow defining a query to validate against the client certificate and the Rego policy. -: Disable client authentication, no certificate will be provided to - the server. +**\--disable-authentication** Disable client authentication, no certificate will be provided to the server. diff --git a/docs/SPIFFE-WORKLOAD-API.md b/docs/SPIFFE-WORKLOAD-API.md index 5e89c85acf..cf73341272 100644 --- a/docs/SPIFFE-WORKLOAD-API.md +++ b/docs/SPIFFE-WORKLOAD-API.md @@ -12,8 +12,9 @@ and verifies them using SPIFFE authentication. To enable workload API support, use the `--use-workload-api` flag. By default, the location of the SPIFFE Workload API socket is picked up from the -`SPIFFE_ENDPOINT_SOCKET` environment variable. The `--workload-api-addr` flag -can be used to explicitly set the address, like so: +`SPIFFE_ENDPOINT_SOCKET` environment variable. If you prefer to specify this via +flag, the `--workload-api-addr` flag can be used to explicitly set the address, +like so: UNIX: ``` diff --git a/main.go b/main.go index a1e3e0f585..f07ac6eac6 100644 --- a/main.go +++ b/main.go @@ -85,7 +85,7 @@ var ( serverAllowedIPs = serverCommand.Flag("allow-ip", "").Hidden().PlaceHolder("SAN").IPList() serverAllowedURIs = serverCommand.Flag("allow-uri", "Allow clients with given URI subject alternative name (can be repeated).").PlaceHolder("URI").Strings() serverAllowPolicy = serverCommand.Flag("allow-policy", "Allow passing the location of an OPA bundle.").PlaceHolder("BUNDLE").String() - serverAllowQuery = serverCommand.Flag("allow-query", "Allow defining a query to validate against the client certificate and the rego policy.").PlaceHolder("QUERY").String() + serverAllowQuery = serverCommand.Flag("allow-query", "Allow defining a query to validate against the client certificate and the Rego policy.").PlaceHolder("QUERY").String() serverDisableAuth = serverCommand.Flag("disable-authentication", "Disable client authentication, no client certificate will be required.").Default("false").Bool() serverAutoACMEFQDN = serverCommand.Flag("auto-acme-cert", "Automatically obtain a certificate via ACME for the specified FQDN").PlaceHolder("FQDN").String() serverAutoACMEEmail = serverCommand.Flag("auto-acme-email", "Email address associated with all ACME requests").PlaceHolder("EMAIL").String() @@ -107,7 +107,7 @@ var ( clientAllowedIPs = clientCommand.Flag("verify-ip", "").Hidden().PlaceHolder("SAN").IPList() clientAllowedURIs = clientCommand.Flag("verify-uri", "Allow servers with given URI subject alternative name (can be repeated).").PlaceHolder("URI").Strings() clientAllowPolicy = clientCommand.Flag("verify-policy", "Allow passing the location of an OPA bundle.").PlaceHolder("BUNDLE").String() - clientAllowQuery = clientCommand.Flag("verify-query", "Allow defining a query to validate against the client certificate and the rego policy.").PlaceHolder("QUERY").String() + clientAllowQuery = clientCommand.Flag("verify-query", "Allow defining a query to validate against the client certificate and the Rego policy.").PlaceHolder("QUERY").String() clientDisableAuth = clientCommand.Flag("disable-authentication", "Disable client authentication, no certificate will be provided to the server.").Default("false").Bool() // TLS options