Berik Ashimov
Senior IT Engineer

Configuration Standards: Naming, Comments, Structure That Scales

· 8 min read
#vyos #networking

Look at a router config written three years ago. Can you understand what each rule does? Who added it? Why? If the answer is “no,” you have a maintenance problem.

Configuration standards aren’t bureaucracy. They’re the difference between “I can fix this in 5 minutes” and “I need to reverse-engineer 500 rules to understand what might break.”

Good config is self-documenting. Bad config is a puzzle box that only its creator could solve — and they left the company.

Naming Conventions

Interface Descriptions

Terminal window
# Bad: No description
set interfaces ethernet eth0


# Bad: Useless description
set interfaces ethernet eth0 description "interface 0"


# Good: Purpose and destination
set interfaces ethernet eth0 description "WAN: ISP-Acme-1Gbps-Circuit-12345"
set interfaces ethernet eth1 description "LAN: Server-VLAN-10.0.0.0/24"
set interfaces ethernet eth2 description "MGMT: OOB-Management-172.16.0.0/24"


# Pattern: <ZONE>: <Purpose>-<Details>

VLAN Naming

Terminal window
# Include VLAN ID in description for clarity
set interfaces ethernet eth0 vif 100 description "VLAN100: Production-Servers"
set interfaces ethernet eth0 vif 200 description "VLAN200: Development"
set interfaces ethernet eth0 vif 999 description "VLAN999: Quarantine-Untrusted"

Firewall Names

Terminal window
# Pattern: <FROM-ZONE>-<TO-ZONE> or <INTERFACE>-<DIRECTION>


# Zone-based naming
set firewall ipv4 name WAN-TO-LAN ...
set firewall ipv4 name LAN-TO-WAN ...
set firewall ipv4 name DMZ-TO-LAN ...


# Interface-based naming
set firewall ipv4 name ETH0-IN ...
set firewall ipv4 name ETH0-OUT ...
set firewall ipv4 name ETH0-LOCAL ...


# Pick one pattern, use it consistently

Firewall Rule Numbering

Terminal window
# Reserve ranges for different purposes:
# 1-99:     Critical infrastructure rules
# 100-199:  Management access
# 200-499:  Application rules
# 500-899:  User rules
# 900-998:  Logging/monitoring rules
# 999:      Default deny (explicit)


set firewall ipv4 name WAN-IN rule 10 description "Allow established"
set firewall ipv4 name WAN-IN rule 100 description "Management: SSH from admin nets"
set firewall ipv4 name WAN-IN rule 200 description "App: Web servers HTTP/HTTPS"
set firewall ipv4 name WAN-IN rule 999 description "Default: Deny and log"

BGP Peer Naming

Terminal window
# Include AS number and purpose
set protocols bgp neighbor 10.0.0.1 description "AS64512: Transit-ISP-Primary"
set protocols bgp neighbor 10.0.0.2 description "AS64513: Transit-ISP-Backup"
set protocols bgp neighbor 192.168.1.1 description "AS65001: Customer-Acme-Corp"
set protocols bgp neighbor 172.16.1.1 description "AS65000: iBGP-RR-Client-DC2"

Comment Strategy

What to Comment

Terminal window
# Comment WHY, not WHAT
# The config shows what. Comments explain why.


# Bad: States the obvious
set firewall ipv4 name WAN-IN rule 100 description "Allow TCP 22"


# Good: Explains the reason
set firewall ipv4 name WAN-IN rule 100 description "SSH: Admin access per SEC-2025-001"


# Good: References ticket/change
set firewall ipv4 name WAN-IN rule 150 description "Temp: Vendor access until 2025-03-01 - TKT-4521"


# Good: Explains non-obvious choice
set firewall ipv4 name WAN-IN rule 200 description "HTTP: Redirect only, actual traffic via reverse proxy"

Temporary Rules

Terminal window
# Always mark temporary rules with expiration
set firewall ipv4 name WAN-IN rule 500 description "TEMP: Contractor VPN until 2025-02-28 - Remove after project X"


