The BGP network statement — origin and exact-match semantics

The BGP network statement is the explicit, intentional way to originate a prefix into BGP. It says: “this prefix is mine; I am willing to advertise it to every BGP peer I have, subject to outbound policy.” On VyOS 1.5 LTS / FRR 10.x the configuration is set protocols bgp address-family ipv4-unicast network <prefix>, and the operator who understands its exact-match semantics and its filtering options can predict the advertisement set without running the protocol.

This lesson is the operator’s reference for the network statement: how it selects prefixes, what it does not do, how to filter it, and how it fails in production.

What the network statement does

The BGP network statement installs a static entry in the BGP Routing Information Base (Loc-RIB) for each prefix that has an exact match in the RIB of the router. The match is exact: network 192.0.2.0/24 matches the RIB entry 192.0.2.0/24 and nothing else. It does not match 192.0.2.0/25 even though that prefix is a subnet of 192.0.2.0/24.

flowchart LR
  RIB["Local RIB\n(connected + static + IGP)"]
  MATCH{"Exact-match\ncheck"}
  STATIC["Static entry in Loc-RIB\n(bgp network)"]
  POLICY["Outbound policy\n(route-map, filter-list,\n prefix-list, community-list)"]
  PEER["BGP peer\n(eBGP / iBGP)"]

  RIB --> MATCH
  MATCH -- "exact match found" --> STATIC
  MATCH -- "no match" --> X["Drop\n(advertisement does not happen)"]
  STATIC --> POLICY
  POLICY --> PEER

The advertisement flow:

1. Static entry — When the operator commits set protocols bgp address-family ipv4-unicast network <prefix>, FRR creates a static entry in the BGP Loc-RIB for that prefix.
2. Existence check — Each time the RIB changes (a route appears, disappears, or is updated), bgpd scans its configured network entries. If the exact prefix exists in the RIB (any source — connected, static, OSPF, IS-IS), the static entry becomes active. If the RIB entry disappears, the static entry is withdrawn.
3. Best path — The static entry participates in the BGP best-path algorithm like any other route.
4. Outbound policy — The route is filtered through outbound policy (route-map, prefix-list, filter-list, distribute-list, community-list, AS-path filter). If the outbound policy rejects the prefix, it is not advertised.
5. Update message — Surviving prefixes are packed into UPDATE messages and sent to each peer that is allowed to receive them.

Where the statement lives in the 1.5 tree

VyOS 1.4 (sagitta) restructured the BGP tree and 1.5 (circinus) kept the new shape. Three things moved, and the network statement is one of them:

This is not a rename. The prefix moved under an address family, which is why the same tree gives you IPv6 origination without a second command family:

set protocols bgp address-family ipv4-unicast network 192.0.2.0/24
set protocols bgp address-family ipv6-unicast network 2001:db8::/48

Under the 1.3 tree an IPv6 network was reached through a separate address-family ipv6-unicast node hanging off the ASN; under 1.5 the ASN is out of the path entirely and both families are siblings. A 1.3-era command pasted into a 1.5 router does not warn you that the tree moved — it fails at commit with a configuration-path error, which is the good case.

The VyOS configuration

The canonical configuration is one line per prefix. The prefix includes the mask.

configure
set protocols bgp system-as 64512
set protocols bgp neighbor 10.0.0.2 remote-as 64513
set protocols bgp address-family ipv4-unicast network 192.0.2.0/24
set protocols bgp address-family ipv4-unicast network 198.51.100.0/24
commit
save

system-as is mandatory. A BGP stanza without one fails verification at commit rather than committing a half-configured process.

After commit, the BGP table should show the two prefixes as *> (valid, best) entries with an empty AS path (locally originated) and an origin code of i (IGP).

$ show ip bgp

   Network          Next Hop            Metric LocPrf Weight Path
*> 192.0.2.0/24     0.0.0.0                  0         32768 i
*> 198.51.100.0/24  0.0.0.0                  0         32768 i

Three columns are the signature of a locally originated network statement, and they are the part worth reading rather than the banner above them: a next hop of 0.0.0.0 (this router is the origin), a weight of 32768 (FRR’s weight for self-originated routes), and an empty Path column with origin code i. FRR defaults network-originated prefixes to origin IGP; the redistribute family defaults to incomplete (?), because the route did not come from an IGP as far as BGP is concerned.

Exact-match semantics

The exact-match rule is the most common source of confusion.

