Networking on OpenBSD

Synopsis #

OpenBSD configures interfaces through ifconfig(8) and persistent hostname.if(5) files. This chapter covers wired and wireless interfaces, static and automatic IPv4 and IPv6 addressing, resolver ownership, routes, bridges, trunks, VLANs, diagnostics, and basic Packet Filter policy. Current automatic IPv4 configuration uses dhcpleased(8) , while resolvd(8) merges DNS proposals into /etc/resolv.conf.

Network Interface Basics #

Each network interface is named according to the driver and unit number, such as em0 for the first Intel gigabit Ethernet interface or iwn0 for an Intel wireless device. To display all interfaces, including inactive ones:

doas ifconfig -a

To check the status of a specific interface:

doas ifconfig em0

To list available network interfaces based on detected hardware, examine the system boot messages:

dmesg | grep -E '^[a-z]+[0-9]+.*(Ethernet|wireless|network)'

Firmware for some wireless devices is not included in the base system. Use fw_update(8) to install required firmware:

doas fw_update

Configuring Wired Interfaces #

Persistent interface files are named /etc/hostname.if, where if is the complete interface name.

Automatic IPv4 Configuration #

Request a DHCP lease by placing inet autoconf in the interface file:

inet autoconf

The older single-word dhcp form remains an alias for inet autoconf, but the explicit form describes the current dhcpleased(8) configuration path.

Static IPv4 Configuration #

A static address, default gateway, and resolver policy belong in separate files. For a host at 192.168.1.100/24 with gateway 192.168.1.1, create /etc/hostname.em0:

inet 192.168.1.100 255.255.255.0

Create mygate(5) at /etc/mygate:

192.168.1.1

Add site-specific resolver lines to resolv.conf(5) :

search example.net
nameserver 192.168.1.53

resolvd(8) manages /etc/resolv.conf, merges proposals from DHCP, SLAAC, VPNs, and supported network devices, then re-appends user-edited lines. Do not make the file immutable.

Apply the complete network configuration with netstart(8) :

doas sh /etc/netstart

A reboot is recommended after a significant persistent network change because it validates configuration order from a clean state.

Configuring Interface Aliases #

An interface alias adds another IP address to a network interface. Common uses include:

  • Running multiple services bound to different IPs
  • Operating virtual hosts
  • Separating traffic for organizational or policy purposes

Aliases can be assigned to the same subnet as the primary address, or to entirely different subnets. When the alias resides in the same subnet, the netmask must be set to 255.255.255.255 to avoid unintended routing behavior. If the alias belongs to a different subnet, the correct netmask for that subnet must be specified, and in many cases, an explicit route will be needed to make the address reachable.

Interface aliases are configured in the interface’s startup file, located in /etc/hostname.if, where if is the interface name (such as em0, re0, or iwn0). These configurations are applied automatically at boot or manually using sh /etc/netstart.

Example: Multiple Aliases in the Same Subnet #

In the following example, the system is assigned a primary IPv4 address of 10.0.0.2/24, along with two aliases in the same subnet:

File: /etc/hostname.re0

inet 10.0.0.2 255.255.255.0
inet alias 10.0.0.3 255.255.255.255
inet alias 10.0.0.4 255.255.255.255

To activate the changes immediately:

doas sh /etc/netstart re0

Example: Alias in a Different Subnet #

If an alias must be added from a different network range, the netmask must match that network. For example, to add an alias in the 192.168.100.0/24 subnet:

inet 10.0.0.2 255.255.255.0
inet alias 192.168.100.10 255.255.255.0

Assigning the address installs a connected route for its prefix. Other networks need a route through the correct gateway.

Viewing Aliases #

By default, ifconfig(8) shows only the primary address of each interface. To view all configured addresses, including aliases, use the -A option:

doas ifconfig -A

This command will display all IPv4 and IPv6 addresses associated with each interface, including any aliases.

Wireless Networking #

Confirm driver attachment and install required firmware before configuring Wi-Fi. Scan for access points with ifconfig(8) :

doas ifconfig iwm0 up
  # Enable the interface
doas ifconfig iwm0 scan
  # Display visible access points

For one protected network, create /etc/hostname.iwm0:

nwid example-net wpakey "replace-with-passphrase"
inet autoconf

For an auto-join list:

join home-net wpakey "replace-with-home-passphrase"
join office-net wpakey "replace-with-office-passphrase"
join guest-net
inet autoconf
inet6 autoconf

Line order does not define network precedence. OpenBSD evaluates matching candidates by criteria that include security and connection quality.

Place address-configuration lines after the wireless selection lines so that DHCP and IPv6 autoconfiguration begin only after association. Restrict the file because it contains network credentials:

doas chown root:wheel /etc/hostname.iwm0
  # Preserve administrative ownership
doas chmod 600 /etc/hostname.iwm0
  # Prevent other users from reading WPA keys

Configure Wi-Fi Roaming and Wired Failover shows how to place Ethernet and Wi-Fi on one trunk(4) failover interface when both reach the same Layer 2 network.

Hostname and DNS Resolution #

Store the fully qualified hostname in myname(5) at /etc/myname:

host.example.net

Local static host records belong in hosts(5) :

127.0.0.1       localhost
192.168.1.1     gateway.example.net gateway

DNS resolution is controlled by /etc/resolv.conf and managed by resolvd(8) . It merges nameserver proposals from dhcpleased(8) , slaacd(8) , iked(8) , and supported devices. If unwind(8) runs, resolvd places nameserver 127.0.0.1 first.

