@takodotid/circuit 0.43.1 → 1.0.0-rc.2

package/src/config/device.ts

@@ -0,0 +1,164 @@
+// One device: its name, where it is, what it is, how Circuit logs in, and its groups. A part of a device, written in another file and given to it by a source.
+
+import type { IP, Secret } from "./common";
+import type { Firewall } from "./firewall";
+import type { Interfaces, Port } from "./interfaces";
+import type { Management } from "./management";
+import type { Monitoring } from "./monitoring";
+import type { AnyFacts, NetworkFacts } from "./network";
+import type { Routing } from "./routing";
+import type { Services } from "./services";
+import type { Switching } from "./switching";
+import type { System } from "./system";
+
+/** A computer with SSH that holds the serial consoles of devices, such as a laptop beside the rack. It runs Python 3. */
+export type Jump = {
+    /** Its address or name. */
+    host: string;
+    /** The user Circuit logs in as. It must be allowed to open the serial ports. */
+    user: string;
+    /** The user's password. */
+    password: Secret;
+    /** SSH port. 22 when absent. */
+    port?: number;
+    /** The jump host is reached through a Cloudflare Tunnel, so Circuit connects with `cloudflared access ssh`, which must be installed. */
+    cloudflared?: true;
+};
+
+/** A serial console, on a jump host or on the computer Circuit runs on. */
+export type Console = {
+    /** The jump host the console cable is plugged into. When absent, the cable is plugged into the computer Circuit runs on. */
+    jump?: Jump;
+    /** The serial port: on Linux or macOS a path under `/dev`, where a path under `/dev/serial/by-path/` stays the same when two adapters swap names; on Windows a COM port, such as `COM3`. */
+    port: string;
+    /** Line speed in bits per second, such as 9600 or 115200. */
+    baud: number;
+    /** The console asks only for a password, with no name first. Circuit then types no name; `connection.user` still picks the password. */
+    password_only?: true;
+};
+
+/** How Circuit itself logs in. `U` is the device's user names. */
+export type Connection<U extends string> = {
+    /** Management address. Absent for a device reached only through its console. Its own value, apart from any interface's address. */
+    host?: IP;
+    /** One of `system.users`. Its password is the login. */
+    user: U;
+    /** SSH port. 22 when absent. */
+    port?: number;
+    /** The device's serial console, for `--console`: the way in before the device has a management address, or when its management network is down. */
+    console?: Console;
+};
+
+/** The names a device declares, by kind. A field that refers to a name takes only one of these. */
+export type Names = {
+    /** Keys of `interfaces.ethernet`. */
+    port: string;
+    /** Keys of `interfaces.lag`. */
+    lag: string;
+    /** Keys of `interfaces.vlan_interface`. */
+    vlanInterface: string;
+    /** Keys of `interfaces.bridge`, `.loopback`, `.gre`, `.vxlan` and `.wireguard`. */
+    interface: string;
+    /** Keys of `switching.vlans`. */
+    vlan: string;
+    /** Keys of `switching.acls`. */
+    acl: string;
+    /** Keys of `routing.policies`. */
+    policy: string;
+    /** Keys of `routing.prefix_sets`. */
+    prefixSet: string;
+    /** Keys of `routing.bgp.neighbor_groups`. */
+    neighborGroup: string;
+    /** Keys of `routing.tables`. */
+    table: string;
+    /** Keys of `routing.vrfs`. */
+    vrf: string;
+    /** Keys of `firewall.address_sets`. */
+    addressSet: string;
+    /** Keys of `firewall.interface_sets`. */
+    interfaceSet: string;
+    /** Keys of `system.users`. */
+    user: string;
+    /** Keys of `system.certificates`. */
+    certificate: string;
+    /** Every port and interface: `port`, `lag`, `vlanInterface` and `interface` together. */
+    anyInterface: string;
+};
+
+/**
+ * The groups of a device, what a part may add to as well. `N` holds the names the device declares, `Ethernet` its ports. `Part` is true in a part, where BGP holds only what the part adds.
+ * `Net` is what the network writes: whether it turns on the check `untrusted_vlans`, and its `communities`.
+ */
+export type Groups<N extends Names, Ethernet, Part extends boolean = false, Net extends NetworkFacts = AnyFacts> = {
+    /** The box itself: banner, time, DNS it uses, users, certificates, logs kept on it, software, hardware. */
+    system?: System<N["user"], N["certificate"], NoInfer<N["anyInterface"]>>;
+    /** How people and tools log in: ssh, https, api, native protocol, console. */
+    management?: Management<NoInfer<N["anyInterface"]>, NoInfer<N["certificate"]>, NoInfer<N["addressSet"]>>;
+    /** What the box reports to collectors: snmp, syslog, flow export, optics. */
+    monitoring?: Monitoring<NoInfer<N["anyInterface"]>>;
+    /** Every port and interface, by kind: ethernet, lag, vlan_interface, bridge, loopback, gre, vxlan, wireguard. */
+    interfaces?: Interfaces<Ethernet, N["lag"], N["vlanInterface"], N["interface"], NoInfer<N["vlan"]>, NoInfer<N["vrf"]>>;
+    /** Layer 2 shared by ports: vlans, stp, lldp, acls. */
+    switching?: Switching<N["vlan"], N["acl"], NoInfer<N["anyInterface"]>, Net["untrusted"]>;
+    /** What the box serves to hosts: dhcp server, dhcp relay, dns server, ntp server. */
+    services?: Services<NoInfer<N["anyInterface"]>>;
+    /** Where packets go: tables, vrfs, policy routing, static routes, bgp, ospf, bfd, rpki, policies, prefix sets. */
+    routing?: Routing<N["policy"], N["prefixSet"], N["neighborGroup"], N["table"], N["vrf"], NoInfer<N["anyInterface"]>, Part, Net>;
+    /** Which packets pass and how they are rewritten: address sets, interface sets, filter, nat, untracked, conntrack helpers. */
+    firewall?: Firewall<N["addressSet"], NoInfer<N["anyInterface"]>, N["interfaceSet"]>;
+};
+
+/**
+ * Everything one device runs. What is not written here is removed from the device or returned to its default.
+ *
+ * `N` holds the names it declares, so a reference to a name it does not declare is an error. `Ethernet` is its ports, checked against the model.
+ * `Site` is the network's sites. `Net` is what the network writes: whether it turns on the check `untrusted_vlans`, and its `communities`.
+ */
+export type Device<
+    Platform extends string,
+    Model extends string,
+    Site extends string,
+    N extends Names,
+    Ethernet,
+    Name extends string = string,
+    Net extends NetworkFacts = AnyFacts,
+> = {
+    /** Its hostname: its name in the network, and the key under which each source gives it a part. */
+    name: Name;
+    /** The site it is at, one of the network's `sites`. The NetBox site and LibreNMS group of that name. */
+    site: Site;
+    /** Its role in NetBox, such as `Core switch`. Circuit makes the role when NetBox has none of that name. */
+    role?: string;
+    /** Operating system. It decides which adapter renders and applies the device. */
+    platform: Platform;
+    /** Hardware model, one of the platform's. It decides which port names exist. */
+    model: Model;
+    /** How Circuit itself logs in. */
+    connection: Connection<NoInfer<N["user"]>>;
+} & Groups<N, Ethernet, false, Net>;
+
+/**
+ * A part of a device, which a source gives it under its hostname: what an upstream, a tenant or a monitoring host adds to it. The names it refers to must be declared by the device or by one of its parts.
+ */
+export type Part<N extends Names, Ethernet, Net extends NetworkFacts = AnyFacts> = {
+    /** How Circuit itself logs in. In a part, only what the part adds, such as the console. */
+    connection?: Partial<Connection<NoInfer<N["user"]>>>;
+} & Groups<N, Ethernet, true, Net>;
+
+/** Any name: what a part, or a device seen from the network, holds. */
+type AnyNames = { [K in keyof Names]: string };
+
+/** A port as a part writes it, before the device it goes to checks its names. */
+export type AnyPort = Port<string, string, string, string>;
+
+/** Any device, as the network holds it. */
+export type AnyDevice = Device<string, string, string, AnyNames, Record<string, AnyPort>>;
+
+/**
+ * A part of one or more devices, written apart from them and given to each device that carries it, under its hostname in a source: an upstream's VLAN, sessions and policies on the router, a tenant's ports on a switch, what every device sends to the monitoring hosts.
+ *
+ * It has a device's shape and docs. What only a whole device has (its site, platform, model) is not here, and what a part writes alone stays optional: a part can add BGP neighbors without the AS, or a console without the user.
+ *
+ * Names a part refers to (a VLAN, an interface, a policy) are checked once the part reaches a device: there they must be declared.
+ */
+export type DevicePart = Part<AnyNames, Record<string, AnyPort>>;

