How to add a WireGuard IP to LND's TLS certificate SANs on StartOS 4?

StartOS Support
,
1

The Problem

I have a StartTunnel WireGuard VPN set up and working. I access my LND node remotely via ZEUS wallet over LND REST through the WireGuard tunnel. Everything works when I disable certificate verification in ZEUS, but I’d like to have proper TLS verification enabled for full functionality.

The issue is that the LND TLS certificate’s Subject Alternative Names (SANs) don’t include my Start9 box’s WireGuard IP. When I inspect the cert, the SANs only contain:

DNS:lnd.startos, IP Address:<LAN_IP>, IP Address:<HOME_PUBLIC_IP>

My WireGuard IP (e.g. 10.x.x.x) is not listed. When ZEUS connects over WireGuard with cert verification enabled, it rejects the connection because the IP it’s connecting to doesn’t match any SAN entry.

There’s also a privacy concern: LND auto-detected my home public IP and included it in the SANs. Since I’m using StartTunnel specifically to avoid exposing my home IP, having it embedded in the TLS certificate undermines that. Anyone who connects to the REST endpoint can see it.

What I Tried

I attempted to add tlsextraip to lnd.conf directly:

tlsextraip=10.59.x.x
tlsautorefresh=true

Then deleted tls.cert and tls.key and restarted LND. This caused a TLS handshake error loop — the StartOS health checker (10.0.3.x) failed every second with http: TLS handshake error: EOF. LND appeared to be running (producing logs, syncing gossip) but the health checks never passed.

The root cause seems to be that StartOS manages LND’s TLS through its own PKI pipeline (Root CA → Intermediate CA → leaf cert). When LND regenerated its own self-signed cert from lnd.conf settings, it didn’t chain back to the StartOS Root CA, so the internal health checks failed TLS verification.

I had to rebuild the LND container through StartOS to get a properly signed cert re-provisioned. Reverting lnd.conf alone (removing the tlsextraip lines) wasn’t sufficient — StartOS needed to re-provision through its own certificate lifecycle.

What I’m Looking For

  1. Is there a supported way to add extra IPs (like a WireGuard IP) to the LND TLS certificate SANs on StartOS 4? Ideally through the StartOS UI or a config option that works with the StartOS PKI, rather than fighting against it.

  2. Can the home public IP be excluded from the SANs? LND has a tlsdisableautofill option that prevents auto-adding interface IPs, but given that StartOS manages the cert chain, I’m not sure if that’s safe to use without breaking the health checks.

  3. For others using StartTunnel + ZEUS over WireGuard — are you running without cert verification, or have you found a way to make the cert include the WireGuard IP?

Current Workaround

ZEUS connects over WireGuard without the TLS certificate imported (cert verification disabled). The WireGuard tunnel itself provides encryption, so the connection is still encrypted in transit — it’s just not verifying the LND endpoint’s identity at the TLS layer. This works but limits some ZEUS features that require cert verification, and it’s not ideal from a security posture standpoint.

Over LAN with the StartOS Root CA installed as a trusted profile on iOS, ZEUS connects fine with full cert verification since the LAN IP is in the SANs.

Environment Details

  • StartOS 4, LND 0.20.1-beta:13

  • StartTunnel WireGuard VPN for remote access

  • 3-cert PKI chain: leaf → StartOS Local Intermediate CA → Local Root CA (self-signed)

  • ZEUS v13.1.2 connecting via LND REST

  • StartOS Root CA installed and trusted on iOS (Settings → General → About → Certificate Trust Settings)

Any guidance appreciated, happy to test suggestions and report back.

2

Short answers:

  1. No — there’s currently no supported way to add a WireGuard IP to LND’s TLS SANs, via UI or config. The LND package generates tls.cert/tls.key itself with fixed SANs (lnd.startos + container IP) and rewrites both files on every service start. That’s also why your tlsextraip + tlsautorefresh experiment broke things: LND regenerated a cert that no longer chains to your Root CA, and the package overwrites/fights those files on each start. (Private domains won’t help here either — they explicitly can’t be attached to WireGuard/StartTunnel gateways.)

  2. The cert ZEUS sees today isn’t actually LND’s cert. On the current package, StartOS terminates TLS for the REST port at the edge and mints a certificate per connection, with SANs = the IP you dialed + the WAN IP of the gateway the connection came through. Your home public IP appears because LAN connections arrive via your router gateway. There’s no knob to exclude it — but note it’s only ever presented to devices that can already reach the port (on LAN or inside your VPN), it’s not broadcast anywhere.

  3. What to do right now: your current setup (cert verification off over WireGuard) is sound, not a hack — WireGuard already gives you mutually-authenticated, encrypted transport, and the macaroon still authenticates the API. Interestingly, per current StartOS code the edge should mint a cert covering the exact IP you dial (including a 10.x tunnel IP) — if you re-test with verification on and still get a SAN mismatch, grab the presented SANs (openssl s_client -connect 10.59.x.x:8080 </dev/null | openssl x509 -noout -ext subjectAltName) and it’s worth a bug report on start-os.

The proper fix is already in the pipeline: the upcoming LND 0.21 package switches REST and gRPC to TLS passthrough — LND’s own StartOS-issued cert end-to-end — and embeds the certificate in the REST lndconnect URL, so Zeus pins LND’s actual cert instead of validating SANs against whatever IP you happen to dial. Once you’re on that release, re-pair Zeus by scanning the lndconnect QR from the LND service page and certificate verification will work over the tunnel, LAN, and Tor alike — with no home IP in the cert.