Capture kit¶
Next release
netdryrun capture and netdryrun sanitize are on the main branch and ship in the next release. They are not in 0.4.0. To try them before that, install from a clone (pip install -e .).
Your team has a licensed image Netdryrun can't get: IOS XE, IOS XR, SR OS, or a newer version of a NOS it already supports. You can still help cover it. Capture what a driver reads on your own lab node, sanitise it, and send the bundle. We never ask for the image, a licence or a config: only the command output you choose to share.
What a capture can and can't do¶
- It can give a driver real output to parse: parser tests for your NOS version, and new shapes the driver must handle.
- It can't prove how the NOS behaves. A driver built only from contributed captures would ship as captured-only: a status that never passes a check its captures don't cover (see the design note; no driver has it yet). A live run by someone who holds the image is still what makes a driver beta.
1. Capture, on a lab node only¶
Deploy your lab with containerlab and bring it to the state you want to capture (the scenario). Then:
capture takes a containerlab topology and a node name from it, never an address or a hostname. Before it runs anything, it asks Docker for the node's container and checks the labels containerlab gives every container it creates (containerlab=<lab>, clab-node-name=<node>). It refuses:
- a node that isn't in the topology;
- a
host,ext-containeror bridge node (containerlab doesn't run those as lab nodes); - a container that is missing, stopped, or whose labels name another lab or node: one someone started with
docker run, for example.
It then runs the driver's own read methods, through a lab object that records every command the driver sends and refuses a command for any other node. So the bundle holds exactly the commands Netdryrun runs, and nothing else.
| Scenario | The lab must show | Needs |
|---|---|---|
established |
at least one BGP session established | |
no-neighbor |
at least one configured session that is not established | |
route-present |
the prefix in the routing table | --prefix |
route-absent |
the prefix in neither the routing table nor BGP | --prefix |
received-not-selected |
two or more BGP paths for the prefix, one best | --prefix |
community, med, no-med, local-pref, as-path |
a BGP path for the prefix with that attribute (no-med: without a MED) |
--prefix |
ping-reply, ping-no-reply |
every ping answered, or none | --target |
If the driver's reading doesn't show the scenario, capture says so and exits 1: fix the lab, or capture the scenario it does show.
| Option | Meaning |
|---|---|
--node NAME |
The node, by its name in the topology (required) |
--scenario NAME |
What the lab shows now, from the table above (required) |
--out DIR |
A new, empty folder for the bundle (required) |
--prefix PREFIX |
The prefix the route scenarios read |
--target ADDRESS |
The address the ping scenarios ping |
--source ADDRESS |
The ping's source address |
--vrf NAME |
The VRF to read (default default) |
--driver NAME |
The driver, when it can't be detected from the node's kind or image |
--nos-version TEXT |
The NOS version as you know it, kept next to the one the node reports |
2. Sanitise¶
The bundle capture wrote is not sanitised: keep it to yourself. sanitize rewrites, the same way in every file of the bundle:
- IPv4 addresses into 10.0.0.0/8, one /16 at a time. The last two octets stay, /16s keep their order, and a shorter prefix (/8 to /15) gets an aligned block, so prefix lengths and containment survive.
- IPv6 addresses into the documentation range 3fff::/20, one /32 at a time, the same way.
- AS numbers, where the output says they are AS numbers (keys such as
remoteAsandpeer-as, AS paths, the AS half of a community,remote-as 65001andAS 65001in text): 2-byte ones to 64512 and up, 4-byte ones to 4200000000 and up, in order. - Hostnames and domain names: the node's name, every
--hostname, and the values of hostname-like keys, tohost-1,host-2, ... - Secrets (passwords and keys) to
<removed>.
It keeps every key, every other value, list lengths and order, numbers as printed, and addresses that identify nobody: loopback, link-local, multicast, masks, 0.0.0.0/8, the documentation and benchmarking ranges, and prefixes shorter than /8. Unknown fields stay: removing them would hide the shape changes we need to see.
Without --confirm, it shows what it would change and writes nothing. With --confirm, it writes the sanitised bundle, but only if its self-check passes. The self-check runs on the result and doesn't trust the rewrite:
- no public address and no AS number outside the private ranges is left, and none of the replaced names;
- every output has the same structure as before;
- the driver, run again against the sanitised outputs, asks for exactly the bundle's commands and reads the sanitised version of what it read from the originals.
The mapping (which original became which) is written next to the bundle, never inside it. Don't share it.
| Option | Meaning |
|---|---|
--out DIR |
Where to write the sanitised bundle (default BUNDLE-sanitized) |
--map FILE |
Where to keep the mapping (default BUNDLE.sanitize-map.json); it must be outside the bundle |
--hostname NAME |
A name to replace; repeat for several |
--confirm |
Write the sanitised bundle (without it, show only) |
Exit codes: 0 done (or shown), 1 the self-check failed and nothing was written, 2 the bundle can't be read, was edited after the capture, or is already sanitised.
Known limits: a four-part version number such as a Linux kernel's 6.6.87.2 reads as an address and is rewritten too; AS numbers in asdot form (1.10) are not recognised yet; MAC addresses are kept.
3. Submit¶
Read the sanitised bundle before you share it: the sanitiser rewrites what it recognises, and you know your network better than it does. Then either:
- open a pull request that adds it under
captures/<nos>/<version>/<scenario>/. The contributor CI validates it within minutes: the manifest, every file's sha256, the sanitiser's self-check, a fresh leak scan, and a replay through the driver; or - attach it as a zip to a capture submission issue.
The bundle¶
r1-established-sanitized/
manifest.json
outputs/01-vtysh-c-show-version.txt
outputs/02-vtysh-c-show-bgp-neighbors-json.txt
manifest.json (netdryrun.capture/v1) records the Netdryrun version, the capture date, the NOS (driver) name, the version the node reports and the one you gave, the containerlab kind, the image and its digest when Docker has one (a private registry host is replaced), the scenario and its options, every command with its exit code, stderr, output file and sha256, a sha256 of the command list, what the driver read, whether that shows the scenario, and the sanitiser's version, self-check result and counts.