package/src/config/firewall.ts

@@ -0,0 +1,150 @@
+// Which packets pass and how they are rewritten: `firewall.address_sets`, `.interface_sets`, `.filter`, `.nat`, `.untracked`, `.conntrack_helpers`.
+
+import type { Family, HostAddress, IP, Named, OneOrMore, Ordered, Prefix } from "./common";
+
+/** An IP protocol. `icmp` means ICMPv6 in an IPv6 rule. */
+export type Protocol = "tcp" | "udp" | "icmp" | "gre" | "esp" | "ah" | "ospf" | "vrrp";
+
+/** The state connection tracking gives a packet. */
+export type ConnectionState = "new" | "established" | "related" | "untracked" | "invalid";
+
+/** Ports from `min` to `max`, both included. */
+export type PortRange = {
+    /** The first port, 0 to 65535. */
+    min: number;
+    /** The last port, 0 to 65535, not below `min`. */
+    max: number;
+};
+
+/** A port, a range of ports, or any of several. */
+export type Ports = number | PortRange | readonly (number | PortRange)[];
+
+/** A TCP header flag. */
+export type TcpFlag = "fin" | "syn" | "rst" | "psh" | "ack" | "urg";
+
+/**
+ * Conditions on a packet. All must be true. A rule with addresses of one family applies to that family only. `I` is the device's
+ * ports and interfaces, `AS` its address sets, `IS` its interface sets.
+ *
+ * `src`, `dst`, `in_interface` and `out_interface` each take a list, and an interface set stands for its interfaces. Where the
+ * platform has no list, Circuit writes one rule per combination: the interface outermost (`in` before `out`), then `src`, then `dst`.
+ */
+export type FilterMatch<I extends string, AS extends string, IS extends string> = {
+    /** Only packets of this family. */
+    family?: Family;
+    /** IP protocol. */
+    protocol?: Protocol;
+    /** Source address or prefix, or any of several. */
+    src?: OneOrMore<Prefix>;
+    /** Destination address or prefix, or any of several. */
+    dst?: OneOrMore<Prefix>;
+    /** One of `firewall.address_sets`: the source is in it. */
+    src_address_set?: AS;
+    /** One of `firewall.address_sets`: the destination is in it. */
+    dst_address_set?: AS;
+    /** Source port, or any of several. TCP and UDP only. */
+    src_port?: Ports;
+    /** Destination port, or any of several. TCP and UDP only. */
+    dst_port?: Ports;
+    /** One of the device's ports or interfaces, or any of several: the packet arrived on it. */
+    in_interface?: OneOrMore<I>;
+    /** One of the device's ports or interfaces, or any of several: the packet leaves through it. */
+    out_interface?: OneOrMore<I>;
+    /** One of `firewall.interface_sets`: the packet arrived on one of its interfaces. Not with `in_interface`. */
+    in_interface_set?: IS;
+    /** One of `firewall.interface_sets`: the packet leaves through one of its interfaces. Not with `out_interface`. */
+    out_interface_set?: IS;
+    /** Connection tracking state, any of these. */
+    connection_state?: readonly ConnectionState[];
+    /** TCP flags that must be set, and flags that must not be. */
+    tcp_flags?: {
+        /** Flags that must be set. */
+        set?: readonly TcpFlag[];
+        /** Flags that must not be set. */
+        unset?: readonly TcpFlag[];
+    };
+};
+
+/**
+ * One firewall rule, the condition first: `{ if: { protocol: "icmp" }, then: "accept" }`. No `if`: every packet.
+ */
+export type FilterRule<I extends string, AS extends string, IS extends string> = {
+    /** Shown beside the rule on the device. */
+    description?: string;
+    /** Which packets the rule applies to. Every packet when absent. */
+    if?: FilterMatch<I, AS, IS>;
+    /** What happens to a matching packet. `reject` answers the sender, `drop` does not. */
+    then: "accept" | "drop" | "reject";
+    /** Send the rest of an accepted flow through the fast path, skipping the remaining rules. */
+    fast_path?: true;
+};
+
+/** Rules in order, the first match wins, then `default_action`. */
+export type Chain<I extends string, AS extends string, IS extends string> = {
+    /** What happens to a packet no rule matched. Accept when absent. */
+    default_action?: "accept" | "drop";
+    /** Rules in order: the first runs first. Written whole in one place; `merge` places rules from other files in it. */
+    rules?: Ordered<FilterRule<I, AS, IS>>;
+};
+
+/**
+ * One address translation, the condition first: `{ if: { src: "10.0.0.0/24", out_interface_set: "uplinks" }, then: "snat", to_address: "192.0.2.1" }`.
+ * No `if`: every packet.
+ */
+export type NatRule<I extends string, AS extends string, IS extends string> = {
+    /** Shown beside the rule on the device. */
+    description?: string;
+    /** Which packets are translated. Every packet when absent. */
+    if?: FilterMatch<I, AS, IS>;
+} & (
+    | {
+          /** `masquerade` uses the address of the outgoing interface. */
+          then: "masquerade";
+      }
+    | {
+          /** `snat` rewrites the source, `dnat` the destination. */
+          then: "snat" | "dnat";
+          /** The address to rewrite to, alone or with its length. */
+          to_address: HostAddress;
+          /** The port to rewrite to. Unchanged when absent. */
+          to_port?: number;
+      }
+);
+
+/** Connection-tracking helpers that rewrite application payloads. None run unless listed. */
+export type Helper = "ftp" | "tftp" | "sip" | "h323" | "pptp" | "rtsp" | "irc";
+
+/** What the device filters and translates. `AS` is the device's address set names, `I` its ports and interfaces, `IS` its interface set names. */
+export type Firewall<AS extends string, I extends string, IS extends string> = {
+    /** Named groups of addresses and prefixes, of either family, that rules match on with `src_address_set` and `dst_address_set`. */
+    address_sets?: Named<AS, readonly (IP | Prefix)[]>;
+    /**
+     * Named groups of the device's ports and interfaces, that rules match on with `in_interface_set` and `out_interface_set`, like a
+     * RouterOS interface list or a FortiOS zone. A list: each part adds its own, such as each upstream its interface to `uplinks`.
+     */
+    interface_sets?: Named<IS, readonly I[]>;
+    /** Traffic to the device (`input`), through it (`forward`), and from it (`output`). */
+    filter?: {
+        /** Traffic to the device itself. */
+        input?: Chain<I, NoInfer<AS>, NoInfer<IS>>;
+        /** Traffic the device routes. */
+        forward?: Chain<I, NoInfer<AS>, NoInfer<IS>>;
+        /** Traffic the device itself sends. */
+        output?: Chain<I, NoInfer<AS>, NoInfer<IS>>;
+    };
+    /** Source translation on the way out, destination translation on the way in. Each is rules in order: the first runs first. */
+    nat?: {
+        /** Rewrites the source of traffic on the way out. */
+        source?: Ordered<NatRule<I, NoInfer<AS>, NoInfer<IS>>>;
+        /** Rewrites the destination of traffic on the way in. */
+        destination?: Ordered<NatRule<I, NoInfer<AS>, NoInfer<IS>>>;
+    };
+    /** Connection-tracking helpers that run. None when absent. */
+    conntrack_helpers?: readonly Helper[];
+    /**
+     * Traffic to and from these prefixes passes without connection tracking. A flood toward them cannot fill the connection table, and rules see its packets in the state `untracked`. Everything is tracked when absent.
+     *
+     * Each address NAT uses inside one of these prefixes (a source translation's `to_address`, a destination translation's `to_address` or matched `dst`) stays tracked: Circuit writes two accept rules for it, one for traffic to it and one for traffic from it, before the untracked rules. Without them, a reply to that address would skip tracking and never be translated back.
+     */
+    untracked?: readonly Prefix[];
+};

