Documentation
¶
Index ¶
- func EnsureDefaultVhost() error
- func EnsureLerdVhost() error
- func EnsureNginxConfig() error
- func GeneratePausedVhost(site config.Site) error
- func GeneratePausedWorktreeVhost(domain, certDomain, pausedDir string, secured bool) error
- func GenerateProxyVhost(domain, upstreamHost string, upstreamPort int) error
- func GenerateSSLVhost(site config.Site, phpVersion string) error
- func GenerateVhost(site config.Site, phpVersion string) error
- func GenerateWorktreeSSLVhost(domain, path, phpVersion, parentDomain string) error
- func GenerateWorktreeVhost(domain, path, phpVersion string) error
- func GetTemplate(name string) ([]byte, error)
- func LoadOrGenerateTrustToken() (string, error)
- func Reload() error
- func RemoveVhost(domain string) error
- func TrustTokenPath() string
- type VhostData
- type VhostRepair
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func EnsureDefaultVhost ¶ added in v0.6.0
func EnsureDefaultVhost() error
EnsureDefaultVhost writes a catch-all default server that shows a branded error page for any HTTP request that doesn't match a registered site. For HTTPS we cannot serve a real catch-all because browsers (Chrome especially) reject TLD-level wildcard certificates like `*.test` with ERR_CERT_COMMON_NAME_INVALID, and we can't issue per-domain certs ahead of time. ssl_reject_handshake produces a clean connection error (ERR_SSL_UNRECOGNIZED_NAME_ALERT) which is the best UX available.
func EnsureLerdVhost ¶ added in v1.0.2
func EnsureLerdVhost() error
EnsureLerdVhost generates the nginx vhost for http://lerd.localhost, which reverse-proxies to the lerd-ui process running on the host so the browser's URL bar stays on lerd.localhost (no redirect to localhost:7073).
Background: lerd-nginx runs in a rootless podman bridge, so any outbound connection it makes to a host service arrives with a non-loopback source IP (the bridge gateway, e.g. 10.89.7.1). Without further context, lerd-ui cannot tell a legitimate proxy hop from this vhost apart from a LAN attacker hitting http://server-ip:7073 directly.
We bridge that gap with a per-install random trust token (see trust_token.go) injected via `proxy_set_header X-Lerd-Trust <token>;`. Two properties make this safe against header injection:
- `proxy_set_header` REPLACES any client-supplied X-Lerd-Trust value, so a LAN attacker who sets the header in their own request has it overwritten by nginx before it reaches lerd-ui. The only header value that ever reaches lerd-ui is the legitimate one nginx put there.
- The token lives in ~/.local/share/lerd/nginx-trust-token with mode
- An off-host attacker cannot read it.
.localhost is RFC 6761 reserved and always resolves to the visiting device's loopback, so this vhost is unreachable from a LAN browser doing the obvious thing (http://lerd.localhost from a remote machine hits the remote machine's own 127.0.0.1, not the lerd server).
func EnsureNginxConfig ¶
func EnsureNginxConfig() error
EnsureNginxConfig copies the base nginx.conf to the data dir if it is missing.
func GeneratePausedVhost ¶ added in v1.0.0
GeneratePausedVhost writes a minimal nginx vhost that serves the static paused landing page for the given site. For secured sites it also adds the HTTPS block so the redirect and TLS still work while the site is paused.
func GeneratePausedWorktreeVhost ¶ added in v1.0.1
GeneratePausedWorktreeVhost writes a paused nginx vhost for a worktree domain. certDomain is the parent site's domain whose cert files back the wildcard.
func GenerateProxyVhost ¶ added in v0.1.21
GenerateProxyVhost renders vhost-proxy.conf.tmpl and writes conf.d/{domain}.conf.
func GenerateSSLVhost ¶
GenerateSSLVhost renders the SSL vhost template and writes it to conf.d.
func GenerateVhost ¶
GenerateVhost renders the HTTP vhost template and writes it to conf.d.
func GenerateWorktreeSSLVhost ¶ added in v0.6.0
GenerateWorktreeSSLVhost renders the SSL vhost template for a worktree checkout, reusing the parent site's wildcard certificate (*.parentDomain).
func GenerateWorktreeVhost ¶ added in v0.6.0
GenerateWorktreeVhost renders the HTTP vhost template for a worktree checkout and writes it to conf.d/<domain>.conf.
func GetTemplate ¶
GetTemplate returns the content of a named nginx template/config file. name can be "nginx.conf", "vhost.conf.tmpl", or "vhost-ssl.conf.tmpl".
func LoadOrGenerateTrustToken ¶ added in v1.8.0
LoadOrGenerateTrustToken returns the per-install nginx → lerd-ui trust token, generating a fresh 32-byte hex value on first call and persisting it to ~/.local/share/lerd/nginx-trust-token (mode 0600). Subsequent calls return the cached value so the file is read at most once per process.
Idempotent across processes: if two lerd processes race on first generation, the second one's write loses but both end up with a valid token because the read-after-write resolves the race.
func RemoveVhost ¶
RemoveVhost deletes the vhost config files for the given domain.
func TrustTokenPath ¶ added in v1.8.0
func TrustTokenPath() string
TrustTokenPath returns the absolute filesystem path of the trust token file.
Types ¶
type VhostData ¶
type VhostData struct {
Domain string // primary domain (used for config file naming)
ServerNames string // space-separated list of all domains for server_name directive
Path string
PHPVersion string
PHPVersionShort string
CertDomain string // domain whose cert files to use (defaults to Domain)
PublicDir string // document root subdirectory, e.g. "public", "web", "."
Proxy bool // true when the site has a worker with WebSocket/HTTP proxy config
ProxyPath string // URL path for the proxy (e.g. "/app")
ProxyPort int // port the worker listens on inside the PHP-FPM container
}
VhostData is the data passed to vhost templates.
type VhostRepair ¶ added in v1.5.1
VhostRepair describes a single vhost that was repaired during pre-flight.
func RepairVhosts ¶ added in v1.5.1
func RepairVhosts() []VhostRepair
RepairVhosts performs pre-flight validation of nginx vhost configs before start. It fixes SSL vhosts that reference cert files that don't exist on the host:
- If the domain belongs to a registered site, the vhost is regenerated as plain HTTP and the site registry is updated (Secured = false).
- If no matching site exists (orphan SSL vhost), the config is removed.
Plain HTTP vhosts are left untouched even if they don't match any site — they are harmless and may belong to worktrees, parked sites, or ignored sites.
Source Files