@takodotid/circuit 0.26.2 → 0.27.0

package/dist/cli/index.js

@@ -110,6 +110,11 @@ var MARKER = /<secret:([A-Za-z0-9_./:-]+)>/g;
 var substitute = (text) => text.replace(MARKER, (_, reference) => valueOf(reference));
 var valueOfReference = valueOf;
 
+// src/transport/console.ts
+import { spawn } from "node:child_process";
+import { Duplex } from "node:stream";
+import { Client as Client2 } from "ssh2";
+
 // src/transport/ssh.ts
 import { Client } from "ssh2";
 function connect(login) {
@@ -202,6 +207,107 @@ function upload(client, path, content) {
   });
 }
 
+// src/transport/console.ts
+var RELAY = `import fcntl, os, select, sys, termios
+
+port, baud = sys.argv[1], int(sys.argv[2])
+fd = os.open(port, os.O_RDWR | os.O_NOCTTY | os.O_NONBLOCK)
+
+try:
+    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+except OSError:
+    sys.stderr.write("busy: another session holds " + port + "\\n")
+    sys.exit(3)
+
+attrs = termios.tcgetattr(fd)
+attrs[0] = attrs[1] = attrs[3] = 0
+attrs[2] = termios.CS8 | termios.CREAD | termios.CLOCAL
+attrs[4] = attrs[5] = getattr(termios, "B%d" % baud)
+termios.tcsetattr(fd, termios.TCSANOW, attrs)
+termios.tcflush(fd, termios.TCIOFLUSH)
+
+sys.stderr.write("ready\\n")
+sys.stderr.flush()
+
+while True:
+    ready, _, _ = select.select([0, fd], [], [])
+
+    if 0 in ready:
+        data = os.read(0, 4096)
+        if not data:
+            break
+        while data:
+            try:
+                data = data[os.write(fd, data):]
+            except BlockingIOError:
+                select.select([], [fd], [])
+
+    if fd in ready:
+        try:
+            data = os.read(fd, 4096)
+        except BlockingIOError:
+            continue
+        if data:
+            os.write(1, data)
+`;
+var RELAY_PATH = "/tmp/circuit-console.py";
+var PORT = /^\/dev\/[\w./:+-]+$/;
+function connectJump(jump) {
+  return new Promise((done, fail) => {
+    const client = new Client2;
+    const login = { username: jump.user, password: resolve(jump.password), readyTimeout: 60000 };
+    client.on("ready", () => done(client)).on("error", fail);
+    if (!jump.cloudflared) {
+      client.connect({ ...login, host: jump.host, port: jump.port ?? 22 });
+      return;
+    }
+    const tunnel = spawn("cloudflared", ["access", "ssh", "--hostname", jump.host], { stdio: ["pipe", "pipe", "ignore"] });
+    tunnel.on("error", (error) => fail(new Error(`cloudflared did not start: ${error.message}`)));
+    client.on("close", () => tunnel.kill());
+    client.connect({ ...login, sock: Duplex.from({ readable: tunnel.stdout, writable: tunnel.stdin }) });
+  });
+}
+async function openConsole(console2) {
+  if (!PORT.test(console2.port))
+    throw new Error(`console port ${console2.port} is not a path under /dev`);
+  if (!Number.isInteger(console2.baud) || console2.baud <= 0)
+    throw new Error(`console baud ${console2.baud} is not a line speed`);
+  const client = await connectJump(console2.jump);
+  try {
+    const encoded = Buffer.from(RELAY).toString("base64");
+    await exec(client, `sh -c 'printf %s ${encoded} | base64 -d > ${RELAY_PATH}'`, 30000);
+    const channel = await new Promise((done, fail) => {
+      client.exec(`python3 ${RELAY_PATH} ${console2.port} ${console2.baud}`, (error, stream) => error ? fail(error) : done(stream));
+    });
+    await new Promise((done, fail) => {
+      let said = "";
+      const limit = setTimeout(() => fail(new Error(`the console relay did not start: ${said.trim()}`)), 30000);
+      channel.stderr.on("data", (chunk) => {
+        said += chunk.toString("utf8");
+        if (said.includes(`ready
+`)) {
+          clearTimeout(limit);
+          done();
+        }
+      });
+      channel.on("close", () => {
+        clearTimeout(limit);
+        fail(new Error(`the console relay stopped: ${said.trim() || "no reason given"}`));
+      });
+    });
+    return {
+      channel,
+      close: () => {
+        channel.end();
+        client.end();
+      }
+    };
+  } catch (error) {
+    client.end();
+    throw error;
+  }
+}
+
 // src/adapters/devices/fortios/names.ts
 function nameOf(device, name) {
   if (device.interfaces && name in device.interfaces)
@@ -1134,7 +1240,9 @@ var TABLES = {
   "firewall policy6": ORDERED,
   "firewall local-in-policy": ORDERED,
   "firewall local-in-policy6": ORDERED,
-  "firewall central-snat-map": ORDERED
+  "firewall central-snat-map": ORDERED,
+  "router static": { distinct: true },
+  "router static6": { distinct: true }
 };
 var IGNORED = new Set(["uuid", "snmp-index"]);
 var IGNORED_IN = { "system global": ["cfg-save", "cfg-revert-timeout", "alias"] };
@@ -1271,7 +1379,7 @@ function compare(path, want, have, table, top, context) {
   }
   for (const [header, child] of want.blocks)
     nested(header, child, have.blocks.get(header) ?? new Block);
-  const entries = table?.byContent ? byContent(path, want, have) : byId(path, want, have, table, context);
+  const entries = table?.byContent ? byContent(path, want, have) : table?.distinct ? distinctById(path, want, have, table, context) : byId(path, want, have, table, context);
   send.push(...entries.send);
   show.push(...entries.show);
   if (top) {
@@ -1320,6 +1428,30 @@ function byId(path, want, have, table, context) {
   }
   return { send, show, removals, removed };
 }
+function distinctById(path, want, have, table, context) {
+  const deletes = [];
+  const creates = [];
+  const show = [];
+  for (const [key, entry] of want.entries) {
+    const old = have.entries.get(key);
+    const where = [...path, bare(entry.id)];
+    if (old) {
+      if (!compare(where, entry.block, old.block, undefined, false, context).send.length)
+        continue;
+      deletes.push(`delete ${old.id}`);
+      show.push(...shown("-", where, old.block));
+    }
+    creates.push(...creation(entry, table));
+    show.push(...shown("+", where, entry.block));
+  }
+  for (const [key, entry] of have.entries) {
+    if (want.entries.has(key) || isFactory(table, entry))
+      continue;
+    deletes.push(`delete ${entry.id}`);
+    show.push(...shown("-", [...path, bare(entry.id)], entry.block));
+  }
+  return { send: [...deletes, ...creates], show, removals: [], removed: [] };
+}
 function moves(want, have) {
   const wanted = [...want.entries.keys()];
   const order = [...have.entries.keys()].filter((key) => want.entries.has(key));
@@ -2356,7 +2488,93 @@ async function login(device) {
     password: resolve(user.password)
   });
 }
