Import rules: preference and communities for some routes only

The import policy did the same to every route of a session. Now `rules`
can do more to some of them: those with certain communities, those for
certain prefixes, or both. Each rule can set the local preference and put
communities on; each route takes the first rule that holds for it.

Rules see a route as the session's own statements leave it, with our
communities taken off and the session's marks put on. So a router can act
on where another router of ours learned a route, by the mark that router
put on it, and a customer's single prefix can be marked for a prepend.

Routes of one UPDATE that different rules hold for go into the table with
attribute sets of their own. An UPDATE that no rule touches is taken as
before, without its attributes being written out again.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

docs/content/docs/guides/import-policy.md

@@ -268,6 +268,81 @@ advertised it. These values do not overlap the
 or the standard communities `64500:n`, which control communities interpret
 as "advertise to AS n".
 
+## Recording Where Routes Are Learned
+
+Informational communities record, on each route, where the local AS
+learned it. Other routers in the local AS, neighbors, and looking glasses
+can then see it, and import rules and control communities can act on it.
+A consistent scheme uses large communities with a function number of 100
+or higher, for example:
+
+| Community | Meaning |
+|---|---|
+| `64500:100:R` | Learned by router `R`. |
+| `64500:101:V` | Learned at venue `V`: an Internet exchange, a transit provider, or customers. |
+| `64500:102:S` | Learned over interconnection `S`. |
+
+Each router adds them with `add_large_communities` on every EBGP session:
+
+```textproto
+peers {
+  name: "exchange-a-rs1-v4"
+  import {
+    add_large_communities: "64500:100:1"
+    add_large_communities: "64500:101:1"
+    add_large_communities: "64500:102:1001"
+  }
+}
+```
+
+The communities are retained on IBGP sessions, so that each router sees
+where the other routers learned their routes. Because Ferrix removes the
+local AS's communities from routes from EBGP neighbors (see
+[Communities of the Local AS](#communities-of-the-local-as)), a neighbor
+cannot set them: every such community on a route was added by a router of
+the local AS.
+
+## Import Rules
+
+Import rules apply local preference and communities to some routes only:
+routes with certain communities, routes for certain prefixes, or both.
+Ferrix evaluates the rules of a session in order, and applies the first
+rule that matches a route. The communities that the rules match are those
+of the route after the session's other import statements are applied, so
+rules can match the session's own informational communities.
+
+The following example, on an IBGP session, prefers routes that the other
+router learned at exchange A over routes that it learned at exchange B,
+and marks the routes of one prefix:
+
+```textproto
+peers {
+  name: "router-2"
+  remote_asn: 64500
+  import {
+    rules { match_communities: "64500:101:1" local_pref: 200 }
+    rules { match_communities: "64500:101:2" local_pref: 130 }
+    rules {
+      match_prefixes { prefix: "192.0.2.0/24" }
+      add_large_communities: "64500:31:10"
+    }
+  }
+}
+```
+
+Routes that the rules do not match keep the local preference that they
+were advertised with. Routes for one prefix that arrive in one UPDATE
+message can match different rules; Ferrix stores each group separately.
+
+> [!TIP]
+> Choose local preferences so that the local AS's outbound traffic leaves
+> through the same venue through which other networks send their traffic
+> in. If a route is preferred at venue A for outbound traffic, use control
+> communities to prepend the local AS number at the venues that are less
+> preferred. Otherwise traffic to and from a network uses different
+> venues, which makes troubleshooting harder and can overload a link that
+> was meant as a fallback.
+
 ## Communities of the Local AS
 
 By default, Ferrix removes the local AS's communities from every route that

docs/content/docs/reference/configuration.md

@@ -111,8 +111,24 @@ accepted. See [Import Policy](@/docs/guides/import-policy.md).
 | `add_large_communities` <span class="type">string, repeated</span> | None | Specifies large communities added to accepted routes, for example `64500:2:1`. |
 | `remove_communities` <span class="type">string, repeated</span> | None | Specifies patterns of communities removed from accepted routes, for example `64500:100`, `64500:*`, or `64500:2:*`. Applied before communities are added. |
 | `local_pref` <span class="type">uint32, optional</span> | 100 | Specifies the local preference of accepted routes. |
+| `rules` <span class="type">[ImportRule](#importrule), repeated</span> | None | Specifies rules for some of the accepted routes. Ferrix applies the first rule that matches a route. See [Import Rules](@/docs/guides/import-policy.md#import-rules). |
 | `accept_control_communities` <span class="type">bool</span> | `false` | Retains the local AS's communities on routes from an EBGP neighbor, so that the neighbor can set control communities on its own routes. By default, Ferrix removes them. Has no effect for an IBGP neighbor. See [Communities of the Local AS](@/docs/guides/import-policy.md#communities-of-the-local-as). |
 
+## ImportRule
+
+A rule for the routes with certain communities or prefixes. A route
+matches a rule if it matches every condition that the rule specifies. The
+communities are those of the route after the other statements of the
+import policy are applied.
+
+| Statement | Default | Description |
+|---|---|---|
+| `match_communities` <span class="type">string, repeated</span> | Any route | Specifies patterns of communities. A route matches if it has a community that matches one of them. The patterns are those of `remove_communities`. |
+| `match_prefixes` <span class="type">[PrefixRange](#prefixrange), repeated</span> | Any prefix | Specifies prefixes. A route matches if its prefix is permitted by one of them. |
+| `local_pref` <span class="type">uint32, optional</span> | Not changed | Specifies the local preference of matching routes. Replaces the `local_pref` of the import policy. |
+| `add_communities` <span class="type">string, repeated</span> | None | Specifies standard communities added to matching routes. |
+| `add_large_communities` <span class="type">string, repeated</span> | None | Specifies large communities added to matching routes. |
+
 ## PrefixRange
 
 A prefix and, optionally, the more specific prefixes within it.