Update docs for the next release by JackDoan · Pull Request #390 · DefinedNet/nebula-docs

JackDoan · 2026-10-26T17:03:00Z

Brings the docs up to date with nebula master (since v1.11.0) for the next release. Includes the offload and CPU pinning docs from #376 (plus fixes to them), so this supersedes #376.

New pages

config/local-api: the control socket and the info API
Guide: nebula ctl and the info HTTP API, including the caveat about trusting identity answers
Guide: FIPS 140-3 mode

Fixed wrong values

tun.tx_queue default is 5000, not 500
static_map.lookup_timeout default is 5s, not 250ms
pki.disconnect_invalid default is true, not false
pki.initiating_version default is 1 or 2 depending on the certs loaded, not 0
stats.protocol: only tcp, tcp4 or tcp6 work; udp never did
FreeBSD/OpenBSD/NetBSD tun.dev naming
logging.timestamp_format, which no longer exists, and the log levels
Stale lighthouse DNS TXT output, and old-format log samples
The ssh debug command list: profiling commands removed, identity added

Newly documented behavior

Offloads and CPU pinning (from Document offload and CPU pinning config #376)
IPv6 non-TCP/UDP/ICMP traffic only matches proto: any
Firewall group value rules and conntrack timeouts
An IPv4 listen.host means Nebula ignores IPv6 underlay addresses
The 8937 MTU cap
Route entry fields, and macOS unsafe_route ownership
Windows network_category and windows_bypass_wdf, and DNS registration being off
UDP buffer fallback without CAP_NET_ADMIN
handshakes.query_buffer
Newer metrics
Automatic rekeying
When a reload restarts sshd
Relay reload behavior
Static map lookup failures keeping the last good addresses
Reloadable / not reloadable labels across most config pages

Notes for review

"Added in v1.12.0" labels assume that's the next version.
relay.am_relay now says a relay does not check the target's relay.relays. That matches the code, but the old text promised otherwise.
Sidebar positions were renumbered to fit the new pages.

🤖 Generated with Claude Code

github-actions · 2026-10-26T17:04:09Z

✅ Deploy Preview for docs-nebula ready!

Name	Link
🔨 Latest commit	`a99e214`
🔍 Latest deploy log	https://github.com/DefinedNet/nebula-docs/actions/runs/40734053378
😎 Deploy Preview Url	https://6576e8e1.docs-nebula.pages.dev
😎 Deploy Preview Alias	https://release-docs.docs-nebula.pages.dev

nbrownus · 2026-10-28T15:07:56Z

+Quote group names. YAML converts unquoted values before Nebula sees them, so `group: 007` would be read as `7` and
+`group: 1.10` as `1.1`. Unquoted integers and booleans still work, but log a warning. A float, a date, a map, a nested
+list, a `null` entry in `groups`, or `group: []` is rejected with an error, which fails startup or fails the reload and
+keeps the previous firewall. A `group` or `groups` key with no value is treated as not set.


A group or groups key with no value is treated as not set. - this is now rejected unless a host, other group or cidr is set

BEEP BOOP ROBOT REPLY: Fixed in 216b1a5. Now says a group or groups key with no value is rejected unless the rule also sets host, cidr, or a non-empty group/groups (matching the #2017 check in convertRule), and points at host: any.

nbrownus · 2026-10-28T15:13:28Z

+
+Every reload ends with one summary line in the log:
+
+| Log line                                                                                     | Level | Meaning                                                                                      |


Missing: "Config reload failed, the new config did not load and a restart is still required".

BEEP BOOP ROBOT REPLY: Added in 216b1a5 (config/reload.go:26): "Nothing was applied, and an earlier reload still needs a restart".

nbrownus · 2026-10-28T15:14:51Z

+
+| Platform        | Settings                                                                                                                                                                                                                                                                      |
+| --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| All             | `cipher`, `routines`, `listen.host`, `listen.port`, `lighthouse.am_lighthouse`, `handshakes.*`, `stats.message_metrics`, `stats.lighthouse_metrics`, `tun.disabled`, `tun.drop_local_broadcast`, `tun.drop_multicast`, `firewall.conntrack.routine_cache_timeout`, `timers.*` |


timers.requery_wait_duration is reloadable, I wonder if we want this guide at all since each config stanza has it's own "reloadable" pill?

BEEP BOOP ROBOT REPLY: Jack says drop it, so the guide is gone in f7e2d46 and the two links to it are removed.

nbrownus · 2026-10-28T15:17:03Z

-
-<Pill className="mb-24">Reloadable</Pill>
+Timestamps are always [RFC3339](https://datatracker.ietf.org/doc/html/rfc3339) with nanosecond precision, e.g.
+`2006-01-02T15:04:05.999999999Z07:00`. The `logging.timestamp_format` setting was removed in v1.11.0 and is ignored.


Technically the precision depends on text (milliseconds) or json (nanoseconds) mode

Actually one of my robots told me yesterday we no longer respect this setting post slog migration? Need to check.

Correct but the precision still changes

ohhhh I see what you mean

BEEP BOOP ROBOT REPLY: Fixed in 216b1a5: text is millisecond (slog's appendRFC3339Millis), json is RFC3339Nano with trailing zeros trimmed. Re the setting: logging.disable_timestamp is still honored post-slog, logging.Handler.Handle zeroes r.Time and slog omits a zero time.

nbrownus · 2026-10-28T15:18:50Z

+match a `tcp` or `udp` rule. These packets are now classified as their real protocol. If you carry such a protocol over
+IPv6 in the overlay, make sure a `proto: any` rule allows it.
+
+IPv6 packets whose extension headers are truncated or more than 8 headers deep are dropped.


"8 or more"

BEEP BOOP ROBOT REPLY: Right, IPv6FindUpperProtocol walks at most 8 headers and fails closed if the 8th is still an extension header, so 8 or more is dropped. Fixed in 216b1a5. (The function's doc comment in iputil/packet.go has the same off-by-one.)

nbrownus · 2026-10-28T15:20:11Z

@@ -0,0 +1,72 @@
+---
+title: FIPS 140-3 mode


Could be helpful to note encrypting keys at rest will be rejected in FIPS mode

I'm trying to decide if we should add an AES mode for that, or lean on "if you need fips, you ought to have your CA key somewhere hardware-backed"

We can certainly improve the encryption at rest story for FIPs folks but it's not gonna make v1.12 unless there is a strong desire for it. Easier to call the gap out or hold this guide until then.

BEEP BOOP ROBOT REPLY: Added in 216b1a5. Verified with a GOFIPS140=v1.0.0 -tags fips140enforce build of master: nebula-cert ca -encrypt fails, and nebula-cert sign can't use a CA key encrypted by a non-FIPS build, both on cipher.NewGCM being refused in FIPS 140-only mode.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…routines > 1, pin_threads_key fallback

…ocument blocklist and newer cert handling

…ps keep the last good addresses

…restart

… limited messages

…ue rules, and conntrack timeouts

…937 MTU cap

…indows tun settings

…r fallback and reloadability, and listen.windows_bypass_wdf

…d in FIPS 140-only mode

…nebula ctl

…ading

…s reload steps

… replace the stale TXT record examples

…y enforces

…load, and say local_range was removed

…uide

…ow failed DNS lookups are handled

…name limits, and nebula ctl

…efaults, and the -networks flag

…y and restart keys, log timestamp precision, FIPS encrypted keys

…text log samples

jasikpark

Checked the added and changed claims against nebula master (2f5232e2). About 200 hold up, including relay.am_relay: the relay never reads the target's relay.relays. The site builds with no broken links or anchors, and prettier is clean. These don't line up with the code:

Wrong

reloading-configuration:46: "Changing a setting back to the value Nebula is running with does not need a restart." RestartRequiredIfChanged compares against the previously loaded config, not running state (config/reload.go), and needsRestart is sticky (config/config.go:230), which the sentence before already says. Only cipher, Windows tun.network_category, and the conditional tun.dev compare against running values.
lighthouse.mdx:67,85 / using-lighthouse-dns:77: the TXT answer isn't JSON as nebula-cert print -json prints it. dns.NewRR(fmt.Sprintf("%s TXT %s", …, crt.MarshalJSON())) doesn't quote the JSON, so miekg/dns splits it into character-strings and strips the quotes; dig shows "{" "details" ":{" …. That's a nebula bug, but the doc shouldn't promise JSON until it's fixed. (print -json also wraps in an array; TXT returns one object.)
tunnels.mdx:38: messages.tx.exhausted only exists with stats.message_metrics: true (nil in newMessageMetricsOnlyRecvError). stats.mdx says so; tunnels.mdx should too.
tun.mdx:198: tun.windows_bypass_wdf is amd64/arm64 only (tun_bypass_windows_386.go is a no-op), like listen.windows_bypass_wdf already says.

Narrower than written

tun.mdx:134: duplicate unsafe_routes: the warning is "only the last entry's via is used", which covers the route tree only. macOS installs the first entry's system route; on Linux, duplicates with different metrics both stay in the kernel.
reloading-configuration:78 / pki.mdx:52: a cert with different networks is refused only for a version already loaded (or when removing v2). Adding a new version with different networks is accepted, then asks for a restart (pki.go:111-118).
lighthouse.mdx:68: other TXT queries get an empty NOERROR answer, not "no answer".
pki.mdx:127: blocklisted handshakes log at debug on the responder side, at warn on the initiator side when the handshake fails.
debug-ssh-commands:106: print-cert also prints JSON with no flag, and its -raw isn't documented.
local-control-and-info-api:106: real ?pretty output is 4-space MarshalIndent with one array element per line.

Structure

+1 to Nate on the restart table in the reloading guide. It already drifted (timers.*), and it duplicates the per-key labels. Relatedly, "Reloadable" is a pill but not-reloadable is prose in about a dozen phrasings ("Not reloadable.", "is not reloadable, changing it takes effect after a restart", …). A Restart required pill would make the config pages the single source, and the guide could link there instead of listing keys.

Unconfirmed

"Added in v1.12.0" labels: everything is still under [Unreleased]; fine once nebula#2027 (v1.12.0 changelog) lands as 1.12.0.

— Caleb + Cache

nbrownus · 2026-10-28T16:58:22Z

-`TXT` records can only be queried over the Nebula network, and contain certificate information for the requested host IP
-address.
+`TXT` records can only be queried from hosts on the Nebula network or from the lighthouse itself, and contain the
+certificate of the requested host IP address as JSON. Other `TXT` queries get no answer.


TXT records don't parse as JSON today and they are only served locally from a lighthouse, maybe redirecting them to the local api socket would be valuable. This also applied to the using-lighthouse-dns guide.

jasikpark

Re-checked at dbf8049 against nebula v1.12.0 (fb4ef139). Dropping the reloading guide and the not-reloadable prose resolves the structure point: the pill is now the single source, and the pill audit is consistent. The trims also cleared the duplicate-unsafe_routes, TXT "no answer", and blocklist log-level items. v1.12.0 is tagged, so the "Added in" labels hold.

Blocking

Check prettier has been red since fc1b33b: docs/config/static-host-map.mdx lost its trailing newline.

Still open from last round

lighthouse.mdx:67,84 / using-lighthouse-dns:77: TXT answers still aren't JSON (dns_server.go:416 builds the RR from unquoted MarshalJSON()). +1 to Nate: drop the JSON promise, or point at the info API, which serves the same identity as real JSON.
tunnels.mdx:40: messages.tx.exhausted is only registered with stats.message_metrics: true. stats.mdx:78 says so, tunnels.mdx doesn't.
tun.mdx:181: tun.windows_bypass_wdf is amd64/arm64 only (overlay/tun_bypass_windows_386.go), the same as listen.windows_bypass_wdf says.
local-control-and-info-api:103: the ?pretty sample is 2-space with inline arrays. Real output is 4-space MarshalIndent (info_api.go:146), with one array element per line.

From the trim

local-api.mdx:87: "On Windows, a change to group takes effect after a restart" leaves out the part that bites. A reload that removes or narrows the group stops the socket until restart (localapi/endpoint.go:66), so nebula ctl goes away mid-reload. The earlier text said this.
local-control-and-info-api (the info API caveat): "only answers for established tunnels and addresses inside this node's own overlay networks" reads as two things it answers for. Suggest "only answers for addresses inside this node's own overlay networks that have an established tunnel".
firewall.mdx tip, nit: "decimal integers" → "integers". groupName sees an int whatever the YAML spelling, so 0x1F is accepted as 31 too.

— Caleb + Cache

JackDoan mentioned this pull request Oct 26, 2026

Document offload and CPU pinning config #376

Closed

nbrownus reviewed Oct 28, 2026

View reviewed changes

JackDoan marked this pull request as ready for review October 28, 2026 15:18

nbrownus reviewed Oct 28, 2026

View reviewed changes

JackDoan and others added 21 commits October 28, 2026 10:32

Document offload and CPU pinning config

82bd7be

Fix prettier wrapping in tun.mdx

af798f2

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Tighten offload and pinning docs: GRO needs batch > 1, pinning needs …

a2065cd

…routines > 1, pin_threads_key fallback

Fix the pki.disconnect_invalid and pki.initiating_version defaults, d…

9557cf4

…ocument blocklist and newer cert handling

Document static_map lookup_timeout's 5s default and that failed looku…

eabe8d2

…ps keep the last good addresses

Document handshakes.query_buffer and that handshakes settings need a …

3a21c60

…restart

Update logging docs for slog levels and timestamps, and document rate…

9bffce0

… limited messages

Fix stats.protocol, mark stats reloadability, and list newer metrics

a59e06c

Document firewall protocol matching for other IP protocols, group val…

92c840e

…ue rules, and conntrack timeouts

Fix the tun.tx_queue default and tun.dev naming rules, document the 8…

bed27ef

…937 MTU cap

Document unsafe_routes entry fields, macOS route ownership, and the W…

16b1f9b

…indows tun settings

Document that an IPv4 listen.host ignores IPv6 underlay, listen buffe…

a6d86c1

…r fallback and reloadability, and listen.windows_bypass_wdf

Mark routines and cipher as not reloadable, note chachapoly is refuse…

a6772ae

…d in FIPS 140-only mode

Document the local control socket, nebula ctl, and the info API

305e479

Update the ssh debug command list, document identity, scripting, and …

335c623

…nebula ctl

Document when a reload restarts sshd, and fix the sshd.trusted_cas he…

4e59af3

…ading

Add a reloading configuration guide and update the CA rotation guide'…

e15f9d6

…s reload steps

Add a FIPS 140-3 mode guide

086a802

Update lighthouse DNS, am_lighthouse, and remote_allow_list docs, and…

3a378d3

… replace the stale TXT record examples

Document relay reload behavior and defaults, and correct what am_rela…

85a5aeb

…y enforces

Mark punchy.punch reloadable, note invalid preferred_ranges fail a re…

78d1f39

…load, and say local_range was removed

JackDoan added 9 commits October 28, 2026 10:32

Document automatic rekeying of long lived tunnels

4f56ddf

Cover the control socket and an existing tun device in the non-root g…

34d6021

…uide

Explain in the host discovery guide how listen.host limits IPv6 and h…

be1d5ac

…ow failed DNS lookups are handled

Update the cert v2 and IPv6 guide for IPv6 underlay, Windows MTU, v2 …

fea5a0f

…name limits, and nebula ctl

Update the quick start for the macOS minimum, ca.crt, 32-bit Argon2 d…

659c86f

…efaults, and the -networks flag

Show how to change the log level at runtime with nebula ctl

ebf0b1b

Link the GRO and GSO metrics to listen.udp_offloads

5bb876e

Address review: null group rejection, ext header depth, reload summar…

91d240a

…y and restart keys, log timestamp precision, FIPS encrypted keys

Drop the reloading configuration guide, and use millisecond times in …

1298dcb

…text log samples

JackDoan force-pushed the release-docs branch from f7e2d46 to 1298dcb Compare October 28, 2026 15:32

jasikpark reviewed Oct 28, 2026

View reviewed changes

nbrownus reviewed Oct 28, 2026

View reviewed changes

JackDoan added 2 commits October 28, 2026 12:05

concise

fc1b33b

more concise

dbf8049

jasikpark reviewed Oct 29, 2026

View reviewed changes


		Every reload ends with one summary line in the log:

		\| Log line \| Level \| Meaning \|

Conversation

JackDoan commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

New pages

Fixed wrong values

Newly documented behavior

Notes for review

Uh oh!

github-actions Bot commented Oct 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for docs-nebula ready!

Uh oh!

nbrownus Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

JackDoan Oct 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasikpark left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jasikpark left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Uh oh!

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JackDoan commented Oct 26, 2026 •

edited

Loading

github-actions Bot commented Oct 26, 2026 •

edited

Loading

nbrownus Oct 28, 2026 •

edited

Loading

JackDoan Oct 28, 2026 •

edited

Loading