package/src/config/index.ts

@@ -0,0 +1,22 @@
+// Circuit v1 for a TypeScript project. Its values (functions, `presets` and `address`) are globals: circuit.d.ts declares them for the editor, and
+// Circuit puts them on `globalThis` before it reads the project. A project never imports them. `lib/` may import the types:
+// `import type { Prefix } from "circuit"`.
+
+export { bgpNeighbors, circuit, literal, merge, part, secret, secretFile } from "./define";
+export { presets } from "./presets";
+export { address } from "./address";
+export type * from "./address";
+export type * from "./common";
+export type * from "./communities";
+export type * from "./device";
+export type * from "./firewall";
+export type * from "./interfaces";
+export type * from "./management";
+export type * from "./models";
+export type * from "./monitoring";
+export type * from "./network";
+export type * from "./routing";
+export type * from "./services";
+export type * from "./switching";
+export type * from "./system";
+export type * from "./time-zones";

package/src/{schema → config}/interfaces.ts

@@ -1,20 +1,22 @@
-import type { InterfaceAddress, IP, MacAddress, Prefix, Secret } from "./common";
+// Every port and interface, by kind: `interfaces.ethernet`, `.lag`, `.vlan_interface`, `.bridge`, `.loopback`, `.gre`, `.vxlan`, `.wireguard`.
 