The mask in the network statement is a prefix length, not a “minimum mask” or “summary mask”. To advertise both /24 and /25 of 192.0.2.0, the operator configures two separate network statements:

set protocols bgp address-family ipv4-unicast network 192.0.2.0/24
set protocols bgp address-family ipv4-unicast network 192.0.2.0/25

Optional route-map filtering

The network statement carries a route-map node of its own — it is a child of the prefix, not of the address family — which lets the operator apply per-prefix policy at the point of origination:

set policy route-map ADVERTISE-ONLY-V4 rule 10 action permit
set policy route-map ADVERTISE-ONLY-V4 rule 10 match interface eth0

set protocols bgp address-family ipv4-unicast network 192.0.2.0/24 route-map ADVERTISE-ONLY-V4

The route-map is matched against the route being installed into the Loc-RIB. A permit allows the route; a deny causes the route to be skipped. This is the right place to apply:

• Source interface — only originate from a specific connected interface (match interface eth0).
• Prefix list — only originate prefixes in an allow-list.
• Community — tag the originating route with a community before advertising.
• Metric — set the MED on the originated route.

# A common production pattern: only advertise if the prefix
# is in the allow-list, and stamp it with a community
set policy prefix-list CUSTOMER-V4 rule 10 action permit
set policy prefix-list CUSTOMER-V4 rule 10 prefix 192.0.2.0/24
set policy prefix-list CUSTOMER-V4 rule 20 action permit
set policy prefix-list CUSTOMER-V4 rule 20 prefix 198.51.100.0/24

set policy route-map ORIGINATE rule 10 action permit
set policy route-map ORIGINATE rule 10 match ip address prefix-list CUSTOMER-V4
set policy route-map ORIGINATE rule 10 set community 64512:100 additive

set protocols bgp address-family ipv4-unicast network 192.0.2.0/24 route-map ORIGINATE
set protocols bgp address-family ipv4-unicast network 198.51.100.0/24 route-map ORIGINATE

Note the two prefix-list rules. A prefix-list rule holds one prefix; writing a second prefix under the same rule number replaces the first rather than adding to it, and the resulting list quietly matches half of what the operator intended.

set community without additive replaces the route’s community list rather than appending to it. On a network-originated prefix there is usually nothing to preserve, so either form works — but keep the habit, because the same route-map reused on a received route would strip the sender’s communities.

network vs redistribute connected

There are two ways to advertise locally attached prefixes into BGP, and the choice has consequences.

Use network when:

• The operator wants explicit, auditable prefix origination.
• The operator wants to control which prefixes are advertised via a route-map.
• The originating prefixes are stable and known at configuration time.

Use redistribute connected when:

• The operator wants all connected routes advertised with no per-prefix configuration.
• The number of prefixes is small and the operator has a tight outbound prefix-list that limits the blast radius.

The classic production anti-pattern: redistribute connected without a filter. A new interface brought up by the operator (an out-of-band management subnet, a DMZ, an accidentally-created tunnel endpoint) is silently advertised to every BGP peer. The fix is either to switch to explicit network statements, or to combine redistribute connected with a route-map on the redistribution itself:

# Safer pattern: redistribute connected with a route-map filter
set policy prefix-list BGP-OUT-CONNECTED rule 10 action permit
set policy prefix-list BGP-OUT-CONNECTED rule 10 prefix 192.0.2.0/24
set policy prefix-list BGP-OUT-CONNECTED rule 20 action permit
set policy prefix-list BGP-OUT-CONNECTED rule 20 prefix 198.51.100.0/24

set policy route-map CONNECTED-OUT rule 10 action permit
set policy route-map CONNECTED-OUT rule 10 match ip address prefix-list BGP-OUT-CONNECTED

set protocols bgp address-family ipv4-unicast redistribute connected route-map CONNECTED-OUT

A VyOS route-map ends with an implicit deny, so the single permit rule above is also the deny-everything-else that makes the pattern safe. That is easy to rely on by accident and hard to read later; an explicit high-numbered rule 100 action deny costs nothing and makes the intent visible in compare.

Validation

The standard validation sequence:

# 1. The prefix is in the local RIB
show ip route 192.0.2.0/24

# 2. The BGP table has a static entry
show ip bgp 192.0.2.0/24

# 3. The peer is receiving the prefix
show ip bgp neighbors 10.0.0.2 advertised-routes

# 4. Which policy is attached to the peer, and what it does
show ip bgp neighbors 10.0.0.2
show policy route-map ORIGINATE