User-edited lines are re-appended when resolvd rewrites the file. Do not use chflags schg to freeze /etc/resolv.conf; doing so prevents legitimate network transitions.

Routing and Default Gateway #

Display routes with route(8) :

route -n show
  # Display all routes without DNS lookups
route -n get 198.51.100.25
  # Display the route selected for one destination

For a static configuration, place the IPv4 and optional IPv6 default gateways on separate lines in /etc/mygate:

192.168.1.1
2001:db8:1::1

If any interface requests inet autoconf, netstart ignores the static IPv4 entry. The corresponding rule applies to inet6 autoconf and the IPv6 entry.

Temporary runtime changes use route add, route change, or route delete. More complex persistent routes can use !route ... directives in hostname.if(5) or mygate(5), but ordinary single-gateway hosts should use /etc/mygate.

IPv6 Configuration #

To use automatic IPv6 addressing via SLAAC:

Add this line to /etc/hostname.em0, preserving existing IPv4 and link settings:

inet6 autoconf

Temporary address extensions are enabled by default. Their explicit interface setting is:

inet6 temporary

To disable SLAAC:

inet6 -autoconf

Static IPv6 configuration:

inet6 2001:db8::100 64
!/sbin/route add -inet6 default 2001:db8::1

Test IPv6 connectivity:

ping6 -c 3 openbsd.org
traceroute6 openbsd.org

To discover local hosts via link-local addresses:

ping6 ff02::1%iwn0

Bridging and Interface Aggregation #

To create a bridge:

cat /etc/hostname.bridge0

Example output:

add em0
add em1
up

Configure member interfaces:

cat /etc/hostname.em0

Example output:

up

cat /etc/hostname.em1

Example output:

up

OpenBSD provides LACP link aggregation through aggr(4) . Configure the member interfaces without addresses:

# /etc/hostname.em0
up

# /etc/hostname.em1
up

Create the aggregate in /etc/hostname.aggr0:

trunkport em0
trunkport em1
inet 192.168.1.2 255.255.255.0
up

The connected switch ports must be configured as members of the same LACP group. A bridge has different loop-prevention requirements and must not be treated as an LACP aggregate.

Use trunk(4) for failover or loadbalance interface groups, not LACP. Configure Wi-Fi Roaming and Wired Failover provides a complete trunkproto failover example.

To check supported media types:

doas ifconfig em0 media

Network Diagnostics #

To test basic connectivity:

ping 1.1.1.1
ping openbsd.org

To test DNS:

host openbsd.org

To view ARP table:

doas arp -a

To trace network paths:

traceroute openbsd.org

To inspect wireless signal strength:

doas ifconfig iwn0

To view available wireless networks:

doas ifconfig iwn0 scan

To send an IPv6 multicast ping:

ping6 ff02::1%iwn0

To capture packets:

doas tcpdump -i em0

Root privileges are required for tcpdump.

Secure Networking Practices #

Keep firmware up to date:

doas fw_update

Avoid connecting to unsecured networks. Use WPA2 with a strong passphrase. OpenBSD 8.0 documents WPA1 and WPA2 support; do not assume WPA3-only networks are compatible.

A default-block PF policy must use the actual management interface and retain recovery access. Keep a console and the current SSH session open while editing /etc/pf.conf. One minimal policy fragment is:

set block-policy drop
block all
pass out
pass in on em0 proto tcp to (em0) port ssh

Replace em0 with the management interface. Parse the complete ruleset before loading it:

doas pfctl -nf /etc/pf.conf
  # Reject syntax errors without changing the active ruleset
doas pfctl -f /etc/pf.conf
  # Load only after the syntax check succeeds
doas pfctl -e
  # Enable PF when it is not already enabled

Open a new SSH session and verify administrative access before closing the recovery session. Configure Secure Remote Access with OpenSSH provides the complete lockout-safe sequence.

To monitor logged traffic:

doas tcpdump -n -e -ttt -i pflog0

VLAN Configuration #

A vlan(4) interface attaches a VLAN identifier to a parent Ethernet interface. For a host address on VLAN 10, create /etc/hostname.vlan10:

parent em0
vnetid 10
inet 192.168.10.100 255.255.255.0
up

The connected switch port must carry VLAN 10 as tagged traffic. The default gateway belongs in /etc/mygate, not in the address line.

Route Multiple VLANs with PF provides a complete trunk, forwarding, inter-VLAN policy, NAT, and packet-capture procedure.

Local DNS Caching #

For an automatically integrated local validating resolver, enable unwind(8) :

doas rcctl enable unwind
doas rcctl start unwind

While unwind runs, resolvd places nameserver 127.0.0.1 first and retains other resolver proposals for transition handling. Confirm the result in /etc/resolv.conf and with unwindctl(8) .

unbound(8) is available when a manually administered recursive resolver is required, but starting it alone does not establish resolver ownership. A deployment that uses unbound must define how /etc/resolv.conf, DHCP and SLAAC proposals, and fallback behavior interact.

Performance Tuning #

To set the Maximum Transmission Unit (MTU):

doas ifconfig em0 mtu 9000

For a specific diagnostic need, disable TCP segmentation offload (TSO) system-wide:

doas sysctl net.inet.tcp.tso=0

Refer to ifconfig(8) for other tunable options.

Report a bug