From 3d28dda6cf926df5e99637449b52f4dab10fad12 Mon Sep 17 00:00:00 2001 From: Cedric Staub Date: Sun, 19 Apr 2026 20:28:27 -0700 Subject: [PATCH 1/2] Fix up release notes --- releases/v1.10.0-rc.1.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/releases/v1.10.0-rc.1.md b/releases/v1.10.0-rc.1.md index f2452813c1..3c0ed3285f 100644 --- a/releases/v1.10.0-rc.1.md +++ b/releases/v1.10.0-rc.1.md @@ -22,16 +22,14 @@ Release candidate for v1.10.0. include CFObject memory leaks in macOS CertificateChain, data races in macOS keychain lazy initialization, a C string leak in `launchdSocket`, a C array leak in `getProviderParam` on Windows, and incorrect certificate store search - order on Windows (#656, #694, #699, #700, #704). + order on Windows (#656, #694, #699, #704). * **Certloader safety improvements.** Replaced `unsafe.Pointer` with `atomic.Pointer[T]` in certloader (#677), extracted shared `baseCertificate` - struct to reduce duplication (#679), replaced `github.com/pkg/errors` with - stdlib `errors` and `fmt` (#684), and improved error context in PKCS#11 code - paths (#690). -* **Dependency cleanup.** Removed the `certigo` dependency (#664), switched - from `fullsailor/pkcs7` to `smallstep/pkcs7` (#663), and replaced - `github.com/pkg/errors` with stdlib `errors` and `fmt` (#684). Various - dependency upgrades via Dependabot. + struct to reduce duplication (#679), and improved error context in PKCS#11 + code paths (#690). +* **Dependency cleanup.** Removed the `certigo` dependency, switched to + `smallstep/pkcs7` (#664), and replaced `github.com/pkg/errors` with stdlib + `errors` and `fmt` (#684). Various dependency upgrades via Dependabot. ## Testing Improvements @@ -40,10 +38,11 @@ Release candidate for v1.10.0. better coverage of features like platform keychain identities. * **Faster & better integration test suite.** Parallelized integration tests with dynamic port allocation and improved timeout handling, significantly reducing - test suite runtime (#662, #696, #703). + test suite runtime (#662, #703). Skipped tests now report SKIP status with + a reason (#696). * **New unit and integration tests.** Added unit and integration tests for keychain handling, certstore reload paths, and edge cases across multiple - packages (#662, #697, #702, #703). + packages (#697, #700, #702). ## Other From f3367818c2cfc7d858069f02314247e402ca1462 Mon Sep 17 00:00:00 2001 From: Cedric Staub Date: Sun, 19 Apr 2026 20:47:40 -0700 Subject: [PATCH 2/2] Various corrections for docs pages for regenerate man pages --- README.md | 9 ++++----- docs/ACME.md | 4 +++- docs/DOCKER.md | 6 +++--- docs/GRACEFUL-SHUTDOWN.md | 10 +++++----- docs/KEYCHAIN.md | 9 +++++---- docs/MANPAGE-darwin.md | 11 ++++++++--- docs/MANPAGE-linux.md | 13 +++++++++---- docs/METRICS.md | 9 +++++---- docs/PROXY-PROTOCOL.md | 4 ++-- docs/SPIFFE-WORKLOAD-API.md | 2 +- 10 files changed, 45 insertions(+), 32 deletions(-) diff --git a/README.md b/README.md index af10e41567..1cee0942c3 100644 --- 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 index 6dca448435..d4e271b17f 100644 --- 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 index 13a727c092..f49d1ac61e 100644 --- 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 index fc7958c5ac..ac7043d3f1 100644 --- 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 index 01dc72c803..95d05dd312 100644 --- 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 index df19b367c7..b11915cf66 100644 --- 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 index dca27ac79c..396f5e8608 100644 --- 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* \ No newline at end of file +Project on GitHub: *https://github.com/ghostunnel/ghostunnel* diff --git a/docs/METRICS.md b/docs/METRICS.md index 3a54370407..575bf5353c 100644 --- 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 index 8c4ed16430..eb6d4e58a9 100644 --- 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 index 0f78d4b4cf..655ee58366 100644 --- 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