Schema reference

Every field netviz accepts, read directly off the models in src/netviz/models/. This is the lookup table; docs/schema.md is the specification that explains the design, and docs/yang-mapping.md explains how the YANG column relates to RFC 8343, RFC 8344 and IEEE 802.1Q.

Reading the tables. Required means the key must be present in the document. Default is the value netviz uses when it is absent — — for a required field, unset when the field simply has no value and nothing downstream supplies one. Several defaults are filled in at load time from elsewhere in the document (an interface's MTU becomes the address families' MTU, the device's forwarding becomes each family's forwarding); those are called out in the description. The YANG column names the node the field maps to, with … standing for /if:interfaces/if:interface and — meaning the field has no standards counterpart.

Element kinds

Document envelope

Every document, whatever its kind, carries these three keys plus a spec whose shape is chosen by kind.

• spec is required and its model is listed in the kind table above.
• Unknown keys are rejected anywhere in the document (NV-D005). A misspelt key that was silently ignored would produce a diagram disagreeing with the file, which is the one failure mode this tool exists to prevent.

metadata

Identity and free-form annotation, shared by every kind.

metadata.location

Where the hardware physically is. Optional, and shared by every kind: a patch panel is racked exactly as a server is.

• position is the lowest rack unit the element occupies and height how many it takes, counting upwards; units are numbered from 1 at the bottom of the cabinet, which is how a rack is labelled.
• site, room and rack together identify a rack (NV-U001). Two elements that name the same three share a cabinet and may not overlap; naming position or rack_height without rack is NV-U004.
• netviz render --layer rack draws one front elevation per rack, empty units included.

spec — switch, router, firewall, hub, computer, server

The six device kinds share one spec shape. They differ in which fields they permit (a hub rejects bridge, vlans, forwarding and all layer-3 configuration) and in the default value of forwarding.

• from merges a template underneath the device: the device's own keys win, interfaces merge by name, and every other list the device declares replaces the template's outright. See §6.6 of schema.md.

spec.forwarding

The device-wide default for per-interface IP forwarding. Both fields are required once the block is written at all.

spec.bridge

The 802.1Q bridge component the device implements.

spec.vlans[]

The device VLAN database. A port may reference a VLAN this list does not declare; that is NV-V004, not an error.

spec.interfaces[]

One entry per port or logical interface. Used by both devices and adapters.

• range expands as an odometer, the rightmost span varying fastest, and the width of a span's low bound is its zero padding ([01-12] yields 01…12). In description, {} and %d stand for the last span and {0}, {1}, … for a span by position. See §6.2.5 of schema.md.
• Inside a spec that declares from, an entry may state only name and the fields it overrides; the template supplies type and the rest.
• type: vlan requires parent and a vlan block in access mode carrying the encapsulation VID.
• type: lag and type: bridge require members, which must be non-empty, free of duplicates, and must not name the interface itself.
• An interface carrying IPv6 addresses must have an MTU of at least 1280 (NV-I011).

spec.interfaces[].ipv4

RFC 8344's ip:ipv4 container.

• A bare list is shorthand for the container: ipv4: [10.0.0.1/24] means ipv4: {addresses: [{ip: 10.0.0.1, prefix_length: 24}]}.

spec.interfaces[].ipv4.addresses[]

One IPv4 address. Addresses are unique within the interface (NV-A002).

• 10.0.0.1/24 is shorthand for the mapping form.
• netmask: 255.255.255.0 may be written instead of prefix_length, but not as well as; it is normalised away on load and never appears in netviz show output.

spec.interfaces[].ipv6

RFC 8344's ip:ipv6 container.

spec.interfaces[].ipv6.addresses[]

One IPv6 address. The 2001:db8::1/64 shorthand applies here too.

spec.interfaces[].vlan

The 802.1Q bridge-port configuration of one interface.

• In access mode: access_vlan is allowed and defaults to 1; trunk_vlans and native_vlan are rejected (NV-V002, NV-V003).
• In trunk mode: trunk_vlans is required and access_vlan is rejected.
• trunk_vlans accepts an id, a list, "10,20,100-110", all (1–4094) or none, and always serialises back to the coalesced string form.

spec.interfaces[].wireless

The radio configuration of a type: wifi interface: which side of the association it is on, where on the air it is, and which networks it serves.

• channel and width_mhz both require band: channel numbers repeat between the 2.4 GHz and 6 GHz plans, and 320 MHz exists only at 6 GHz (NV-W003, NV-W004).
• A medium: wireless cable joins exactly one ap radio to one station or mesh radio (NV-W007); that association is what the layer-2 view labels with SSID @ channel/band.

