Merge pull request ghostunnel#710 from ghostunnel/cs/fixup

csstaub · web-flow · commit 4b45064c523b · 2026-04-19T21:12:25.000-07:00
Various corrections for docs pages and regenerate man pages
diff --git a/README.md b/README.md
@@ -306,11 +306,10 @@ successful, the reloaded certificate will be used for new connections going
 forward.
 
 Additionally, Ghostunnel uses `SO_REUSEPORT` to bind the listening socket on
-platforms where it is supported (Linux, Apple macOS, FreeBSD, NetBSD, OpenBSD
-and DragonflyBSD). This means a new Ghostunnel can be started on the same
-host/port before the old one is terminated, to minimize dropped connections (or
-avoid them entirely depending on how the OS implements the `SO_REUSEPORT`
-feature).
+platforms where it is supported (Linux, Apple macOS, FreeBSD, NetBSD and
+OpenBSD). This means a new Ghostunnel can be started on the same host/port
+before the old one is terminated, to minimize dropped connections (or avoid
+them entirely depending on how the OS implements the `SO_REUSEPORT` feature).
 
 Note that if you are using an HSM/PKCS#11 module, only the certificate will
 be reloaded. It is assumed that the private key in the HSM remains the same.
diff --git a/docs/ACME.md b/docs/ACME.md
@@ -29,7 +29,9 @@ ghostunnel server \
 Ghostunnel defaults to using [Let's Encrypt][letsencrypt] as the ACME CA. You
 can specify a different ACME CA URL using `--auto-acme-ca`. To test against a
 non-production CA (e.g. Let's Encrypt's staging environment), use
-`--auto-acme-testca`. When set, the `--auto-acme-ca` flag is ignored.
+`--auto-acme-testca=URL` with the staging CA's directory URL (e.g.
+`--auto-acme-testca=https://acme-staging-v02.api.letsencrypt.org/directory`).
+When set, the `--auto-acme-ca` flag is ignored.
 
 ## Requirements
 
diff --git a/docs/DOCKER.md b/docs/DOCKER.md
@@ -9,9 +9,9 @@ variants are available:
 
 | Variant | Tag | Base |
 |---------|-----|------|
-| Alpine | `ghostunnel/ghostunnel:latest`, `ghostunnel/ghostunnel:v1.x.x` | Alpine Linux |
-| Debian | `ghostunnel/ghostunnel:latest-debian`, `ghostunnel/ghostunnel:v1.x.x-debian` | Debian slim |
-| Distroless | `ghostunnel/ghostunnel:latest-distroless`, `ghostunnel/ghostunnel:v1.x.x-distroless` | Google Distroless |
+| Alpine | `ghostunnel/ghostunnel:latest-alpine`, `ghostunnel/ghostunnel:v1.x.x-alpine` | Alpine Linux |
+| Debian | `ghostunnel/ghostunnel:latest-debian`, `ghostunnel/ghostunnel:v1.x.x-debian` | Debian Slim |
+| Distroless | `ghostunnel/ghostunnel:latest-distroless`, `ghostunnel/ghostunnel:v1.x.x-distroless` | Distroless (`gcr.io/distroless/base-nossl:nonroot`) |
 
 The `latest` tags always point to the most recent release.
 
diff --git a/docs/GRACEFUL-SHUTDOWN.md b/docs/GRACEFUL-SHUTDOWN.md
@@ -54,11 +54,11 @@ When a shutdown is triggered, the following happens in order:
    that the process is shutting down.
 2. **Status HTTP server begins shutting down**: best-effort graceful shutdown
    of the internal status listener.
-3. **Listener closes**: Ghostunnel stops accepting new connections.
-4. **In-flight connections continue**: existing connections are not
-   interrupted. Data continues to flow until both sides close normally.
-5. **Force-exit timer starts**: a timer begins counting down from the
+3. **Force-exit timer starts**: a timer begins counting down from the
    `--shutdown-timeout` value (default: 5 minutes).
+4. **Listener closes**: Ghostunnel stops accepting new connections.
+5. **In-flight connections continue**: existing connections are not
+   interrupted. Data continues to flow until both sides close normally.
 6. **Process exits** when either:
    - All in-flight connections have drained (exit code 0), or
    - The shutdown timeout fires (exit code 1).
@@ -88,7 +88,7 @@ workload when tuning this value:
   `terminationGracePeriodSeconds`) to avoid the orchestrator killing the
   process before Ghostunnel's own timeout fires.
 
-Other flags like `--connect-timeout` and `--conn-max-lifetime` also influence
+Other flags like `--connect-timeout` and `--max-conn-lifetime` also influence
 connection behavior and may be relevant when tuning shutdown. See
 [Command-Line Flags]({{< ref "FLAGS.md" >}}) for the full list.
 
diff --git a/docs/KEYCHAIN.md b/docs/KEYCHAIN.md
@@ -80,7 +80,7 @@ ghostunnel server \
     --allow-ou=client
 ```
 
-This flag is only available on macOS and has no effect on Windows.
+This flag is only available on macOS.
 
 See Apple's [Protecting keys with the Secure Enclave][apple-secure-enclave]
 and the [Secure Enclave security overview][apple-se-overview] for more on
@@ -174,7 +174,8 @@ ghostunnel client \
 ### Windows
 
 On Windows, `--keychain-identity` and `--keychain-issuer` work the same way
-but search the Windows Certificate Store (the "MY" store for the current user):
+but search the Windows Certificate Store (MY, CURRENT_SERVICE, and
+LOCAL_MACHINE stores, as described [above](#importing-into-the-certificate-store)):
 
 ```bash
 ghostunnel client \
