@takodotid/circuit 0.39.0 → 0.40.0

package/dist/types/schema/device.d.ts

@@ -2,7 +2,7 @@ import type { IP, Secret } from "./common.js";
 import type { AclRule, Firewall } from "./firewall.js";
 import type { Interface, Port, Vlan } from "./interfaces.js";
 import type { PrefixSet, RoutePolicy } from "./policy.js";
-import type { Routing } from "./routing.js";
+import type { Routing, StaticRoute } from "./routing.js";
 import type { Certificate, DhcpRelay, DhcpServer, FlowExport, Management, System, User } from "./system.js";
 /** How the framework reaches the device. */
 export type Connection<U extends string> = {
@@ -39,6 +39,24 @@ export type Console = {
     /** The console asks only for a password, with no name first. Circuit then types no name; `connection.user` still picks the password. */
     passwordOnly?: true;
 };
+/**
+ * Virtual domains, on FortiOS: the device's own traffic kept apart from the traffic it routes. Everything is in `root` when absent.
+ *
+ * Multi-VDOM mode is turned on by hand, not by a plan: it moves the whole configuration into `root` and ends every session.
+ */
+export type Vdoms<I extends string> = {
+    /**
+     * A VDOM for the device's own traffic: FortiGuard, NTP, DNS and logging leave from it, by its own routes, so they never follow the routed traffic's default route. Everything not listed here stays in `root`.
+     */
+    management: {
+        /** Its name, such as `mgmt`. Not `root`. */
+        name: string;
+        /** The ports and interfaces in it, by name. A LAG's member ports go with the LAG. */
+        interfaces: readonly I[];
+        /** Its static routes, such as its own default route. */
+        static?: readonly StaticRoute<I, never>[];
+    };
+};
 /** A separate routing table, with the interfaces that route in it. */
 export type Vrf = {
     /** What the VRF is for. */
@@ -103,4 +121,6 @@ export type Device<Pl extends string = string, M extends string = string, N exte
     };
     /** Forward in hardware where the platform can. An interface may override it. */
     hardware_offload?: boolean;
+    /** Virtual domains, on FortiOS only: a management VDOM apart from the routed traffic. */
+    vdoms?: Vdoms<NoInfer<I | N>>;
 };

package/dist/types/schema/firewall.d.ts

@@ -96,7 +96,7 @@ export type Firewall<I extends string, AS extends string> = {
     };
     /** Helpers that run. None when absent. */
     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. */
+    /** 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`. An address NAT uses inside one stays tracked, or its replies would never be translated back. Everything is tracked when absent. */
     untracked?: readonly Prefix[];
 };
 /** A stateless rule evaluated in hardware where traffic arrives, before routing. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.39.0",
+    "version": "0.40.0",
     "description": "Declarative, vendor-neutral network configuration: describe each device in TypeScript, and Circuit makes the device match. Alpha.",
     "keywords": [
         "network",

package/src/core/validator.ts

@@ -93,6 +93,31 @@ export class Validator {
         Validator.checkFirewall(device, names, cidr);
         Validator.checkServices(device, names, report, cidr);
         Validator.checkCertificates(device, names, report);
+        Validator.checkVdoms(device, names, report, cidr, ip);
+    }
+
+    /** A management VDOM: FortiOS only, not `root`, with declared interfaces, and routes that leave through its own. */
+    private static checkVdoms(device: Device, names: Names, report: Report, cidr: Checker, ip: Checker): void {
+        const management = device.vdoms?.management;
+        if (!management) return;
+
+        if (device.platform !== "fortios") report("vdoms are a FortiOS setting");
+        if (management.name === "root") report("vdoms.management.name is root, the VDOM everything else is in; give it a name of its own");
+
+        for (const name of management.interfaces) {
+            names.expectInterface("vdoms.management interface", name);
+            const port = device.ports?.[name as keyof typeof device.ports];
+            if (port?.lag) report(`vdoms.management interface ${name} is in LAG ${port.lag}; list the LAG`);
+        }
+
+        for (const route of management.static ?? []) {
+            const where = `vdoms.management static route ${route.prefix}`;
+            cidr(where, route.prefix);
+            if (route.via) ip(where, route.via);
+            if (!route.via && !route.interface && !route.blackhole) report(`${where} has no next hop`);
+            if (route.interface && !management.interfaces.includes(route.interface))
+                report(`${where} leaves through ${route.interface}, which is not in the VDOM`);
+        }
     }
 
     /** What the model's hardware holds, from the catalog. A LAG with too many members is an error; too many switch rules is a warning, since the limit is only roughly known. */