spec.interfaces[].wireless.bss[]

One basic service set: an SSID the radio beacons, or — on a client radio — the one it is associated to.

• An ap radio lists one entry per SSID it serves; a station or mesh radio lists at most one (NV-W006).
• vlan is where the SSID's traffic goes on the wired side. It has to be a VLAN the access point carries somewhere (NV-W009), or clients associate and reach nothing.

spec.netns[]

One network namespace the machine runs (§23.1) — a whole second network stack, with its own interfaces, addresses and routing table. An interface joins it with netns.

• parent names another entry of the same table, which is how namespaces nest: a namespace is created from inside exactly one other, so the nesting is a tree (NV-N021). Unset means the machine's initial namespace, which no document declares.
• Not a VRF. A VRF partitions the routing table of one stack; a namespace is a second stack, so it partitions the interface names, the addresses and the sockets as well. An interface can be in both.
• Namespaces are joined by veth pairs, which are ordinary type: ethernet interfaces naming each other with peer (§23.2).
• A namespace no interface is in holds nothing, which is NV-N026.

spec.vrfs[]

One routing instance — a VRF (§16.1). An interface joins it with vrf, and that binding is what makes an address private to the instance.

• Two devices that use the same name are taken to mean the same VRF; the route distinguisher is recorded because MPLS needs it, not to identify the instance.
• A VRF no interface binds to holds nothing, which is NV-F014.

spec.route_tables[]

One routing table beyond the three every stack has (§16.2). A table is a container routes are placed in; what reaches it is a rule in routing_policy.

• main, local and default exist without being declared and may not be declared, by either name or number (NV-F015).
• A table nothing looks up is consulted by nothing (NV-F023); a rule looking up a table nothing is placed in falls through (NV-F022).

spec.routes[]

One configured static route (§16.3).

• At least one of via, dev and blackhole is required, and blackhole excludes the other two (NV-F004).
• via is of the same family as prefix (NV-F003) and must be on-link: inside a prefix the device configures, in the same VRF (NV-F008).
• vrf and table are alternatives, not a pair: a VRF is a routing table of its own (NV-F018).

spec.routing_policy[]

One rule of the routing policy database (§16.4): which table a packet is routed by, decided from where it came from, what marked it, where it arrived or its DSCP.

• The database is walked from the lowest priority upwards and the first match decides, so priority is the rule's position and its identity: unique within the device, per family (NV-F020).
• A rule with no selector matches every packet, which terminates the database — and makes every rule after it in that family unreachable (NV-F024).
• There is no layer-4 selector. Mark the packet in the firewall and match fwmark here; see §16.7.

spec.routing

The dynamic routing protocols the device takes part in (§16.5). Both blocks are optional and neither implies the other.

spec.routing.ospf

One OSPF area, and the interfaces that run it.

• area accepts 0 and 0.0.0.0 for the backbone and stores the dotted quad, so two documents that spell one area differently still compare equal.
• One area per device: per-interface areas, and therefore area border routers, are deferred (§16.7).

spec.routing.bgp

The autonomous system this device is in, and the sessions it configures.

spec.routing.bgp.neighbors[]

One BGP session. The peer is an address, which is what the device is configured with — never an element name (§16.6).

• The address is resolved against every address the inventory configures. A peer that resolves to nothing is a warning (NV-F013), because an eBGP peer may be a transit provider nobody declares here; a peer whose own asn contradicts remote_asn is an error (NV-F011).

spec.zones[]

One security zone (§24.1): a name, and the interfaces in it. Policy is written between zones rather than between interfaces, so a rule survives a port being renamed.

• An interface is in at most one zone (NV-B003). That is the defining property of a zone, and what makes from lan a statement about a packet rather than a question.
• local is the machine itself and may not be declared (NV-B001); it is nameable in a rule without being declared.
• A zone holding no interface is inert (W150); an interface in no zone, on a device that declares zones at all, is worth a second look (W151).

spec.firewall

What the device does to the packets it sees (§24.2): the three defaults, the filter policy and the address translations.

• The defaults are deny inbound, deny transit, permit outbound. Each has to decide the packet, so mark and log are refused there (NV-B007).
• Available on every layer-3 kind, not only on kind: firewall: a router with three rules on it filters, and that is what most networks run. A hub has no IP stack and refuses both this and zones (NV-H003).

spec.firewall.rules[]

One filter rule (§24.2): which packets it picks out, and what happens to them. Read it as a sentence — at priority 100, TCP from the lan zone to this machine's port 22 is accepted.

