Published : 2013-08-10

Interface management

OpenBSD is a BSD system primarily focused on security and networking. It is well suited for roles such as router, load balancer, firewall, or VPN endpoint. This short article describes the common interface types on OpenBSD and how to manage them (configuration is similar to FreeBSD).

Inet/Inet6 interfaces

Inet/Inet6 interfaces are the IP network interfaces. The commands below also apply to tunnel or encapsulation interfaces.

IPv4

Assign an IPv4 address as on any UNIX system:

ifconfig bnx0 10.4.2.1/24

Remove the primary address with delete:

ifconfig bnx0 delete 10.4.2.1

Add additional addresses using aliases:

ifconfig bnx0 alias 10.4.2.2

Remove an alias:

ifconfig bnx0 -alias 10.4.2.2

IPv6

Assign an IPv6 address:

ifconfig bnx0 fd00:abcd::ca2d:458/64

Disable IPv6 on an interface:

ifconfig bnx0 -inet6

Data link layer

You can change the interface MAC address explicitly or set it to a random value:

ifconfig bnx0 lladdr 00:11:22:33:44:55
ifconfig bnx0 lladdr random

To inspect supported media and options use ifconfig <iface> media. Without arguments it shows the interface configuration and supported modes:

supported media:
       media none
       media 10baseT
       media 10baseT mediaopt full-duplex
       media 100baseTX
       media 100baseTX mediaopt full-duplex
       media 1000baseT
       media 1000baseT mediaopt full-duplex
       media autoselect

Set the media to 1Gb full-duplex for example:

ifconfig bnx0 media 1000baseT mediaopt full-duplex

You can also change the MTU (for jumbo frames):

ifconfig bnx0 mtu 6000

Interface state

Bring an interface up or down:

ifconfig bnx0 up
ifconfig bnx0 down

Destroying a virtual interface

One command can cause chaos:

ifconfig vlan45 destroy

Administrative conveniences

Add a description to an interface (use -description to remove it):

ifconfig bnx0 description "Internet fiber"

Create interface groups (names up to 15 characters, not ending with a digit) and add interfaces to groups. This helps with bulk operations such as shutting down a set of interfaces for failover:

ifconfig bnx0 group lan group priv
ifconfig bnx0 -group priv

Routing / MPLS

Several options can be applied to interfaces for routing protocols or MPLS.

Set an interface metric, which affects route selection (higher metric is less preferred):

ifconfig bnx0 metric 20

Enable or disable MPLS on an interface:

ifconfig bnx0 mpls
ifconfig bnx0 -mpls

Change the routing domain of an interface for isolation (default is domain 0):

ifconfig bnx0 rtdomain 4

Persisting interface configuration

To make interface configuration persistent across reboots, create files under /etc/ named /etc/hostname.<interfacename>, for example /etc/hostname.gre4.

OpenBSD will correct file permissions at boot if needed. You can also reconfigure an interface manually using netstart:

source /etc/netstart gre4

Bridge interfaces

A bridge groups multiple physical interfaces into a single logical switch-like interface.

Create a bridge:

ifconfig bridge0 create

Add a physical interface to the bridge:

ifconfig bridge0 add bnx0
ifconfig bridge0 del bnx0

Spanning Tree management

Because a bridge behaves like a switch, it is often useful to enable spanning tree to avoid switching loops.

ifconfig bridge0 stp bnx0
ifconfig bridge0 -stp bnx0

OpenBSD supports both classic STP and RSTP (Rapid Spanning Tree Protocol, which is the default).

You can adjust spanning-tree priority (0-61440):

ifconfig bridge0 spanpriority 4

Because the spanning-tree root is tied to a physical interface, you can also change per-interface priority (0-240):

ifconfig bridge0 ifpriority bnx0 6

And you can change interface cost (1-65535 in STP, 1-200000000 in RSTP, default 55):

ifconfig bridge0 ifcost bnx0 7

Finally, you can adjust the STP max age (6-40 seconds, default 20):

ifconfig bridge0 maxage 30

Layer 2 cache management

First configure which physical interfaces are used for host discovery:

ifconfig bridge0 discover bnx0
ifconfig bridge0 -discover bnx0

To inspect the bridge forwarding cache:

ifconfig bridge0 addr

You can limit the maximum address-cache size (default 150):

ifconfig bridge0 maxaddr 150

Now configure which interfaces will learn MAC addresses for LAN hosts:

ifconfig bridge0 learn bnx0
ifconfig bridge0 -learn bnx1

Adjust the maximum lifetime of entries in the cache (default 240, 0 means infinite and is not recommended):

ifconfig bridge0 timeout 70

If you need to pin an entry in the forwarding table so that a host is reachable only on one side of the bridge:

ifconfig bridge0 static bnx0 00:11:22:33:44:55

Finally, flush the cache. The first command removes only dynamically learned entries; the second removes everything:

ifconfig bridge0 flush
ifconfig bridge0 flushall

CARP interfaces