# Create reminder
# Add to monitoring/ticketing system
# Set calendar reminder


# Pattern: TEMP: <purpose> until <date> - <context>

Configuration Sections

Terminal window
# Use comments to mark logical sections


# === MANAGEMENT ACCESS ===
set firewall ipv4 name WAN-IN rule 100 ...
set firewall ipv4 name WAN-IN rule 101 ...


# === APPLICATION TRAFFIC ===
set firewall ipv4 name WAN-IN rule 200 ...


# VyOS doesn't have section comments in config, but you can use
# a rule with high number as section marker:


set firewall ipv4 name WAN-IN rule 99 action accept
set firewall ipv4 name WAN-IN rule 99 description "=== MANAGEMENT SECTION ==="
set firewall ipv4 name WAN-IN rule 99 state established enable
# This rule does nothing special but marks a section

Firewall Groups

Groups are aliases that make rules readable and maintainable.

Network Groups

Terminal window
# Define once, use everywhere
set firewall group network-group ADMIN-NETS network 10.0.0.0/24
set firewall group network-group ADMIN-NETS network 192.168.100.0/24
set firewall group network-group ADMIN-NETS description "Admin workstation networks"


set firewall group network-group RFC1918 network 10.0.0.0/8
set firewall group network-group RFC1918 network 172.16.0.0/12
set firewall group network-group RFC1918 network 192.168.0.0/16
set firewall group network-group RFC1918 description "Private address space"


# Use in rules
set firewall ipv4 name WAN-IN rule 100 source group network-group ADMIN-NETS

Port Groups

Terminal window
set firewall group port-group WEB-PORTS port 80
set firewall group port-group WEB-PORTS port 443
set firewall group port-group WEB-PORTS description "HTTP and HTTPS"


set firewall group port-group MAIL-PORTS port 25
set firewall group port-group MAIL-PORTS port 465
set firewall group port-group MAIL-PORTS port 587
set firewall group port-group MAIL-PORTS port 993
set firewall group port-group MAIL-PORTS description "Mail server ports"


# Use in rules
set firewall ipv4 name WAN-IN rule 200 destination group port-group WEB-PORTS

Address Groups

Terminal window
# For individual IPs
set firewall group address-group DNS-SERVERS address 8.8.8.8
set firewall group address-group DNS-SERVERS address 8.8.4.4
set firewall group address-group DNS-SERVERS address 1.1.1.1
set firewall group address-group DNS-SERVERS description "Public DNS resolvers"


set firewall group address-group NTP-SERVERS address 129.6.15.28
set firewall group address-group NTP-SERVERS address 129.6.15.29
set firewall group address-group NTP-SERVERS description "NIST NTP servers"

Group Maintenance

Terminal window
# When a network changes, update the group - all rules update automatically


# Old approach (nightmare):
# Search every rule for 10.0.0.0/24, update each one


# Group approach:
show firewall group network-group ADMIN-NETS
# Update one place
set firewall group network-group ADMIN-NETS network 10.0.1.0/24
delete firewall group network-group ADMIN-NETS network 10.0.0.0/24
commit
# All rules using ADMIN-NETS now use new network

Policy Structure

Route Maps

Terminal window
# Consistent naming: <PURPOSE>-<DIRECTION>-<PEER-TYPE>


# For BGP
set policy route-map TRANSIT-IN-FILTER rule 10 ...
set policy route-map TRANSIT-OUT-FILTER rule 10 ...
set policy route-map CUSTOMER-IN-FILTER rule 10 ...
set policy route-map PEER-IN-FILTER rule 10 ...


# For redistribution
set policy route-map OSPF-TO-BGP rule 10 ...
set policy route-map BGP-TO-OSPF rule 10 ...
set policy route-map CONNECTED-TO-OSPF rule 10 ...

Prefix Lists

Terminal window
# Name clearly
set policy prefix-list BOGONS rule 10 prefix 0.0.0.0/8 le 32
set policy prefix-list BOGONS rule 10 action deny
set policy prefix-list BOGONS description "Invalid source addresses"


