Windows Service

Available since v1.11.0.

Ghostunnel can run as a native Windows service managed by the Service Control Manager (SCM). The ghostunnel service subcommands handle installation, removal, and lifecycle control. All service management commands require Administrator privileges.

Installing a Service #

Use ghostunnel service install to register Ghostunnel with the SCM. Proxy arguments (server or client mode flags) are passed after a -- separator:

ghostunnel service install -- server `
    --listen localhost:8443 `
    --target localhost:8080 `
    --cert C:\certs\server-cert.pem `
    --key C:\certs\server-key.pem `
    --cacert C:\certs\cacert.pem `
    --allow-cn client

This registers the service, sets it to start automatically on boot, and immediately starts it. The service appears in the SCM with the display name “Ghostunnel (<name>)”.

Custom Service Name #

By default the service is named ghostunnel. Use --service-name to run multiple instances with different configurations:

ghostunnel service install --service-name ghostunnel-api -- server `
    --listen localhost:8443 --target localhost:8080 ...

ghostunnel service install --service-name ghostunnel-admin -- server `
    --listen localhost:9443 --target localhost:9080 ...

Service names may contain letters, digits, hyphens, underscores, and spaces (max 256 characters).

Managing a Service #

# Check service status
ghostunnel service status [--service-name NAME]

# Start a stopped service
ghostunnel service start [--service-name NAME]

# Stop a running service (graceful drain)
ghostunnel service stop [--service-name NAME]

# Remove the service entirely
ghostunnel service uninstall [--service-name NAME]

Stopping a service triggers a graceful shutdown: Ghostunnel stops accepting new connections and drains in-flight requests before exiting, the same as sending Ctrl-C to an interactive process.

Uninstall will refuse to remove a service that was not originally installed by Ghostunnel (identified by a GhostunnelManaged registry marker).

Windows Event Log #

When running as a service, you typically want logs written to the Windows Event Log rather than stdout. Pass --eventlog in the proxy arguments:

ghostunnel service install -- server --eventlog `
    --listen localhost:8443 --target localhost:8080 ...

Events are written under the source name matching the service name (default ghostunnel). View them with Event Viewer or PowerShell:

# Proxy logs (default is 'ghostunnel' source)
Get-WinEvent -FilterHashtable @{LogName='Application'; ProviderName='ghostunnel'} -MaxEvents 20

# Lifecycle events for a custom-named service
Get-WinEvent -FilterHashtable @{LogName='Application'; ProviderName='some-custom-name'} -MaxEvents 20

The --eventlog flag also works when running Ghostunnel interactively (outside of a service), though this is less common. In that mode the source defaults to ghostunnel, which must already be registered with the Event Log (for example, by a prior ghostunnel service install) or Event Viewer will display “The description for Event ID … cannot be found.” for each entry.

Subcommand Reference #

All subcommands default to --service-name ghostunnel if not specified.