@takodotid/circuit 0.13.0 → 0.15.0

package/dist/cli/index.js

@@ -3347,6 +3347,67 @@ async function ripeStat(query, family) {
 }
 var registries = { "ripe-stat": ripeStat };
 
+// src/adapters/registries/librenms.ts
+var AUTH = { sha1: "SHA", sha256: "SHA-256" };
+var PRIVACY = { aes128: "AES", des: "DES" };
+function settingsOf2(network2) {
+  if (!network2.librenms)
+    throw new Error("the network has no librenms settings");
+  return {
+    base: `${network2.librenms.url.replace(/\/+$/, "")}/api/v0`,
+    headers: { "X-Auth-Token": resolve(network2.librenms.api_token), "Content-Type": "application/json" }
+  };
+}
+function credentials(device) {
+  const snmp3 = device.management?.snmp;
+  const [name, user] = Object.entries(snmp3?.users ?? {})[0] ?? [];
+  if (name && user) {
+    return {
+      snmpver: "v3",
+      authlevel: "authPriv",
+      authname: name,
+      authpass: resolve(user.auth_password),
+      authalgo: AUTH[user.auth],
+      cryptopass: resolve(user.privacy_password),
+      cryptoalgo: PRIVACY[user.privacy]
+    };
+  }
+  if (snmp3?.community)
+    return { snmpver: "v2c", community: resolve(snmp3.community) };
+  return;
+}
+async function planLibreNms(network2) {
+  const { base, headers } = settingsOf2(network2);
+  const response = await fetch(`${base}/devices?type=all`, { headers, signal: AbortSignal.timeout(30000) });
+  if (!response.ok)
+    throw new Error(`LibreNMS answered ${response.status} to the device list`);
+  const monitored = new Set((await response.json()).devices.map((device) => device.hostname));
+  const ours = new Set(network2.devices.map((device) => device.connection.host));
+  const missing = network2.devices.filter((device) => !monitored.has(device.connection.host));
+  return {
+    additions: missing.filter((device) => device.management?.snmp),
+    withoutSnmp: missing.filter((device) => !device.management?.snmp),
+    unknown: [...monitored].filter((hostname) => !ours.has(hostname)).sort()
+  };
+}
+async function sendLibreNms(network2, additions) {
+  const { base, headers } = settingsOf2(network2);
+  for (const device of additions) {
+    const body = { hostname: device.connection.host, display_template: device.name, ...credentials(device) };
+    const response = await fetch(`${base}/devices`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(60000)
+    });
+    const answer = await response.json().catch(() => ({}));
+    if (!response.ok || answer.status !== "ok") {
+      throw new Error(`${device.name}: LibreNMS refused it: ${answer.message ?? response.status}`);
+    }
+    console.log(`  ${device.name}: ${answer.message}`);
+  }
+}
+
 // src/adapters/registries/peeringdb.ts
 var API = "https://www.peeringdb.com/api";
 var addressesOf = (iface) => (iface.addresses ?? []).map((entry) => typeof entry === "string" ? entry : entry.address);
@@ -3440,6 +3501,48 @@ async function sendPeeringDb(network2, changes2) {
   }
 }
 
