@takodotid/circuit 0.42.0 → 0.43.0

package/package.json

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

package/src/core/utils.ts

@@ -19,6 +19,11 @@ export class Utils {
         return result as Merged<T>;
     }
 
+    /** The table a route or a BGP session is in, beside the main one: `undefined` for the main table, written `main` or left out. */
+    static otherTable(table: string | undefined): string | undefined {
+        return table === "main" ? undefined : table;
+    }
+
     /** Minutes east of UTC an IANA zone is at now, for platforms that take an offset rather than a zone. */
     static timeZoneOffset(zone: string): number {
         const name = new Intl.DateTimeFormat("en-US", {

package/src/core/validator.ts

@@ -1,6 +1,7 @@
 // Rules every network has to satisfy, whatever its design. Types catch most of this at compile time; these run again at load, because config is data and may not come from TypeScript.
 
 import { X509Certificate } from "node:crypto";
+import { Utils } from "./utils";
 import { Platforms } from "../platforms";
 import { Catalog } from "../platforms/catalog";
 import type { Device, Switched } from "../schema";
@@ -63,7 +64,10 @@ export class Validator {
 
             const adapter = Platforms.find(device.platform);
             if (!adapter) report(`no adapter for platform ${device.platform}`);
-            else for (const field of adapter.unsupported(device)) report(`${device.platform} cannot express ${field}`);
+            else {
+                for (const field of adapter.unsupported(device)) report(`${device.platform} cannot express ${field}`);
+                findings.push(...(adapter.checks?.(device) ?? []));
+            }
         }
 
         findings.push(...CrossChecks.run(network.devices));
@@ -294,9 +298,10 @@ export class Validator {
             names.expect(
                 `static route ${route.prefix} table`,
                 route.table,
-                route.table !== undefined && route.table in (routing?.tables ?? {})
+                route.table !== undefined && (route.table === "main" || route.table in (routing?.tables ?? {}))
             );
-            if (route.vrf && route.table) report(`static route ${route.prefix} has both vrf and table; a route is in one of them`);
+            if (route.vrf && Utils.otherTable(route.table))
+                report(`static route ${route.prefix} has both vrf and table; a route is in one of them`);
         }
 
         Validator.checkTables(device, names, report, cidr);
@@ -306,7 +311,7 @@ export class Validator {
 
         for (const prefix of bgp?.networks ?? []) cidr("BGP network", prefix);
 
-        const isTable = (table: string | undefined) => table !== undefined && table in (routing?.tables ?? {});
+        const isTable = (table: string | undefined) => table !== undefined && (table === "main" || table in (routing?.tables ?? {}));
 
         for (const [name, group] of Object.entries(bgp?.groups ?? {})) {
             for (const policy of [group.import, group.export]) {
@@ -348,9 +353,12 @@ export class Validator {
         const bgp = routing?.bgp;
 
         const installed = new Set<string>();
-        for (const route of routing?.static ?? []) if (route.table) installed.add(route.table);
+        for (const route of routing?.static ?? []) {
+            const table = Utils.otherTable(route.table);
+            if (table) installed.add(table);
+        }
         for (const neighbor of Object.values(bgp?.neighbors ?? {})) {
-            const table = neighbor.table ?? (neighbor.group ? bgp?.groups?.[neighbor.group]?.table : undefined);
+            const table = Utils.otherTable(neighbor.table ?? (neighbor.group ? bgp?.groups?.[neighbor.group]?.table : undefined));
             if (table) installed.add(table);
         }
 

package/src/helpers/bgp.ts

@@ -80,13 +80,22 @@ export type CommunityScheme<
     /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
     prepend?: { once?: number; twice?: number; three_times?: number };
     /**
-     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it, and so does every upstream in `upstreams`.
-     *
-     * `upstreams` maps an upstream's AS to its own blackhole community, as its NOC gives it. The route is passed to that upstream with it, so the traffic stops before it reaches your links. An upstream not listed never receives the route.
+     * A neighbor asks: drop all traffic to this route, `asn:function:0`, usually one address under attack. Your router drops it. An upstream whose own blackhole community you know (`communities.blackhole` on the neighbor you pass to `actions`) receives the route with it and drops the traffic too; any other never receives the route.
      */
-    blackhole?: { function: number; upstreams?: Readonly<Record<number, StandardCommunity>> };
+    blackhole?: { function: number };
+};
+
+/** The communities another network offers us, as its NOC gives them: what it does with a route we send it. */
+export type NeighborCommunities = {
+    /** It drops traffic to a route we send it with this community. */
+    blackhole?: StandardCommunity | LargeCommunity;
+    /** It does not pass a route we send it with this community to the AS given, such as an exchange's route servers' `rs-asn:0:peer-asn`. */
+    do_not_announce_to?: (asn: number) => StandardCommunity | LargeCommunity;
 };
 
+/** A neighbor an export goes to: its AS, or its AS and the communities it offers. */
+export type ExportNeighbor = number | { asn: number; communities?: NeighborCommunities };
+
 /** The class names a scheme declares, or any name when it declares none. */
 type ClassName<Classes extends CommunityClasses> = {} extends Classes ? string : Extract<keyof Classes, string>;
 
@@ -248,10 +257,12 @@ export class Bgp {
      * Policy rules and a catalogue from one community scheme, so the communities your routers set, the ones they act on, and the ones you publish never disagree.
      *
      * - `tag(neighborClass, neighborAs, { site, trusted })`: one rule for an import policy, `{ description: "Learned from AS<n>", set }`. Its `set` removes your standard communities and your large ones (a `trusted` neighbor loses only the "where it came from" functions, so it keeps its requests: do not announce, prepend, blackhole), then adds `learned_from`, `learned_at` and `learned_from_as` where the scheme has them. `site` is needed when the scheme has `learned_at`.
-     * - `actions(neighborAs)`: the rules for an export policy toward one neighbor, before the rules that accept. They are `[...blackholeExport(n), ...rejectDoNotAnnounce(n), ...prepends(n), stripOurs()]`; toward a neighbor that takes blackholes (`blackhole.upstreams`), `rejectDoNotAnnounce(n)` comes first, so a route asked not to go there is never passed on as a blackhole.
-     * - `blackholeExport(neighborAs)`: a blackholed route goes no further, `Blackholed here, never announced`, unless `blackhole.upstreams` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too. Nothing without `blackhole`.
-     * - `rejectDoNotAnnounce(neighborAs)`: rejects a route asked not to be announced anywhere, then one asked not to be announced to this neighbor. Nothing without `do_not_announce`.
-     * - `prepends(neighborAs)`: prepends once, twice or three times toward this neighbor, where a route asks. Nothing without `prepend`.
+     * Each export helper takes the neighbor: its AS, or `{ asn, communities }` with the communities it offers, such as an `Upstreams.catalog` entry.
+     *
+     * - `actions(neighbor)`: the rules for an export policy toward one neighbor, before the rules that accept. They are `[...blackholeExport(n), ...rejectDoNotAnnounce(n), ...prepends(n), stripOurs()]`; toward a neighbor that takes blackholes (`communities.blackhole`), `rejectDoNotAnnounce(n)` comes first, so a route asked not to go there is never passed on as a blackhole.
+     * - `blackholeExport(neighbor)`: a blackholed route goes no further, `Blackholed here, never announced`, unless the neighbor has `communities.blackhole`: then it is passed on with it, so the neighbor drops the traffic too. Nothing without `blackhole` in the scheme.
+     * - `rejectDoNotAnnounce(neighbor)`: rejects a route asked not to be announced anywhere, then one asked not to be announced to this neighbor. Nothing without `do_not_announce`.
+     * - `prepends(neighbor)`: prepends once, twice or three times toward this neighbor, where a route asks. Nothing without `prepend`.
      * - `stripOurs()`: one rule removing every community of yours, `Our communities stay inside our network`.
      * - `blackhole(prefixSets)`: rules for the import policy of a neighbor you trust with blackholes, before anything that rejects long prefixes. They take a route the neighbor asked to blackhole, but only inside `prefixSets`, its own space, and drop traffic to it here. One rule per set, so one call covers both families.
      * - `catalogue`: every community, for `communities` in `defineNetwork`.
@@ -331,28 +342,38 @@ export class Bgp {
             }));
         };
 
+        /** The neighbor's AS. */
+        const asnOf = (neighbor: ExportNeighbor) => (typeof neighbor === "number" ? neighbor : neighbor.asn);
+
         /** The neighbor's own blackhole community, when it takes blackholes from us. */
-        const passOnTo = (neighborAs: number) => scheme.blackhole?.upstreams?.[neighborAs];
+        const passOnTo = (neighbor: ExportNeighbor) => (typeof neighbor === "number" ? undefined : neighbor.communities?.blackhole);
 
-        const blackholeExport = (neighborAs: number): PolicyRule<never, never>[] => {
+        const blackholeExport = (neighbor: ExportNeighbor): PolicyRule<never, never>[] => {
             if (scheme.blackhole === undefined) return [];
 
-            const passOn = passOnTo(neighborAs);
+            const passOn = passOnTo(neighbor);
             const match = { large_community: community(scheme.blackhole.function, 0) };
+            if (!passOn) return [{ description: "Blackholed here, never announced", match, action: "reject" }];
 
-            return passOn
-                ? [
-                      {
-                          description: `Blackhole passed on to AS${neighborAs}`,
-                          match,
-                          set: { remove_communities: ours.standard, remove_large_communities: ours.large, add_communities: [passOn] },
-                          action: "accept",
-                      },
-                  ]
-                : [{ description: "Blackholed here, never announced", match, action: "reject" }];
+            const large = passOn.split(":").length === 3;
+            return [
+                {
+                    description: `Blackhole passed on to AS${asnOf(neighbor)}`,
+                    match,
+                    set: {
+                        remove_communities: ours.standard,
+                        remove_large_communities: ours.large,
+                        ...(large
+                            ? { add_large_communities: [passOn as LargeCommunity] }
+                            : { add_communities: [passOn as StandardCommunity] }),
+                    },
+                    action: "accept",
+                },
+            ];
         };
 
-        const rejectDoNotAnnounce = (neighborAs: number): PolicyRule<never, never>[] => {
+        const rejectDoNotAnnounce = (neighbor: ExportNeighbor): PolicyRule<never, never>[] => {
+            const neighborAs = asnOf(neighbor);
             const fn = scheme.do_not_announce;
             if (fn === undefined) return [];
 
@@ -366,8 +387,9 @@ export class Bgp {
             ];
         };
 
-        const prepends = (neighborAs: number): PolicyRule<never, never>[] =>
+        const prepends = (neighbor: ExportNeighbor): PolicyRule<never, never>[] =>
             Bgp.PREPENDS.flatMap(([name, times]) => {
+                const neighborAs = asnOf(neighbor);
                 const fn = scheme.prepend?.[name];
                 if (fn === undefined) return [];
 
@@ -386,10 +408,10 @@ export class Bgp {
         });
 
         // A route asked not to be announced to a neighbor is never passed on to it as a blackhole either; where nothing is passed on, both only reject.
-        const actions = (neighborAs: number): PolicyRule<never, never>[] =>
-            passOnTo(neighborAs)
-                ? [...rejectDoNotAnnounce(neighborAs), ...blackholeExport(neighborAs), ...prepends(neighborAs), stripOurs()]
-                : [...blackholeExport(neighborAs), ...rejectDoNotAnnounce(neighborAs), ...prepends(neighborAs), stripOurs()];
+        const actions = (neighbor: ExportNeighbor): PolicyRule<never, never>[] =>
+            passOnTo(neighbor)
+                ? [...rejectDoNotAnnounce(neighbor), ...blackholeExport(neighbor), ...prepends(neighbor), stripOurs()]
+                : [...blackholeExport(neighbor), ...rejectDoNotAnnounce(neighbor), ...prepends(neighbor), stripOurs()];
 
         const catalogue: Community[] = [
             ...Object.entries<number>(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
@@ -424,9 +446,7 @@ export class Bgp {
                 ? [
                       {
                           community: written(scheme.blackhole.function, 0),
-                          description: Object.keys(scheme.blackhole.upstreams ?? {}).length
-                              ? `Blackhole: dropped in AS${asn} and by its upstreams that take it`
-                              : `Blackhole: dropped in AS${asn}, not announced further`,
+                          description: `Blackhole: dropped in AS${asn}, and by the upstreams that take it`,
                       },
                   ]
                 : []),

package/src/helpers/index.ts

@@ -1,7 +1,16 @@
 // Building blocks most networks write the same way: address lists, cables written once for both ends, edge filters, a BGP import sanity policy, an exchange's member ports and route servers, upstreams written once, checks, and helpers for checks of your own. Each returns plain config to place where it belongs, so nothing here applies itself.
 
 export { Bgp } from "./bgp";
-export type { AnnounceOptions, Announced, CommunityScheme, DefaultOnlyOptions, LearnOptions, SanityLengths } from "./bgp";
+export type {
+    AnnounceOptions,
+    Announced,
+    CommunityScheme,
+    DefaultOnlyOptions,
+    ExportNeighbor,
+    LearnOptions,
+    NeighborCommunities,
+    SanityLengths,
+} from "./bgp";
 export { Cables } from "./cables";
 export type { FarEnd } from "./cables";
 export { Checks } from "./checks";

package/src/helpers/upstreams.ts

@@ -5,6 +5,8 @@ import type {
     FilterRule,
     Gre,
     InterfaceAddress,
+    StandardCommunity,
+    LargeCommunity,
     IP,
     Neighbor,
     NeighborSettings,
@@ -15,6 +17,7 @@ import type {
     Vlan,
     VlanInterface,
 } from "../schema";
+import type { NeighborCommunities } from "./bgp";
 
 /** A route policy an upstream's sessions use: its name on the device, and its rules, in order. */
 export type UpstreamPolicy = {
@@ -67,7 +70,7 @@ export type Upstream = {
     group?: string;
     /** The sessions are more than one hop away, from this address of ours. */
     multihop?: { local_address: IP; families?: readonly Family[]; password?: Secret };
-    /** The routing table its sessions install the routes they learn in, one of the router's `routing.tables`: a transit that carries only one block's traffic out. The main table when absent. */
+    /** The routing table its sessions install the routes they learn in: `main`, or one of the router's `routing.tables`, for a transit that carries only one block's traffic out. The main table when absent; write `main` to say so. On RouterOS the sessions also announce from that table, so what they announce needs a route there too. */
     table?: string;
     /** The most prefixes a session may send, by its family: about twice what it sends. Over it, the session closes until it is cleared. */
     limits?: { ipv4?: number; ipv6?: number };
@@ -77,6 +80,8 @@ export type Upstream = {
     export: UpstreamPolicy;
     /** Its VLAN is listed by `privateDrops()`, for an ACL that drops RFC 1918 sources arriving from it. Nothing else is done with it. */
     drop_private?: true;
+    /** The communities it offers, as its NOC gives them: its blackhole community, and how to keep a route from one AS. `communityScheme().actions(upstream)` passes blackholes on with it, and `Upstreams.doNotAnnounceTo` uses the other. */
+    communities?: NeighborCommunities;
 };
 
 /** Upstreams by key. */
@@ -107,11 +112,45 @@ type PolicyName<C> = Values<{
 }>;
 /** Each BGP group name. */
 type GroupName<C> = Values<{ [K in keyof C]: C[K] extends { group: infer N extends string } ? N : never }>;
-/** Each routing table name. */
-type TableName<C> = Values<{ [K in keyof C]: C[K] extends { table: infer N extends string } ? N : never }>;
+/** Each routing table name, other than main. */
+type TableName<C> = Exclude<Values<{ [K in keyof C]: C[K] extends { table: infer N extends string } ? N : never }>, "main">;
 
 /** A network's upstreams written once, and each device's part built from them. */
 export class Upstreams {
+    /**
+     * A catalog of upstreams, by key, written once and checked: a key the shape doesn't have is refused by its name. It gives the catalog back as written, so its keys and entries can be read, and is what `define` takes.
+     */
+    static catalog<const C extends UpstreamCatalog>(catalog: C & UpstreamCatalog): C {
+        return catalog;
+    }
+
+    /**
+     * Export rules asking an upstream not to pass our routes to these ASes, with its own `communities.do_not_announce_to`: one rule, `description`, adding one community per AS. Nothing for no AS. An upstream without `do_not_announce_to` is an error, since it can't be asked.
+     */
+    static doNotAnnounceTo(upstream: Upstream, asns: readonly number[], description: string): PolicyRule<never, never>[] {
+        if (!asns.length) return [];
+
+        const community = upstream.communities?.do_not_announce_to;
+        if (!community)
+            throw new Error(
+                `Upstreams: ${upstream.name ?? `AS${upstream.asn}`} has no communities.do_not_announce_to, so it can't be asked to keep our routes from AS${asns.join(", AS")}`
+            );
+
+        const communities = asns.map(community);
+        const large = communities.filter((value) => value.split(":").length === 3) as LargeCommunity[];
+        const standard = communities.filter((value) => value.split(":").length === 2) as StandardCommunity[];
+
+        return [
+            {
+                description,
+                set: {
+                    ...(standard.length ? { add_communities: standard } : {}),
+                    ...(large.length ? { add_large_communities: large } : {}),
+                },
+            },
+        ];
+    }
+
     /**
      * Each upstream written once: its AS, where it lands, its sessions, limits and policies, and every name it puts on a device. Everything a device needs is built from it:
      *
@@ -229,7 +268,7 @@ export class Upstreams {
                 role: upstream.role,
                 ...(upstream.import ? { import: upstream.import.name as PolicyName<C> } : {}),
                 export: upstream.export.name as PolicyName<C>,
-                ...(upstream.table ? { table: upstream.table as TableName<C> } : {}),
+                ...(upstream.table ? { table: upstream.table as TableName<C> | "main" } : {}),
                 ...(multihop
                     ? {
                           local_address: multihop.local_address,

package/src/platforms/bgp-wait.ts

@@ -15,23 +15,23 @@ export class BgpWait {
      */
     static readonly AFTER_APPLY: WaitLimits = { seconds: 180, every: 10 };
 
-    /** Read the sessions until `enough` holds or time runs out, and give the last read. `waiting` is told of each read that fell short, before the pause. */
-    static async until(
-        read: () => Promise<BgpSession[]>,
-        enough: (sessions: BgpSession[]) => boolean,
+    /** Read until `enough` holds or time runs out, and give the last read: the sessions, or what they announce. `waiting` is told of each read that fell short, before the pause. */
+    static async until<T>(
+        read: () => Promise<T>,
+        enough: (value: T) => boolean,
         limits: WaitLimits,
-        waiting: (sessions: BgpSession[]) => void = () => {}
-    ): Promise<BgpSession[]> {
+        waiting: (value: T) => void = () => {}
+    ): Promise<T> {
         const deadline = Date.now() + limits.seconds * 1000;
-        let sessions = await read();
+        let value = await read();
 
-        while (!enough(sessions) && Date.now() < deadline) {
-            waiting(sessions);
+        while (!enough(value) && Date.now() < deadline) {
+            waiting(value);
             await sleep(Math.min(limits.every * 1000, Math.max(0, deadline - Date.now())));
-            sessions = await read();
+            value = await read();
         }
 
-        return sessions;
+        return value;
     }
 
     /** How many of these sessions are established. */

package/src/platforms/derive.ts

@@ -1,6 +1,7 @@
 // Values more than one adapter derives from a device in the same way.
 
 import { Address } from "../core/address";
+import { Utils } from "../core/utils";
 import type { Device } from "../schema";
 
 /** A feature a platform renders once proved on one of its devices. */
@@ -54,7 +55,7 @@ export class Derive {
         for (const route of routing?.static ?? []) {
             if (route.bfd && !has("static-route-bfd"))
                 found.push(`routing.static ${route.prefix} bfd, BFD on a static route is ${unproved}`);
-            if (route.table && !has("routing-tables"))
+            if (Utils.otherTable(route.table) && !has("routing-tables"))
                 found.push(`routing.static ${route.prefix} table, a routing table beside the main one is ${unproved}`);
         }
 
@@ -66,12 +67,12 @@ export class Derive {
         const bgp = routing?.bgp;
 
         for (const [name, group] of Object.entries(bgp?.groups ?? {})) {
-            if (group.table && !has("routing-tables"))
+            if (Utils.otherTable(group.table) && !has("routing-tables"))
                 found.push(`routing.bgp.groups.${name}.table, a routing table beside the main one is ${unproved}`);
         }
 
         for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
-            if (neighbor.table && !has("routing-tables"))
+            if (Utils.otherTable(neighbor.table) && !has("routing-tables"))
                 found.push(`routing.bgp.neighbors.${name}.table, a routing table beside the main one is ${unproved}`);
 
             const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;

package/src/platforms/platform.ts

@@ -1,4 +1,5 @@
 import type { Neighbor } from "../core/cabling";
+import type { Finding } from "../core/define";
 import type { Device, Family } from "../schema";
 import type { ConsoleDialect } from "../transport/console";
 import type { WaitLimits } from "./bgp-wait";
@@ -100,6 +101,8 @@ export abstract class Platform {
     readonly console: ConsoleDialect | undefined = undefined;
     /** Fields this platform cannot express. Validation fails on any of them, so nothing is skipped silently. */
     abstract unsupported(device: Device): string[];
+    /** What the platform does with a config that it may not do elsewhere, each as `validate` reports it: an error stops `diff` and `apply`, a warning is reported only. Absent on a platform with none. */
+    checks?(device: Device): Finding[];
     /** The switch rules the render makes from the device's hardware ACLs, so `validate` can hold them to the model's limits. Absent on a platform whose rules are not counted. */
     switchRules?(device: Device): SwitchRules;
     /** The whole configuration the device should run. Secrets appear as markers, never values. */

package/src/platforms/routeros/TRAPS.md

@@ -64,6 +64,8 @@ Behaviour that looks like something else. Each one has been hit on a real device
 - No MAC learning limit on 7.23.5: `/interface bridge port` has `learn` but no limit, and `/interface ethernet switch port` has none (CCR2216). `mac_limit` stays refused.
 - A switch rule matches a kind of frame with `mac-protocol` (`ip`, `ipv6`, `arp` among 23 kinds), but cannot match "not" one. An ethertype filter is a rule that lets each kind through and a last one with an empty `new-dst-ports` for the rest, after the port's ACL rules, which match only `ip` or `ipv6`. Four such rules on a free port took the router to 70 switch rules, none invalid (CCR2216, 7.23.5).
 - A routing table holds no routes the router forwards by unless it has `fib`: `/routing table add fib name=...`. The export prints the flag between the properties, `add comment=... fib name=...`.
-- A BGP connection's `routing-table` installs what it learns in that table and not in main; the next hop still resolves through main. Proved on a CCR2216 on 7.23.5 with a session to a test speaker: its routes showed `routing-table=<table>`, active, and main kept only its own static route. The export prints `routing-table` only when it is not `main`.
+- A BGP connection's `routing-table` is where the session installs what it learns and also where it announces from: an `output.network` prefix is announced only while that table has a route for it, and a route in main alone is not enough. On a CCR2216 on 7.23.5, a fresh session with `routing-table=<table>` installed its routes there, active, with the next hop resolved through main, and announced nothing until the table had the prefix too; then it did. Circuit's validate refuses a session in a table that holds none of `networks`, and warns for each it lacks. Routing filters cannot move a route to a table: `set routing-table` and `set table` are `invalid argument`.
+- A running session takes a new `routing-table` only when it restarts, but its announcements stop at once: set from main to a table, it withdrew everything within seconds, kept its learned routes in main, and announced nothing even once the table had the prefix; set back to main, it still announced nothing until it restarted. `/routing bgp session resend afi=ipv6` did not help either, on the router where this was found (#157). Disabling and enabling the connection restarted it in the new table. The plan does exactly that, written on the plan's line, and after an apply Circuit checks that every session still announces what it announced of `networks` before (CCR2216, 7.23.5).
+- A passive connection without `local.address` listens only on its default local address, `local.default-address`, which may be a public one: a peer connecting to another address of the router gets a TCP reset (CCR2216, 7.23.5).
 - `/routing rule` is an ordered list without names, like a filter chain, and the plan rewrites it whole in the config's order. `lookup-only-in-table` drops a packet its table has no route for (a ping printed `no route`); `lookup` routes it by main instead (the ping left). An interface to match is `interface=`. A `drop` or `unreachable` rule is printed with `!realm`, which Circuit does not write (CCR2216, 7.23.5).
 - An eBGP connection to an address on no connected network, without `multihop=yes`, takes the TCP connection, logs `connection <local> from <remote>`, and closes it with no OPEN and nothing else in the log, even with `bgp,debug` logging on (CCR2216, 7.23.5).

package/src/platforms/routeros/index.ts

@@ -3,8 +3,10 @@
 // The platform applies every command the moment it arrives and has no candidate configuration, so a run is guarded three ways. Every command is first compiled on the device without running, so a syntax error or an unknown property costs nothing. A backup is saved and a scheduler armed to restore it, and the run must log in again in a fresh session before the scheduler is removed. A command the device refuses restores the backup at once, rather than leaving the device half applied.
 
 import type { Client } from "ssh2";
+import { Utils } from "../../core/utils";
 import { Address } from "../../core/address";
 import type { Neighbor } from "../../core/cabling";
+import type { Finding } from "../../core/define";
 import { Secrets } from "../../core/secrets";
 import type { Device, Family } from "../../schema";
 import { SerialConsole, type ConsoleDialect, ConsoleShell } from "../../transport/console";
@@ -84,6 +86,12 @@ export class RouterOs extends Platform {
     ].join(" ");
 
     /** Open again the session from one address, only while it is closed on its limit. */
+    /** Each advertisement of these prefixes, one line each: `ADV|<session>|<prefix>`. One line, because a script sent over exec runs as one. */
+    private static listAdvertisements(prefixes: readonly string[]): string {
+        const where = prefixes.map((prefix) => `dst=${prefix}`).join(" or ");
+        return `:foreach a in=[/routing bgp advertisements print as-value where ${where}] do={ :put ("ADV|" . ($a->"peer") . "|" . ($a->"dst")) }`;
+    }
+
     private static clearLimit(address: string): string {
         return `/routing bgp session clear [find remote.address=${address} and limit-exceeded] flag=limit-exceeded`;
     }
@@ -135,6 +143,58 @@ export class RouterOs extends Platform {
 
     override readonly console = RouterOs.CONSOLE;
 
+    /**
+     * A BGP session with a `table` announces from that table, not from main: each prefix of `networks` it announces needs a route in the table too, or it is not announced (TRAPS.md). A session left with nothing to announce is an error; a prefix missing from its table is a warning, since its export may not announce it anyway.
+     */
+    checks(device: Device): Finding[] {
+        const bgp = device.routing?.bgp;
+        const statics = device.routing?.static ?? [];
+        const findings: Finding[] = [];
+
+        for (const [name, neighbor] of Object.entries(bgp?.neighbors ?? {})) {
+            const group = neighbor.group ? bgp?.groups?.[neighbor.group] : undefined;
+            const table = Utils.otherTable(neighbor.table ?? group?.table);
+            if (!table) continue;
+
+            const families = neighbor.families ?? group?.families ?? [Address.family(neighbor.address)];
+            const networks = (bgp?.networks ?? []).filter((prefix) => families.includes(Address.family(Address.host(prefix))));
+            const inTable = (prefix: string) =>
+                statics.some((route) => route.table === table && Address.canonical(route.prefix) === Address.canonical(prefix));
+            // What its export accepts by prefix: a network it would reject anyway needs no route in the table. Every network when the export names none.
+            const exportPolicy = neighbor.export ?? group?.export;
+            const accepted = (exportPolicy ? (device.policies?.[exportPolicy] ?? []) : [])
+                .filter((rule) => rule.action === "accept" && rule.match?.prefix)
+                .map((rule) => Address.canonical(rule.match!.prefix!));
+            const announced = accepted.length ? networks.filter((prefix) => accepted.includes(Address.canonical(prefix))) : networks;
+
+            const missing = announced.filter((prefix) => !inTable(prefix));
+            if (!missing.length) continue;
+
+            const where = `routing.bgp.neighbors.${name}`;
+            const route = (prefix: string) => `{ prefix: "${prefix}", blackhole: true, table: "${table}" }`;
+            const fix = `On RouterOS a session announces from its own table, ${table}`;
+
+            if (missing.length === announced.length) {
+                findings.push({
+                    level: "error",
+                    device: device.name,
+                    message: `${where} would announce nothing: ${fix}, which has no route for any of networks. Add the routes it announces to ${table} too, such as ${route(missing[0]!)} in routing.static`,
+                });
+                continue;
+            }
+
+            for (const prefix of missing) {
+                findings.push({
+                    level: "warning",
+                    device: device.name,
+                    message: `${where} does not announce ${prefix}: ${fix}, which has no route for it. If its export should announce it, add ${route(prefix)} to routing.static`,
+                });
+            }
+        }
+
+        return findings;
+    }
+
     unsupported(device: Device): string[] {
         const found: string[] = [];
 
@@ -427,13 +487,14 @@ export class RouterOs extends Platform {
     }
 
     /**
-     * Two checks after an apply. When the plan touched switch rules, none may be invalid. BGP sessions established before the apply must be established again, within `BgpWait.AFTER_APPLY`.
+     * Three checks after an apply. When the plan touched switch rules, none may be invalid. BGP sessions established before the apply must be established again, and announce again each of the device's `networks` they announced before, within `BgpWait.AFTER_APPLY`. A session can stay up and stop announcing (TRAPS.md), which the session check alone would not see.
      */
     async health(device: Device, plan: Plan, options: HealthOptions = {}): Promise<HealthCheck> {
         const switchRules = plan.steps.some((step) => step.send.some((command) => command.startsWith(RouterOs.SWITCH_RULES)));
         const limits = options.bgp ?? BgpWait.AFTER_APPLY;
 
         const establishedBefore = await this.establishedSessions(device, options);
+        const announcedBefore = establishedBefore.length ? await this.announcedNow(device, options) : [];
 
         return {
             run: async () => {
@@ -447,7 +508,8 @@ export class RouterOs extends Platform {
                 try {
                     const switchProblems = switchRules ? await RouterOs.invalidSwitchRules(session, device) : [];
                     const bgpProblems = await this.bgpBack(device, session, establishedBefore, limits);
-                    return [...switchProblems, ...bgpProblems];
+                    const announceProblems = await this.announcedBack(device, session, announcedBefore, limits);
+                    return [...switchProblems, ...bgpProblems, ...announceProblems];
                 } finally {
                     session.close();
                 }
@@ -563,6 +625,72 @@ export class RouterOs extends Platform {
         );
     }
 
+    /** What each session announces of the device's own `networks`, as `neighbor prefix`. None, without logging in, on a device without networks. */
+    private async announcedNow(device: Device, options: ReadOptions): Promise<string[]> {
+        if (!device.routing?.bgp?.networks?.length) return [];
+
+        const session = await this.session(device, options);
+
+        try {
+            return await this.announced(device, session);
+        } finally {
+            session.close();
+        }
+    }
+
+    /** The `networks` each session announces, as `neighbor prefix`, sorted. An advertisement names its session, which is matched to its neighbor by address first, as in `bgpSessions`. */
+    private async announced(device: Device, session: ReadSession): Promise<string[]> {
+        const bgp = device.routing?.bgp;
+        const networks = bgp?.networks ?? [];
+        if (!networks.length) return [];
+
+        const sessions = (await session.run(RouterOs.LIST_BGP_SESSIONS, 60_000))
+            .split(/\r?\n/)
+            .map((line) => line.trim().split("|"))
+            .filter((fields) => fields.length > 1 && fields[0] !== "disabled");
+        const neighbors = Object.entries(bgp?.neighbors ?? {});
+        const neighborOf = (sessionName: string) => {
+            const remote = sessions.find(([name]) => name === sessionName)?.[1];
+            const byAddress = neighbors.find(([, neighbor]) => neighbor.address === remote);
+            const byName = neighbors.find(([name]) => name === sessionName.replace(/-\d+$/, ""));
+            return (byAddress ?? byName)?.[0];
+        };
+
+        const output = await session.run(RouterOs.listAdvertisements(networks), 60_000);
+        return output
+            .split(/\r?\n/)
+            .map((line) => line.trim().split("|"))
+            .flatMap(([marker, peer, prefix]) => {
+                const neighbor = marker === "ADV" && peer ? neighborOf(peer) : undefined;
+                return neighbor && prefix ? [`${neighbor} ${prefix}`] : [];
+            })
+            .sort();
+    }
+
+    /** Wait until each session announces again what it announced before, and give a problem for each prefix a session no longer announces when time runs out. */
+    private async announcedBack(device: Device, session: ReadSession, before: readonly string[], limits: WaitLimits): Promise<string[]> {
+        if (!before.length) return [];
+
+        const missing = (now: string[]) => before.filter((pair) => !now.includes(pair));
+        const after = await BgpWait.until(
+            () => this.announced(device, session),
+            (now) => !missing(now).length,
+            limits,
+            (now) => console.log(`  BGP: ${missing(now).length} announcement(s) not back yet, checking again in ${limits.every} s`)
+        );
+
+        const gone = missing(after);
+        if (!gone.length) {
+            console.log(`  BGP: every session announces what it announced before`);
+            return [];
+        }
+
+        return gone.map((pair) => {
+            const [neighbor, prefix] = pair.split(" ");
+            return `BGP session ${neighbor} announced ${prefix} before the apply and does not ${limits.seconds} s after it, though it may still be established. A RouterOS session announces from its routing table: that table needs a route for ${prefix}, and a session whose table changed must restart. Look with: circuit show ${device.name} '/routing bgp advertisements print'`;
+        });
+    }
+
     /** A problem when any switch rule is invalid, saying what to do. */
     private static async invalidSwitchRules(session: ReadSession, device: Device): Promise<string[]> {
         const answer = (await session.run(RouterOs.COUNT_INVALID_SWITCH_RULES)).trim();