Static route options — tag, description, on-link, VRF, disable

The set protocols static route tree in VyOS 1.5 LTS has more attributes than the canonical next-hop and interface. The production operator needs tag to mark routes for redistribution policy, description to document the route in the running configuration, on-link to handle a next-hop outside the connected subnet, vrf to bind a route to a non-default routing table, and disable to keep a route in the configuration without activating it. This lesson walks through each attribute, the configuration idiom, and the operational impact.

What the static route attributes are

flowchart TD
  A[Static route<br/>10.20.0.0/16] --> B[Required: prefix]
  A --> C[Required: next-hop or interface]
  A --> D[Optional attributes]
  D --> D1[tag 0-65535]
  D --> D2[description text]
  D --> D3[on-link]
  D --> D4[vrf name]
  D --> D5[distance 0-255]
  D --> D6[metric 0-4294967295]
  D --> D7[disable]
  D --> D8[blackhole]
  D --> D9[reject]

The set protocols static route <prefix> command takes a prefix and a sequence of attribute nodes. The required attributes are the prefix and at least one of next-hop or interface. The optional attributes modify the route’s behaviour without changing the prefix or the next-hop.

Tag — for redistribution policy

The tag attribute is a 16-bit integer that travels with the route through the RIB. It is preserved when the route is redistributed into a dynamic protocol (BGP, OSPF). Route policy can match on the tag and decide whether to accept or modify the route.

[edit]
vyos@vyos# set protocols static route 10.20.0.0/16 next-hop 192.0.2.2 tag 65001
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

The route is tagged with 65001. When the route is redistributed into OSPF or BGP, the tag is carried as an OSPF external-route tag or a BGP community.

[edit]
vyos@vyos# set policy route-map RM-STATIC-TO-BGP rule 10 action permit
[edit]
vyos@vyos# set policy route-map RM-STATIC-TO-BGP rule 10 match tag 65001
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

The route-map matches on the tag and permits the route. The tag-based filter is a clean way to mark a subset of static routes for redistribution without listing each prefix in a prefix-list.

The tag is a number 0-65535. Production tags are typically an AS number (65001) or a service identifier (100, 200). A common mistake is to use the same tag for unrelated routes across multiple sites; the tag is router-local, not global, but a global convention helps when the routes are exchanged.

Description — for operational documentation

The description attribute is a free-text annotation that appears in the VyOS configuration tree but not in FRR. It is the operator’s primary mechanism for documenting why a route exists and who owns it.

[edit]
vyos@vyos# set protocols static route 10.20.0.0/16 next-hop 192.0.2.2 description 'CR-1234 upstream-primary to dc01-eu'
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

show configuration protocols static shows the description:

vyos@vyos:~$ show configuration protocols static
route 10.20.0.0/16 {
    next-hop 192.0.2.2
    description "CR-1234 upstream-primary to dc01-eu"
}

The description is searchable in show configuration | match. A new operator reviewing the configuration can read the description and know that this route was added under change request CR-1234 and points to the primary upstream for the EU data centre. Without the description, the operator sees a bare IP address and no context.

The convention in many teams is to include the change-request identifier, the upstream or destination name, and the date. The description is the documentation that survives the operator who wrote it.

On-link — for off-subnet next-hops

The on-link attribute tells the kernel to install the static route even if the next-hop is not on a connected subnet. Without on-link, the kernel performs a recursive lookup to find the egress interface; if the next-hop is not on a connected subnet, the route is inactive.

[edit]
vyos@vyos# set protocols static route 10.20.0.0/16 next-hop 192.0.2.2 on-link
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

The on-link attribute renders as the onlink keyword on the ip route line. The kernel installs the route and forwards packets to the next-hop using the egress interface specified in the route (or determined by the kernel’s on-link handling).

VRF — for table isolation

The vrf attribute binds a static route to a non-default routing table. The route is installed in the named VRF’s table, not in the default table. Traffic in the default table does not see the route; traffic in the VRF does.