set policy prefix-list OUR-PREFIXES rule 10 prefix 203.0.113.0/24
set policy prefix-list OUR-PREFIXES description "Our announced address space"


set policy prefix-list DEFAULT-ONLY rule 10 prefix 0.0.0.0/0
set policy prefix-list DEFAULT-ONLY description "Match only default route"

AS Path Lists

Terminal window
# For BGP filtering
set policy as-path-list CUSTOMER-AS rule 10 regex "^65001$"
set policy as-path-list CUSTOMER-AS description "Customer AS65001 only"


set policy as-path-list NO-TRANSIT rule 10 regex ".*65000.*"
set policy as-path-list NO-TRANSIT description "Block routes through AS65000"

Configuration Templates

Standard Router Sections

Terminal window
# Order your config consistently:


# 1. System settings
set system host-name router01
set system domain-name example.com
set system time-zone UTC


# 2. Users and authentication
set system login user admin ...


# 3. Interfaces
set interfaces ethernet eth0 ...


# 4. Firewall groups (define before using)
set firewall group ...


# 5. Firewall rules
set firewall ipv4 name ...


# 6. NAT
set nat source ...


# 7. Routing protocols
set protocols static ...
set protocols bgp ...


# 8. Services (DHCP, DNS, etc)
set service dhcp-server ...


# 9. VPN
set vpn ...


# 10. Zone policy
set zone-policy ...

Change Documentation Template

When making changes, document:

## Change: <Brief description>
Date: 2025-01-08
Ticket: TKT-12345
Author: admin


### Purpose
Why this change is needed.


### Changes
- Added firewall rule 150 for new application
- Updated ADMIN-NETS group with new subnet


### Testing
- Verified connectivity from admin network
- Confirmed application accessible


### Rollback
Commands to undo:
delete firewall ipv4 name WAN-IN rule 150
delete firewall group network-group ADMIN-NETS network 10.0.2.0/24
commit

Avoiding Common Mistakes

Mistake 1: Magic Numbers

Terminal window
# Bad: What is 10.5.32.15?
set firewall ipv4 name WAN-IN rule 100 source address 10.5.32.15


# Good: Use groups with descriptions
set firewall group address-group MONITORING-SERVERS address 10.5.32.15
set firewall group address-group MONITORING-SERVERS description "Prometheus server"
set firewall ipv4 name WAN-IN rule 100 source group address-group MONITORING-SERVERS

Mistake 2: No Rule Descriptions

Terminal window
# Bad: What does this do?
set firewall ipv4 name WAN-IN rule 47 action accept
set firewall ipv4 name WAN-IN rule 47 destination port 8443


# Good: Self-documenting
set firewall ipv4 name WAN-IN rule 200 action accept
set firewall ipv4 name WAN-IN rule 200 destination port 8443
set firewall ipv4 name WAN-IN rule 200 description "App: Customer portal HTTPS"
set firewall ipv4 name WAN-IN rule 200 protocol tcp

Mistake 3: Inconsistent Numbering

Terminal window
# Bad: Random rule numbers
set firewall ipv4 name WAN-IN rule 5 ...
set firewall ipv4 name WAN-IN rule 23 ...
set firewall ipv4 name WAN-IN rule 7 ...
set firewall ipv4 name WAN-IN rule 156 ...


# Good: Deliberate ranges
# 1-99: Infrastructure
# 100-199: Management
# 200-899: Applications
# 900-999: Cleanup/deny

The Lesson

Good config is self-documenting. Bad config is a puzzle box.

Standards to adopt today:

  1. Name things by purpose: WAN-TO-LAN, not FIREWALL1
  2. Use groups: Define once, maintain once
  3. Number consistently: Ranges for different rule types
  4. Describe everything: Future you will thank present you
  5. Reference tickets: Link to change management

The time spent on naming and comments pays back 100x when troubleshooting at 3 AM.

A config you can read is a config you can fix. A config you can’t read is a liability waiting to become an incident.

Write configs for the next person. The next person might be you, six months from now, with no memory of why rule 47 exists.