The advertised-routes view is the proof. If the prefix is in the local BGP table but not in advertised-routes, an outbound route-map or prefix-list is rejecting it.

Step 4 is where operators reach for a command that does not exist. There is no single “show me the effective policy for this peer” view. The neighbour detail from show ip bgp neighbors 10.0.0.2 names the route-maps attached in each direction, and show policy route-map <name> prints what that map does; you join the two yourself. show configuration commands | match route-map is the fastest way to see every attachment point at once.

$ show ip bgp neighbors 10.0.0.2 advertised-routes

   Network          Next Hop            Metric LocPrf Weight Path
*> 192.0.2.0/24     0.0.0.0                  0         32768 i
*> 198.51.100.0/24  0.0.0.0                  0         32768 i

Total number of prefixes 2

The mirror-image command, show ip bgp neighbors <peer> received-routes, is the one that surprises people: it returns nothing unless the peer is configured with set protocols bgp neighbor <peer> address-family ipv4-unicast soft-reconfiguration inbound, because without it FRR keeps no copy of the pre-policy input. ... neighbors <peer> routes (post-policy) always works and is usually what you actually wanted.

Failure modes

network does not produce an advertisement

The most common production failure. The configuration is correct, the peer is Established, but the prefix is not in advertised-routes.

Diagnostic path:

1. Is the prefix in the RIB? show ip route 192.0.2.0/24. If not, the network statement has nothing to advertise. Fix the missing RIB entry (the connected interface is down, the static route was removed, the OSPF adjacency is broken).
2. Is the BGP table aware? show ip bgp 192.0.2.0/24. If the prefix is absent, FRR has not installed the static entry. This usually means the network statement’s mask does not match the RIB (see exact-match above), or the statement was committed under the wrong address family.
3. Is outbound policy rejecting it? Compare show ip bgp 192.0.2.0/24 with show ip bgp neighbors 10.0.0.2 advertised-routes. Present in the first and absent from the second means an outbound route-map is denying it; read the map with show policy route-map <name>.
4. Is the peer up? show ip bgp summary. If the peer is not Established, no advertisements are flowing.

Prefix is advertised but peer rejects it

The peer receives the UPDATE but does not install the route.

Diagnostic:

• On the peering router, show ip bgp <prefix> — does the peer have the prefix at all?
• If the peer is a VyOS box you control, show ip bgp neighbors <peer> routes shows what survived its inbound policy.
• The peer’s inbound prefix-list may be filtering it, or its inbound policy may require a community the originator is not setting.

Two network statements for the same prefix

Committing set protocols bgp address-family ipv4-unicast network 192.0.2.0/24 twice is idempotent — the configuration tree holds one node, and the second set is a no-op rather than an error.

The same is true of the route-map under it, and that is the part that catches people: route-map is a single-value leaf under the prefix. Setting it a second time with a different name replaces the first, silently and with no error at commit. There is no “both route-maps apply” and no “the first one wins” — the tree simply cannot hold two. An operator who wants two policies on one originated prefix is using the wrong tool; combine the logic into one route-map with two rules, or originate through aggregate-address instead.

Rollback

# Drop the network statement
delete protocols bgp address-family ipv4-unicast network 198.51.100.0/24
commit

# Or roll back the entire configuration to the previous revision
rollback 1

# If the change broke production: reload the last known-good file
load /config/backup/bgp-known-good.conf
commit

rollback 1 loads the previous revision into the candidate configuration and, on VyOS 1.4 and later, prompts for the reboot or commit that applies it — it is not a one-word undo, so read what it tells you before answering.

network is a low-risk change. The worst-case behaviour is “the prefix is not advertised”. The rollback path is straightforward: delete the network statement, commit. The peers receive a withdrawal for the prefix on the next update cycle.

Production discipline

Cross-course references

• Part XXIII (XXIII-VyOS-BGPFund) covers the BGP RIB and best-path algorithm that consume the network static entry.
• Part XXIV (XXIV-VyOS-BGPSessions) covers the peer session state machine and the Established state that gates UPDATE sending.
• Part XXVI (XXVI-VyOS-BGPAttributes) covers the origin attribute (always i for network) and other attributes that interact with the advertisement.
• Part XXVIII (XXVIII-VyOS-BGPPrefixFilter) covers the outbound prefix-list and route-map that filter the advertisement.
• Part XXXIII (XXXIII-VyOS-RoutePolicy) covers the route-map primitives that the network filter references.

Quiz