package/src/helpers/upstreams.ts

@@ -163,7 +163,10 @@ type Names<C, N, F extends Field, Ks extends Key<C>> = { [K in Ks]: Named<C, N,
 /** The catalog as written, with any key the shape does not have refused, at every level. */
 type Exact<S, T> = T extends readonly unknown[] | string | number | boolean | Secret | ((...args: never[]) => unknown)
     ? T
-    : { [K in keyof T]: K extends keyof S ? Exact<NonNullable<S[K]>, T[K]> : never };
+    : // A shape that is a union, such as a storm-control threshold, is each of its members in turn: its keys are any member's.
+      S extends unknown
+      ? { [K in keyof T]: K extends keyof S ? Exact<NonNullable<S[K]>, T[K]> : never }
+      : never;
 
 /** The names as written, with a name or a role Upstreams does not make refused. */
 type ExactNames<N> = {

package/src/platforms/derive.ts

@@ -4,7 +4,8 @@ import { Address } from "../core/address";
 import type { Device } from "../schema";
 
 /** A feature a platform renders once proved on one of its devices. */
-export type ProvedFeature = "bfd-timers" | "static-route-bfd" | "multihop-bfd" | "alarm-severity" | "mac-limit" | "ethertype-filter";
+export type ProvedFeature =
+    "bfd-timers" | "static-route-bfd" | "multihop-bfd" | "alarm-severity" | "mac-limit" | "ethertype-filter" | "management-vdom";
 
 export class Derive {
     /** Each LAG's number: its own `id`, or its position among the device's LAGs. */
@@ -41,6 +42,7 @@ export class Derive {
         const has = (feature: ProvedFeature) => proved.includes(feature);
 
         if (routing?.bfd && !has("bfd-timers")) found.push(`routing.bfd, BFD timers are ${unproved}`);
+        if (device.vdoms && !has("management-vdom")) found.push(`vdoms, a management VDOM is ${unproved}`);
 
         for (const route of routing?.static ?? []) {
             if (route.bfd && !has("static-route-bfd"))

package/src/platforms/fortios/firewall.ts

@@ -155,6 +155,15 @@ export class FortiOsFirewall {
         );
     }
 
+    /** Who reaches the device's own services, alone: for a management VDOM, which routes no traffic of its own. */
+    static managementOnly(root: FortiOsBlock, device: Device): void {
+        const localIns = { ipv4: 0, ipv6: 0 };
+        const localInEntry = (family: Family) =>
+            root.block(family === "ipv4" ? "firewall local-in-policy" : "firewall local-in-policy6").entry(++localIns[family]);
+
+        FortiOsFirewall.management(localInEntry, new Objects(root, device), device);
+    }
+
     /** Packet filtering, who reaches the device, NAT and stateless ACLs. */
     static render(root: FortiOsBlock, device: Device): void {
         const fw = device.firewall;

package/src/platforms/fortios/index.ts

@@ -18,6 +18,7 @@ import { FortiOsPlan } from "./plan";
 import { FortiOsRender } from "./render";
 import { FortiOsRouting } from "./routing";
 import { FortiOsBlock, FortiOsTree } from "./tree";
+import { FortiOsVdoms } from "./vdoms";
 
 /** What a session reads and writes: an SSH shell, or anything else that streams the CLI. */
 export type Channel = {
@@ -194,6 +195,7 @@ export class FortiOs extends Platform {
 
         if (device.stp) found.push("stp, ports are routed");
         found.push(...FortiOs.transparentGaps(device));
+        found.push(...FortiOsVdoms.gaps(device));
 
         for (const [name, iface] of Object.entries(device.interfaces ?? {})) {
             if (iface.type === "vlan" && iface.mac) found.push(`interfaces.${name}.mac, which only RouterOS sets for now`);
@@ -224,7 +226,8 @@ export class FortiOs extends Platform {
             device,
             async (cli) => {
                 await FortiOs.checkVersion(cli, device);
-                return FortiOs.neighborsOf(await cli.run("diagnose lldprx neighbor details"), device);
+                const details = await FortiOs.inGlobal(cli, device, () => cli.run("diagnose lldprx neighbor details"));
+                return FortiOs.neighborsOf(details, device);
             },
             options
         );
@@ -259,7 +262,7 @@ export class FortiOs extends Platform {
     }
 
     plan(desired: string, current: string, options: ApplyOptions): Plan {
-        return FortiOsPlan.of(desired, current, options);
+        return FortiOsVdoms.plan(desired, current, (want, have) => FortiOsPlan.of(want, have, options));
     }
 
     async apply(device: Device, network: readonly Device[], changes: Plan, options: ApplyOptions): Promise<void> {
@@ -269,7 +272,7 @@ export class FortiOs extends Platform {
         const switched = changes.steps.some((step) => step.send.some((line) => line.startsWith("set opmode ")));
         if (!switched) return;
 
-        const again = FortiOsPlan.of(FortiOsRender.of(device), await this.read(device, network, options), options);
+        const again = this.plan(FortiOsRender.of(device), await this.read(device, network, options), options);
         if (!again.steps.length) return;
 
         console.log("  the operation mode changed; applying what it added on its own");
@@ -281,7 +284,8 @@ export class FortiOs extends Platform {
         await FortiOs.withCli(device, async (cli) => {
             await FortiOs.checkVersion(cli, device);
 
-            for (const line of FortiOs.fillLines(set, family, prefixes)) {
+            const lines = FortiOs.fillLines(set, family, prefixes);
+            for (const line of device.vdoms ? FortiOsVdoms.wrap({ kind: "vdom", vdom: FortiOsVdoms.ROOT }, lines) : lines) {
                 let answer = await cli.run(line);
                 if (FortiOsCli.QUESTION.test(cli.prompt) && line === "purge") answer = await cli.answer("y");
                 if (FortiOs.REFUSED.test(answer)) throw new Error(`${set}: ${line}\n    device said: ${answer.trim().slice(0, 300)}`);
@@ -433,8 +437,8 @@ export class FortiOs extends Platform {
         }
     }
 
-    /** Refuse a device on a release this adapter was not proved on, before anything is read or sent. */
-    private static async checkVersion(cli: FortiOsCli, device: Device): Promise<void> {
+    /** Refuse a device on a release this adapter was not proved on, before anything is read or sent. Gives what `get system status` printed. */
+    private static async checkVersion(cli: FortiOsCli, device: Device): Promise<string> {
         const status = await cli.run("get system status");
         const version = /^Version: \S+ v(\d+)\.(\d+)\.(\d+)/m.exec(status);
 
@@ -444,6 +448,21 @@ export class FortiOs extends Platform {
                 `${device.name} runs FortiOS ${version[1]}.${version[2]}.${version[3]}; this adapter renders for FortiOS ${FortiOs.SUPPORTED}`
             );
         }
+
+        return status;
+    }
+
+    /** Run `work` among the device's own settings: inside `config global` on a device with VDOMs, as it is on one without. */
+    private static async inGlobal<T>(cli: FortiOsCli, device: Device | boolean, work: () => Promise<T>): Promise<T> {
+        const multi = typeof device === "boolean" ? device : Boolean(device.vdoms);
+        if (!multi) return work();
+
+        await cli.run("config global");
+        try {
+            return await work();
+        } finally {
+            await FortiOs.leave(cli);
+        }
     }
 
     /** Secrets the device prints: a password or an SNMPv3 key as a cipher, a certificate's key encrypted, and the SNMP community in clear. None leave the read. */
@@ -470,13 +489,15 @@ export class FortiOs extends Platform {
 
     /** Every section Circuit manages, as the device holds it, credentials scrubbed. */
     private static async readConfig(cli: FortiOsCli, device: Device): Promise<string> {
-        await FortiOs.checkVersion(cli, device);
-
+        const status = await FortiOs.checkVersion(cli, device);
+        const show = (section: string) =>
+            cli.run(`${FortiOsRender.FULL.includes(section) ? "show full-configuration" : "show"} ${section}`, 120_000);
         const parts: string[] = [];
 
-        for (const section of FortiOsRender.SECTIONS) {
-            const show = FortiOsRender.FULL.includes(section) ? "show full-configuration" : "show";
-            parts.push(await cli.run(`${show} ${section}`, 120_000));
+        if (/^Virtual domain configuration: (multiple|split-task)/m.test(status)) {
+            parts.push(...(await FortiOs.readVdoms(cli, device, show)));
+        } else {
+            for (const section of FortiOsRender.SECTIONS) parts.push(await show(section));
         }
 
         const text = parts.join("\n");
@@ -485,16 +506,51 @@ export class FortiOs extends Platform {
         return FortiOs.scrub(FortiOsPlan.clean(text));
     }
 
+    /**
+     * A device in multi-VDOM mode, read where each section lives: the device's own under `config global`, the rest in `root`, and a management VDOM's sections named as the render names them. A VDOM that does not exist yet is not entered, since `edit` would make it.
+     */
+    private static async readVdoms(cli: FortiOsCli, device: Device, show: (section: string) => Promise<string>): Promise<string[]> {
+        const management = FortiOsVdoms.managementOf(device);
+        if (!management) throw new Error(`${device.name} runs several VDOMs and its config has no vdoms; write vdoms.management`);
+
+        const parts: string[] = [];
+        const inVdom = async (vdom: string, sections: readonly string[]) => {
+            await cli.run("config vdom");
+            await cli.run(`edit ${vdom}`);
+            try {
+                for (const section of sections) {
+                    const text = await show(section);
+                    parts.push(vdom === FortiOsVdoms.ROOT ? text : FortiOsVdoms.named(vdom, text));
+                }
+            } finally {
+                await FortiOs.leave(cli);
+            }
+        };
+
+        const listed = await FortiOs.inGlobal(cli, true, async () => {
+            for (const section of FortiOsRender.SECTIONS.filter((one) => FortiOsVdoms.GLOBAL.has(one))) parts.push(await show(section));
+            return FortiOsVdoms.listed(await cli.run("diagnose sys vd list"));
+        });
+
+        await inVdom(
+            FortiOsVdoms.ROOT,
+            FortiOsRender.SECTIONS.filter((one) => !FortiOsVdoms.GLOBAL.has(one))
+        );
+        if (listed.includes(management)) await inVdom(management, FortiOsVdoms.MANAGEMENT_SECTIONS);
+
+        return parts;
+    }
+
     /** Leave every `config` and `edit` level, back to the top prompt. */
     private static async leave(cli: FortiOsCli): Promise<void> {
         for (let level = 0; level < 10 && /\(.*\) [#$] $/.test(cli.prompt); level++) await cli.run("end");
     }
 
     /** Send the lines that set how the device saves changes. */
-    private static async saving(cli: FortiOsCli, mode: "revert" | "automatic", seconds?: number): Promise<void> {
+    private static async saving(cli: FortiOsCli, mode: "revert" | "automatic", multi: boolean, seconds?: number): Promise<void> {
         const lines = ["config system global", `set cfg-save ${mode}`, ...(seconds ? [`set cfg-revert-timeout ${seconds}`] : []), "end"];
 
-        for (const line of lines) {
+        for (const line of multi ? FortiOsVdoms.wrap({ kind: "global" }, lines) : lines) {
             const answer = await cli.run(line);
             if (FortiOs.REFUSED.test(answer)) throw new Error(`the device refused ${line}: ${answer.trim().slice(0, 300)}`);
         }
@@ -503,14 +559,14 @@ export class FortiOs extends Platform {
     /**
      * Send a plan line by line, each applied as it arrives. The device is first set to revert what is not saved, so a refused line or a fresh login that fails reloads its saved configuration. Once access is proved the change is saved, and changes save themselves again.
      */
-    private static async configure(cli: FortiOsCli, plan: Plan, guard: Guard): Promise<void> {
+    private static async configure(cli: FortiOsCli, plan: Plan, guard: Guard, multi: boolean): Promise<void> {
         const minutes = guard.seconds / 60;
-        await FortiOs.saving(cli, "revert", guard.seconds);
+        await FortiOs.saving(cli, "revert", multi, guard.seconds);
 
         // The session still open reloads the saved configuration at once; if it cannot, the device does when the time runs out.
         const restore = async (reason: string) => {
             await FortiOs.leave(cli).catch(() => undefined);
-            await cli.run("execute cfg reload").catch(() => undefined);
+            await FortiOs.inGlobal(cli, multi, () => cli.run("execute cfg reload")).catch(() => undefined);
             return new Reloaded(
                 `${reason}\n    the device reloads its saved configuration, which undoes what was sent, at the latest in ${minutes} minutes`
             );
@@ -545,14 +601,14 @@ export class FortiOs extends Platform {
             throw await restore(`a fresh login failed: ${(error as Error).message}`);
         }
 
-        const saved = await cli.run("execute cfg save", 120_000);
+        const saved = await FortiOs.inGlobal(cli, multi, () => cli.run("execute cfg save", 120_000));
         if (!/config saved|no config to be saved/.test(saved)) {
             throw new Error(
                 `access was proved but the save failed; the device reverts in ${minutes} minutes:\n    ${saved.trim().slice(0, 300)}`
             );
         }
 
-        await FortiOs.saving(cli, "automatic");
+        await FortiOs.saving(cli, "automatic", multi);
         console.log("  logged in again, saved");
     }
 
@@ -566,8 +622,9 @@ export class FortiOs extends Platform {
             const settled = await FortiOs.withCli(
                 device,
                 async (cli) => {
-                    if (!/no config to be reloaded/.test(await cli.run("execute cfg reload"))) return false;
-                    await FortiOs.saving(cli, "automatic");
+                    const reloaded = await FortiOs.inGlobal(cli, device, () => cli.run("execute cfg reload"));
+                    if (!/no config to be reloaded/.test(reloaded)) return false;
+                    await FortiOs.saving(cli, "automatic", Boolean(device.vdoms));
                     return true;
                 },
                 options
@@ -575,7 +632,7 @@ export class FortiOs extends Platform {
             if (settled) return "the device is back and saves changes on its own again";
         }
 
-        return "the device did not come back in time and still reverts every change; set `cfg-save automatic` under `config system global`";
+        return "the device did not come back in time and still reverts every change; set `cfg-save automatic` under `config system global` (in `config global` on a device with VDOMs)";
     }
 
     private static async applyOnce(device: Device, plan: Plan, options: ApplyOptions): Promise<void> {
@@ -586,7 +643,7 @@ export class FortiOs extends Platform {
             if (options.console) {
                 await FortiOs.consoleSession(device, async (cli, relogin) => {
                     await FortiOs.checkVersion(cli, device);
-                    await FortiOs.configure(cli, plan, { seconds, prove: relogin });
+                    await FortiOs.configure(cli, plan, { seconds, prove: relogin }, Boolean(device.vdoms));
                 });
                 return;
             }
@@ -594,13 +651,18 @@ export class FortiOs extends Platform {
             await FortiOs.withCli(device, async (cli) => {
                 await FortiOs.checkVersion(cli, device);
 
-                await FortiOs.configure(cli, plan, {
-                    seconds,
-                    prove: async () => {
-                        const proof = await FortiOs.login(device);
-                        proof.end();
+                await FortiOs.configure(
+                    cli,
+                    plan,
+                    {
+                        seconds,
+                        prove: async () => {
+                            const proof = await FortiOs.login(device);
+                            proof.end();
+                        },
                     },
-                });
+                    Boolean(device.vdoms)
+                );
             });
         } catch (error) {
             if (!(error instanceof Reloaded)) throw error;

package/src/platforms/fortios/render.ts

@@ -8,6 +8,7 @@ import { FortiOsFirewall } from "./firewall";
 import { FortiOsNames } from "./names";
 import { FortiOsRouting } from "./routing";
 import { FortiOsBlock, FortiOsTree } from "./tree";
+import { FortiOsVdoms } from "./vdoms";
 
 export type Section = (typeof FortiOsRender.SECTIONS)[number];
 
@@ -292,10 +293,28 @@ export class FortiOsRender {
         FortiOsRouting.render(root, device);
         FortiOsRender.helpers(section("system session-helper"), device);
         FortiOsFirewall.render(root, device);
+        FortiOsRender.managementVdom(root, device);
 
         return FortiOsTree.print(root);
     }
 
+    /** A management VDOM's routes, and who reaches the device's own services through it, as sections of their own after everything else. */
+    private static managementVdom(root: FortiOsBlock, device: Device): void {
+        const management = device.vdoms?.management;
+        if (!management) return;
+
+        const vdom = new FortiOsBlock();
+        for (const section of FortiOsVdoms.MANAGEMENT_SECTIONS) vdom.block(section);
+
+        FortiOsRender.staticRoutes(vdom.block("router static"), vdom.block("router static6"), {
+            ...device,
+            routing: { static: management.static ?? [] },
+        });
+        FortiOsFirewall.managementOnly(vdom, device);
+
+        for (const [section, block] of vdom.blocks) root.blocks.set(FortiOsVdoms.key(management.name, section), block);
+    }
+
     /** A certificate with its key is the device's own; one without is only trusted. */
     private static certificates(local: FortiOsBlock, trusted: FortiOsBlock, device: Device): void {
         for (const [name, certificate] of Object.entries(device.certificates ?? {})) {
@@ -330,6 +349,9 @@ export class FortiOsRender {
         if (device.system?.banner) block.set("pre-login-banner", "enable");
 
         if (device.lldp === true) block.set("lldp-transmission", "enable").set("lldp-reception", "enable");
+
+        const vdom = FortiOsVdoms.managementOf(device);
+        if (vdom) block.set("vdom-mode", "multi-vdom").set("management-vdom", FortiOsTree.quote(vdom));
     }
 
     /** Each user, with the profile its role takes. */
@@ -365,7 +387,7 @@ export class FortiOsRender {
             const settings = device.ports?.[port as keyof typeof device.ports];
             const entry = block.entry(Catalog.spell(device.platform, device.model, port));
 
-            entry.set("vdom", FortiOsTree.quote("root"));
+            entry.set("vdom", FortiOsTree.quote(FortiOsVdoms.vdomOf(device, port)));
             entry.set("type", "physical");
 
             if (!settings) {
@@ -395,7 +417,7 @@ export class FortiOsRender {
                 .map(([port]) => Catalog.spell(device.platform, device.model, port));
 
             const entry = block.entry(name);
-            entry.set("vdom", FortiOsTree.quote("root"));
+            entry.set("vdom", FortiOsTree.quote(FortiOsVdoms.vdomOf(device, name)));
             entry.set("type", "aggregate");
             if (members.length) entry.set("member", FortiOsTree.quoteAll(members));
             if (iface.mode === "static") entry.set("lacp-mode", "static");
@@ -410,7 +432,7 @@ export class FortiOsRender {
 
             const parent = FortiOsRender.vlanParent(device, iface.vlan);
             const entry = block.entry(name);
-            entry.set("vdom", FortiOsTree.quote("root"));
+            entry.set("vdom", FortiOsTree.quote(FortiOsVdoms.vdomOf(device, name)));
             if (parent) entry.set("interface", FortiOsTree.quote(FortiOsNames.nameOf(device, parent)));
             entry.set("vlanid", device.vlans?.[iface.vlan]?.id ?? 0);
             const domain = FortiOsNames.forwardDomainOf(device, name);
@@ -425,7 +447,7 @@ export class FortiOsRender {
             if (iface.type !== "loopback") continue;
 
             const entry = block.entry(name);
-            entry.set("vdom", FortiOsTree.quote("root"));
+            entry.set("vdom", FortiOsTree.quote(FortiOsVdoms.vdomOf(device, name)));
             entry.set("type", "loopback");
             if (iface.description) entry.set("description", FortiOsTree.quote(iface.description));
             FortiOsRender.redirects(entry, device);
@@ -454,7 +476,7 @@ export class FortiOsRender {
             }
 
             const entry = block.entry(name);
-            entry.set("vdom", FortiOsTree.quote("root"));
+            entry.set("vdom", FortiOsTree.quote(FortiOsVdoms.vdomOf(device, name)));
             entry.set("type", iface.type === "gre" ? "tunnel" : "vxlan");
             entry.set("interface", via);
             if (iface.type === "vxlan" && iface.mac) entry.set("macaddr", iface.mac.toLowerCase());