netviz list

netviz list prints what the inventory declares, one subject at a time: the devices, the cables, the tunnels, the VLANs, the subnets or the power strips. It answers "what is in here, and how much of it?" without drawing anything — which is what you want when the question is a count, a spelling or a missing row rather than a shape.

Synopsis

netviz [GLOBAL OPTIONS] list [OPTIONS] [devices|cables|tunnels|vlans|bss|subnets|power|users|groups]

The subject argument

The single argument picks the subject, and defaults to devices. Each subject has its own columns, chosen so that one terminal-width row says the useful thing about one element:

The columns that are not self-evident:

bss is one row per SSID per radio, which is the unit an operator works with: a dual-band access point serving three networks has six of them, each with its own BSSID, VLAN and security. Client radios appear too, so "who is on the guest network?" is a question the listing answers. A hidden SSID is marked as such rather than left out — it is still on the air. See §6.2.6 of the schema.

power: one row per PDU, and two load figures

power is one row per pdu document (§17.6 of the schema), shaped after the netviz ipam utilisation table and for the same reason: the question is capacity planning, so the columns are what is there, what is used, what is left, and the percentage that decides whether anybody has to act.

The interesting part is the pair of load columns.

• LOAD is the normal-operation figure. A dual-corded device draws through both cords, so each of its n feeds carries typical / n — a 420 W server on two strips puts 210 W on each. This is the state the plant is in on every day that nothing has failed, so it is the figure E039 grades against CAPACITY, and the one UTIL is computed from.
• FAILOVER counts each load whole, because that is what this strip carries the moment the other one in the pair dies. It is reported without a verdict: a pair of PDUs each sized for half a rack is a design, not an error, and a rule that graded the failover number would fail every correctly built A/B cabinet.

The gap between the two is the redundancy plan, stated where somebody can read it. A single-fed rack has LOAD and FAILOVER the same, which is exactly the diagnosis worth having: nothing is dual-corded, so there is nothing to fail over to.

$ netviz -q -i examples/patch-room list power
PDU       FEED       OUTLETS  USED  FREE  CAPACITY   LOAD  FAILOVER   UTIL  LOADS
--------  ---------  -------  ----  ----  --------  -----  --------  -----  -----
pdu-r1-a  utility-a       24     2    22      3680   41.5        83   1.1%      2
pdu-r1-b  ups-1           24     2    22      3680   41.5        83   1.1%      2
pdu-r2-a  utility-a        8     3     5      1840  492.5       985  26.8%      3
pdu-r2-b  ups-1            8     3     5      1840  492.5       985  26.8%      3

Four strips, two racks, one A/B design. Each r2 unit carries 492.5 W of the 985 W its three loads draw between them and would carry all 985 W alone — 53.5 % of its 1840 W rating rather than 26.8 %, which is the headroom the second feed buys. Where each of those watts comes from and goes to is --layer power and netviz export power.

users and groups: the accounts, and what each grants

Identity is an element kind like any other (§19 of the schema), so it is listed like one. Two subjects rather than one, because they answer different questions and a single table would have half its columns blank in every row.

The pair of member columns on groups is the interesting part, for the same reason the pair of load columns on power is. MEMBERS is what the document says. PEOPLE is how many user accounts the group actually reaches once nested groups have been walked, which is the number an access rule written against it grants to — and no single document holds it.

$ netviz -q -i examples/home-lab list groups
GROUP      GID  EMAIL  MEMBERS  NESTED  PEOPLE  HOLDS
---------  ---  -----  -------  ------  ------  -----------
admins     100  -            1       0       1  ana
household  101  -            2       1       2  admins, kit

household names two members and holds two people: kit directly, and ana through admins. Writing ana into both groups would say the same thing and would be one more place to forget her.

GROUPS on users is the same derivation read backwards. Membership is written on the group and nowhere else, so "which groups is this person in?" is a question $ netviz -q -i examples/home-lab list users USER LOGIN FULL NAME EMAIL UID TYPE STATUS KEYS GROUPS

ana ana Ana Brandt ana@example.invalid 1000 person active 1 admins kit kit Kit Brandt kit@example.invalid 1001 person active 0 household backup backup - - 900 service active 0 -

