Bug fix release.

Bug Fixes

• UNIX socket targets in client mode restored. The stricter --target validation added in v1.11.0 (#762) rejected unix:PATH targets in client mode, even though they had worked through v1.10.0 (and remained supported in server mode). Client mode now accepts both HOST:PORT and unix:PATH targets again, while the listen-only systemd:/launchd: schemes stay rejected at startup. This is useful for sidecar setups where two processes rendezvous on a shared socket instead of a localhost port, with mTLS running over the socket. Note that a unix:PATH target carries no hostname, so set --override-server-name to give hostname verification a name to check (unless --use-workload-api or --verify-spki-pin replaces hostname verification) (#799, thanks to @molchalih).

Other

• Documentation fixes for --use-workload-api-timeout. The v1.11.1 release notes and the Linux man page now correctly document the --use-workload-api-timeout flag introduced in that release, instead of describing the initial SPIFFE Workload API fetch as bounded by the connect timeout (#800).

Highlights

• SPKI pinning. New --allow-spki-pin (server) and --verify-spki-pin (client) flags authenticate peers by pinning their public keys directly, with no CA involvement. Useful for out-of-band key distribution where running a PKI is overkill (#787 by @tomfitzhenry, #789).
• Hot-path performance improvements. TLS configs are now cached instead of re-cloned on every connection, metric collection is skipped entirely when no metrics sink is configured, and GOMAXPROCS now honors container CPU quotas (#781).
• Reliability fixes. A batch of fixes across proxy teardown, certificate reload (PKCS#11, macOS/Windows keychain), SPIFFE startup, and graceful shutdown (#786, #793).

New Features

• SPKI pinning. In server mode, --allow-spki-pin <algo>:<base64-digest> allows clients whose SPKI hash matches one of the given pins; in client mode, --verify-spki-pin verifies the server the same way. Pins are repeatable, support multiple hash algorithms, and accept the algorithm prefix case-insensitively. This is out-of-band key pinning: the peer is authenticated by the pin alone, and its certificate chain, validity period, and hostname are not verified. Thus, the flags are mutually exclusive with other access control/verification flags. In pin mode the server no longer advertises client CA names in the handshake, and --verify-spki-pin can be combined with --disable-authentication for DNS-over-TLS-style deployments without client certificates (#787, #789, thanks to @tomfitzhenry).

Behavior Changes

• Default --close-timeout raised from 1s to 60s. Connections are now half-closed during teardown, letting in-flight return traffic drain instead of being cut off after one second (see also the proxy teardown fixes below) (#786, #794).
• Fix GOMAXPROCS handling for containers. The explicit runtime.GOMAXPROCS(NumCPU) call was removed so the Go 1.25+ runtime can apply its cgroup-aware default in quota-limited containers and honor the GOMAXPROCS environment variable (#781).
• OPA policies combinable with other allow flags. --allow-policy can now be used together with other --allow-* flags instead of being mutually exclusive with them (#782), fixing an inconsistency in how the policy flag was treated between client and server modes.

Bug Fixes

• SPIFFE Workload API startup hang. Building a TLS config waited on the first Workload API update with an unbounded context, so an unreachable SPIFFE agent hung Ghostunnel forever instead of surfacing a startup error. The initial fetch is now bounded by the new --use-workload-api-timeout flag (default 10m); set it to 0 to wait indefinitely, restoring the previous behavior (#786, #793).
• PKCS#11 reload key mismatch. Reload now keeps the previous key pair when a freshly read certificate no longer matches the cached HSM private key, instead of publishing a broken cert/key pair (#786).
• Keychain resource leaks and races. Reload now closes the OS certificate store and releases unused identities (previously leaked on every startup and reload), cached certificate access in the macOS keychain identity is properly synchronized across concurrent handshakes, and Windows security status codes are compared without sign extension so errors map correctly (#786).
• Proxy teardown and error accounting. TLS connections are half-closed during copy teardown, backend dial and PROXY protocol header write failures are counted as errors, connection resets and broken pipes are treated as expected teardown, and Ghostunnel fails closed when PROXY protocol TLS metadata cannot be encoded (#786).
• Shutdown robustness. The connection wait-group slot is reserved before accepting, proxy shutdown is safe against concurrent calls, reload signals are ignored while draining during shutdown (previously a SIGHUP mid-drain could hard-kill the process), and the status endpoint keeps reporting stopping status once shutdown has begun instead of briefly flipping back to ready (#786).
• Reject JKS keystores with private keys. These use Sun's proprietary key protector, which is not supported; Ghostunnel now rejects them with an actionable error pointing at PKCS#12 conversion instead of failing obscurely (#786).
• Access control fast path. The URI SAN intersection checks are skipped when no --allow-uri is configured (#782).

Testing Improvements

• Load and stress integration tests. New integration tests covering handshake floods, idle connection reaping, accept error recovery, connection and semaphore churn, abortive closes, reload and shutdown-drain behavior, backend flapping, large transfers, full-duplex traffic, and small-write data integrity (#788). Also added regression tests for the reliability fixes in this release (#786).
• Coverage flake fixes. Integration tests now use unique per-process and per-invocation coverage directories, fixing coverage data corruption when tests run in parallel (#790, #791).

Other

• Website improvements. Added Pagefind search, copy-to-clipboard buttons on code blocks, previous/next navigation and edit-on-GitHub links on docs pages, anchors for deep linking, and general design polish; CI now builds the website and checks internal links on pull requests (#780, #784, #792).
• Documentation. New SPKI pinning docs, updated JCEKS/JKS format information with PKCS#12 conversion steps, regenerated man pages, and assorted documentation and code comment improvements (#782, #786, #789, #790).
• Dependency upgrades. Go dependency, golangci-lint, and GitHub Actions updates (#783).

New Flags

Highlights

• Native Windows Service Control Manager support. Ghostunnel can now run as a proper Windows service, with service install/uninstall/start/ stop/status subcommands and Windows Event Log integration via the new --eventlog flag (#712, #713, #717, thanks to @bdudley-cw for #712 and #717).
• TLS settings modernization. Dropped the explicit CurvePreferences setting so Ghostunnel inherits Go's defaults (which include the X25519MLKEM768 hybrid post-quantum key exchange), and added read/idle timeouts plus a bounded shutdown context on the status HTTP server (#761).
• FreeBSD in CI. Integration tests now run on FreeBSD in GitHub Actions, with coverage uploaded to Codecov (#750).

New Features

• Windows Service Control Manager. New service install, service uninstall, service start, service stop, and service status subcommands register Ghostunnel with the Windows SCM. The service starts automatically on boot, responds to stop/shutdown controls from the SCM, and reports start/failure status back through the SCM (#712, #717, thanks to @bdudley-cw). Non-Windows platforms are unaffected.
• Windows Event Log. New --eventlog flag sends logs to the Windows Event Log instead of stdout (#713).
• Generalized notify-ready. The systemd notify-ready code was generalized into a platform-independent helper and is now also used by the Windows SCM integration to signal readiness to the service manager.

Bug Fixes

• PROXY protocol over UNIX socket listeners. Fixed an issue where PROXY protocol on a UNIX socket listener dropped every connection (#751).
• Accept loop backoff. The accept loop no longer spins hot on persistent accept errors and instead backs off with a capped delay (#757).
• Wildcard separator handling. wildcard.CompileWithSeparator now properly regex-quotes the separator, and trailing-separator handling plus bare ** behavior are now correct (#752, #754).
• Shutdown handler. The /_shutdown handler can no longer block forever on repeated POSTs (#755).
• Rego policy reload race. Fixed a data race on env.regoPolicy between startup and the timed-reload goroutine (#760).
• Cipher-suite parsing. Deduplicated cipher-suite parsing logic so the client and server paths can no longer drift (#759).
• Target and status flag validation. Server mode now correctly rejects --target systemd: and --target launchd: at startup instead of accepting them and failing to dial later (#758), other undialable --target networks are now rejected at flag validation, and --status https:// is now rejected on non-TCP listeners (#762).
• ACME renewal under mTLS. Improved ACME certificate renewal when the listener is configured for mTLS (#743).
• Landlock UNIX-socket FS rules. Fixed Landlock silently dropping filesystem rules for UNIX socket paths (#742).
• Client mode UNIX socket unlink. Client mode no longer unlinks a UNIX socket that is managed by systemd or launchd socket activation (#745).
• Workload API flag validation. --use-workload-api is now rejected when combined with file-based credential flags (#744).
• Systemd socket activation. Fixed a bug where systemd socket activation could not be used for the listen and status sockets at the same time.

Code Quality Changes

• Landlock upgrade. Switched to the Landlock V8 ABI and added IgnoreIsMissing handling so Ghostunnel logs cleanly and continues without sandboxing on older kernels (#735, #736).
• Status HTTP server. Added ReadTimeout/IdleTimeout to the status HTTP server, dropped the now-counterproductive WriteTimeout, and bounded the shutdown context to 5s to avoid goroutine leaks (#761).
• Go version source of truth. Builds now derive the Go toolchain version from go.mod rather than a separately pinned version (#737).

Testing Improvements

• FreeBSD integration tests. Added a FreeBSD job to the GitHub Actions workflow running the full integration test suite, with coverage uploaded to Codecov (#750).
• Windows SCM integration tests. Added integration tests for the new Windows service subcommands and improved the integration test harness's coverage handling. The integration harness can now also run from a configurable temp directory (#746).
• ACME under mTLS regression test. Added integration and unit tests exercising ACME renewal under mTLS so the bug stays fixed (#743).
• Additional unit and integration tests. Broader coverage for error paths, corner cases, and previously-untested helpers across multiple packages (#722, #749).

Other

• Documentation pass. Proofread and corrected documentation across the site and repo, expanded the security/deployment docs, added Windows service docs, and expanded launchd docs with KeepAlive, reload, and shutdown notes (#734, #747).
• Release workflow modernized. Releases are now built with the gh CLI instead of the deprecated GitHub release actions (#733).
• Dependency upgrades. OPA upgraded to v1.17.0, plus various other Go and GitHub Actions dependency bumps via Dependabot (#731, #738, #739, #740, #741).

New Flags

New Subcommands

Release candidate for v1.11.0.

Highlights

• Native Windows Service Control Manager support. Ghostunnel can now run as a proper Windows service, with service install/uninstall/start/ stop/status subcommands and Windows Event Log integration via the new --eventlog flag (#712, #713, #717, thanks to @bdudley-cw for #712 and #717).
• TLS settings modernization. Dropped the explicit CurvePreferences setting so Ghostunnel inherits Go's defaults (which include the X25519MLKEM768 hybrid post-quantum key exchange), and added read/idle timeouts plus a bounded shutdown context on the status HTTP server (#761).
• FreeBSD in CI. Integration tests now run on FreeBSD in GitHub Actions, with coverage uploaded to Codecov (#750).

New Features

• Windows Service Control Manager. New service install, service uninstall, service start, service stop, and service status subcommands register Ghostunnel with the Windows SCM. The service starts automatically on boot, responds to stop/shutdown controls from the SCM, and reports start/failure status back through the SCM (#712, #717, thanks to @bdudley-cw). Non-Windows platforms are unaffected.
• Windows Event Log. New --eventlog flag sends logs to the Windows Event Log instead of stdout (#713).
• Generalized notify-ready. The systemd notify-ready code was generalized into a platform-independent helper and is now also used by the Windows SCM integration to signal readiness to the service manager.

Bug Fixes

• PROXY protocol over UNIX socket listeners. Fixed an issue where PROXY protocol on a UNIX socket listener dropped every connection (#751).
• Accept loop backoff. The accept loop no longer spins hot on persistent accept errors and instead backs off with a capped delay (#757).
• Wildcard separator handling. wildcard.CompileWithSeparator now properly regex-quotes the separator, and trailing-separator handling plus bare ** behavior are now correct (#752, #754).
• Shutdown handler. The /_shutdown handler can no longer block forever on repeated POSTs (#755).
• Rego policy reload race. Fixed a data race on env.regoPolicy between startup and the timed-reload goroutine (#760).
• Cipher-suite parsing. Deduplicated cipher-suite parsing logic so the client and server paths can no longer drift (#759).
• Target and status flag validation. Server mode now correctly rejects --target systemd: and --target launchd: at startup instead of accepting them and failing to dial later (#758), other undialable --target networks are now rejected at flag validation, and --status https:// is now rejected on non-TCP listeners (#762).
• ACME renewal under mTLS. Improved ACME certificate renewal when the listener is configured for mTLS (#743).
• Landlock UNIX-socket FS rules. Fixed Landlock silently dropping filesystem rules for UNIX socket paths (#742).
• Client mode UNIX socket unlink. Client mode no longer unlinks a UNIX socket that is managed by systemd or launchd socket activation (#745).
• Workload API flag validation. --use-workload-api is now rejected when combined with file-based credential flags (#744).
• Systemd socket activation. Fixed a bug where systemd socket activation could not be used for the listen and status sockets at the same time.

Code Quality Changes

• Landlock upgrade. Switched to the Landlock V8 ABI and added IgnoreIsMissing handling so Ghostunnel logs cleanly and continues without sandboxing on older kernels (#735, #736).
• Status HTTP server. Added ReadTimeout/IdleTimeout to the status HTTP server, dropped the now-counterproductive WriteTimeout, and bounded the shutdown context to 5s to avoid goroutine leaks (#761).
• Go version source of truth. Builds now derive the Go toolchain version from go.mod rather than a separately pinned version (#737).

Testing Improvements

• FreeBSD integration tests. Added a FreeBSD job to the GitHub Actions workflow running the full integration test suite, with coverage uploaded to Codecov (#750).
• Windows SCM integration tests. Added integration tests for the new Windows service subcommands and improved the integration test harness's coverage handling. The integration harness can now also run from a configurable temp directory (#746).
• ACME under mTLS regression test. Added integration and unit tests exercising ACME renewal under mTLS so the bug stays fixed (#743).
• Additional unit and integration tests. Broader coverage for error paths, corner cases, and previously-untested helpers across multiple packages (#722, #749).

Other

• Documentation pass. Proofread and corrected documentation across the site and repo, expanded the security/deployment docs, added Windows service docs, and expanded launchd docs with KeepAlive, reload, and shutdown notes (#734, #747).
• Release workflow modernized. Releases are now built with the gh CLI instead of the deprecated GitHub release actions (#733).
• Dependency upgrades. OPA upgraded to v1.17.0, plus various other Go and GitHub Actions dependency bumps via Dependabot (#731, #738, #739, #740, #741).

New Flags

New Subcommands

New Features

• PROXY protocol v2 TLS metadata. New --proxy-protocol-mode flag for PROXY protocol v2 with optional TLS metadata TLVs (#705). Modes: conn (connection info only, same as the existing --proxy-protocol flag), tls (adds TLS version/ALPN/SNI), and tls-full (adds TLS metadata and client certificate).

Code Quality Changes

• Native code correctness fixes. Landed a number of fixes in the macOS keychain and Windows certificate store code, identified through GitHub code scanning (CodeQL, Copilot Autofix) and local AI development tools. These 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, #704).
• Certloader safety improvements. Replaced unsafe.Pointer with atomic.Pointer[T] in certloader (#677), extracted shared baseCertificate 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

• Windows integration testing. The integration test suite can now run on Windows (#695), and we added a number of new unit and integration tests for 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, #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 (#697, #700, #702).

Other

• Website. Launched project website on ghostunnel.dev and made comprehensive documentation improvements (#657, #659, #704, #707).

Release candidate for v1.10.0.

New Features

• PROXY protocol v2 TLS metadata. New --proxy-protocol-mode flag for PROXY protocol v2 with optional TLS metadata TLVs (#705). Modes: conn (connection info only, same as the existing --proxy-protocol flag), tls (adds TLS version/ALPN/SNI), and tls-full (adds TLS metadata and client certificate).

Code Quality Changes

• Native code correctness fixes. Landed a number of fixes in the macOS keychain and Windows certificate store code, identified through GitHub code scanning (CodeQL, Copilot Autofix) and local AI development tools. These 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, #704).
• Certloader safety improvements. Replaced unsafe.Pointer with atomic.Pointer[T] in certloader (#677), extracted shared baseCertificate 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

• Windows integration testing. The integration test suite can now run on Windows (#695), and we added a number of new unit and integration tests for 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, #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 (#697, #700, #702).

Other

• Website. Launched project website on ghostunnel.dev and made comprehensive documentation improvements (#657, #659, #704, #707).

Bug fix release

Changes

• Allow 5 retries for ACME production certs (by @erikng in #646). This makes fetching ACME certificates on startup more reliable by doing a limited number of retries, with exponential backoff, when initial requests are timing out. Note that this can make Ghostunnel a bit slower to fail on startup in some circumstances.
• Fix --cacert being ignored in ACME mode (by @csstaub in #649). This fixes #647, a bug where Ghostunnel would not honor the --cacert setting if it was otherwise getting certs from ACME. Thanks to @erikng for finding & reporting this, as well as verifying the fix.

Minor Changes

• General housekeeping, such as bumping dependencies and fixing typos (#632, #636, #640, #644), adding a new mage go:lint target for easier linting in development (#638), additional unit/integration testing (#641, #642, #643), and upgrading to Go 1.26 for builds (#637).

Full Changelog: v1.9.1...v1.9.2

Housekeeping release

Changes

• Fixed a few lints/very minor bugs
• Made improvements to the documentation (typos, inconsistent wording)
• Moved the build system from make to mage to streamline workflows/release
• Updated workflows so that macOS release binaries are now signed & notarized

This is the first time our official release binaries are signed & notarized, please let us know if you encounter issues with Gatekeeper on macOS preventing these from running!

Full Changelog: v1.9.0...v1.9.1

Highlights

• Enabled Landlock sandboxing by default in best-effort mode (Linux). Use the new --disable-landlock flag to disable. Note that Landlock is not compatible with PKCS#11 and is disabled automatically if any of the PKCS#11 options are used.
• Upgraded to OPA v1.0+ and added support for loading OPA bundles (not just policies) via the --allow-policy flag. It's recommended to use bundles instead of policies so you can set which version of Rego to use.
• Improved proxy memory usage through shared buffers and added various new flags to control proxy behavior (--close-timeout, --max-conn-lifetime, and --max-concurrent-conns).
• Go version upgraded from Go 1.22 to Go 1.24+.

Major Changes

• Improve proxy performance and connection handling (by @csstaub in #523)
  • Shared buffer pools for reduced memory allocations
  • Better connection lifetime tracking and logging
  • Bytes sent/received now logged for each connection
• Add maximum concurrent connections feature (by @csstaub in #561)
  • New --max-concurrent-conns flag to limit simultaneous proxy connections
• Use context for cancellation and modernize proxy handling (by @csstaub in #571)
  • Refactored to use Go's context package for timeout and cancellation handling
  • Improved timeout error detection
• Enable Landlock by default (Linux, best-effort mode) (by @csstaub in #607)
  • Automatically enabled on Linux systems that support it
  • Gracefully degrades on systems without Landlock support

Minor Changes

• Improved proxy logging (by @csstaub in #543)
  • Use "forwarded/returned" instead of "sent/recv" for clearer logs
  • Log bytes sent/received in connection close messages
• Show more information in status line/endpoint (by @csstaub in #551)
  • Display listen/forward address in status output (endpoint and systemd)
• Fix compatibility for OPA upgrade from v0 to v1 (by @csstaub in #563)
  • Handle backwards compatibility for v0 Rego files
  • Updated tests to use OPA bundles instead of naked Rego files
• Hide the --cipher-suites flag (by @csstaub in #566)
  • Flag is now hidden; modern TLS defaults are used
• Add new flag for setting max TLS version (by @csstaub in #572)
  • New --max-tls-version flag (TLS1.2, TLS1.3)
• Add new flag to skip DNS resolution on startup (by @csstaub in #609)
  • New --skip-resolve flag, useful when starting Ghostunnel before network is ready (fixes #585)

New Flags

Deprecations

• --connect-proxy flag is now deprecated (hidden), use --proxy instead
• --cipher-suites flag is now hidden

Dependency Updates

• OPA upgraded from v0.x to v1.5.0
• gRPC upgraded to v1.72.2
• go-proxyproto upgraded from v0.8.0 to v0.8.1
• go-spiffe upgraded from v2.4.0 to v2.5.0
• golang.org/x/net upgraded to v0.36.0
• go-jose upgraded from v4.0.4 to v4.0.5

Other Changes

• Reduced Dockerfile-debian image size by removing apt lists
• Removed BUG-BOUNTY.md notice (Square/Block suspended the program)
• Improved documentation and man page
• Various test reliability improvements (especially for Windows)

Full Changelog: v1.8.4...v1.9.0

Highlights

• Enabled Landlock sandboxing by default in best-effort mode (Linux), use the new --disable-landlock flag to disable. Note that Landlock is not compatible with PKCS#11 and is disabled automatically if any of the PKCS#11 options are used.
• Upgraded to OPA v1.0+ and added support for loading OPA bundles (not just policies) via the --allow-policy flag. It's recommended to use bundles instead of policies so you can set which version of Rego to use.
• Improved proxy memory usage through shared buffers and added various new flags to control proxy behavior (--close-timeout, --max-conn-lifetime, and --max-concurrent-conns).

Major Changes

• Improve proxy performance and connection handling (by @csstaub in #523)
• Add maximum concurrent connections feature (by @csstaub in #561)
• Use context for cancellation and modernize proxy handling (by @csstaub in #571)
• Enable landlock by default (Linux, best-effort mode) (by @csstaub in #607)

Minor Changes

• Improved proxy logging (by @csstaub in #543)
• Show a bit more information in status line/endpoint( by @csstaub in #551)
• Fix compatibility for OPA upgrade from v0 to v1 (by @csstaub in #563)
• Hide the --cipher-suites flag (by @csstaub in #566)
• Add new flag for setting max TLS version (by @csstaub in #572)
• Add new flag to skip DNS resolution on startup (by @csstaub in #609)

Full Changelog: v1.8.4...v1.9.0-rc.1