[edit]
vyos@vyos# set vrf name customer-a table 1000
[edit]
vyos@vyos# set protocols static route 10.20.0.0/16 next-hop 192.0.2.2 vrf customer-a
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

The route is in the customer-a VRF. The egress interface must be assigned to the VRF (typically with set interfaces ethernet eth0 vrf customer-a).

show ip route vrf customer-a shows the route:

vyos@vyos:~$ show ip route vrf customer-a
S>* 10.20.0.0/16 [1/0] via 192.0.2.2, eth0

The route is in the VRF table, not in the default table. The default table does not see 10.20.0.0/16; only traffic that arrives on a customer-a-bound interface consults this table.

The VRF attribute is the standard way to isolate customer traffic in a multi-tenant router. A failure of one VRF’s routing does not affect the other VRFs. The operational discipline is to verify the egress interface is in the right VRF; a static route to the right prefix with the wrong VRF attribute is installed in the wrong table and is invisible to the intended traffic.

Disable — for staged rollout

The disable attribute keeps the route in the configuration but does not render it to FRR. The route is absent from FRR’s RIB; the kernel does not see it.

[edit]
vyos@vyos# set protocols static route 10.20.0.0/16 next-hop 192.0.2.2 disable
[edit]
vyos@vyos# commit
[edit]
vyos@vyos# save

show configuration protocols static shows the route. show ip route static does not.

The disable attribute is the operator’s mechanism for staged rollout. A team can write the full configuration for a new upstream or a new failover partner, but keep the new route disabled until the change is ready. On the day of the change, the operator removes disable and commits; the new route activates without re-typing the configuration.

How the result is validated

The validation command set depends on which attributes are in use.

For the basic attributes (next-hop, distance, metric):

show ip route static
ip route show

For the VRF attribute:

show ip route vrf <name>
show vrf name <name>

For the disable attribute:

show configuration protocols static
show ip route static

The first shows the route in the configuration (with disable). The second does not show the route in the RIB. The two views must agree for the operator to know the intended state.

For the on-link attribute:

ip route show

The route appears with the onlink flag in the kernel.

How it fails

The production failure modes the engineer must recognise:

• Tag not matching the policy. The route is redistributed but the receiving protocol’s policy does not match the tag. The route is filtered out at the redistribution point.
• Description absent. A new operator sees a bare configuration with no context. The route is deleted during cleanup because the operator does not know what it does.
• On-link to wrong next-hop. The route is installed regardless of next-hop reachability. Traffic is sent to a next-hop that does not respond; packets are dropped.
• VRF mismatch. A static route bound to a VRF whose egress interface is in a different VRF. The route is installed in the right table but the egress is wrong; the route is inactive.
• Disable forgotten. A new route is added with disable for staging but the operator forgets to remove disable on the change day. The route is in the configuration but not in the FIB; traffic is blackholed.

Rollback

The recovery from a bad attribute configuration:

• Wrong tag: set protocols static route <prefix> tag <correct>; commit; save.
• Wrong description: delete protocols static route <prefix> description; commit; save.
• Wrong on-link: delete protocols static route <prefix> on-link; commit; save.
• Wrong VRF: delete protocols static route <prefix> vrf; set protocols static route <prefix> vrf <correct>; commit; save.
• Disable forgotten: delete protocols static route <prefix> disable; commit; save.

For emergency rollback of the entire route, delete protocols static route <prefix>; commit; save. For whole-tree rollback, rollback N; commit; save.

Production discipline

Cross-course references

The BGP course’s XXXIII-RoutePolicy covers the route-map and prefix-list mechanisms that match on tag. The VRF course’s XV-VRF covers table isolation in depth. The Multi-WAN course’s XXXIX-Multi-WAN covers on-link in the transit-network scenario. The Linux course’s V-Linux-NetConfig covers the equivalent ip route attributes.

Quiz