`backup` is in nothing, and is a `service` account, so
[`I004`](../validation-rules.md#i004--person-in-no-group) says nothing about it:
an account nobody logs in as belonging to no group is the normal shape of one.

## Computed, not transcribed

`vlans`, `subnets`, `power` and `groups` are computed from the resolved graph or
plan rather than from what each document literally says: a host on an untagged access port is listed as a
member of that VLAN even though it declares none, and a PDU's row is built from the
`spec.power.inputs` of everything plugged into it rather than from anything the PDU
declares about itself — nothing on a strip names its own downstream devices
([§17.4](../schema.md#174-how-power-paths-are-resolved)). Loopback and link-local
prefixes are left out of `subnets`, since listing `127.0.0.0/8` once per machine
would say nothing about the addressing plan.

The point of computing them is that they cannot disagree with the pictures.
`subnets` is the same grouping
[`--layer l3`](../rendering.md#l3-prefixes-and-who-is-addressed-in-them) draws,
`power` the same resolution
[`--layer power`](../rendering.md#power-the-pdus-and-what-they-feed) and
[`netviz export power`](export.md) use,
`tunnels` the same resolution
[`--layer overlay`](../rendering.md#overlay-tunnels-and-what-runs-inside-what)
draws, and `groups` the same membership
[`--layer identity`](../rendering.md#identity-who-is-in-what) draws. A tunnel whose endpoints do not resolve is still listed — you are most
likely running the command *because* something is wrong — with its stack left at
its own type.

The `ENCRYPTED` column reads `underlay` for a tunnel that encrypts nothing
itself but runs inside one that does:

<!-- run: -->
```console
$ netviz -i examples/overlay list tunnels
NAME                STACK             VNI  ENCRYPTED  ENDS  ENDPOINTS
------------------  ----------------  ---  ---------  ----  ----------------------------------------------
tunnels/wg-mesh     wireguard           -  yes           3  rtr-branch-a:wg0, rtr-branch-b:wg0, rtr-hq:wg0
tunnels/ipsec-hq-b  ipsec               -  yes           2  rtr-branch-b:ipsec0, rtr-hq:ipsec0
tunnels/vx-100      vxlan over ipsec  100  underlay      2  rtr-branch-b:vxlan100, rtr-hq:vxlan100
tunnels/gre-mgmt    gre over ipsec      -  underlay      2  rtr-branch-b:gre1, rtr-hq:gre1
tunnels/ovpn-admin  openvpn             -  yes           2  pc-branch-b:tun0, rtr-hq:ovpn0

A document that will not load is reported as a warning on stderr and its elements are simply absent from the table — list answers about what did load, and refusing to answer because an unrelated file is broken would not help. Run netviz validate for the details.

Output formats

-F table is for reading and is the default. -F json and -F yaml are for piping, and both carry more fields than the table has room for: the short name and the namespace as well as the qualified name, every address rather than the first, the bit rate as an integer rather than 1Gbps, a cable's duplex and label, a tunnel's transport, port, MTU and over chain, the full member list of a VLAN or a prefix, and the file#document:line each element was read from.

There is no csv here: a listing is a document with nested lists in it, and flattening one into a single row is a decision better made by whatever consumes it. netviz ipam -F csv and netviz export cable-list are the commands that produce a spreadsheet on purpose.

$ netviz -i examples/home-lab list devices
NAME               KIND      PORTS  ADDRESS           VLANS
-----------------  --------  -----  ----------------  -----
hosts/adp-usb-eth  adapter       1  192.168.10.30/24  10
hosts/laptop       computer      2  -                 10
hosts/pc-desk      computer      3  192.168.10.20/24  10
hosts/phone        computer      1  192.168.10.40/24  -
hosts/srv-nas      server        2  192.168.10.10/24  10
routers/rtr-home   router        3  192.0.2.1/32      10
switches/sw-home   switch        7  192.168.10.2/24   10,20
wireless/ap-home   switch        4  192.168.10.3/24   10,20

hosts/laptop shows - because it has no routable address of its own: it reaches the network through the USB adapter on the row above it.

When a listing beats a diagram

A diagram is the right answer to a question about shape. A listing is the right answer to everything else, and is usually faster to act on:

• Counting and spotting the gap. Six devices where you expected seven is one glance at list devices; finding the missing box in a rendered graph is not.
• Spelling. list devices is the canonical source of the fully-qualified names that netviz show, --neighbors-of and netviz path take.
• Reviewing an addressing plan. list subnets fits a whole campus on a screen, where the layer-3 diagram of one does not. When the question is how full a prefix is rather than what prefixes exist, go on to netviz ipam.
• No Graphviz. list needs nothing but Python, so it works in a container where a render exits 5.
• Diffing. Two -F json listings diff cleanly; two .svg files do not.

Arguments

Options

Exit codes

list reports what loaded rather than judging it, so it has no failure of its own: validation is not run and findings do not change the code.

See also

• netviz show — one element in full, once list has told you its name.
• netviz ipam and docs/ipam.md — list subnets says which prefixes exist; ipam says whether the plan is healthy.
• docs/rendering.md — the layers whose groupings subnets, tunnels and power print as tables.
• netviz export power and docs/export.md — list power says whether each strip has room; the load schedule says which outlet every cord is in.
• docs/validation.md — the command to run when list warns that a document is missing from its output.