CARP interfaces use the CARP protocol, a BSD alternative to technologies such as VRRP. In its simplest form, CARP provides IP-level redundancy so that if one OpenBSD router fails, another can immediately take over.

Create a CARP interface:

ifconfig carp0 create

CARP relies on periodic advertisements to keep nodes synchronized. Each node can be in one of three states: master, backup, or init. Every CARP interface is attached to a lower-level interface such as a physical NIC, VLAN, or bridge.

Attach the CARP interface to a lower-level interface:

ifconfig carp0 carpdev vlan45

To configure the interval between advertisements, adjust advbase (1-255):

ifconfig carp0 advbase 10

In a failover setup, every node must have a different priority. The lower advskew wins:

ifconfig carp0 advskew 4

Then configure the CARP group parameters: vhid (1-255) and optionally a password, which is hashed with MD5 on the wire:

ifconfig carp0 vhid 40 pass MYPW6Z

Assign the shared virtual IP address to the CARP interface:

ifconfig carp0 10.4.5.2/27

Repeat the configuration on each node in the CARP group.

For additional security, you can restrict advertisements to a single peer, which also makes it possible to encapsulate them inside IPsec:

ifconfig carp0 carppeer 10.4.5.18

If everything works, the master should look like this:

carp0: flags=28843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500
  lladdr 00:00:5e:00:01:01
  priority: 0
  carp: MASTER carpdev vlan45 vhid 40 advbase 10 advskew 4 carppeer 10.4.5.18
  groups: carp
  status: master
  inet 10.4.5.2 netmask 0xffffffe0 broadcast 10.4.5.31

Since OpenBSD 5.1, CARP can also do load balancing. This lets you group several hosts behind one virtual IP and spread traffic across them. Four balancing modes are available: arp, ip, ip-stealth, and ip-unicast.

arp is suitable only when the load balancer lives on the same LAN.
ip supports routed load balancing between remote hosts.
ip-stealth forces nodes to use their physical MAC address instead of the CARP MAC, which can reduce flooding on switches.
ip-unicast improves the previous mode for monitored switching environments.

Example load-balancing configuration on each host:

ifconfig carp0 10.50.3.4/30 carpnodes 1:50,2:90 balancing ip-unicast

Both interfaces should then appear as MASTER.

pflow interfaces

pflow interfaces export accounting data using the NetFlow v5 format. They rely on Packet Filter.

Create the interface:

ifconfig pflow0 create

Then configure source and destination:

ifconfig pflow0 flowsrc 10.4.2.4 flowdst 10.6.7.34:44566

You can also switch to an older protocol version for legacy collectors:

ifconfig pflow0 pflowproto 4

pfsync interfaces

pfsync synchronizes Packet Filter state tables between firewalls on the same LAN. Because the protocol is unauthenticated, it should be carried on a dedicated network.

Configure pfsync0 on bnx0:

ifconfig pfsync0 create
ifconfig pfsync0 syncdev bnx0

You can also specify a unicast peer and encapsulate updates through IPsec:

ifconfig pfsync0 syncpeer 10.4.1.3

Tune the number of updates sent in one frame (1-255):

ifconfig pfsync0 maxupd 200

trunk interfaces

A trunk interface aggregates several physical NICs into one virtual interface. This is useful for link-level load balancing or failover.

Create a trunk and add or remove ports:

ifconfig trunk0 create
ifconfig trunk0 trunkport bnx0
ifconfig trunk0 trunkport bnx1
ifconfig trunk0 -trunkport bnx0

OpenBSD supports several aggregation modes:

broadcast: send/receive frames on all ports
failover: one active port, the others act as backups
lacp: 802.3ad aggregation with redundancy and higher throughput
loadbalance: spread traffic using header-based hashing
none: disable traffic without shutting down the interface
roundrobin: distribute frames in interface order

Change the aggregation protocol like this:

ifconfig trunk0 trunkproto lacp

Tunnel interfaces

OpenBSD natively supports GIF and GRE tunnels. These are lightweight stateless tunnels, but if the underlying path fails they become black holes until routing adapts. In practice, dynamic routing is the best companion for these tunnels.

Create tunnel interfaces:

ifconfig gif12 create
ifconfig gre2 create
ifconfig gre2 10.0.0.1/32

Each tunnel needs a source and a destination:

ifconfig gre2 tunnel 10.4.5.1 192.168.6.2

Delete the tunnel configuration:

ifconfig gre2 deletetunnel 10.4.5.1 192.168.6.2

GRE also supports keepalives. You specify an interval and a failure threshold (minimum 2):

ifconfig gre2 keepalive 60 6

You can also assign a routing domain to the tunnel:

ifconfig gre2 tunneldomain 2

VLAN interfaces

VLAN interfaces encapsulate traffic with 802.1Q tags, allowing several tagged networks to share one physical NIC.

Each VLAN interface is attached to a physical interface. The interface name does not have to match the VLAN tag, but doing so usually makes administration easier.

ifconfig vlan452 create
ifconfig vlan452 vlan 452 vlandev bnx0