Networking

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:

# ifconfig -a

To check the status of a specific interface:

# 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:

# 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) :

# 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 allows multiple IP addresses to be assigned to a single network interface. This is useful in many scenarios, including:

  • 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:

# 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. Networks beyond that directly connected prefix still require an explicit route through the appropriate 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:

# 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) :

# ifconfig iwm0 up
  # Enable the interface
# 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:

# chown root:wheel /etc/hostname.iwm0
  # Preserve administrative ownership
# 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:

# echo 'inet6 autoconf' > /etc/hostname.em0

To enable privacy extensions (temporary addresses):

inet6 autoconfprivacy

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
add em0
add em1
up

Configure member interfaces:

# cat /etc/hostname.em0
up media 1000baseT mediaopt full-duplex

# cat /etc/hostname.em1
up media 1000baseT mediaopt full-duplex

OpenBSD 7.9 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:

# 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:

# arp -a

To trace network paths:

# traceroute openbsd.org

To inspect wireless signal strength:

# ifconfig iwn0

To view available wireless networks:

# ifconfig iwn0 scan

To send an IPv6 multicast ping:

# ping6 ff02::1%iwn0

To capture packets:

# tcpdump -i em0

Root privileges are required for tcpdump.

Secure Networking Practices #

Keep firmware up to date:

# fw_update

Avoid connecting to unsecured networks. Use strong WPA2 or WPA3 passphrases.

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:

# pfctl -nf /etc/pf.conf
  # Reject syntax errors without changing the active ruleset
# pfctl -f /etc/pf.conf
  # Load only after the syntax check succeeds
# 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:

# 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) :

# rcctl enable unwind
# 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):

# ifconfig em0 mtu 9000

To disable features like TCP segmentation offload (TSO):

# ifconfig em0 -tso

Refer to ifconfig(8) for other tunable options.

Report a bug