docs: T9202: document the DHCPv4 lease Client ID column - #2198
docs: T9202: document the DHCPv4 lease Client ID column#2198allanice001 wants to merge 1 commit into
Conversation
Adds the column introduced by vyos-1x#5394 to the three `show dhcp server leases` samples, and a note on how to read it: most clients send 01: plus their MAC, while a systemd-networkd host sends an RFC 4361 identifier and it is the DUID inside that -- not the whole string -- that a static mapping's `duid` has to be set to. The sort key list is corrected while adding client_id to it. It named `hardware_address`, which the command has never accepted: $ show dhcp server leases sort hardware_address DHCP sort "hardware_address" is invalid! $ show dhcp server leases sort mac IP Address MAC address State ... The DHCPv6 list a few sections below is stale in the same way -- it names expires, iaid_duid and last_comm where the command wants end, duid and last_communication, and omits hostname. That is left alone here: it is a different command, untouched by this change, and wants its own task. Signed-off-by: allanice001 <allanice001@gmail.com>
📝 WalkthroughSummary by CodeRabbit
WalkthroughChangesThe DHCP server documentation adds DHCP lease documentation
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches✨ Simplify code
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
|
Claude finished @allanice001's task in 3m 32s —— View job Review complete
IssuesNone. The PR's technical claims check out against the source. Verification notes
Optional (non-blocking) nitThe shorthand Pass 1 findingsAll 34 Pass 1 "CLI path not found" hits are on pre-existing lines this PR does not touch (lines 401–1378, none in the diff range 1043–1103). They look like reference-DB subsystem-scoping false positives (paths that do exist in Stats
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/configuration/service/dhcp-server.md`:
- Around line 1060-1062: Update the DHCP Client ID documentation near the
existing option 61 explanation to state that the CLI displays `-` when a client
sends no identifier, while preserving the current populated-identifier examples.
- Around line 1063-1065: Qualify the systemd-networkd behavior in the DHCP
client-identifier documentation: state that it applies when
ClientIdentifier=duid, describe the RFC 4361 ff:<IAID>:<DUID> format, and
clarify that static mappings use only the embedded DUID. Note that other
ClientIdentifier modes produce different formats.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Central YAML (inherited), Organization UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: 0891d694-a7af-408f-a486-90fcc47b1123
📒 Files selected for processing (1)
docs/configuration/service/dhcp-server.md
🔗 Linked repositories identified
CodeRabbit considers these linked repositories for cross-repo context during reviews:
ansible/ansible(manual)
📜 Review details
⏰ Context from checks skipped due to timeout. (3)
- GitHub Check: validate
- GitHub Check: Mergify Merge Protections
- GitHub Check: Summary
🧰 Additional context used
📓 Path-based instructions (2)
docs/**/*.md
📄 CodeRabbit inference engine (AGENTS.md)
docs/**/*.md: Canonical docs pages must be written as MyST Markdown (.md); edit existing pages in.mdonly and never use the oldmd-prefix for new pages.
Use{cfgcmd},{opcmd}, and{cmdincludemd}fenced directives in MyST pages for VyOS command coverage; do not replace them with plaintextorbashfences.
Use MyST ATX headings (#,##,###, etc.) in canonical pages; the RST heading hierarchy does not apply to.mdsources.
In MyST pages, prefer single backticks for inline code; double backticks are reserved for embedded RST contexts.
Use% stop_vyoslinterand% start_vyoslintercomment markers in top-level MyST content to suppress real IPs or other allowed long-line exceptions, and keep them paired.
In MyST pages, write TODO markers as{todo}fenced directives.
Files:
docs/configuration/service/dhcp-server.md
docs/{_include/*.txt,**/*.md}
📄 CodeRabbit inference engine (AGENTS.md)
Keep documentation lines within 80 characters unless the content is inside a code block or fenced/preformatted block.
Files:
docs/configuration/service/dhcp-server.md
🧠 Learnings (13)
📚 Learning: 2026-05-06T20:48:49.689Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:71-71
Timestamp: 2026-05-06T20:48:49.689Z
Learning: In vyos/vyos-documentation, the 80-character line-length rule documented under Source conventions / Formatting applies only to documentation source files located under docs/ (e.g., docs/**/*.rst and docs/**/*.md). The rule is enforced by the vyoslinter (doc-linter.py from vyos/.github) when reviewing changed files via lint-doc.yml, and only for files within docs/**. Do not suggest hard-wrapping CLAUDE.md (repo-root documentation) because GitHub renders and reflows content. For CLAUDE.md, reviews should not enforce the 80-char wrapping; apply the rule only to files matching **/docs/**/*.{rst,md}.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-06T20:48:57.970Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:91-93
Timestamp: 2026-05-06T20:48:57.970Z
Learning: The 80-character line limit applies only to documentation sources under docs/** (RST/MD). Do not enforce this limit on repo-root Markdown files like CLAUDE.md or README.md. The vyoslinter (doc-linter.py, run via lint-doc.yml from vyos/.github) lints only changed files within docs/**; root files are excluded. GitHub renders root Markdown with viewport-width reflow, so hard-wrapping these files reduces readability without tooling benefit.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-06T20:48:50.446Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:64-64
Timestamp: 2026-05-06T20:48:50.446Z
Learning: Enforce the 80-character line-length limit only for documentation source files under docs/ (docs/**/*.md and docs/**/*.rst rendered by Sphinx and linted by vyoslinter via lint-doc.yml). Do not flag line-length issues in repository-root Markdown files such as CLAUDE.md or README.md, which GitHub renders with viewport-width reflow. This applies to all files within docs/ that are part of the documentation source.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-06T20:48:54.578Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:80-84
Timestamp: 2026-05-06T20:48:54.578Z
Learning: Enforce the 80-character line-length limit only for documentation source files under docs/ (docs/**/*.rst and docs/**/*.md). Do not flag repo-root files like CLAUDE.md or README.md, since they are rendered by GitHub and not subject to this rule. The doc-linter (doc-linter.py via lint-doc.yml) only lints docs/**, so CI checks won't flag root files for line length.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-06T20:49:00.044Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:108-108
Timestamp: 2026-05-06T20:49:00.044Z
Learning: Limit the 80-character line length check and vyoslinter (doc-linter.py) enforcement to documentation source files under docs/**/*.{rst,md}. Do not apply or flag line-length issues in repo-root files like CLAUDE.md or README.md, which are rendered directly by GitHub and are not linted by lint-doc.yml. This pattern narrows checks to Sphinx source docs and prevents false positives in non-doc files.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-06T20:48:53.302Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:79-79
Timestamp: 2026-05-06T20:48:53.302Z
Learning: Limit line length to 80 characters only for documentation sources under the docs directory (docs/**/*.rst and docs/**/*.md). This is enforced by the vyoslinter doc-linter.py (from the vyos/.github repo) via lint-doc.yml on changed files under docs/**. Do not flag line-length violations in repository-root Markdown files like CLAUDE.md or README.md, as they are rendered by GitHub and reflow in the UI.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-06T20:49:10.359Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:142-142
Timestamp: 2026-05-06T20:49:10.359Z
Learning: In vyos/vyos-documentation, the 80-character line limit and vyoslinter enforcement apply only to documentation source files under docs/**/*.rst and docs/**/*.md that Sphinx renders. Repo-root files such as CLAUDE.md and README.md are outside the linter's scope (lint-doc.yml runs on docs/**) and are rendered by GitHub with automatic paragraph reflow — do not flag line-length violations in these files.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-06T20:49:15.361Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1902
File: CLAUDE.md:163-163
Timestamp: 2026-05-06T20:49:15.361Z
Learning: In vyos/vyos-documentation, enforce the 80-character line-length limit (Source conventions / Formatting) only for Sphinx documentation source files under docs/**/*.rst and docs/**/*.md. The lint-doc.yml workflow runs the doc-linter (doc-linter.py) and checks only docs/** changed files. Files in the repository root (e.g., CLAUDE.md, README.md) are rendered by GitHub and are not subject to this rule; do not flag line-length violations in those files.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-08T07:01:22.978Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1878
File: docs/troubleshooting/connectivity.rst:0-0
Timestamp: 2026-05-08T07:01:22.978Z
Learning: For the VyOS documentation (MyST-based docs), MyST directive opener lines must keep the entire directive arguments on a single line. This includes MyST fenced-directive openers like ```{opcmd} ... ``` and the RST-equivalent form .. opcmd:: ... when ported/used in MyST. Because the MyST parser does not support wrapped/continued directive arguments across multiple lines, do not raise/keep review warnings suggesting line wrapping for these directive opener lines due to line-length (even if they exceed 80 characters).
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-08T07:01:22.978Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 1878
File: docs/troubleshooting/connectivity.rst:0-0
Timestamp: 2026-05-08T07:01:22.978Z
Learning: In vyos/vyos-documentation, do not raise line-length (>80 chars) review findings for MyST directive opener lines (the directive “opener” that uses MyST directive syntax such as `{cfgcmd}` / `{opcmd}` fence/openers). CI does not enforce the 80-character limit for these specific opener lines, and existing documentation contains longer opener lines that pass lint.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-13T22:16:06.198Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 2021
File: docs/automation/terraform/terraformvyos.md:14-14
Timestamp: 2026-05-13T22:16:06.198Z
Learning: In the vyos/vyos-documentation repo, when a PR is a byte-for-byte documentation port of an existing file from the rolling branch to a release branch (e.g., circinus, sagitta), keep the port content identical to the production-tested rolling source. For these ports, do not raise new review findings for documentation issues that are already present in the rolling source (for example, markdownlint MD059 like non-descriptive link text such as `[link]`/`[install]`). Instead, defer those existing issues to a rolling-side cleanup PR (e.g., `#2024`) and then backport the cleanup via Mergify.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-05-13T22:43:41.056Z
Learnt from: andamasov
Repo: vyos/vyos-documentation PR: 2024
File: docs/automation/terraform/terraformvyos.md:0-0
Timestamp: 2026-05-13T22:43:41.056Z
Learning: In docs/**/*.md, for Markdown reference definition lines of the form `[label]: <URL>`, if the line cannot be shortened to <= 80 characters (because the URL itself is near/at the limit), suppress the vyoslinter warning by wrapping only that reference definition with a `% stop_vyoslinter` / `% start_vyoslinter` block. If the reference definition can fit within 80 characters, leave it outside any suppression block.
Applied to files:
docs/configuration/service/dhcp-server.md
📚 Learning: 2026-06-05T19:21:44.474Z
Learnt from: LiudmylaNad
Repo: vyos/vyos-documentation PR: 2066
File: docs/configuration/protocols/traffic-engineering.md:0-0
Timestamp: 2026-06-05T19:21:44.474Z
Learning: In the vyos/vyos-documentation MyST documentation pages, when writing CLI example invocations directly under a `{cfgcmd}` directive, use `none` fenced code blocks for those examples. Do not change these example blocks to `{opcmd}` or `{cfgcmd}`—`{opcmd}` is reserved for operational-mode commands, and the surrounding `{cfgcmd}` directive already documents the target command. Plain `none` blocks for these CLI examples are intentional and correct.
Applied to files:
docs/configuration/service/dhcp-server.md
🪛 LanguageTool
docs/configuration/service/dhcp-server.md
[style] ~1065-~1065: Consider a more concise word here.
Context: ... static mapping's duid must be set to in order to match. ::: ```{opcmd} show dhcp server...
(IN_ORDER_TO_PREMIUM)
🔍 Remote MCP vyos.dev
Relevant review context
- Related task T9202, “DHCPv4 lease output omits the client identifier,” is Open, priority Requires assessment, and marked compatible. It specifies exposing Kea’s existing
client-idasclient_id, using-when absent, appendingClient ID, and adding the DHCPv4 sort key. - T9202’s only comment links this work to GitHub PR
#5394. - Kea lease data is documented as already containing a
client_idCSV field, including both01:<MAC>identifiers and empty values. - A separate open task reports observed inconsistencies in DHCP HA lease
Originoutput and filtering. The updated remote/local examples should therefore be checked against actual current behavior rather than assumingOriginis always reliable.
🔇 Additional comments (2)
docs/configuration/service/dhcp-server.md (2)
1046-1051: LGTM!Also applies to: 1092-1103
1077-1079: 🎯 Functional CorrectnessVerify the HA
Originsample before publishing.Related HA context reports inconsistencies in
Originoutput and filtering. Confirm thatshow dhcp server leases origin remoteproduces this row and theremotevalue on the supported VyOS/Kea version. Update the sample if observed output differs.Source: MCP tools
| :::{hint} | ||
| The Client ID column reports DHCP option 61 as the client sent it. Most clients | ||
| send `01:` followed by their MAC address, as above. A client using |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Document the empty Client ID representation.
The examples show only populated client identifiers. Add that the CLI displays - when the client sends no identifier. Otherwise, users cannot distinguish an absent identifier from a missing column value.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/configuration/service/dhcp-server.md` around lines 1060 - 1062, Update
the DHCP Client ID documentation near the existing option 61 explanation to
state that the CLI displays `-` when a client sends no identifier, while
preserving the current populated-identifier examples.
Source: MCP tools
| systemd-networkd sends an {rfc}`4361` identifier instead, of the form | ||
| `ff:<IAID>:<DUID>` — and it is the DUID inside it, not the whole string, that a | ||
| static mapping's `duid` must be set to in order to match. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
For the systemd-networkd version supported by VyOS, confirm which DHCPv4 ClientIdentifier values are supported and when the RFC 4361 ff:<IAID>:<DUID> format is used.
💡 Result:
As of August 2026, VyOS does not use systemd-networkd as its primary DHCP client [1][2]. While there has been discussion and development interest in migrating to systemd-networkd in future releases [1][2], VyOS currently relies on other DHCP implementations [1]. Therefore, there is no official VyOS-supported version of systemd-networkd for this purpose [1]. In contexts where systemd-networkd is used (e.g., Linux environments), the DHCPv4 ClientIdentifier settings are configured via the ClientIdentifier option in the [DHCPv4] section of a.network file [3][4]. Supported ClientIdentifier values include [4]: 1. mac: Uses the MAC address of the link as the DHCPv4 client identifier. 2. duid: Uses an RFC 4361-compliant client ID, which combines the Identity Association Identifier (IAID) and the DHCP Unique Identifier (DUID) [4]. This is the default setting [4]. 3. duid-only: Uses only the DUID, which may not be fully RFC-compliant but is sometimes required for compatibility with specific legacy setups [4]. The RFC 4361 format (ff::) is used when ClientIdentifier=duid is configured [5][4]. In this mode, systemd-networkd constructs the DHCPv4 client identifier by setting the type field to 255 (0xff), followed by the four-byte IAID, and finally the DUID [5][6]. This ensures the client identifier is node-specific and stable rather than tied exclusively to a hardware MAC address [6].
Citations:
- 1: https://vyos.dev/T7807
- 2: dhcpv6: T7807: update build environment for dhcpcd vyos-build#1168
- 3: https://freedesktop.org/software/systemd/man/latest/systemd.network.html
- 4: https://manpages.debian.org/bookworm/systemd/systemd.network.5
- 5: https://unix.stackexchange.com/questions/743776/systemd-network-duid-iaid-and-dhcpv4-clientidentifier
- 6: https://www.rfc-editor.org/info/rfc4361/
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- target excerpt ---'
sed -n '1035,1110p' docs/configuration/service/dhcp-server.md
printf '%s\n' '--- systemd/networkd references ---'
rg -n -i 'systemd-networkd|ClientIdentifier|client.?identifier|systemd' . \
--glob '!*.png' --glob '!*.jpg' | head -200Repository: vyos/vyos-documentation
Length of output: 40958
🌐 Web query:
VyOS supported systemd version and systemd-networkd DHCPv4 ClientIdentifier=duid behavior for that version, including the exact ff:<IAID>:<DUID> format
💡 Result:
VyOS has transitioned to using systemd as its primary init and service management system, beginning with base systems derived from Debian Jessie and continuing through current versions like VyOS 1.4 (Sagitta, based on Debian 12 Bookworm) and 1.5 (Circinus) [1][2][3][4]. As a result, VyOS relies on the systemd version packaged within its underlying Debian release [4]. When using systemd-networkd for DHCPv4, setting ClientIdentifier=duid results in the client sending an RFC 4361-compliant identifier [5][6][7]. The format of this identifier is defined as a concatenation of the DUID type (specifically 0xFF, indicating DHCPv6 IAID+DUID), the 4-byte Interface Association Identifier (IAID), and the DHCPv6 DUID [5]. The exact structure of the DHCPv4 Client Identifier when ClientIdentifier=duid is used follows this format: ff:: In this structure: - ff: This is the first octet (decimal 255), which signifies that the identifier contains both an IAID and a DUID [5][8]. - : This is a 4-byte (32-bit) value that identifies the specific interface [5][7]. If not explicitly configured, systemd-networkd typically generates this value based on a hash of the interface's name or its MAC address to ensure stability [5]. - : This is the DHCPv6 DUID of the system, which is typically generated based on the machine's /etc/machine-id [5][7]. Because systemd-networkd automatically includes this specific formatting when ClientIdentifier=duid is selected, users cannot typically override the inclusion of the IAID or the 'ff' prefix to provide a raw, unstructured identifier using standard configuration options [8][9]. Users requiring different behavior, such as sending only the MAC address, must explicitly configure ClientIdentifier=mac [5][6].
Citations:
- 1: https://docs.vyos.io/en/rolling/troubleshooting/system.html
- 2: https://docs.vyos.io/en/1.5/troubleshooting/system.html
- 3: https://vyos.dev/T2185
- 4: https://vyos.dev/T5003
- 5: https://unix.stackexchange.com/questions/743776/systemd-network-duid-iaid-and-dhcpv4-clientidentifier
- 6: https://forum.vyos.io/t/dhcp-client-on-lan-gets-wrong-non-static-lease-on-first-boot-despite-correct-configuration-in-vyos-new-quirk-between-systemd-networkd-and-vyos/14689
- 7: https://manpages.debian.org/bullseye/systemd/networkd.conf.5.en.html
- 8: Dhcp clientidentifier duid-only not working correctly systemd/systemd#25562
- 9: [Networkd][DHCP] Allow users to provide custom DHCP client identifier via DUIDRawData systemd/systemd#32858
🏁 Script executed:
#!/bin/bash
set -eu
printf '%s\n' '--- static mapping documentation ---'
rg -n -C 5 '\bduid\b|static mapping|client.?id' docs/configuration/service/dhcp-server.md docs/_include \
--glob '*.md' --glob '*.txt' | head -240Repository: vyos/vyos-documentation
Length of output: 11806
🏁 Script executed (no clone):
#!/bin/bash
set -eu
python3 - <<'PY'
import urllib.request
urls = [
"https://manpages.debian.org/bookworm/systemd/systemd.network.5.en.gz",
"https://raw.githubusercontent.com/systemd/systemd/v252.30/src/network/networkd-dhcp4.c",
]
for url in urls:
print(f"--- {url} ---")
try:
data = urllib.request.urlopen(url, timeout=10).read()
if url.endswith(".gz"):
import gzip
text = gzip.decompress(data).decode("utf-8", "replace")
else:
text = data.decode("utf-8", "replace")
for line in text.splitlines():
if "ClientIdentifier" in line or "duid-only" in line or "RFC 4361" in line:
print(line[:300])
except Exception as exc:
print(type(exc).__name__, exc)
PY
Length of output: 585
Qualify the systemd-networkd behavior at docs/configuration/service/dhcp-server.md:1062-1065.
When ClientIdentifier=duid is configured, systemd-networkd sends an RFC 4361 identifier in the form ff:<IAID>:<DUID>. A static mapping's duid must match the DUID inside this value, not the complete identifier. Other modes use different formats.
🧰 Tools
🪛 LanguageTool
[style] ~1065-~1065: Consider a more concise word here.
Context: ... static mapping's duid must be set to in order to match. ::: ```{opcmd} show dhcp server...
(IN_ORDER_TO_PREMIUM)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/configuration/service/dhcp-server.md` around lines 1063 - 1065, Qualify
the systemd-networkd behavior in the DHCP client-identifier documentation: state
that it applies when ClientIdentifier=duid, describe the RFC 4361
ff:<IAID>:<DUID> format, and clarify that static mappings use only the embedded
DUID. Note that other ClientIdentifier modes produce different formats.
Source: Linters/SAST tools
1 participant
Change summary
Documents the
Client IDcolumn that vyos-1x#5394 adds toshow dhcp server leases, and corrects the sort key list on the same page.The column is added to the three lease samples on the page, with a note on how to read it — most clients send
01:followed by their MAC, while a systemd-networkd host sends an {rfc}4361identifier of the formff:<IAID>:<DUID>, and it is the DUID inside that, not the whole string, that a static mapping'sduidmust be set to in order to match. Getting that wrong produces a reservation the CLI accepts and Kea never matches, so it seemed worth stating explicitly rather than leaving to be inferred from a column of hex.The sort key list was already wrong and is corrected while
client_idis added to it. It namedhardware_address, which the command has never accepted:The DHCPv6 sort key list a few sections below is stale in the same way — it names
expires,iaid_duidandlast_commwhere the command wantsend,duidandlast_communication, and omitshostnameentirely:That is deliberately not touched here — it is a different command, untouched by this change, and wants its own task. Flagging it so it is not lost.
Related PR(s)
Related Task(s)