@takodotid/circuit 0.14.0 → 0.16.0

package/dist/cli/index.js

@@ -3502,15 +3502,46 @@ 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 }
+      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";
@@ -3870,6 +3901,7 @@ var HELP = `usage: circuit <command> [device...] [options]
   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`;
@@ -4124,6 +4156,13 @@ Nothing sent. Re-run with --confirm.`);
   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`);

package/dist/presets/index.js

@@ -161,15 +161,14 @@ function communityScheme(scheme) {
   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 tag = (neighborClass, neighborAs, options = {}) => {
-    const { site } = options;
-    const isCustomer = scheme.customers?.includes(neighborClass) ?? false;
+    const { site, trusted = false } = options;
     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: trusted ? information.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,65 +177,69 @@ function communityScheme(scheme) {
       }
     };
   };
-  const blackhole = (prefixSet) => {
-    if (scheme.blackhole === undefined)
+  const blackhole = (prefixSets) => {
+    const fn = scheme.blackhole?.function;
+    if (fn === undefined)
       throw new Error("communityScheme: blackhole needs a function number in the scheme");
-    return {
-      description: "Blackhole, asked by the customer",
-      match: { large_community: community(scheme.blackhole, 0), prefix_set: prefixSet },
+    return prefixSets.map((prefixSet) => ({
+      description: "Blackhole, asked by the neighbor",
+      match: { large_community: community(fn, 0), prefix_set: prefixSet },
       set: { blackhole: true },
       action: "accept"
-    };
+    }));
   };
-  const actions = (neighborAs, options = {}) => [
-    ...scheme.blackhole !== undefined && !options.blackhole ? [
-      {
-        description: "Blackholed here, never announced",
-        match: { large_community: community(scheme.blackhole, 0) },
-        action: "reject"
-      }
-    ] : [],
-    ...scheme.do_not_announce !== undefined ? [
-      {
-        description: "Asked not to be announced anywhere",
-        match: { large_community: community(scheme.do_not_announce, 0) },
-        action: "reject"
-      },
-      {
-        description: `Asked not to be announced to AS${neighborAs}`,
-        match: { large_community: community(scheme.do_not_announce, neighborAs) },
-        action: "reject"
-      }
-    ] : [],
-    ...scheme.blackhole !== undefined && options.blackhole ? [
-      {
-        description: `Blackhole passed on to AS${neighborAs}`,
-        match: { large_community: community(scheme.blackhole, 0) },
-        set: {
-          remove_communities: ours.standard,
-          remove_large_communities: ours.large,
-          add_communities: [options.blackhole]
+  const actions = (neighborAs) => {
+    const passOn = scheme.blackhole?.upstreams?.[neighborAs];
+    return [
+      ...scheme.blackhole !== undefined && !passOn ? [
+        {
+          description: "Blackholed here, never announced",
+          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) },
+          action: "reject"
         },
-        action: "accept"
-      }
-    ] : [],
-    ...PREPENDS.flatMap(([name, times]) => {
-      const fn = scheme.prepend?.[name];
-      if (fn === undefined)
-        return [];
-      return [
         {
-          description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
-          match: { large_community: community(fn, neighborAs) },
-          set: { prepend: times }
+          description: `Asked not to be announced to AS${neighborAs}`,
+          match: { large_community: community(scheme.do_not_announce, neighborAs) },
+          action: "reject"
         }
-      ];
-    }),
-    {
-      description: "Our communities stay inside our network",
-      set: { remove_communities: ours.standard, remove_large_communities: ours.large }
-    }
-  ];
+      ] : [],
+      ...scheme.blackhole !== undefined && passOn ? [
+        {
+          description: `Blackhole passed on to AS${neighborAs}`,
+          match: { large_community: community(scheme.blackhole.function, 0) },
+          set: {
+            remove_communities: ours.standard,
+            remove_large_communities: ours.large,
+            add_communities: [passOn]
+          },
+          action: "accept"
+        }
+      ] : [],
+      ...PREPENDS.flatMap(([name, times]) => {
+        const fn = scheme.prepend?.[name];
+        if (fn === undefined)
+          return [];
+        return [
+          {
+            description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
+            match: { large_community: community(fn, neighborAs) },
+            set: { prepend: times }
+          }
+        ];
+      }),
+      {
+        description: "Our communities stay inside our network",
+        set: { remove_communities: ours.standard, remove_large_communities: ours.large }
+      }
+    ];
+  };
   const catalogue = [
     ...Object.entries(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
       community: community(scheme.learned_from.function, value),
@@ -258,7 +261,12 @@ function communityScheme(scheme) {
       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: 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`
+      }
+    ] : []
   ];
   return { community, tag, actions, blackhole, catalogue };
 }

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

@@ -9,3 +9,8 @@ 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/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,34 +71,40 @@ 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`. */
+    /** A neighbor asks: 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`. */
+    /** A neighbor asks: 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: 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.
+     */
+    blackhole?: {
+        function: number;
+        upstreams?: Readonly<Record<number, string>>;
+    };
 };
 /**
  * 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, trusted })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A `trusted` neighbor keeps its requests: do not announce, prepend, blackhole. `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(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`.
  */
 export declare function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>): {
     community: (fn: number, parameter: number | string) => string;
     tag: (neighborClass: Class, neighborAs: number, options?: {
         site?: number;
+        trusted?: boolean;
     }) => PolicyRule<never, never>;
-    actions: (neighborAs: number, options?: {
-        blackhole?: string;
-    }) => PolicyRule<never, never>[];
-    blackhole: <S extends string>(prefixSet: S) => PolicyRule<never, S>;
+    actions: (neighborAs: number) => PolicyRule<never, never>[];
+    blackhole: <S extends string>(prefixSets: readonly 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. */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@takodotid/circuit",
-    "version": "0.14.0",
+    "version": "0.16.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/prometheus.ts

@@ -1,10 +1,16 @@
-// Prometheus targets for snmp_exporter, in its file-based discovery format: one entry per device that answers SNMP, labelled with what the config knows about it.
+// 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 } from "../../schema";
+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 {
@@ -12,8 +18,54 @@ export function prometheusTargets(network: Network): { targets: PrometheusTarget
             .filter((device) => device.management?.snmp)
             .map((device) => ({
                 targets: [device.connection.host],
-                labels: { device: device.name, platform: device.platform, model: device.model },
+                // `__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

@@ -9,7 +9,7 @@ import type { ApplyOptions, DeviceAdapter, Plan } from "../adapters/devices/type
 import { registries } from "../adapters/registries";
 import { planLibreNms, sendLibreNms } from "../adapters/registries/librenms";
 import { planPeeringDb, sendPeeringDb } from "../adapters/registries/peeringdb";
-import { prometheusTargets } from "../adapters/registries/prometheus";
+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";
@@ -33,6 +33,7 @@ const HELP = `usage: circuit <command> [device...] [options]
   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`;
@@ -352,6 +353,13 @@ async function librenmsCommand(): Promise<void> {
 }
 
 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));

package/src/presets/index.ts

@@ -226,18 +226,20 @@ 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`. */
+    /** A neighbor asks: 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`. */
+    /** A neighbor asks: 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: 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.
+     */
+    blackhole?: { function: number; upstreams?: Readonly<Record<number, string>> };
 };
 
 const PREPENDS = [
@@ -251,9 +253,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, trusted })`: a rule for an import policy. It removes your communities a neighbor set, then adds where the route was learned. A `trusted` neighbor keeps its requests: do not announce, prepend, blackhole. `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(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`.
  */
 export function communityScheme<const Class extends string>(scheme: CommunityScheme<Class>) {
@@ -265,9 +267,12 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         (fn): fn is number => fn !== undefined
     );
 
-    const tag = (neighborClass: Class, neighborAs: number, options: { site?: number } = {}): PolicyRule<never, never> => {
-        const { site } = options;
-        const isCustomer = scheme.customers?.includes(neighborClass) ?? false;
+    const tag = (
+        neighborClass: Class,
+        neighborAs: number,
+        options: { site?: number; trusted?: boolean } = {}
+    ): PolicyRule<never, never> => {
+        const { site, trusted = false } = options;
         if (scheme.learned_at && site === undefined)
             throw new Error(`communityScheme: tag for AS${neighborAs} needs a site, for learned_at`);
 
@@ -275,7 +280,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 trusted neighbor keeps its requests and loses only the "where it came from" tags, which are ours to set. Anyone else loses every community of ours.
+                remove_large_communities: trusted ? information.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,72 +291,78 @@ export function communityScheme<const Class extends string>(scheme: CommunitySch
         };
     };
 
-    const blackhole = <S extends string>(prefixSet: S): PolicyRule<never, S> => {
-        if (scheme.blackhole === undefined) throw new Error("communityScheme: blackhole needs a function number in the scheme");
+    const blackhole = <S extends string>(prefixSets: readonly S[]): PolicyRule<never, S>[] => {
+        const fn = scheme.blackhole?.function;
+        if (fn === undefined) throw new Error("communityScheme: blackhole needs a function number in the scheme");
 
-        return {
-            description: "Blackhole, asked by the customer",
-            match: { large_community: community(scheme.blackhole, 0), prefix_set: prefixSet },
+        return prefixSets.map((prefixSet) => ({
+            description: "Blackhole, asked by the neighbor",
+            match: { large_community: community(fn, 0), prefix_set: prefixSet },
             set: { blackhole: true },
             action: "accept",
-        };
+        }));
     };
 
-    const actions = (neighborAs: number, options: { blackhole?: string } = {}): PolicyRule<never, never>[] => [
-        ...(scheme.blackhole !== undefined && !options.blackhole
-            ? [
-                  {
-                      description: "Blackholed here, never announced",
-                      match: { large_community: community(scheme.blackhole, 0) },
-                      action: "reject" as const,
-                  },
-              ]
-            : []),
-        ...(scheme.do_not_announce !== undefined
-            ? [
-                  {
-                      description: "Asked not to be announced anywhere",
-                      match: { large_community: community(scheme.do_not_announce, 0) },
-                      action: "reject" as const,
-                  },
-                  {
-                      description: `Asked not to be announced to AS${neighborAs}`,
-                      match: { large_community: community(scheme.do_not_announce, neighborAs) },
-                      action: "reject" as const,
-                  },
-              ]
-            : []),
-        ...(scheme.blackhole !== undefined && options.blackhole
-            ? [
-                  {
-                      description: `Blackhole passed on to AS${neighborAs}`,
-                      match: { large_community: community(scheme.blackhole, 0) },
-                      set: {
-                          remove_communities: ours.standard,
-                          remove_large_communities: ours.large,
-                          add_communities: [options.blackhole],
+    const actions = (neighborAs: number): PolicyRule<never, never>[] => {
+        // The upstream's own blackhole community, when it takes blackholes from us.
+        const passOn = scheme.blackhole?.upstreams?.[neighborAs];
+
+        return [
+            ...(scheme.blackhole !== undefined && !passOn
+                ? [
+                      {
+                          description: "Blackholed here, never announced",
+                          match: { large_community: community(scheme.blackhole.function, 0) },
+                          action: "reject" as const,
                       },
-                      action: "accept" as const,
-                  },
-              ]
-            : []),
-        ...PREPENDS.flatMap(([name, times]) => {
-            const fn = scheme.prepend?.[name];
-            if (fn === undefined) return [];
-
-            return [
-                {
-                    description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
-                    match: { large_community: community(fn, neighborAs) },
-                    set: { prepend: times },
-                },
-            ];
-        }),
-        {
-            description: "Our communities stay inside our network",
-            set: { remove_communities: ours.standard, remove_large_communities: ours.large },
-        },
-    ];
+                  ]
+                : []),
+            ...(scheme.do_not_announce !== undefined
+                ? [
+                      {
+                          description: "Asked not to be announced anywhere",
+                          match: { large_community: community(scheme.do_not_announce, 0) },
+                          action: "reject" as const,
+                      },
+                      {
+                          description: `Asked not to be announced to AS${neighborAs}`,
+                          match: { large_community: community(scheme.do_not_announce, neighborAs) },
+                          action: "reject" as const,
+                      },
+                  ]
+                : []),
+            ...(scheme.blackhole !== undefined && passOn
+                ? [
+                      {
+                          description: `Blackhole passed on to AS${neighborAs}`,
+                          match: { large_community: community(scheme.blackhole.function, 0) },
+                          set: {
+                              remove_communities: ours.standard,
+                              remove_large_communities: ours.large,
+                              add_communities: [passOn],
+                          },
+                          action: "accept" as const,
+                      },
+                  ]
+                : []),
+            ...PREPENDS.flatMap(([name, times]) => {
+                const fn = scheme.prepend?.[name];
+                if (fn === undefined) return [];
+
+                return [
+                    {
+                        description: `Asked to prepend ${name.replace("_", " ")} to AS${neighborAs}`,
+                        match: { large_community: community(fn, neighborAs) },
+                        set: { prepend: times },
+                    },
+                ];
+            }),
+            {
+                description: "Our communities stay inside our network",
+                set: { remove_communities: ours.standard, remove_large_communities: ours.large },
+            },
+        ];
+    };
 
     const catalogue: Community[] = [
         ...Object.entries<number>(scheme.learned_from?.classes ?? {}).map(([name, value]) => ({
@@ -380,7 +392,14 @@ 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: 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`,
+                  },
+              ]
             : []),
     ];