• The chain is walked from the lowest priority upwards and the first terminal match decides, so priority is the rule's position and its identity: unique within the device, per family (NV-B008).
• accept, drop and reject are terminal; mark and log do something to the packet and carry on walking, which is what makes them useful.
• The hook is derived, never written: dst_zone: local is input, src_zone: local is output, two real zones are forward. A rule naming one real zone is in both the hooks it could be in.
• A rule with no selector matches everything reaching its hooks, which terminates the chain — and makes every rule after it unreachable (W154).
• action: mark is the half of §16.9 that writes; spec.routing_policy[].fwmark is the half that reads. A mark written that nothing reads is W152, and one read that nothing writes is W153.

spec.firewall.nat[]

One address translation (§24.4). Apart from the filter rules because it happens apart from them: a packet is translated and filtered, in different hooks.

• Order in the list is the order the translations are tried, first match winning. There is no priority: a number that only ever repeated the position would be one more thing to keep in step.
• snat and dnat state the address they translate to; masquerade cannot (it is the egress interface's, unknown until the packet leaves) and redirect need not (it is this machine) — NV-B006.

spec — cable

A cable is an undirected physical link between exactly two interfaces, and a first-class element so that it can carry its own metadata.

spec.endpoints[]

A reference to one port. Written as the string device:interface; the mapping form below is equivalent and both serialise back to the string.

spec — adapter

An adapter presents network interfaces over a non-network host port: USB dongles, Thunderbolt docks, media converters.

spec.upstream

The host-facing port of an adapter.

• Declaring attached_to and cabling the upstream port is an error (NV-X005): the host attachment is declared exactly once.

spec — tunnel

A tunnel is an undirected logical link between two or more interfaces of type: tunnel. It is to a logical topology what a cable is to a physical one, and a first-class element for the same reason.

• endpoints uses the same device:interface form a cable does, and each one must name an interface of type: tunnel (NV-T003) — the virtual interface the tunnel presents, not the physical port its outer packets leave by.
• over nests one tunnel inside another: vxlan over ipsec is written by naming the IPsec tunnel there. The chain must not loop (NV-T005).
• type supplies the defaults for port, encrypted and mode, and the encapsulation overhead NV-T011 measures an MTU against. Materialised on load, so a loaded document states them explicitly.
• There is nowhere to put a key, a password or a certificate, and the fields people reach for are rejected by name (NV-T010). auth records the method.

spec — patchpanel

A patch panel is a passive cross-connect: numbered positions on the front, the same numbers on the rear, and a coupler joining each front position to one rear position.

• ports is the only required key. Each position it names becomes two interfaces, front/<n> and rear/<n>, which a cable terminates on exactly as it terminates on a device port (NV-P001).
• A panel is not a hop. netviz render --layer physical draws it and both cable segments; every other layer splices the run into the single edge it electrically is, between the two active ports.
• couplers is only needed for a panel that is cross-wired. The default is the identity mapping, which is what the numbering printed on a real panel promises.

spec — pdu

A power distribution unit: numbered outlets, a rated capacity, and the supply that feeds it. The power half of what a patch panel is for data.

• outlets is the only required key, and takes the same count-or-range shorthand ports does. An outlet is not an interface: a power cord is not a cable, so nothing is cabled to a PDU — a device names an outlet in power.inputs instead.
• A PDU is placed on a rack elevation through metadata.location, exactly as a switch is, and netviz render --layer rack annotates it with its utilisation.
• input_feed is free text and is compared only for equality. It is what makes A/B redundancy checkable: two units on one feed fail together (NV-E015).

spec.power

What a device draws, which outlets feed it, and how much PoE it hands out. One block for both directions, because they are one question about one box.

• draw_watts accepts a bare number as shorthand for {typical: n}. The typical figure is what a load schedule sums; maximum is what a breaker has to survive.
• redundant: true needs at least two inputs (NV-E002), and they have to land on different units and different input_feeds for the claim to hold (NV-E015).
• powered_by: poe excludes inputs (NV-E005): a device fed over its uplink has no cord. NV-E014 then checks the far end of that uplink actually sources power.

spec.power.draw_watts

The nameplate load of one device, in watts. Written as a bare number when only the typical figure is known.

spec.power.inputs[]

One power supply and the outlet feeding it. Accepts the compact form pdu-r1-a:7 and the equivalent mapping, the same grammar a cable endpoint uses.

interfaces[].poe

This port is power sourcing equipment: it hands power down the cable. Only on a type a cable terminates on — ethernet or lag (NV-E006).

• How much the port reserves is said once: a class, or a budget_watts, never both (NV-E004). With neither, the port reserves its standard's maximum, which is what a switch with no per-port configuration does.
• A poe block on a port with nothing on it is a capability and takes no budget. A port that feeds something, or one with an explicit budget_watts, does — see NV-E013.

spec of a user document

One identity: a person, a service account or a shared login. Owns no interfaces and terminates no cable — a person is not a host — so it appears only in the identity view.

• login is optional because metadata.name is usually the account name already. Absent means the two are the same; everything downstream reads the materialised value, so nothing has to re-apply the default.
• A departed account is kept, not deleted: the group memberships still to be revoked are what NV-S015 reports, and deleting the document would delete them too.
• Only public keys. A pasted private key is refused with an explanation (NV-S002), which is the point of checking the shape at all.

spec of a group document

A named set of identities. members may name a user or another group, which is what makes a hierarchy expressible.

• Membership is written on the group and nowhere else. A user does not list its groups: two spellings of one fact are how an inventory starts disagreeing with itself.
• A member is an ordinary element reference (§4.1), resolved outwards from the group's own namespace. It must resolve (NV-S010) and must be an identity (NV-S011).
• A group naming itself is refused by the model; a longer loop needs the whole tree and is NV-S012.

spec of a layout document

Where things are drawn, per view. A sidecar: it carries no network facts, and the elements it places know nothing about it. netviz layout writes it.

• Coordinates are points (1/72 inch), y upwards, origin at the bottom left, and a position is the centre of what it places — Graphviz's system, so a stored arrangement can be handed straight back to it.
• A key is an address, resolved like any other reference. A node the inventory does not declare is keyed by its graph id instead: subnet:10.0.0.0/24, tunnel:site/wg0, rack:hq/comms/r1.
• A key naming something the inventory no longer has is NV-Y001, a warning; netviz layout --prune drops it.

spec.views.<view>

One view's arrangement. The view name is a layer netviz draws — physical, l1, l2, l3, overlay, routing, rack, power — because the same device sits somewhere different in each.

spec.views.<view>.nodes.<address>

Where one node is drawn.

• size is optional and is not seeded by netviz layout --write: Graphviz derives the same box from the same label on every run. It is honoured on read, for an editor that lets somebody resize a box on purpose.

spec.views.<view>.edges.<address>

How one link is drawn: the bends it goes through, the style it is routed in and where its label sits. Bends are not seeded unless netviz layout --write --waypoints is asked for — a computed spline is noise, a hand-placed bend is a decision — but a routing or a label is always written, neither being derivable.

• The waypoints are interior points: the two ends of a route are the nodes themselves, so dragging either endpoint carries the bends along instead of invalidating them.

spec.views.<view>.edges.<address>.label

Where a link's annotation sits, as a position on the link rather than a coordinate — so nudging a VLAN label clear of a crossing cable survives both endpoints moving.

spec.views.<view>.groups.<namespace>

The box one namespace cluster is drawn as. Unlike a node it carries a required size: nothing else decides how big a cluster is.

A point

Two numbers, in points. {x: 240, y: 396} or the shorthand [240, 396]; both mean the same thing and both are read.

A size

Two positive numbers, in points. {width: 220, height: 90} or [220, 90].

spec of a testsuite document

Named claims about the network the other documents describe. netviz test grades them and exits non-zero when one does not hold.

• A suite must assert something (NV-K002). A suite that checked nothing would report a green run, which is worse than having no suite at all.
• Assertions are graded in the order they are written, and a failure names the file and line of the assertion so an editor can jump to it.

One assertion

assert chooses the claim; every other key is read in its light. A key that belongs to a different assertion is rejected by name (NV-K003) rather than ignored.

• reachable, not-reachable and path-shorter-than take from and to in the spellings netviz path accepts: an element, element:interface, an IP address, or a selector matching several of them.
• same-vlan, distinct-vlan, within-prefix, has-interface, port-count-at-least, unique and count take select, in netviz render's filter vocabulary.
• no-single-point-of-failure takes neither, and optionally narrows the candidates with select and the views with layer.

spec of a note document

One callout on the diagram. Presentational throughout: a note cannot make netviz validate fail, cannot move a hop in netviz path, and never reaches an exported configuration.

• A note needs somewhere to be: either an anchor, or a geometry giving x and y. Both is the shape dragging an anchored note produces — the point places it, the anchor is what the leader line points at.
• views scopes the note to the drawings it makes sense in; empty means all of them. A note naming an element the inventory no longer has is NV-G001, a warning, exactly as a stale layout key is.

spec.anchor

What a note is about: one element, or one link. Exactly one of the two, and what makes the note survive the diagram being laid out again.

spec.geometry of an annotation

Where an annotation is drawn and how big it is. Flat rather than §18's nested position/size, because these four numbers are what a drag and a resize produce.

• Coordinates are §18's: points, y upwards, origin at the bottom left, and x/y is the centre of the box. Both or neither — half a position places nothing.

spec of an area document

A labelled box drawn behind the nodes. It says what it contains with members, a selector or an explicit geometry, and at least one of the three is required.

• members and selector box wherever the elements were drawn, so the zone follows them; geometry boxes a region of the canvas instead, for a zone that is about the paper rather than about devices.
• An area matching nothing is NV-G004, a warning: an empty box on a diagram reads as a claim that the zone is empty.

spec.selector

Which elements an area contains, said as a query rather than a list — the form that does not go stale when a rack gains a switch.

• Every clause given must match. A selector with no clause at all is refused: it would silently box the whole inventory.

spec of a legend document

A key: what the colours and the line styles of this drawing mean. Positioned by corner rather than by coordinate, because a key belongs at the edge of the paper and should stay there when the diagram is laid out again.

• auto: layers builds the entries from what the view actually drew — the node kinds present, the media of the links present — which is the only form of key that cannot disagree with the picture. It excludes entries, and one of the two is required.

spec.entries[]

One row of the key: a swatch, and what it means.

spec.style

How one element is drawn. Optional on every drawable kind and on cables and tunnels; every field is optional in turn, and an absent one inherits from the theme, then the icon set, then the built-in palette.

• The vocabulary is closed. A colour is a hex literal or one of the named colours, and every other field is a small enum or a bounded number, because these values end up inside Graphviz attributes and mxGraph style strings and a free-form pass-through would be an injection (NV-Z001).
• shape is ignored on a cable and a tunnel, which have no shape to set. icon names a picture inside the --icons theme and is ignored when no theme is in use; icon: none draws this one element as a plain shape.

Enumerations

interfaces[].type

Only ethernet, wifi and lag can terminate a cable (NV-C009).

vlan.mode

A netviz abstraction; 802.1Q has no equivalent leaf.

vlan.acceptable_frames

The values are the 802.1Q identity names, unabbreviated.

bridge.type

Decides the dot1q:port-type of every port on the device.

cable.medium

wireless constrains the endpoint interface types.

cable.duplex

upstream.type

Only usb and usb-c have an IANA interface-type identity.

tunnel.type

Each type fixes the layer carried, the outer transport and port, whether the payload is encrypted, and the encapsulation overhead. See §14.1 of the schema for the table.

tunnel outer transport

Derived from type; gre and esp run directly over IP and carry no port.

tunnel.mode

IPsec only; every other type has a single mode.

firewall.rules[].action

accept, drop and reject decide the packet and end the walk; mark and log do something to it and carry on to the next rule.

firewall.rules[].protocol

Only tcp, udp and sctp have ports to select on. icmp is IPv4 and icmpv6 is IPv6, so stating either against the other family is refused (NV-B005).

firewall.rules[].ct_state

Connection-tracking states, matched as a set. One rule accepting established and related replaces the return path of every other rule in the file.

firewall.nat[].type

snat and masquerade rewrite the source on the way out; dnat and redirect rewrite the destination on the way in.

firewall hook

Never written in a document: derived from src_zone and dst_zone, and named here because the three defaults of spec.firewall are one per hook.

poe.standard

Which IEEE 802.3 amendment the port implements, and therefore which classes exist: 802.3af stops at class 3, 802.3at adds 4, 802.3bt adds 5 to 8.

power.powered_by

outlet is the default. poe says the device takes power over its uplink and has no cord, so it declares no inputs.

tunnel.auth

The authentication method. netviz never stores key material (NV-T010).

user.type

Decides which identity rules apply: only a person can depart (NV-S015), and only a person is expected to be in a group (NV-S016).

user.status

departed is kept rather than deleted, so the memberships still to be revoked stay visible.

Scalar formats

Values that are normalised on load: what you write and what netviz show prints back may differ.

Booleans are strict on purpose: a quoted "true" or a YAML 1.1 yes is an error, not a silently accepted truth value. A MAC address written unquoted can be parsed by YAML as a sexagesimal integer, which loses the original digits — netviz detects the case and tells you to quote it.