-async function session(device, work) {
+var CONSOLE_STATES = [
+  ["login", /login: $/],
+  ["password", /Password: $/],
+  ["banner", BANNER2],
+  ["pager", /--More-- $/],
+  ["context", /\([^)\n]*\) [#$] $/],
+  ["prompt", /[#$] $/]
+];
+function prompted(channel, write, timeout = 30000) {
+  return new Promise((done, fail) => {
+    let text = "";
+    const stop = () => {
+      clearTimeout(limit);
+      channel.removeListener("data", onData);
+    };
+    const onData = (chunk) => {
+      text += chunk.toString("utf8").replace(/\r/g, "");
+      const state = CONSOLE_STATES.find(([, pattern]) => pattern.test(text));
+      if (!state)
+        return;
+      stop();
+      done(state[0]);
+    };
+    const limit = setTimeout(() => {
+      stop();
+      fail(new Error(`the console did not answer: ${text.slice(-200)}`));
+    }, timeout);
+    channel.on("data", onData);
+    channel.write(write);
+  });
+}
+async function consoleLogin(channel, user, password) {
+  const toward = {
+    password: "\r",
+    banner: "a",
+    pager: "q",
+    context: "end\r",
+    prompt: "exit\r"
+  };
+  let state = await prompted(channel, "\r");
+  for (let step = 0;state !== "login"; step++) {
+    if (step >= 10)
+      throw new Error(`the console never reached a login prompt; it is at ${state}`);
+    state = await prompted(channel, toward[state]);
+  }
+  if (await prompted(channel, `${user}\r`) !== "password")
+    throw new Error("the console did not ask for a password");
+  const answer = await prompted(channel, `${password}\r`, 60000);
+  if (answer !== "prompt")
+    throw new Error(`the console refused the login of ${user}`);
+  return new Cli(channel, "\r");
+}
+async function consoleLogout(cli) {
+  await leave(cli).catch(() => {
+    return;
+  });
+  await cli.run("exit", 1e4).catch(() => {
+    return;
+  });
+}
+function consoleOf(device) {
+  const console2 = device.connection.console;
+  if (!console2)
+    throw new Error(`${device.name}: no connection.console`);
+  const user = device.users?.[device.connection.user];
+  if (!user)
+    throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
+  return { console: console2, user: device.connection.user, password: resolve(user.password) };
+}
+async function consoleSession(device, work) {
+  const { console: console2, user, password } = consoleOf(device);
+  const opened = await openConsole(console2);
+  try {
+    const cli = await consoleLogin(opened.channel, user, password);
+    const relogin = async () => {
+      await consoleLogin(opened.channel, user, password);
+    };
+    const result = await work(cli, relogin);
+    await consoleLogout(cli);
+    return result;
+  } finally {
+    opened.close();
+  }
+}
+async function session(device, work, options = {}) {
+  if (options.console)
+    return consoleSession(device, (cli) => work(cli));
   const client = await login(device);
   try {
     const channel = await shell(client, 4000);
@@ -2412,8 +2630,8 @@ async function readConfig(cli, device) {
     throw new Error(`${device.name} returned no configuration`);
   return scrub(clean(text));
 }
-function read(device) {
-  return session(device, (cli) => readConfig(cli, device));
+function read(device, _network = [], options = {}) {
+  return session(device, (cli) => readConfig(cli, device), options);
 }
 function withSecrets(line) {
   const key = line.startsWith("set private-key ");
@@ -2490,7 +2708,7 @@ async function configure(cli, plan, guard) {
 class Reloaded extends Error {
 }
 var RELOAD = { attempts: 20, interval: 15000 };
-async function settle(device) {
+async function settle(device, options) {
   for (let attempt = 0;attempt < RELOAD.attempts; attempt++) {
     await new Promise((done) => setTimeout(done, RELOAD.interval));
     const settled = await session(device, async (cli) => {
@@ -2498,18 +2716,26 @@ async function settle(device) {
         return false;
       await saving(cli, "automatic");
       return true;
-    }).catch(() => false);
+    }, options).catch(() => false);
     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`";
 }
 async function apply(device, _network, plan, options) {
+  const seconds = options.rollback * 60;
   try {
+    if (options.console) {
+      await consoleSession(device, async (cli, relogin) => {
+        await checkVersion(cli, device);
+        await configure(cli, plan, { seconds, prove: relogin });
+      });
+      return;
+    }
     await session(device, async (cli) => {
       await checkVersion(cli, device);
       await configure(cli, plan, {
-        seconds: options.rollback * 60,
+        seconds,
         prove: async () => {
           const proof = await login(device);
           proof.end();
@@ -2520,7 +2746,7 @@ async function apply(device, _network, plan, options) {
     if (!(error instanceof Reloaded))
       throw error;
     throw new Error(`${error.message}
-    ${await settle(device)}`);
+    ${await settle(device, options)}`);
   }
 }
 function fillLines(set, family, prefixes) {
@@ -2920,6 +3146,7 @@ function serviceGaps(device) {
 }
 var fortios = {
   extension: ".conf",
+  console: true,
   unsupported,
   render,
   read,
@@ -8661,6 +8888,7 @@ var HELP = `usage: circuit <command> [device...] [options]
   apply <device>        read the device, plan against what it runs, and send with --confirm
                           --secrets      also send every secret, to rotate one
                           --rollback=N   minutes before a device that can restore itself does, default 10
+                          --console      through the device's serial console on its jump host, instead of SSH; also for snapshot
   refresh <device>      fetch prefix sets that come from a registry onto the device, with --confirm
   wireguard <device> <interface> <peer>
                         a client config for one peer, its private key left for the peer to fill
@@ -8721,7 +8949,8 @@ var names = rest.filter((arg) => !arg.startsWith("--"));
 var confirmed = flags.includes("--confirm");
 var options = {
   secrets: flags.includes("--secrets"),
-  rollback: Number(flags.find((flag) => flag.startsWith("--rollback="))?.split("=")[1] ?? 10)
+  rollback: Number(flags.find((flag) => flag.startsWith("--rollback="))?.split("=")[1] ?? 10),
+  ...flags.includes("--console") ? { console: true } : {}
 };
 function fail(message) {
   console.error(message);
@@ -8738,7 +8967,16 @@ function one() {
   const [device] = selected(false);
   return device ?? fail("name a device");
 }
-var adapterOf = (device) => adapters[device.platform] ?? fail(`no adapter for ${device.platform}`);
+function adapterOf(device) {
+  const adapter = adapters[device.platform] ?? fail(`no adapter for ${device.platform}`);
+  if (!options.console)
+    return adapter;
+  if (!adapter.console)
+    fail(`${device.name}: ${device.platform} cannot be reached through a console yet`);
+  if (!device.connection.console)
+    fail(`${device.name}: --console needs connection.console`);
+  return adapter;
+}
 var generated = join4(root2, ".circuit");
 var stateDirectory = join4(generated, "state");
 var statePath = (device) => join4(stateDirectory, device.name + adapterOf(device).extension);
@@ -8805,7 +9043,7 @@ function diffCommand() {
 }
 async function snapshotCommand() {
   for (const device of selected(true)) {
-    const text = await adapterOf(device).read(device, network3.devices);
+    const text = await adapterOf(device).read(device, network3.devices, options);
     writeState(device, text);
     console.log(`${device.name}: ${text.split(`
 `).length} lines`);
@@ -8824,7 +9062,7 @@ async function applyCommand() {
   const device = one();
   guard([device]);
   const adapter = adapterOf(device);
-  const live = await adapter.read(device, network3.devices);
+  const live = await adapter.read(device, network3.devices, options);
   writeState(device, live);
   const plan = adapter.plan(adapter.render(device), live, options);
   if (!show(device, plan))
@@ -8838,7 +9076,7 @@ Nothing sent. Re-run with --confirm.`);
     return;
   }
   await adapter.apply(device, network3.devices, plan, options);
-  writeState(device, await adapter.read(device, network3.devices));
+  writeState(device, await adapter.read(device, network3.devices, options));
   console.log("snapshot updated");
 }
 async function refreshCommand() {

package/dist/types/adapters/devices/fortios/index.d.ts

@@ -1,6 +1,6 @@
 import type { Client } from "ssh2";
 import type { Device, Family } from "../../../schema";
-import type { ApplyOptions, DeviceAdapter, Plan } from "../types";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 /** What a session reads and writes: an SSH shell, or anything else that streams the CLI. */
 export type Channel = {
     write(data: string): unknown;
@@ -26,13 +26,17 @@ export declare class Cli {
     private collect;
 }
 export declare function login(device: Device): Promise<Client>;
+/**
+ * Log in on a serial console, whatever state the last session left it in: a pager is quit, a `config` level left, a session someone left open logged out, so every session starts from a fresh login. The CLI ends a line at a carriage return.
+ */
+export declare function consoleLogin(channel: Channel, user: string, password: string): Promise<Cli>;
 /** Refuse a device on a release this adapter was not proved on, before anything is read or sent. */
 export declare function checkVersion(cli: Cli, device: Device): Promise<void>;
 /** 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. */
 export declare function scrub(text: string): string;
 /** Every section Circuit manages, as the device holds it, credentials scrubbed. */
 export declare function readConfig(cli: Cli, device: Device): Promise<string>;
-export declare function read(device: Device): Promise<string>;
+export declare function read(device: Device, _network?: readonly Device[], options?: ReadOptions): Promise<string>;
 /**
  * A line with each secret's value in place, escaped inside its quotes. A certificate's key from a variable is PEM encoded as one line of base64, and is sent as the PEM it holds. A file saved with Windows line endings is sent with plain ones: the CLI takes each carriage return as a line of its own, and refuses the key, `Invalid private key`. A `?`, which the CLI takes as a call for help, is typed literally.
  */

package/dist/types/adapters/devices/fortios/plan.d.ts

@@ -12,6 +12,8 @@ type Table = {
     created?: (entry: Block) => readonly string[];
     /** Settings an entry keeps for life. A change deletes the entry and creates it again. */
     fixed?: readonly string[];
+    /** The device refuses an entry that holds the same as another, `Duplicated entry`, even for a moment while entries are renumbered. */
+    distinct?: true;
 };
 /** Tables whose entries need more than a plain comparison, by section. */
 export declare const TABLES: Record<string, Table>;

package/dist/types/adapters/devices/types.d.ts

@@ -15,16 +15,22 @@ export type ApplyOptions = {
     secrets: boolean;
     /** Minutes before a platform that can restore itself does so, if the run does not prove access survived. */
     rollback: number;
+    /** Reach the device through its serial console, `connection.console`, instead of SSH to its management address. */
+    console?: boolean;
 };
+/** How a device is read. */
+export type ReadOptions = Pick<ApplyOptions, "console">;
 export type DeviceAdapter = {
     /** File extension of a saved snapshot, for syntax highlighting. */
     extension: string;
     /** Fields this platform cannot express. Validation fails on any of them, so nothing is skipped silently. */
     unsupported(device: Device): string[];
+    /** The platform can be read and applied through a serial console, `--console`. */
+    console?: true;
     /** The whole configuration the device should run. Secrets appear as markers, never values. */
     render(device: Device): string;
     /** What the device runs now, secrets removed, in the form `render` produces where the platform allows. */
-    read(device: Device, network: readonly Device[]): Promise<string>;
+    read(device: Device, network: readonly Device[], options?: ReadOptions): Promise<string>;
     /** What it takes to go from `current` to `desired`. */
     plan(desired: string, current: string, options: ApplyOptions): Plan;
     /** Replace the contents of a prefix set fetched from a registry. Absent on a platform that cannot hold one. */

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

@@ -1,4 +1,4 @@
-import type { IP } from "./common";
+import type { IP, Secret } from "./common";
 import type { AclRule, Firewall } from "./firewall";
 import type { Interface, Port, Vlan } from "./interfaces";
 import type { PrefixSet, RoutePolicy } from "./policy";
@@ -12,6 +12,30 @@ export type Connection<U extends string> = {
     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;
+};
+/** 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, reached through a jump host. */
+export type Console = {
+    /** The jump host the console cable is plugged into. */
+    jump: Jump;
+    /** The serial port on the jump host. A path under `/dev/serial/by-path/` stays the same when two adapters swap names. */
+    port: string;
+    /** Line speed in bits per second, such as 9600 or 115200. */
+    baud: number;
 };
 /** A separate routing table, with the interfaces that route in it. */
 export type Vrf = {

package/dist/types/transport/console.d.ts

@@ -0,0 +1,9 @@
+import { type ClientChannel } from "ssh2";
+import type { Console } from "../schema";
+/** An open console: the stream to the device's CLI, and how to let it go. */
+export type ConsoleSession = {
+    channel: ClientChannel;
+    close: () => void;
+};
+/** Open a device's serial console through its jump host. Fails when another session holds the port. */
+export declare function openConsole(console: Console): Promise<ConsoleSession>;

package/package.json

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

package/src/adapters/devices/fortios/TRAPS.md

@@ -19,7 +19,7 @@ Behaviour that looks like something else. Each one has been hit on a FortiGate 3
 - Global `alias` is set again at every start, whatever was saved.
 - `log memory setting` prints its `status` whether on or off, and `unset status` turns memory logging on.
 - Two interfaces that are up cannot have overlapping subnets, `Subnets overlap between ...`, so an address moving from one to another must leave the first before it joins the second.
-- A static route identical to another is refused, `Duplicated entry`. An IPv4 route's destination is not printed when it is the default route; neither is IPv6's.
+- A static route identical to another is refused, `Duplicated entry`, even for a moment: editing route 1 into what route 2 holds fails before route 2 is changed. A plan deletes every route that changes or goes before it creates any. An IPv4 route's destination is not printed when it is the default route; neither is IPv6's.
 - A deny policy is given `logtraffic disable`, and its action is not printed, since deny is the default. `send-deny-packet` exists only while a policy denies: set before `action deny` or unset after `action accept`, it is `command parse error`. So the render writes `action deny` before `send-deny-packet`, and a plan removes the settings that go before it sets the ones that come: `send-deny-packet` is unset while the policy still denies, and set only once it does.
 - `show` prints `unset` in two places: an ICMP service's `unset icmptype`, and a prefix list rule's `unset ge` and `unset le` for a bound it does not have.
 - An SNMPv3 user authenticates with MD5 or SHA1 only, and has no list of sources: only a community has hosts. Circuit decides who reaches every service with local-in policies instead.
@@ -38,3 +38,4 @@ Behaviour that looks like something else. Each one has been hit on a FortiGate 3
 - There is no WireGuard and no RPKI, `command parse error`. A route map has no large community and a BGP neighbor no role: neither is among their settings. SNMPv3 offers no SHA256.
 - `execute backup config flash <comment>` keeps a revision on the device, and `execute restore config flash <id>` restores one.
 - The ports are `port1` to `port4` at 40G and `port5` to `port32` at 10G, then `mgmt1` and `mgmt2`. The factory dedicates both management ports to management and gives them addresses `192.168.1.99` and `192.168.2.99`.
+- On the serial console a line ends at a carriage return. A session left open stays logged in, and one left inside `config` stays there, so the next login must first leave and log out. The console takes 9600 bits per second: reading the sections Circuit manages takes about two minutes.

package/src/adapters/devices/fortios/index.ts

@@ -6,9 +6,10 @@ import type { Client } from "ssh2";
 import { familyOf, host, split } from "../../../core/addr";
 import { MARKER, resolve, valueOfReference } from "../../../core/secrets";
 import type { AclRule, Device, Family, FilterRule } from "../../../schema";
+import { openConsole } from "../../../transport/console";
 import { connect, shell } from "../../../transport/ssh";
 import { portsOf, spell } from "../catalog";
-import type { ApplyOptions, DeviceAdapter, Plan } from "../types";
+import type { ApplyOptions, DeviceAdapter, Plan, ReadOptions } from "../types";
 import { acceptsBeforeDrop, familiesOf, isImplied, serviceOf } from "./firewall";
 import { holderOf, interfaceFor, network, settingsOf, subnet } from "./names";
 import { clean, plan } from "./plan";
@@ -147,8 +148,115 @@ export async function login(device: Device): Promise<Client> {
     });
 }
 
-/** Log in, open the CLI, and run `work` in it. */
-async function session<T>(device: Device, work: (cli: Cli) => Promise<T>): Promise<T> {
+/** What a console shows when it waits for something, in the order they are checked. */
+const CONSOLE_STATES = [
+    ["login", /login: $/],
+    ["password", /Password: $/],
+    ["banner", BANNER],
+    ["pager", /--More-- $/],
+    ["context", /\([^)\n]*\) [#$] $/],
+    ["prompt", /[#$] $/],
+] as const;
+
+type ConsoleState = (typeof CONSOLE_STATES)[number][0];
+
+/** Write to a console, then wait until it shows one of its states. */
+function prompted(channel: Channel, write: string, timeout = 30_000): Promise<ConsoleState> {
+    return new Promise((done, fail) => {
+        let text = "";
+
+        const stop = () => {
+            clearTimeout(limit);
+            channel.removeListener("data", onData);
+        };
+
+        const onData = (chunk: Buffer) => {
+            text += chunk.toString("utf8").replace(/\r/g, "");
+
+            const state = CONSOLE_STATES.find(([, pattern]) => pattern.test(text));
+            if (!state) return;
+
+            stop();
+            done(state[0]);
+        };
+
+        const limit = setTimeout(() => {
+            stop();
+            fail(new Error(`the console did not answer: ${text.slice(-200)}`));
+        }, timeout);
+
+        channel.on("data", onData);
+        channel.write(write);
+    });
+}
+
+/**
+ * Log in on a serial console, whatever state the last session left it in: a pager is quit, a `config` level left, a session someone left open logged out, so every session starts from a fresh login. The CLI ends a line at a carriage return.
+ */
+export async function consoleLogin(channel: Channel, user: string, password: string): Promise<Cli> {
+    // What to send in each state to get closer to a login prompt.
+    const toward: Record<Exclude<ConsoleState, "login">, string> = {
+        password: "\r",
+        banner: "a",
+        pager: "q",
+        context: "end\r",
+        prompt: "exit\r",
+    };
+
+    let state = await prompted(channel, "\r");
+    for (let step = 0; state !== "login"; step++) {
+        if (step >= 10) throw new Error(`the console never reached a login prompt; it is at ${state}`);
+        state = await prompted(channel, toward[state]);
+    }
+
+    if ((await prompted(channel, `${user}\r`)) !== "password") throw new Error("the console did not ask for a password");
+
+    const answer = await prompted(channel, `${password}\r`, 60_000);
+    if (answer !== "prompt") throw new Error(`the console refused the login of ${user}`);
+
+    return new Cli(channel, "\r");
+}
+
+/** Log out of a console, so no session is left open on it. */
+async function consoleLogout(cli: Cli): Promise<void> {
+    await leave(cli).catch(() => undefined);
+    await cli.run("exit", 10_000).catch(() => undefined);
+}
+
+/** The device's console and its login. */
+function consoleOf(device: Device) {
+    const console = device.connection.console;
+    if (!console) throw new Error(`${device.name}: no connection.console`);
+
+    const user = device.users?.[device.connection.user];
+    if (!user) throw new Error(`${device.name}: connection user ${device.connection.user} is not one of its users`);
+
+    return { console, user: device.connection.user as string, password: resolve(user.password) };
+}
+
+/** Log in on the console, open the CLI, and run `work` in it. `work` is also given a way to log in afresh on the same console. */
+async function consoleSession<T>(device: Device, work: (cli: Cli, relogin: () => Promise<void>) => Promise<T>): Promise<T> {
+    const { console, user, password } = consoleOf(device);
+    const opened = await openConsole(console);
+
+    try {
+        const cli = await consoleLogin(opened.channel, user, password);
+        const relogin = async () => {
+            await consoleLogin(opened.channel, user, password);
+        };
+
+        const result = await work(cli, relogin);
+        await consoleLogout(cli);
+        return result;
+    } finally {
+        opened.close();
+    }
+}
+
+/** Log in, open the CLI, and run `work` in it: through the console when asked, else over SSH. */
+async function session<T>(device: Device, work: (cli: Cli) => Promise<T>, options: ReadOptions = {}): Promise<T> {
+    if (options.console) return consoleSession(device, (cli) => work(cli));
+
     const client = await login(device);
 
     try {
@@ -216,8 +324,8 @@ export async function readConfig(cli: Cli, device: Device): Promise<string> {
     return scrub(clean(text));
 }
 
-export function read(device: Device): Promise<string> {
-    return session(device, (cli) => readConfig(cli, device));
+export function read(device: Device, _network: readonly Device[] = [], options: ReadOptions = {}): Promise<string> {
+    return session(device, (cli) => readConfig(cli, device), options);
 }
 
 /**
@@ -317,15 +425,19 @@ const RELOAD = { attempts: 20, interval: 15_000 } as const;
 /**
  * Once the device is back from a reload, set it to save changes on its own again: the saved configuration still says to revert. Setting it saves what runs, so it is set only once the device says nothing is left to reload; until then the reload is asked for again.
  */
-async function settle(device: Device): Promise<string> {
+async function settle(device: Device, options: ReadOptions): Promise<string> {
     for (let attempt = 0; attempt < RELOAD.attempts; attempt++) {
         await new Promise((done) => setTimeout(done, RELOAD.interval));
 
-        const settled = await session(device, async (cli) => {
-            if (!/no config to be reloaded/.test(await cli.run("execute cfg reload"))) return false;
-            await saving(cli, "automatic");
-            return true;
-        }).catch(() => false);
+        const settled = await session(
+            device,
+            async (cli) => {
+                if (!/no config to be reloaded/.test(await cli.run("execute cfg reload"))) return false;
+                await saving(cli, "automatic");
+                return true;
+            },
+            options
+        ).catch(() => false);
         if (settled) return "the device is back and saves changes on its own again";
     }
 
@@ -333,12 +445,23 @@ async function settle(device: Device): Promise<string> {
 }
 
 export async function apply(device: Device, _network: readonly Device[], plan: Plan, options: ApplyOptions): Promise<void> {
+    const seconds = options.rollback * 60;
+
     try {
+        // Through the console, a fresh login on the same console proves the change left the device's logins working; over SSH, a fresh SSH session proves the management path too.
+        if (options.console) {
+            await consoleSession(device, async (cli, relogin) => {
+                await checkVersion(cli, device);
+                await configure(cli, plan, { seconds, prove: relogin });
+            });
+            return;
+        }
+
         await session(device, async (cli) => {
             await checkVersion(cli, device);
 
             await configure(cli, plan, {
-                seconds: options.rollback * 60,
+                seconds,
                 prove: async () => {
                     const proof = await login(device);
                     proof.end();
@@ -347,7 +470,7 @@ export async function apply(device: Device, _network: readonly Device[], plan: P
         });
     } catch (error) {
         if (!(error instanceof Reloaded)) throw error;
-        throw new Error(`${error.message}\n    ${await settle(device)}`);
+        throw new Error(`${error.message}\n    ${await settle(device, options)}`);
     }
 }
 
@@ -791,6 +914,7 @@ function serviceGaps(device: Device): string[] {
 
 export const fortios: DeviceAdapter = {
     extension: ".conf",
+    console: true,
     unsupported,
     render,
     read,

package/src/adapters/devices/fortios/plan.ts

@@ -18,6 +18,8 @@ type Table = {
     created?: (entry: Block) => readonly string[];
     /** Settings an entry keeps for life. A change deletes the entry and creates it again. */
     fixed?: readonly string[];
+    /** The device refuses an entry that holds the same as another, `Duplicated entry`, even for a moment while entries are renumbered. */
+    distinct?: true;
 };
 
 /** Objects every FortiGate running 6.2 is shipped with, which policies and profiles of the factory name. */
@@ -168,6 +170,8 @@ export const TABLES: Record<string, Table> = {
     "firewall local-in-policy": ORDERED,
     "firewall local-in-policy6": ORDERED,
     "firewall central-snat-map": ORDERED,
+    "router static": { distinct: true },
+    "router static6": { distinct: true },
 };
 
 /** Settings the device keeps for itself: an object's UUID and an interface's SNMP index. */
@@ -346,7 +350,11 @@ function compare(path: string[], want: Block, have: Block, table: Table | undefi
 
     for (const [header, child] of want.blocks) nested(header, child, have.blocks.get(header) ?? new Block());
 
-    const entries = table?.byContent ? byContent(path, want, have) : byId(path, want, have, table, context);
+    const entries = table?.byContent
+        ? byContent(path, want, have)
+        : table?.distinct
+          ? distinctById(path, want, have, table, context)
+          : byId(path, want, have, table, context);
     send.push(...entries.send);
     show.push(...entries.show);
 
@@ -410,6 +418,37 @@ function byId(path: string[], want: Block, have: Block, table: Table | undefined
     return { send, show, removals, removed };
 }
 
+/** Entries matched by name in a table that refuses two alike: every entry that changes or goes is deleted before any is created, so none is ever briefly the same as another. */
+function distinctById(path: string[], want: Block, have: Block, table: Table, context: Context): Diff {
+    const deletes: string[] = [];
+    const creates: string[] = [];
+    const show: string[] = [];
+
+    for (const [key, entry] of want.entries) {
+        const old = have.entries.get(key);
+        const where = [...path, bare(entry.id)];
+
+        if (old) {
+            if (!compare(where, entry.block, old.block, undefined, false, context).send.length) continue;
+
+            deletes.push(`delete ${old.id}`);
+            show.push(...shown("-", where, old.block));
+        }
+
+        creates.push(...creation(entry, table));
+        show.push(...shown("+", where, entry.block));
+    }
+
+    for (const [key, entry] of have.entries) {
+        if (want.entries.has(key) || isFactory(table, entry)) continue;
+
+        deletes.push(`delete ${entry.id}`);
+        show.push(...shown("-", [...path, bare(entry.id)], entry.block));
+    }
+
+    return { send: [...deletes, ...creates], show, removals: [], removed: [] };
+}
+
 /** The `move` commands that put a table's entries in the render's order. Kept entries hold their place on the device and new ones are added at the end. */
 function moves(want: Block, have: Block): string[] {
     const wanted = [...want.entries.keys()];

package/src/adapters/devices/types.ts

@@ -11,17 +11,24 @@ export type ApplyOptions = {
     secrets: boolean;
     /** Minutes before a platform that can restore itself does so, if the run does not prove access survived. */
     rollback: number;
+    /** Reach the device through its serial console, `connection.console`, instead of SSH to its management address. */
+    console?: boolean;
 };
 
+/** How a device is read. */
+export type ReadOptions = Pick<ApplyOptions, "console">;
+
 export type DeviceAdapter = {
     /** File extension of a saved snapshot, for syntax highlighting. */
     extension: string;
     /** Fields this platform cannot express. Validation fails on any of them, so nothing is skipped silently. */
     unsupported(device: Device): string[];
+    /** The platform can be read and applied through a serial console, `--console`. */
+    console?: true;
     /** The whole configuration the device should run. Secrets appear as markers, never values. */
     render(device: Device): string;
     /** What the device runs now, secrets removed, in the form `render` produces where the platform allows. */
-    read(device: Device, network: readonly Device[]): Promise<string>;
+    read(device: Device, network: readonly Device[], options?: ReadOptions): Promise<string>;
     /** What it takes to go from `current` to `desired`. */
     plan(desired: string, current: string, options: ApplyOptions): Plan;
     /** Replace the contents of a prefix set fetched from a registry. Absent on a platform that cannot hold one. */

package/src/cli/index.ts

@@ -32,6 +32,7 @@ const HELP = `usage: circuit <command> [device...] [options]
   apply <device>        read the device, plan against what it runs, and send with --confirm
                           --secrets      also send every secret, to rotate one
                           --rollback=N   minutes before a device that can restore itself does, default 10
+                          --console      through the device's serial console on its jump host, instead of SSH; also for snapshot
   refresh <device>      fetch prefix sets that come from a registry onto the device, with --confirm
   wireguard <device> <interface> <peer>
                         a client config for one peer, its private key left for the peer to fill
@@ -109,6 +110,7 @@ const confirmed = flags.includes("--confirm");
 const options: ApplyOptions = {
     secrets: flags.includes("--secrets"),
     rollback: Number(flags.find((flag) => flag.startsWith("--rollback="))?.split("=")[1] ?? 10),
+    ...(flags.includes("--console") ? { console: true } : {}),
 };
 
 function fail(message: string): never {
@@ -131,7 +133,15 @@ function one(): Device {
     return device ?? fail("name a device");
 }
 
-const adapterOf = (device: Device): DeviceAdapter => adapters[device.platform] ?? fail(`no adapter for ${device.platform}`);
+/** The adapter of a device, which must be able to use its console when `--console` asks for it. */
+function adapterOf(device: Device): DeviceAdapter {
+    const adapter = adapters[device.platform] ?? fail(`no adapter for ${device.platform}`);
+    if (!options.console) return adapter;
+
+    if (!adapter.console) fail(`${device.name}: ${device.platform} cannot be reached through a console yet`);
+    if (!device.connection.console) fail(`${device.name}: --console needs connection.console`);
+    return adapter;
+}
 /** What Circuit writes, beside the config. */
 const generated = join(root, ".circuit");
 const stateDirectory = join(generated, "state");
@@ -215,7 +225,7 @@ function diffCommand(): void {
 
 async function snapshotCommand(): Promise<void> {
     for (const device of selected(true)) {
-        const text = await adapterOf(device).read(device, network.devices);
+        const text = await adapterOf(device).read(device, network.devices, options);
         writeState(device, text);
         console.log(`${device.name}: ${text.split("\n").length} lines`);
     }
@@ -238,7 +248,7 @@ async function applyCommand(): Promise<void> {
     const adapter = adapterOf(device);
 
     // The plan is made against what the device runs now, never against an old snapshot.
-    const live = await adapter.read(device, network.devices);
+    const live = await adapter.read(device, network.devices, options);
     writeState(device, live);
 
     const plan = adapter.plan(adapter.render(device), live, options);
@@ -253,7 +263,7 @@ async function applyCommand(): Promise<void> {
 
     await adapter.apply(device, network.devices, plan, options);
 
-    writeState(device, await adapter.read(device, network.devices));
+    writeState(device, await adapter.read(device, network.devices, options));
     console.log("snapshot updated");
 }
 

package/src/schema/device.ts

@@ -1,4 +1,4 @@
-import type { IP } from "./common";
+import type { IP, Secret } from "./common";
 import type { AclRule, Firewall } from "./firewall";
 import type { Interface, Port, Vlan } from "./interfaces";
 import type { PrefixSet, RoutePolicy } from "./policy";
@@ -13,6 +13,32 @@ export type Connection<U extends string> = {
     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;
+};
+
+/** 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, reached through a jump host. */
+export type Console = {
+    /** The jump host the console cable is plugged into. */
+    jump: Jump;
+    /** The serial port on the jump host. A path under `/dev/serial/by-path/` stays the same when two adapters swap names. */
+    port: string;
+    /** Line speed in bits per second, such as 9600 or 115200. */
+    baud: number;
 };
 
 /** A separate routing table, with the interfaces that route in it. */

package/src/transport/console.ts

@@ -0,0 +1,127 @@
+// Serial consoles on a jump host. Circuit logs in to the jump host over SSH and starts a small relay there, which joins the serial port to the session. The device's CLI then streams through it as through an SSH shell.
+
+import { spawn } from "node:child_process";
+import { Duplex } from "node:stream";
+import { Client, type ClientChannel } from "ssh2";
+import { resolve } from "../core/secrets";
+import type { Console, Jump } from "../schema";
+import { exec } from "./ssh";
+
+/** The relay, in Python's standard library only: the serial port in raw mode, locked against a second session, joined to standard input and output. */
+const RELAY = `import fcntl, os, select, sys, termios
+
+port, baud = sys.argv[1], int(sys.argv[2])
+fd = os.open(port, os.O_RDWR | os.O_NOCTTY | os.O_NONBLOCK)
+
+try:
+    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+except OSError:
+    sys.stderr.write("busy: another session holds " + port + "\\n")
+    sys.exit(3)
+
+attrs = termios.tcgetattr(fd)
+attrs[0] = attrs[1] = attrs[3] = 0
+attrs[2] = termios.CS8 | termios.CREAD | termios.CLOCAL
+attrs[4] = attrs[5] = getattr(termios, "B%d" % baud)
+termios.tcsetattr(fd, termios.TCSANOW, attrs)
+termios.tcflush(fd, termios.TCIOFLUSH)
+
+sys.stderr.write("ready\\n")
+sys.stderr.flush()
+
+while True:
+    ready, _, _ = select.select([0, fd], [], [])
+
+    if 0 in ready:
+        data = os.read(0, 4096)
+        if not data:
+            break
+        while data:
+            try:
+                data = data[os.write(fd, data):]
+            except BlockingIOError:
+                select.select([], [fd], [])
+
+    if fd in ready:
+        try:
+            data = os.read(fd, 4096)
+        except BlockingIOError:
+            continue
+        if data:
+            os.write(1, data)
+`;
+
+const RELAY_PATH = "/tmp/circuit-console.py";
+
+/** A serial port path the relay is started with, which reaches the jump host's shell. */
+const PORT = /^\/dev\/[\w./:+-]+$/;
+
+/** A session to a jump host, through `cloudflared access ssh` when it sits behind a Cloudflare Tunnel. */
+function connectJump(jump: Jump): Promise<Client> {
+    return new Promise((done, fail) => {
+        const client = new Client();
+        const login = { username: jump.user, password: resolve(jump.password), readyTimeout: 60_000 };
+
+        client.on("ready", () => done(client)).on("error", fail);
+
+        if (!jump.cloudflared) {
+            client.connect({ ...login, host: jump.host, port: jump.port ?? 22 });
+            return;
+        }
+
+        const tunnel = spawn("cloudflared", ["access", "ssh", "--hostname", jump.host], { stdio: ["pipe", "pipe", "ignore"] });
+        tunnel.on("error", (error) => fail(new Error(`cloudflared did not start: ${error.message}`)));
+        client.on("close", () => tunnel.kill());
+
+        client.connect({ ...login, sock: Duplex.from({ readable: tunnel.stdout, writable: tunnel.stdin }) });
+    });
+}
+
+/** An open console: the stream to the device's CLI, and how to let it go. */
+export type ConsoleSession = { channel: ClientChannel; close: () => void };
+
+/** Open a device's serial console through its jump host. Fails when another session holds the port. */
+export async function openConsole(console: Console): Promise<ConsoleSession> {
+    if (!PORT.test(console.port)) throw new Error(`console port ${console.port} is not a path under /dev`);
+    if (!Number.isInteger(console.baud) || console.baud <= 0) throw new Error(`console baud ${console.baud} is not a line speed`);
+
+    const client = await connectJump(console.jump);
+
+    try {
+        const encoded = Buffer.from(RELAY).toString("base64");
+        await exec(client, `sh -c 'printf %s ${encoded} | base64 -d > ${RELAY_PATH}'`, 30_000);
+
+        const channel = await new Promise<ClientChannel>((done, fail) => {
+            client.exec(`python3 ${RELAY_PATH} ${console.port} ${console.baud}`, (error, stream) => (error ? fail(error) : done(stream)));
+        });
+
+        // The relay says it is ready once it holds the port, or why it cannot.
+        await new Promise<void>((done, fail) => {
+            let said = "";
+            const limit = setTimeout(() => fail(new Error(`the console relay did not start: ${said.trim()}`)), 30_000);
+
+            channel.stderr.on("data", (chunk: Buffer) => {
+                said += chunk.toString("utf8");
+                if (said.includes("ready\n")) {
+                    clearTimeout(limit);
+                    done();
+                }
+            });
+            channel.on("close", () => {
+                clearTimeout(limit);
+                fail(new Error(`the console relay stopped: ${said.trim() || "no reason given"}`));
+            });
+        });
+
+        return {
+            channel,
+            close: () => {
+                channel.end();
+                client.end();
+            },
+        };
+    } catch (error) {
+        client.end();
+        throw error;
+    }
+}