@@ -186,8 +187,8 @@ ghostunnel client \
 
 ## Certificate Reloading
 
-Keychain certificates support reloading via `SIGHUP`/`SIGUSR1` or
-`--timed-reload`. On reload, Ghostunnel re-queries the keychain for a
+Keychain certificates support reloading via `SIGHUP`/`SIGUSR1` (Unix only) or
+`--timed-reload` (all platforms). On reload, Ghostunnel re-queries the keychain for a
 certificate matching the same identity/issuer criteria. If the certificate
 has been updated in the keychain (e.g. renewed), the new certificate will
 be used for subsequent connections.
diff --git a/docs/MANPAGE-darwin.md b/docs/MANPAGE-darwin.md
@@ -201,7 +201,7 @@ PKCS12 keystore).
 
 **--key=PATH** Path to certificate private key (PEM with private key).
 
-**--storepass=PASS** Password for keystore (if using PKCS keystore,
+**--storepass=PASS** Password for keystore (if using PKCS12 keystore,
 optional).
 
 **--cacert=CACERT** Path to CA bundle file (PEM/X509). Uses system trust
@@ -297,8 +297,13 @@ unix:PATH).
 **--target-status=""** Address to target for status checking downstream
 healthchecks. Defaults to a TCP healthcheck if this flag is not passed.
 
-**--proxy-protocol** Enable PROXY protocol v2 to signal connection info
-to backend
+**--proxy-protocol** Enable PROXY protocol v2 (connection info only,
+equivalent to --proxy-protocol-mode=conn).
+
+**--proxy-protocol-mode=PROXY-PROTOCOL-MODE** PROXY protocol v2 mode:
+conn (connection info only), tls (add TLS version/ALPN/SNI metadata),
+tls-full (add TLS metadata and client certificate). Mutually exclusive
+with --proxy-protocol.
 
 **--unsafe-target** If set, does not limit target to localhost,
 127.0.0.1, \[::1\], or UNIX sockets.
diff --git a/docs/MANPAGE-linux.md b/docs/MANPAGE-linux.md
@@ -201,7 +201,7 @@ PKCS12 keystore).
 
 **--key=PATH** Path to certificate private key (PEM with private key).
 
-**--storepass=PASS** Password for keystore (if using PKCS keystore,
+**--storepass=PASS** Password for keystore (if using PKCS12 keystore,
 optional).
 
 **--cacert=CACERT** Path to CA bundle file (PEM/X509). Uses system trust
@@ -290,8 +290,13 @@ unix:PATH).
 **--target-status=""** Address to target for status checking downstream
 healthchecks. Defaults to a TCP healthcheck if this flag is not passed.
 
-**--proxy-protocol** Enable PROXY protocol v2 to signal connection info
-to backend
+**--proxy-protocol** Enable PROXY protocol v2 (connection info only,
+equivalent to --proxy-protocol-mode=conn).
+
+**--proxy-protocol-mode=PROXY-PROTOCOL-MODE** PROXY protocol v2 mode:
+conn (connection info only), tls (add TLS version/ALPN/SNI metadata),
+tls-full (add TLS metadata and client certificate). Mutually exclusive
+with --proxy-protocol.
 
 **--unsafe-target** If set, does not limit target to localhost,
 127.0.0.1, \[::1\], or UNIX sockets.
@@ -397,4 +402,4 @@ connections could drain.
 
 Website: *https://ghostunnel.dev*
 
-Project on GitHub: *https://github.com/ghostunnel/ghostunnel*
+Project on GitHub: *https://github.com/ghostunnel/ghostunnel*
diff --git a/docs/METRICS.md b/docs/METRICS.md
@@ -77,10 +77,11 @@ flag, see
 
 ## Backend Healthchecks
 
-The `/_status` endpoint includes a backend healthcheck. By default, Ghostunnel
-performs a TCP connection check against the `--target` address. You can override
-this with `--target-status=URL` to perform an HTTP GET against the given URL
-instead. Ghostunnel expects an HTTP 200 response.
+The `/_status` endpoint includes a backend healthcheck (server mode only). By
+default, Ghostunnel performs a TCP connection check against the `--target`
+address. You can override this with `--target-status=URL` (must use `http://`
+or `https://` scheme) to perform an HTTP GET against the given URL instead.
+Ghostunnel expects an HTTP 200 response.
 
 The `/_status` JSON response includes:
 
diff --git a/docs/PROXY-PROTOCOL.md b/docs/PROXY-PROTOCOL.md
@@ -46,8 +46,8 @@ ghostunnel server ... --proxy-protocol-mode=tls
 ghostunnel server ... --proxy-protocol-mode=tls-full
 ```
 
-Using `--proxy-protocol-mode` implies `--proxy-protocol`; you do not need to
-pass both.
+`--proxy-protocol-mode` and `--proxy-protocol` are mutually exclusive; use one
+or the other, not both.
 
 The backend will receive a PROXY protocol v2 binary header on each new
 connection, followed by the normal application data stream.
diff --git a/docs/SPIFFE-WORKLOAD-API.md b/docs/SPIFFE-WORKLOAD-API.md
@@ -22,7 +22,7 @@ On UNIX systems (Linux, macOS):
 
 ```bash
 ghostunnel server \
-    --use-workload-api-addr /run/spire/sockets/agent.sock \
+    --use-workload-api-addr unix:///run/spire/sockets/agent.sock \
     --listen localhost:8443 \
     --target localhost:8080 \
     --allow-uri spiffe://domain.test/frontend