+// src/adapters/registries/prometheus.ts
+var AUTH2 = { sha1: "SHA", sha256: "SHA256" };
+var PRIVACY2 = { aes128: "AES", des: "DES" };
+function prometheusTargets(network2) {
+  return {
+    targets: network2.devices.filter((device) => device.management?.snmp).map((device) => ({
+      targets: [device.connection.host],
+      labels: { device: device.name, platform: device.platform, model: device.model, __param_auth: device.name }
+    })),
+    withoutSnmp: network2.devices.filter((device) => !device.management?.snmp)
+  };
+}
+function fromEnvironment(secret, notes, where) {
+  if ("secret" in secret)
+    return `\${${secret.secret}}`;
+  notes.push(`${where} is read from a file; write its value in place of FILL_IN`);
+  return "FILL_IN";
+}
+function snmpExporterAuths(network2) {
+  const notes = [];
+  const lines = [
+    "# Written by `circuit prometheus --auths`. Load it beside snmp.yml, with --config.expand-environment-variables.",
+    "auths:"
+  ];
+  for (const device of network2.devices) {
+    const snmp3 = device.management?.snmp;
+    if (!snmp3)
+      continue;
+    const [name, user] = Object.entries(snmp3.users ?? {})[0] ?? [];
+    lines.push(`  ${device.name}:`);
+    if (name && user) {
+      lines.push("    version: 3", `    username: ${name}`, "    security_level: authPriv", `    password: ${fromEnvironment(user.auth_password, notes, `${device.name}'s SNMP password`)}`, `    auth_protocol: ${AUTH2[user.auth]}`, `    priv_protocol: ${PRIVACY2[user.privacy]}`, `    priv_password: ${fromEnvironment(user.privacy_password, notes, `${device.name}'s SNMP privacy password`)}`);
+    } else {
+      lines.push("    version: 2", "    community: FILL_IN");
+      notes.push(`${device.name} has only an SNMP version 2c community, which snmp_exporter cannot read from its environment; write it in place of FILL_IN, or give the device a version 3 user`);
+    }
+  }
+  return { yaml: lines.join(`
+`) + `
+`, notes };
+}
+
 // src/core/validate.ts
 import { X509Certificate as X509Certificate2 } from "node:crypto";
 function validate(network2) {
@@ -3796,6 +3899,9 @@ var HELP = `usage: circuit <command> [device...] [options]
                         a client config for one peer, its private key left for the peer to fill
   communities           the network's BGP communities, one per line, for a looking glass or bgp.tools
   peeringdb             bring PeeringDB's exchange records in line with the config, with --confirm
+  librenms              add every device LibreNMS does not monitor yet, with --confirm
+  prometheus            every device with SNMP, as Prometheus targets for snmp_exporter
+                          --auths        snmp_exporter's auths for them instead, with secrets as \${NAME}
   secrets               every secret the config uses, and whether each can be read
 
   --config <path>       the network's config file, circuit.config.ts in the working directory by default`;
@@ -4030,6 +4136,38 @@ Nothing sent. Re-run with --confirm.`);
   }
   await sendPeeringDb(network2, plan4.changes);
 }
+async function librenmsCommand() {
+  const plan4 = await planLibreNms(network2);
+  for (const hostname of plan4.unknown)
+    console.log(`  LibreNMS monitors ${hostname}, which the config does not. Remove it by hand if it is gone.`);
+  for (const device of plan4.withoutSnmp)
+    console.log(`  ${device.name} has no SNMP in its config, so LibreNMS cannot poll it. Add management.snmp first.`);
+  for (const device of plan4.additions)
+    console.log(`  add ${device.name}, ${device.connection.host}`);
+  if (!plan4.additions.length) {
+    console.log("LibreNMS monitors every device it can.");
+    return;
+  }
+  if (!confirmed) {
+    console.log(`
+Nothing sent. Re-run with --confirm.`);
+    return;
+  }
+  await sendLibreNms(network2, plan4.additions);
+}
+function prometheusCommand() {
+  if (flags.includes("--auths")) {
+    const { yaml, notes } = snmpExporterAuths(network2);
+    for (const note of notes)
+      console.error(note);
+    process.stdout.write(yaml);
+    return;
+  }
+  const { targets, withoutSnmp } = prometheusTargets(network2);
+  for (const device of withoutSnmp)
+    console.error(`${device.name} has no SNMP in its config; left out`);
+  console.log(JSON.stringify(targets, null, 4));
+}
 function secretsIn(value2, found = new Set) {
   if (isSecret(value2))
     found.add(referenceOf(value2));
@@ -4042,7 +4180,7 @@ function secretsIn(value2, found = new Set) {
   return found;
 }
 function secretsCommand() {
-  const references = [...secretsIn([network2.devices, network2.peeringdb])].sort();
+  const references = [...secretsIn([network2.devices, network2.peeringdb, network2.librenms])].sort();
   let missing = 0;
   for (const reference of references) {
     const name = reference.replace(/^file:/, "");
@@ -4068,6 +4206,8 @@ var commands = {
   wireguard: wireguardCommand,
   communities: communitiesCommand,
   peeringdb: peeringdbCommand,
+  librenms: librenmsCommand,
+  prometheus: prometheusCommand,
   secrets: secretsCommand
 };
 var run = commands[command2];

package/dist/presets/index.js

@@ -160,16 +160,22 @@ function communityScheme(scheme) {
   const community = (fn, parameter) => `${asn}:${fn}:${parameter}`;
   const ours = { standard: [`${asn}:*`], large: [`${asn}:*:*`] };
   const information = [scheme.learned_from?.function, scheme.learned_at?.function, scheme.learned_from_as].filter((fn) => fn !== undefined);
+  const requests = [
+    { functions: [scheme.do_not_announce?.function], trusted: scheme.do_not_announce?.trusted },
+    { functions: PREPENDS.map(([name]) => scheme.prepend?.[name]), trusted: scheme.prepend?.trusted },
+    { functions: [scheme.blackhole?.function], trusted: scheme.blackhole?.trusted }
+  ].map(({ functions, trusted }) => ({ functions: functions.filter((fn) => fn !== undefined), trusted: trusted ?? [] }));
   const tag = (neighborClass, neighborAs, options = {}) => {
     const { site } = options;
-    const isCustomer = scheme.customers?.includes(neighborClass) ?? false;
+    const untrusted = requests.filter((request) => !request.trusted.includes(neighborClass)).flatMap((request) => request.functions);
+    const trustedForAny = requests.some((request) => request.functions.length && request.trusted.includes(neighborClass));
     if (scheme.learned_at && site === undefined)
       throw new Error(`communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
     return {
       description: `Learned from AS${neighborAs}`,
       set: {
         remove_communities: ours.standard,
-        remove_large_communities: isCustomer ? information.map((fn) => community(fn, "*")) : ours.large,
+        remove_large_communities: trustedForAny ? [...information, ...untrusted].map((fn) => community(fn, "*")) : ours.large,
         add_large_communities: [
           ...scheme.learned_from ? [community(scheme.learned_from.function, scheme.learned_from.classes[neighborClass])] : [],
           ...scheme.learned_at ? [community(scheme.learned_at.function, site)] : [],
@@ -178,12 +184,14 @@ function communityScheme(scheme) {
       }
     };
   };
-  const blackhole = (prefixSet) => {
+  const blackhole = (neighborClass, prefixSet) => {
     if (scheme.blackhole === undefined)
       throw new Error("communityScheme: blackhole needs a function number in the scheme");
+    if (!scheme.blackhole.trusted.includes(neighborClass))
+      throw new Error(`communityScheme: ${neighborClass} is not trusted to ask for a blackhole`);
     return {
-      description: "Blackhole, asked by the customer",
-      match: { large_community: community(scheme.blackhole, 0), prefix_set: prefixSet },
+      description: "Blackhole, asked by the neighbor",
+      match: { large_community: community(scheme.blackhole.function, 0), prefix_set: prefixSet },
       set: { blackhole: true },
       action: "accept"
     };
@@ -192,26 +200,26 @@ function communityScheme(scheme) {
     ...scheme.blackhole !== undefined && !options.blackhole ? [
       {
         description: "Blackholed here, never announced",
-        match: { large_community: community(scheme.blackhole, 0) },
+        match: { large_community: community(scheme.blackhole.function, 0) },
         action: "reject"
       }
     ] : [],
     ...scheme.do_not_announce !== undefined ? [
       {
         description: "Asked not to be announced anywhere",
-        match: { large_community: community(scheme.do_not_announce, 0) },
+        match: { large_community: community(scheme.do_not_announce.function, 0) },
         action: "reject"
       },
       {
         description: `Asked not to be announced to AS${neighborAs}`,
-        match: { large_community: community(scheme.do_not_announce, neighborAs) },
+        match: { large_community: community(scheme.do_not_announce.function, neighborAs) },
         action: "reject"
       }
     ] : [],
     ...scheme.blackhole !== undefined && options.blackhole ? [
       {
         description: `Blackhole passed on to AS${neighborAs}`,
-        match: { large_community: community(scheme.blackhole, 0) },
+        match: { large_community: community(scheme.blackhole.function, 0) },
         set: {
           remove_communities: ours.standard,
           remove_large_communities: ours.large,
@@ -251,14 +259,14 @@ function communityScheme(scheme) {
     ] : [],
     ...scheme.learned_from_as !== undefined ? [{ community: community(scheme.learned_from_as, "nnn"), description: "Learned from AS$0" }] : [],
     ...scheme.do_not_announce !== undefined ? [
-      { community: community(scheme.do_not_announce, 0), description: "Do not announce to anyone" },
-      { community: community(scheme.do_not_announce, "nnn"), description: "Do not announce to AS$0" }
+      { community: community(scheme.do_not_announce.function, 0), description: "Do not announce to anyone" },
+      { community: community(scheme.do_not_announce.function, "nnn"), description: "Do not announce to AS$0" }
     ] : [],
     ...PREPENDS.flatMap(([name]) => {
       const fn = scheme.prepend?.[name];
       return fn === undefined ? [] : [{ community: community(fn, "nnn"), description: `Prepend ${name.replace("_", " ")} to AS$0` }];
     }),
-    ...scheme.blackhole !== undefined ? [{ community: community(scheme.blackhole, 0), description: `Blackhole: dropped in AS${asn}, not announced further` }] : []
+    ...scheme.blackhole !== undefined ? [{ community: community(scheme.blackhole.function, 0), description: `Blackhole: dropped in AS${asn}, not announced further` }] : []
   ];
   return { community, tag, actions, blackhole, catalogue };
 }

package/dist/types/adapters/registries/librenms.d.ts

@@ -0,0 +1,15 @@
+import type { Network } from "../../core/define";
+import type { Device } from "../../schema";
+/** What `librenms` would do. */
+export type LibreNmsPlan = {
+    /** Devices to add. */
+    additions: Device[];
+    /** Devices that cannot be added: their config turns SNMP off. */
+    withoutSnmp: Device[];
+    /** Hostnames LibreNMS holds that no device in the config has. */
+    unknown: string[];
+};
+/** Compare the config with what LibreNMS monitors. A device is known to LibreNMS by its management address. */
+export declare function planLibreNms(network: Network): Promise<LibreNmsPlan>;
+/** Add each device, named after its `name` and polled with the credentials from its config. */
+export declare function sendLibreNms(network: Network, additions: readonly Device[]): Promise<void>;

package/dist/types/adapters/registries/prometheus.d.ts

@@ -0,0 +1,16 @@
+import type { Network } from "../../core/define";
+import type { Device } from "../../schema";
+export type PrometheusTarget = {
+    targets: string[];
+    labels: Record<string, string>;
+};
+/** The targets, and the devices left out because their config turns SNMP off. */
+export declare function prometheusTargets(network: Network): {
+    targets: PrometheusTarget[];
+    withoutSnmp: Device[];
+};
+/** The `auths` section, as YAML, and what the operator must still fill in by hand. */
+export declare function snmpExporterAuths(network: Network): {
+    yaml: string;
+    notes: string[];
+};

package/dist/types/core/define.d.ts

@@ -45,6 +45,13 @@ export type Network = {
         /** An API key with write access to the network's record. */
         api_key: Secret;
     };
+    /** Keeps LibreNMS monitoring every device: `circuit librenms`. */
+    librenms?: {
+        /** Where LibreNMS is, such as `https://librenms.example.com`. */
+        url: string;
+        /** An API token that can add devices. */
+        api_token: Secret;
+    };
 };
 /** Declare the network, in `circuit.config.ts`. */
 export declare const defineNetwork: (network: Network) => Network;

package/dist/types/presets/index.d.ts

@@ -64,8 +64,6 @@ export type CommunityScheme<Class extends string = string> = {
         function: number;
         classes: Readonly<Record<Class, number>>;
     };
-    /** Which of the classes above are your customers. Only a customer may ask you for something, such as not announcing its route somewhere; what anyone else asks is removed when the route comes in. */
-    customers?: readonly NoInfer<Class>[];
     /** Set on import: the site a route was learned at, `asn:function:site`. `sites` names the sites, for the catalogue. */
     learned_at?: {
         function: number;
@@ -73,23 +71,32 @@ export type CommunityScheme<Class extends string = string> = {
     };
     /** Set on import: the AS a route was learned from, `asn:function:asn`. */
     learned_from_as?: number;
-    /** Set by a customer: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
-    do_not_announce?: number;
-    /** Set by a customer: prepend toward an AS once, twice or three times, `asn:function:asn`. */
-    prepend?: {
+    /** A neighbor asks: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
+    do_not_announce?: Request<Class> & {
+        function: number;
+    };
+    /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
+    prepend?: Request<Class> & {
         once?: number;
         twice?: number;
         three_times?: number;
     };
-    /** Set by a customer: drop traffic to the route in your network, before it reaches them, `asn:function:0`. The route is never announced further. */
-    blackhole?: number;
+    /** A neighbor asks: drop traffic to the route in your network, before it reaches them, `asn:function:0`. */
+    blackhole?: Request<Class> & {
+        function: number;
+    };
+};
+/** Something a neighbor can ask you for, and who may. */
+type Request<Class extends string> = {
+    /** The classes allowed to ask for it, from `learned_from.classes`. From anyone else, the request is removed when the route comes in. */
+    trusted: readonly NoInfer<Class>[];
 };
 /**
  * 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 })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A customer, a class in `customers`, keeps its requests. `site` is needed when the scheme has `learned_at`.
+ * - `tag(neighborClass, neighborAs, { site })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A neighbor keeps the requests its class is trusted with. `site` is needed when the scheme has `learned_at`.
  * - `actions(neighborAs, { blackhole })`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept. A blackholed route goes no further, unless `blackhole` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too.
- * - `blackhole(prefixSet)`: a rule for a customer's import policy, before anything that rejects long prefixes. It takes a route the customer asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
+ * - `blackhole(neighborClass, prefixSet)`: a rule for the import policy of a neighbor trusted with blackholes, before anything that rejects long prefixes. It takes a route the neighbor asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
 export declare function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>): {
@@ -100,7 +107,7 @@ export declare function communityScheme<const Class extends string>(scheme: Comm
     actions: (neighborAs: number, options?: {
         blackhole?: string;
     }) => PolicyRule<never, never>[];
-    blackhole: <S extends string>(prefixSet: S) => PolicyRule<never, S>;
+    blackhole: <S extends string>(neighborClass: Class, prefixSet: S) => PolicyRule<never, S>;
     catalogue: Community[];
 };
 /** A member of an internet exchange: a network with a port on the fabric and an address on the peering LAN. */
@@ -138,3 +145,4 @@ export declare function internetExchange<const V extends string>(exchange: Inter
     ports: (device: string) => Record<string, Port<V, string, string, string>>;
     check: Check;
 };
+export {};

package/package.json

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

package/src/adapters/registries/librenms.ts

@@ -0,0 +1,90 @@
+// Keeps LibreNMS in step with the config: every device Circuit manages is monitored there, polled with the SNMP credentials its config gives it. A device LibreNMS holds that the config does not is reported, never deleted.
+
+import type { Network } from "../../core/define";
+import { resolve } from "../../core/secrets";
+import type { Device } from "../../schema";
+
+/** What `librenms` would do. */
+export type LibreNmsPlan = {
+    /** Devices to add. */
+    additions: Device[];
+    /** Devices that cannot be added: their config turns SNMP off. */
+    withoutSnmp: Device[];
+    /** Hostnames LibreNMS holds that no device in the config has. */
+    unknown: string[];
+};
+
+/** LibreNMS's names for the algorithms. */
+const AUTH = { sha1: "SHA", sha256: "SHA-256" } as const;
+const PRIVACY = { aes128: "AES", des: "DES" } as const;
+
+function settingsOf(network: Network) {
+    if (!network.librenms) throw new Error("the network has no librenms settings");
+
+    return {
+        base: `${network.librenms.url.replace(/\/+$/, "")}/api/v0`,
+        // The header every version of API v0 accepts.
+        headers: { "X-Auth-Token": resolve(network.librenms.api_token), "Content-Type": "application/json" },
+    };
+}
+
+/** How LibreNMS polls a device: its first SNMP version 3 user, or else its version 2c community. */
+function credentials(device: Device): Record<string, string> | undefined {
+    const snmp = device.management?.snmp;
+    const [name, user] = Object.entries(snmp?.users ?? {})[0] ?? [];
+
+    if (name && user) {
+        return {
+            snmpver: "v3",
+            authlevel: "authPriv",
+            authname: name,
+            authpass: resolve(user.auth_password),
+            authalgo: AUTH[user.auth],
+            cryptopass: resolve(user.privacy_password),
+            cryptoalgo: PRIVACY[user.privacy],
+        };
+    }
+
+    if (snmp?.community) return { snmpver: "v2c", community: resolve(snmp.community) };
+    return undefined;
+}
+
+/** Compare the config with what LibreNMS monitors. A device is known to LibreNMS by its management address. */
+export async function planLibreNms(network: Network): Promise<LibreNmsPlan> {
+    const { base, headers } = settingsOf(network);
+
+    const response = await fetch(`${base}/devices?type=all`, { headers, signal: AbortSignal.timeout(30_000) });
+    if (!response.ok) throw new Error(`LibreNMS answered ${response.status} to the device list`);
+
+    const monitored = new Set(((await response.json()) as { devices: { hostname: string }[] }).devices.map((device) => device.hostname));
+    const ours = new Set(network.devices.map((device) => device.connection.host));
+    const missing = network.devices.filter((device) => !monitored.has(device.connection.host));
+
+    return {
+        additions: missing.filter((device) => device.management?.snmp),
+        withoutSnmp: missing.filter((device) => !device.management?.snmp),
+        unknown: [...monitored].filter((hostname) => !ours.has(hostname)).sort(),
+    };
+}
+
+/** Add each device, named after its `name` and polled with the credentials from its config. */
+export async function sendLibreNms(network: Network, additions: readonly Device[]): Promise<void> {
+    const { base, headers } = settingsOf(network);
+
+    for (const device of additions) {
+        const body = { hostname: device.connection.host, display_template: device.name, ...credentials(device) };
+        const response = await fetch(`${base}/devices`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(60_000),
+        });
+        const answer = (await response.json().catch(() => ({}))) as { status?: string; message?: string };
+
+        if (!response.ok || answer.status !== "ok") {
+            throw new Error(`${device.name}: LibreNMS refused it: ${answer.message ?? response.status}`);
+        }
+
+        console.log(`  ${device.name}: ${answer.message}`);
+    }
+}

package/src/adapters/registries/prometheus.ts

@@ -0,0 +1,71 @@
+// Prometheus targets for snmp_exporter, in its file-based discovery format, and the `auths` section of its config: one auth per device, named after it, so each device is asked with its own credentials.
+//
+// The auths hold no secret. A password is written as `${NAME}`, the name of its secret, and snmp_exporter reads it from its environment when started with `--config.expand-environment-variables`.
+
+import type { Network } from "../../core/define";
+import type { Device, Secret } from "../../schema";
+
+export type PrometheusTarget = { targets: string[]; labels: Record<string, string> };
+
+/** snmp_exporter's names for the algorithms. */
+const AUTH = { sha1: "SHA", sha256: "SHA256" } as const;
+const PRIVACY = { aes128: "AES", des: "DES" } as const;
+
+/** The targets, and the devices left out because their config turns SNMP off. */
+export function prometheusTargets(network: Network): { targets: PrometheusTarget[]; withoutSnmp: Device[] } {
+    return {
+        targets: network.devices
+            .filter((device) => device.management?.snmp)
+            .map((device) => ({
+                targets: [device.connection.host],
+                // `__param_auth` picks the device's own auth in snmp_exporter.
+                labels: { device: device.name, platform: device.platform, model: device.model, __param_auth: device.name },
+            })),
+        withoutSnmp: network.devices.filter((device) => !device.management?.snmp),
+    };
+}
+
+/** A password as snmp_exporter reads it from its environment, or a note when the secret is a file, which it cannot read. */
+function fromEnvironment(secret: Secret, notes: string[], where: string): string {
+    if ("secret" in secret) return `\${${secret.secret}}`;
+
+    notes.push(`${where} is read from a file; write its value in place of FILL_IN`);
+    return "FILL_IN";
+}
+
+/** The `auths` section, as YAML, and what the operator must still fill in by hand. */
+export function snmpExporterAuths(network: Network): { yaml: string; notes: string[] } {
+    const notes: string[] = [];
+    const lines = [
+        "# Written by `circuit prometheus --auths`. Load it beside snmp.yml, with --config.expand-environment-variables.",
+        "auths:",
+    ];
+
+    for (const device of network.devices) {
+        const snmp = device.management?.snmp;
+        if (!snmp) continue;
+
+        const [name, user] = Object.entries(snmp.users ?? {})[0] ?? [];
+        lines.push(`  ${device.name}:`);
+
+        if (name && user) {
+            lines.push(
+                "    version: 3",
+                `    username: ${name}`,
+                "    security_level: authPriv",
+                `    password: ${fromEnvironment(user.auth_password, notes, `${device.name}'s SNMP password`)}`,
+                `    auth_protocol: ${AUTH[user.auth]}`,
+                `    priv_protocol: ${PRIVACY[user.privacy]}`,
+                `    priv_password: ${fromEnvironment(user.privacy_password, notes, `${device.name}'s SNMP privacy password`)}`
+            );
+        } else {
+            // snmp_exporter reads no community from the environment, and Circuit never writes a secret's value.
+            lines.push("    version: 2", "    community: FILL_IN");
+            notes.push(
+                `${device.name} has only an SNMP version 2c community, which snmp_exporter cannot read from its environment; write it in place of FILL_IN, or give the device a version 3 user`
+            );
+        }
+    }
+
+    return { yaml: lines.join("\n") + "\n", notes };
+}

package/src/cli/index.ts

@@ -7,7 +7,9 @@ import { basename, dirname, join, resolve } from "node:path";
 import { adapters } from "../adapters/devices";
 import type { ApplyOptions, DeviceAdapter, Plan } from "../adapters/devices/types";
 import { registries } from "../adapters/registries";
+import { planLibreNms, sendLibreNms } from "../adapters/registries/librenms";
 import { planPeeringDb, sendPeeringDb } from "../adapters/registries/peeringdb";
+import { prometheusTargets, snmpExporterAuths } from "../adapters/registries/prometheus";
 import { network as prefixOf } from "../core/addr";
 import type { Network } from "../core/define";
 import { isSecret, referenceOf, resolve as reveal, sourceOf, useRoot } from "../core/secrets";
@@ -29,6 +31,9 @@ const HELP = `usage: circuit <command> [device...] [options]
                         a client config for one peer, its private key left for the peer to fill
   communities           the network's BGP communities, one per line, for a looking glass or bgp.tools
   peeringdb             bring PeeringDB's exchange records in line with the config, with --confirm
+  librenms              add every device LibreNMS does not monitor yet, with --confirm
+  prometheus            every device with SNMP, as Prometheus targets for snmp_exporter
+                          --auths        snmp_exporter's auths for them instead, with secrets as \${NAME}
   secrets               every secret the config uses, and whether each can be read
 
   --config <path>       the network's config file, circuit.config.ts in the working directory by default`;
@@ -325,6 +330,41 @@ async function peeringdbCommand(): Promise<void> {
     await sendPeeringDb(network, plan.changes);
 }
 
+async function librenmsCommand(): Promise<void> {
+    const plan = await planLibreNms(network);
+
+    for (const hostname of plan.unknown)
+        console.log(`  LibreNMS monitors ${hostname}, which the config does not. Remove it by hand if it is gone.`);
+    for (const device of plan.withoutSnmp)
+        console.log(`  ${device.name} has no SNMP in its config, so LibreNMS cannot poll it. Add management.snmp first.`);
+    for (const device of plan.additions) console.log(`  add ${device.name}, ${device.connection.host}`);
+
+    if (!plan.additions.length) {
+        console.log("LibreNMS monitors every device it can.");
+        return;
+    }
+
+    if (!confirmed) {
+        console.log("\nNothing sent. Re-run with --confirm.");
+        return;
+    }
+
+    await sendLibreNms(network, plan.additions);
+}
+
+function prometheusCommand(): void {
+    if (flags.includes("--auths")) {
+        const { yaml, notes } = snmpExporterAuths(network);
+        for (const note of notes) console.error(note);
+        process.stdout.write(yaml);
+        return;
+    }
+
+    const { targets, withoutSnmp } = prometheusTargets(network);
+    for (const device of withoutSnmp) console.error(`${device.name} has no SNMP in its config; left out`);
+    console.log(JSON.stringify(targets, null, 4));
+}
+
 /** Every secret reference in a value, however deep. */
 function secretsIn(value: unknown, found = new Set<string>()): Set<string> {
     if (isSecret(value)) found.add(referenceOf(value));
@@ -335,7 +375,7 @@ function secretsIn(value: unknown, found = new Set<string>()): Set<string> {
 }
 
 function secretsCommand(): void {
-    const references = [...secretsIn([network.devices, network.peeringdb])].sort();
+    const references = [...secretsIn([network.devices, network.peeringdb, network.librenms])].sort();
     let missing = 0;
 
     for (const reference of references) {
@@ -365,6 +405,8 @@ const commands: Record<string, () => void | Promise<void>> = {
     wireguard: wireguardCommand,
     communities: communitiesCommand,
     peeringdb: peeringdbCommand,
+    librenms: librenmsCommand,
+    prometheus: prometheusCommand,
     secrets: secretsCommand,
 };
 

package/src/core/define.ts

@@ -86,6 +86,13 @@ export type Network = {
         /** An API key with write access to the network's record. */
         api_key: Secret;
     };
+    /** Keeps LibreNMS monitoring every device: `circuit librenms`. */
+    librenms?: {
+        /** Where LibreNMS is, such as `https://librenms.example.com`. */
+        url: string;
+        /** An API token that can add devices. */
+        api_token: Secret;
+    };
 };
 
 /** Declare the network, in `circuit.config.ts`. */

package/src/presets/index.ts

@@ -226,18 +226,22 @@ export type CommunityScheme<Class extends string = string> = {
     asn: number;
     /** Set on import: the kind of neighbor a route came from, `asn:function:class`. */
     learned_from?: { function: number; classes: Readonly<Record<Class, number>> };
-    /** Which of the classes above are your customers. Only a customer may ask you for something, such as not announcing its route somewhere; what anyone else asks is removed when the route comes in. */
-    customers?: readonly NoInfer<Class>[];
     /** Set on import: the site a route was learned at, `asn:function:site`. `sites` names the sites, for the catalogue. */
     learned_at?: { function: number; sites?: Readonly<Record<number, string>> };
     /** Set on import: the AS a route was learned from, `asn:function:asn`. */
     learned_from_as?: number;
-    /** Set by a customer: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
-    do_not_announce?: number;
-    /** Set by a customer: prepend toward an AS once, twice or three times, `asn:function:asn`. */
-    prepend?: { once?: number; twice?: number; three_times?: number };
-    /** Set by a customer: drop traffic to the route in your network, before it reaches them, `asn:function:0`. The route is never announced further. */
-    blackhole?: number;
+    /** A neighbor asks: do not announce the route to an AS, `asn:function:asn`, or to anyone, `asn:function:0`. */
+    do_not_announce?: Request<Class> & { function: number };
+    /** A neighbor asks: prepend toward an AS once, twice or three times, `asn:function:asn`. */
+    prepend?: Request<Class> & { once?: number; twice?: number; three_times?: number };
+    /** A neighbor asks: drop traffic to the route in your network, before it reaches them, `asn:function:0`. */
+    blackhole?: Request<Class> & { function: number };
+};
+
+/** Something a neighbor can ask you for, and who may. */
+type Request<Class extends string> = {
+    /** The classes allowed to ask for it, from `learned_from.classes`. From anyone else, the request is removed when the route comes in. */
+    trusted: readonly NoInfer<Class>[];
 };
 
 const PREPENDS = [
@@ -251,9 +255,9 @@ const article = (word: string) => (/^[aeiou]/i.test(word) ? `an ${word}` : `a ${
 /**
  * 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 })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A customer, a class in `customers`, keeps its requests. `site` is needed when the scheme has `learned_at`.
+ * - `tag(neighborClass, neighborAs, { site })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A neighbor keeps the requests its class is trusted with. `site` is needed when the scheme has `learned_at`.
  * - `actions(neighborAs, { blackhole })`: rules for an export policy toward one neighbor. They act on a customer's action communities, then remove all of yours. Place them before the rules that accept. A blackholed route goes no further, unless `blackhole` names the neighbor's own blackhole community: then it is passed on with it, so the neighbor drops the traffic too.
- * - `blackhole(prefixSet)`: a rule for a customer's import policy, before anything that rejects long prefixes. It takes a route the customer asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
+ * - `blackhole(neighborClass, prefixSet)`: a rule for the import policy of a neighbor trusted with blackholes, before anything that rejects long prefixes. It takes a route the neighbor asked to blackhole, but only inside `prefixSet`, its own space, and drops traffic to it here.
  * - `catalogue`: every community, for `communities` in `defineNetwork`.
  */
 export function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>) {
@@ -265,9 +269,17 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         (fn): fn is number => fn !== undefined
     );
 
+    // Each request's function numbers, and who may make it.
+    const requests = [
+        { functions: [scheme.do_not_announce?.function], trusted: scheme.do_not_announce?.trusted },
+        { functions: PREPENDS.map(([name]) => scheme.prepend?.[name]), trusted: scheme.prepend?.trusted },
+        { functions: [scheme.blackhole?.function], trusted: scheme.blackhole?.trusted },
+    ].map(({ functions, trusted }) => ({ functions: functions.filter((fn): fn is number => fn !== undefined), trusted: trusted ?? [] }));
+
     const tag = (neighborClass: Class, neighborAs: number, options: { site?: number } = {}): PolicyRule<never, never> => {
         const { site } = options;
-        const isCustomer = scheme.customers?.includes(neighborClass) ?? false;
+        const untrusted = requests.filter((request) => !request.trusted.includes(neighborClass)).flatMap((request) => request.functions);
+        const trustedForAny = requests.some((request) => request.functions.length && request.trusted.includes(neighborClass));
         if (scheme.learned_at && site === undefined)
             throw new Error(`communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
 
@@ -275,7 +287,8 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             description: `Learned from AS${neighborAs}`,
             set: {
                 remove_communities: ours.standard,
-                remove_large_communities: isCustomer ? information.map((fn) => community(fn, "*")) : ours.large,
+                // A neighbor trusted with nothing loses every community of ours it set. One trusted with some requests keeps those, and loses the rest.
+                remove_large_communities: trustedForAny ? [...information, ...untrusted].map((fn) => community(fn, "*")) : ours.large,
                 add_large_communities: [
                     ...(scheme.learned_from ? [community(scheme.learned_from.function, scheme.learned_from.classes[neighborClass])] : []),
                     ...(scheme.learned_at ? [community(scheme.learned_at.function, site!)] : []),
@@ -285,12 +298,14 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         };
     };
 
-    const blackhole = <S extends string>(prefixSet: S): PolicyRule<never, S> => {
+    const blackhole = <S extends string>(neighborClass: Class, prefixSet: S): PolicyRule<never, S> => {
         if (scheme.blackhole === undefined) throw new Error("communityScheme: blackhole needs a function number in the scheme");
+        if (!scheme.blackhole.trusted.includes(neighborClass))
+            throw new Error(`communityScheme: ${neighborClass} is not trusted to ask for a blackhole`);
 
         return {
-            description: "Blackhole, asked by the customer",
-            match: { large_community: community(scheme.blackhole, 0), prefix_set: prefixSet },
+            description: "Blackhole, asked by the neighbor",
+            match: { large_community: community(scheme.blackhole.function, 0), prefix_set: prefixSet },
             set: { blackhole: true },
             action: "accept",
         };
@@ -301,7 +316,7 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             ? [
                   {
                       description: "Blackholed here, never announced",
-                      match: { large_community: community(scheme.blackhole, 0) },
+                      match: { large_community: community(scheme.blackhole.function, 0) },
                       action: "reject" as const,
                   },
               ]
@@ -310,12 +325,12 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             ? [
                   {
                       description: "Asked not to be announced anywhere",
-                      match: { large_community: community(scheme.do_not_announce, 0) },
+                      match: { large_community: community(scheme.do_not_announce.function, 0) },
                       action: "reject" as const,
                   },
                   {
                       description: `Asked not to be announced to AS${neighborAs}`,
-                      match: { large_community: community(scheme.do_not_announce, neighborAs) },
+                      match: { large_community: community(scheme.do_not_announce.function, neighborAs) },
                       action: "reject" as const,
                   },
               ]
@@ -324,7 +339,7 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             ? [
                   {
                       description: `Blackhole passed on to AS${neighborAs}`,
-                      match: { large_community: community(scheme.blackhole, 0) },
+                      match: { large_community: community(scheme.blackhole.function, 0) },
                       set: {
                           remove_communities: ours.standard,
                           remove_large_communities: ours.large,
@@ -371,8 +386,8 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             : []),
         ...(scheme.do_not_announce !== undefined
             ? [
-                  { community: community(scheme.do_not_announce, 0), description: "Do not announce to anyone" },
-                  { community: community(scheme.do_not_announce, "nnn"), description: "Do not announce to AS$0" },
+                  { community: community(scheme.do_not_announce.function, 0), description: "Do not announce to anyone" },
+                  { community: community(scheme.do_not_announce.function, "nnn"), description: "Do not announce to AS$0" },
               ]
             : []),
         ...PREPENDS.flatMap(([name]) => {
@@ -380,7 +395,7 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
             return fn === undefined ? [] : [{ community: community(fn, "nnn"), description: `Prepend ${name.replace("_", " ")} to AS$0` }];
         }),
         ...(scheme.blackhole !== undefined
-            ? [{ community: community(scheme.blackhole, 0), description: `Blackhole: dropped in AS${asn}, not announced further` }]
+            ? [{ community: community(scheme.blackhole.function, 0), description: `Blackhole: dropped in AS${asn}, not announced further` }]
             : []),
     ];