-/** A VLAN. Its key in `vlans` is its name. */
-export type Vlan = {
-    /** The VLAN's number on the wire, 1 to 4094. */
-    id: number;
-    /** What the VLAN is for. */
-    description?: string;
-};
+import type { HostAddress, IP, InterfaceAddress, MacAddress, Named, Prefix, Secret } from "./common";
 
 /** A storm-control threshold: packets per second, or percent of the link's speed. */
-export type Threshold = { pps: number } | { percent: number };
+export type Threshold =
+    | {
+          /** Packets per second. */
+          pps: number;
+      }
+    | {
+          /** Percent of the link's speed, above 0 and up to 100. */
+          percent: number;
+      };
 
 /** A kind of frame, by the ethertype in its header: `ipv4` is 0x0800, `ipv6` 0x86DD, `arp` 0x0806. */
 export type Ethertype = "ipv4" | "ipv6" | "arp";
 
-/** A virtual router address shared with other devices on the same segment, RFC 5798. */
+/** A virtual router address shared with other devices on the same segment, RFC 9568 (VRRPv3). */
 export type Vrrp = {
     /** Virtual router number, 1 to 255. The same on every device sharing the address. */
     id: number;
@@ -28,22 +30,6 @@ export type Vrrp = {
     interval?: number;
 };
 
-/** Layer 3 settings shared by every interface that can have an address. */
-export type Routed<F extends string> = {
-    /** Addresses with their length. Use `{ address, peer }` for a point-to-point address whose far end is outside its own prefix. */
-    addresses?: readonly (InterfaceAddress | { address: InterfaceAddress; peer: IP })[];
-    /** Send IPv6 router advertisements on this interface. Off when absent. */
-    ipv6_ra?: boolean;
-    /** Overrides the device's `hardware_offload` for traffic routed through this interface. Software forwarding is what makes the firewall apply. */
-    hardware_offload?: boolean;
-    /** Virtual router addresses on this interface. */
-    vrrp?: readonly Vrrp[];
-    /** The VRF this interface routes in. The default table when absent. */
-    vrf?: F;
-    /** This interface is the network's presence at an internet exchange. Devices ignore it; `circuit peeringdb` publishes it. */
-    exchange?: Exchange;
-};
-
 /** Presence at an internet exchange, as a registry lists it. The addresses are the interface's own. */
 export type Exchange = {
     /** The exchange's name, for output. */
@@ -54,6 +40,32 @@ export type Exchange = {
     peeringdb_ixlan?: number;
 };
 
+/** An address with its length, or `{ address, peer_address }` for a point-to-point address whose far end is outside its own prefix. */
+export type Address =
+    | InterfaceAddress
+    | {
+          /** Our address, with its length. */
+          address: InterfaceAddress;
+          /** The far end's address. */
+          peer_address: IP;
+      };
+
+/** Layer 3 settings shared by every interface that can have an address. `Vrf` is the device's VRF names. */
+export type Routed<Vrf extends string> = {
+    /** Addresses with their length. Use `{ address, peer_address }` for a point-to-point address whose far end is outside its own prefix. */
+    addresses?: readonly Address[];
+    /** Send IPv6 router advertisements on this interface. Off when absent. */
+    ipv6_ra?: boolean;
+    /** Overrides `system.hardware_offload` for traffic routed through this interface. Software forwarding is what makes the firewall apply. */
+    hardware_offload?: boolean;
+    /** Virtual router addresses on this interface. */
+    vrrp?: readonly Vrrp[];
+    /** One of `routing.vrfs`: the VRF this interface routes in. The main table when absent. */
+    vrf?: Vrf;
+    /** This interface is the network's presence at an internet exchange. Devices ignore it; `circuit peeringdb` publishes it. */
+    exchange?: Exchange;
+};
+
 /** Spanning tree settings for one port. */
 export type PortStp = {
     /** The port faces a host, never a switch, so it forwards at once. */
@@ -64,33 +76,43 @@ export type PortStp = {
     priority?: number;
 };
 
-/** Layer 2 membership. A port or LAG with none of these is routed. */
-export type Switched<V extends string> = {
-    /** The one VLAN this port or LAG is in, untagged. */
-    access_vlan?: V;
-    /** The VLANs this port or LAG carries, tagged. */
-    trunk_vlans?: readonly V[];
-    /** Untagged frames on a trunk are in this VLAN. Only with `trunk_vlans`. */
-    native_vlan?: V;
-    /** Overrides the device's `stp` for this port. `false` stops it sending or acting on BPDUs. */
+/** Drop flooded traffic above these thresholds. */
+export type StormControl = {
+    /** Frames to every host. */
+    broadcast?: Threshold;
+    /** Frames to a group. */
+    multicast?: Threshold;
+    /** Frames to a MAC address the switch has not learned. */
+    unknown_unicast?: Threshold;
+};
+
+/** Layer 2 membership. A port or LAG with none of these is routed. `Vlan` is the device's VLAN names. */
+export type Switched<Vlan extends string> = {
+    /** One of `switching.vlans`: the one VLAN this port or LAG is in, untagged. */
+    access_vlan?: Vlan;
+    /** Some of `switching.vlans`: the VLANs this port or LAG carries, tagged. */
+    trunk_vlans?: readonly Vlan[];
+    /** One of `switching.vlans`: untagged frames on a trunk are in this VLAN. Only with `trunk_vlans`. */
+    native_vlan?: Vlan;
+    /** Overrides `switching.stp` for this port. `false` stops it sending or acting on BPDUs. */
     stp?: boolean | PortStp;
     /** Drop flooded traffic above these thresholds. */
-    storm_control?: {
-        broadcast?: Threshold;
-        multicast?: Threshold;
-        unknown_unicast?: Threshold;
-    };
+    storm_control?: StormControl;
     /** The most MAC addresses this port or LAG learns, 1 or more. Frames from any other source address are dropped. An exchange sets 1 on a member port, so each member sends from one router only. No limit when absent. */
     mac_limit?: number;
     /** The only kinds of frame this port or LAG takes in; any other kind is dropped. An exchange takes `ipv4`, `ipv6` and `arp` on a member port. Every kind when absent. */
     ethertypes?: readonly Ethertype[];
 };
 
-/** The other end of a cable: another device and its port. Both ends must agree on how they are switched. */
+/**
+ * The other end of a cable: another of our devices and its port. Both ends must agree on how they are switched, and the far end must
+ * link back. The port's own `description` names that end, `<far device> <far port as printed there>`, such as `fw-01 port6`:
+ * Circuit warns when it doesn't, and never writes it.
+ */
 export type Link = {
-    /** Name of the device at the other end. */
+    /** The device at the other end, by its key in `devices`. */
     device: string;
-    /** The port on that device. */
+    /** The port on that device, such as `10g-2`. */
     port: string;
     /**
      * What is between the two ends when the cable is not direct, such as a carrier's local loop or L2 transport: `"Carrier A local loop"`. LLDP then sees the carrier's switches, not the far end, so `validate` does not compare LLDP on this port. Both ends name the same carrier.
@@ -98,27 +120,27 @@ export type Link = {
     through?: string;
 };
 
-/** A physical port. Ports a device does not declare are shut down. */
-export type Port<V extends string, A extends string, L extends string, F extends string> = Routed<F> &
-    Switched<V> & {
-        /** What is plugged in. */
+/** A physical port, by its key `<speed>-<position>`, such as `10g-4`. Ports a device does not declare are shut down. */
+export type Port<Vlan extends string, Acl extends string, Lag extends string, Vrf extends string> = Routed<Vrf> &
+    Switched<Vlan> & {
+        /** What is plugged in. On a port with a `link`, the far end: `<far device> <far port as printed there>`. */
         description?: string;
         /** Largest IP packet, in bytes. 1500 when absent. */
         mtu?: number;
         /** Fixed speed, for an optic slower than the cage. Negotiated when absent. */
         speed?: "100m" | "1g" | "10g" | "25g" | "40g" | "50g" | "100g";
-        /** Overrides the device's `lldp` for this port. */
+        /** Overrides `switching.lldp` for this port. */
         lldp?: boolean;
-        /** Hardware ACL applied to traffic arriving on this port. */
-        acl?: A;
-        /** The LAG this port is in. Every other setting goes on the LAG. */
-        lag?: L;
-        /** Another of our devices at the other end of the cable. */
+        /** One of `switching.acls`: the hardware ACL applied to traffic arriving on this port. */
+        ingress_acl?: Acl;
+        /** One of `interfaces.lag`: the LAG this port is in. Every other setting goes on the LAG. */
+        in_lag?: Lag;
+        /** Another of our devices at the other end of the cable. Circuit checks that it links back, and warns when `description` doesn't name it. */
         link?: Link;
     };
 
 /** Settings every interface that is not a physical port shares. */
-type Base<F extends string> = Routed<F> & {
+export type Base<Vrf extends string> = Routed<Vrf> & {
     /** What the interface is for. */
     description?: string;
     /** Largest IP packet, in bytes. */
@@ -126,10 +148,9 @@ type Base<F extends string> = Routed<F> & {
 };
 
 /** A layer 3 interface on a VLAN. */
-export type VlanInterface<V extends string, F extends string> = Base<F> & {
-    type: "vlan";
-    /** The VLAN it is on. */
-    vlan: V;
+export type VlanInterface<Vlan extends string, Vrf extends string> = Base<Vrf> & {
+    /** One of `switching.vlans`: the VLAN it is on. */
+    vlan: Vlan;
     /**
      * A MAC address of its own, instead of the one it shares with the device's other VLAN interfaces. A gateway in front of a transparent firewall needs one: frames to it come back on another VLAN, where the bridge would otherwise take a shared MAC for its own and keep them.
      */
@@ -137,12 +158,11 @@ export type VlanInterface<V extends string, F extends string> = Base<F> & {
 };
 
 /** An interface that is always up and is on no link, for addresses that must not depend on one. */
-export type Loopback<F extends string> = Base<F> & { type: "loopback" };
+export type Loopback<Vrf extends string> = Base<Vrf>;
 
-/** A link aggregation. Each member port points to it with `lag`. */
-export type Lag<V extends string, F extends string> = Base<F> &
-    Switched<V> & {
-        type: "lag";
+/** A link aggregation. Each member port points to it with `in_lag`. */
+export type Lag<Vlan extends string, Vrf extends string> = Base<Vrf> &
+    Switched<Vlan> & {
         /** LACP negotiates membership with the far end; `static` joins the ports without asking. LACP when absent. */
         mode?: "lacp" | "static";
         /** Number, on platforms where a LAG has a number instead of a name. Its position among the device's LAGs when absent. */
@@ -150,23 +170,21 @@ export type Lag<V extends string, F extends string> = Base<F> &
     };
 
 /** A GRE tunnel. */
-export type Gre<F extends string> = Base<F> & {
-    type: "gre";
-    /** Our tunnel endpoint. */
-    local: IP;
+export type Gre<Vrf extends string> = Base<Vrf> & {
+    /** Our tunnel endpoint, alone or with its length. */
+    local_address: HostAddress;
     /** The far tunnel endpoint. */
-    remote: IP;
+    remote_address: IP;
 };
 
 /** A point-to-point VXLAN tunnel. */
-export type Vxlan<F extends string> = Base<F> & {
-    type: "vxlan";
-    /** Segment identifier, the same on both ends. */
+export type Vxlan<Vrf extends string> = Base<Vrf> & {
+    /** Segment identifier, the same on both ends, 1 to 16777215. */
     vni: number;
-    /** Our tunnel endpoint. */
-    local: IP;
+    /** Our tunnel endpoint, alone or with its length. */
+    local_address: HostAddress;
     /** The far tunnel endpoint. */
-    remote: IP;
+    remote_address: IP;
     /** UDP port. 4789 when absent. */
     port?: number;
     /** Fixed MAC address, so a rebuild keeps the one the far side learned. */
@@ -193,12 +211,11 @@ export type WireGuardPeer = {
 };
 
 /** A WireGuard interface. */
-export type WireGuard<F extends string> = Base<F> & {
-    type: "wireguard";
+export type WireGuard<Vrf extends string> = Base<Vrf> & {
     /** UDP port peers connect to. */
     listen_port: number;
-    /** The address clients connect to, for generated client configs. */
-    endpoint?: IP;
+    /** The address clients connect to, for generated client configs, alone or with its length. */
+    endpoint?: HostAddress;
     /** This interface's private key. Its public key is derived from it. */
     private_key: Secret;
     /** Who may connect. */
@@ -208,12 +225,31 @@ export type WireGuard<F extends string> = Base<F> & {
 /**
  * A layer 2 bridge between VLAN interfaces, each keeping its own VLAN: a frame that comes in on one member leaves another with that member's tag. A firewall filters what crosses it, by the rules of its forward chain between the members, without routing it.
  */
-export type Bridge<F extends string> = Base<F> & {
-    type: "bridge";
-    /** The VLAN interfaces it joins, by name. Each has no address of its own. */
-    members: readonly string[];
+export type Bridge<VlanInterface extends string, Vrf extends string> = Base<Vrf> & {
+    /** Some of `interfaces.vlan_interface`: the VLAN interfaces it joins. Each has no address of its own. */
+    member_interfaces: readonly VlanInterface[];
 };
 
-/** Any interface that is not a physical port. */
-export type Interface<V extends string, F extends string> =
-    VlanInterface<V, F> | Loopback<F> | Lag<V, F> | Gre<F> | Vxlan<F> | WireGuard<F> | Bridge<F>;
+/**
+ * Every port and interface, by kind, each keyed by its name. A port's key is `<speed>-<position>` from the model.
+ *
+ * The type parameters are the names the device declares: `Ethernet` the ports, `L` LAGs, `VI` VLAN interfaces, `T` the other interfaces, `V` VLANs, `A` ACLs, `F` VRFs.
+ */
+export type Interfaces<Ethernet, L extends string, VI extends string, T extends string, V extends string, F extends string> = {
+    /** Physical ports, keyed by `<speed>-<position>` from the model, such as `10g-4`. Ports not listed are shut down. */
+    ethernet?: Ethernet;
+    /** Link aggregations, keyed by name. Each member port names one with `in_lag`. */
+    lag?: Named<L, Lag<V, F>>;
+    /** Layer 3 interfaces on a VLAN, keyed by name. Each names its VLAN in `vlan`. */
+    vlan_interface?: Named<VI, VlanInterface<V, F>>;
+    /** Layer 2 bridges between VLAN interfaces, keyed by name. */
+    bridge?: Named<T, Bridge<NoInfer<VI>, F>>;
+    /** Interfaces on no link, keyed by name. */
+    loopback?: Named<T, Loopback<F>>;
+    /** GRE tunnels, keyed by name. */
+    gre?: Named<T, Gre<F>>;
+    /** Point-to-point VXLAN tunnels, keyed by name. */
+    vxlan?: Named<T, Vxlan<F>>;
+    /** WireGuard interfaces, keyed by name. */
+    wireguard?: Named<T, WireGuard<F>>;
+};