OpenBSD FAQ - Networking [FAQ Index]


For the bulk of this document, it helps if you have read and at least partially understand the ifconfig(8) and netstat(1) man pages.

If you are a network administrator, setting up routing protocols, using your OpenBSD box as a router or want to go in-depth into IP networking, it is recommended that you read the chapter on IP addressing in the TCP/IP guide. It contains fundamental knowledge to build upon when working with IP networks, especially when you deal with or are responsible for more than one network.

If you are working with applications such as web servers, ftp servers and mail servers, you may wish to read some of the RFCs. The RFCs define many standards for protocols on the internet and explain how they are supposed to work.

Note that this FAQ page does not cover firewalling on OpenBSD: this topic is described in the PF User's Guide.

Network configuration

Normally, OpenBSD's network settings are initially configured by the installation process. All network configuration is done using text files in /etc.

Identifying and setting up your network interfaces

In OpenBSD, interfaces are named for the type of card, not for the type of connection. For example, here is the part of the dmesg(8) for an Intel Fast Ethernet network card, which uses the device name fxp.
fxp0 at pci0 dev 10 function 0 "Intel 82557" rev 0x0c: irq 5, address 00:02:b3:2b:10:f7
inphy0 at fxp0 phy 1: i82555 10/100 media interface, rev. 4
This device uses the fxp(4) driver, and is assigned the number 0 here.

You can find out what network interfaces have been identified by using the ifconfig(8) utility. The following command will show all network interfaces on a system. This sample output shows us only one physical Ethernet interface, an fxp(4).

$ ifconfig
lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> mtu 33200
        index 3 priority 0 llprio 3
        groups: lo
        inet netmask 0xff000000
        lladdr 00:02:b3:2b:10:f7
        index 1 priority 0 llprio 3
        media: Ethernet autoselect (100baseTX full-duplex)
        status: active
        inet netmask 0xffffff00 broadcast
enc0: flags=0<>
        index 2 priority 0 llprio 3
        groups: enc
        status: active
pflog0: flags=141<UP,RUNNING,PROMISC> mtu 33200
        index 4 priority 0 llprio 3
        groups: pflog
As you can see here, ifconfig(8) gives us a lot more information than we need at this point. In the above example, an IP network is configured on fxp0, hence the values inet netmask 0xffffff00 broadcast Also, the UP and RUNNING flags are set.

The netstart(8) script configures network interfaces at boot time using hostname.if(5) files, where "if" is replaced by the full name of each interface. The example above would use the file /etc/hostname.fxp0:

$ cat /etc/hostname.fxp0
Note that this hostname.fxp0 file has an interactive equivalent:
# ifconfig fxp0
See hostname.if(5) for the precise relation with ifconfig(8).

Finally, you will notice several other interfaces come enabled by default. These are virtual interfaces that serve various functions. The following manual pages describe them:

Other virtual interfaces can be added with the ifconfig(8) create command. These include, but are not limited to: For a complete listing of virtual interfaces, refer to the ifconfig(8) man page.

Default hostname and gateway

The /etc/myname and /etc/mygate files are read by the netstart(8) script. Both of these files consist of a single line, specifying the fully qualified domain name of the system and the address of the gateway host, respectively. The /etc/mygate file need not exist on all systems. See myname(5) for more details.

DNS resolution

DNS resolution is controlled by resolv.conf(5).
$ cat /etc/resolv.conf
lookup file bind
Here, the default domain name will be, there will be two DNS resolvers, and, and the hosts(5) file will be consulted before the DNS resolvers are.

If you are using DHCP, you'll want to read DHCP, taking note of resolv.conf.tail(5).

Activating the changes

From here, you can either reboot or run the netstart(8) script:
# sh /etc/netstart
Note that a few warnings may be produced when running this script if you are reconfiguring interfaces that have already been configured. Use ifconfig(8) to make sure that your interfaces were set up correctly.

Even though you can completely reconfigure networking on a running OpenBSD system, a reboot is recommended after any significant reconfiguration. The reason for this is that the environment at boot is somewhat different than it is when the system is up and running. For example, if you had specified a DNS-resolved symbolic name in any of the files, you would probably find it worked as expected after reconfiguring. On initial boot, however, your external resolver may not be available, so the configuration will fail.

Checking routes

You can check your routes via netstat(1) or route(8). If you are having routing problems, you may want to use the -n flag to route(8), which prints the IP addresses rather than doing a DNS lookup and displaying the hostname.
$ netstat -rn
Routing tables

Destination        Gateway            Flags     Refs     Use    Mtu  Prio Interface
default             UGS         4       16      -    12 fxp0
224/4              URS         0        0  32768     8 lo0
127/8              UGRS        0        0  32768     8 lo0          UH          2       15  32768     1 lo0
10.0.0/24          link#1             UC          1        4      -     4 fxp0           aa:0:4:0:81:d      UHL         1       11      -     1 fxp0          UGHS        0        0      -     1 lo0

$ route show
Routing tables

Destination        Gateway            Flags     Refs     Use    Mtu  Prio Iface
default             UGS         4       16      -    12 fxp0
base-address.mcast localhost          URS         0        0  32768     8 lo0
loopback           localhost          UGRS        0        0  32768     8 lo0
localhost          localhost          UH          2       15  32768     1 lo0
10.0.0/24          link#1             UC          1        4      -     4 fxp0           aa:0:4:0:81:d      UHL         1       11      -     1 fxp0          localhost          UGHS        0        0      -     1 lo0

Setting up aliases on an interface

OpenBSD has a simple mechanism for setting up IP aliases on an interface. To do this, simply edit the hostname.if(5) file of that interface.

Suppose you have a dc0 interface. You are on the network, the IP address for dc0 is and the netmask is

Assuming you are using multiple IP addresses which are in the same IP subnet with aliases, your netmask setting for each alias becomes They do not need to follow the netmask of the first IP bound to the interface. In this example, two aliases are added to the interface dc0, which was configured as netmask

$ cat /etc/hostname.dc0
inet alias
inet alias
Once you've created this file, run netstart or reboot. To view all aliases, use $ ifconfig -A

Dynamic Host Configuration Protocol

The Dynamic Host Configuration Protocol (DHCP) is a way to configure network interfaces automatically. OpenBSD can be a DHCP server that configures other machines, or a DHCP client that is configured by a DHCP server.

DHCP client

To use dhclient(8), edit the hostname.if(5) file of your interface. The wireless networking section explains how to set up wireless interfaces. For ethernet interfaces one line is enough:
$ cat /etc/hostname.xl0
This will cause OpenBSD to start the DHCP client on boot. By default, OpenBSD will gather its IP address, default gateway, and DNS servers from the DHCP server.

If you want to start a DHCP client from the command line, simply run

# dhclient xl0
where xl0 is the interface on which you want to receive DHCP.

Once the interface is configured, dhclient(8) will overwrite the resolv.conf(5) file. You can customize the resolver configuration by using settings in dhclient.conf(5) and using resolv.conf.tail(5).

For example, to prevent the DHCP server from overriding the DNS server you configured in /etc/resolv.conf.tail, add

ignore domain-name-servers;
to your /etc/dhclient.conf.

There are several useful configuration snippets in /etc/examples/dhclient.conf.

DHCP server

If you want to use OpenBSD as a DHCP server, enable the dhcpd(8) daemon at startup.
# rcctl enable dhcpd
On the next boot, dhcpd will run and attach to all NICs that have valid configurations in dhcpd.conf(5). You may specify individual interfaces instead by naming them explicitly.
# rcctl set dhcpd flags em1 em2
An example /etc/dhcpd.conf file might look like this:
# Home
subnet netmask {
	option domain-name-servers;
	option routers;

# Guests
subnet netmask {
	option domain-name-servers,;
	option routers;
There are two subnets in this example: a home network and a guest network. Clients will automatically be given an IP address and pointed to the gateway and DNS servers you specify. See dhcp-options(5) for more options.

PXE booting (i386, amd64)

The Preboot Execution Environment (PXE) is a standard method of booting systems using only the network. A client's PXE-capable NIC broadcasts a DHCP request at the start of the boot process and, rather than only receiving basic IP/DNS information, is also given a file to boot from. On OpenBSD, this file is known as pxeboot(8), and is typically served by tftpd(8).

Wireless networking

OpenBSD has support for a number of wireless chipsets. Further supported devices can be found in usb(4) and pci(4). The precise extent of their support is described in the driver man pages.

The following cards support Host-based Access Point (HostAP) mode, permitting them to be used as a wireless access point.

The ifconfig(8) media subcommand shows media capabilities of network interfaces. For wireless devices, it displays supported 802.11a/b/g/n media modes and the supported operating modes (hostap, ibss, monitor). For example, to see media capabilities of interface ath0, type:
$ ifconfig ath0 media
In order to use some wireless cards, you will need to acquire firmware files with fw_update(1). Some manufacturers refuse to allow free distribution of their firmware, so it can't be included with OpenBSD.

Another option to consider: use a conventional NIC and an external bridging wireless access point for your OpenBSD-based firewall. This has the added advantage of letting you easily position the antenna where it is most effective, which is often not directly on the back of your firewall.

Configuring your wireless adapter

Adapters based on supported chips can be used like any other network interface. To connect an OpenBSD system to an existing wireless network, use the ifconfig(8) utility.

An example of a hostname.if(5) file for a wireless client might be:

nwid puffyuberalles
wpakey puffyguffy
Note that the dhcp keyword should be after the other configuration lines, as the network adapter will not be able to send a DHCP request until it is configured.

The corresponding access point might be configured like this:

mediaopt hostap mode 11a
nwid puffyuberalles
wpakey puffyguffy

Trunking your wireless adapter

Many laptops have both a wireless and a hard-wired adapter. Sometimes, you may be directly connected to your high speed network and want the full performance of the wire, other times, you will be using the wireless. You probably don't want to reconfigure your machine each time you switch locations.

You could set up both interfaces with DHCP, but then you would have to wait for the unused interface to time out while booting (see the link-timeout option of dhclient.conf(5)). Things would be a little confusing if you had both resources available, and switching between the two resources would be a bit annoying.

Using a trunk(4) device may simplify your life. Trunks are virtual interfaces consisting of one or more network interfaces.

In the rest of this section, we will use a laptop with a wired bge0 and a wireless iwn0 interface. Using these two interfaces, we will build a trunk0 interface, then use DHCP to get an IP address for this virtual interface.

To do this, we first configure the two physical ports. As we are just assigning them to a combined trunk0 interface, we won't do much of anything with the wired interface other than activate it:

# echo up > /etc/hostname.bge0
The wireless interface, however, needs a bit more configuration. It will need to attach to our wireless WPA-protected network:
$ cat /etc/hostname.iwn0
nwid puffynet
wpakey mysecretkey
Now, our trunk interface is defined like this:
$ cat /etc/hostname.trunk0
trunkproto failover trunkport bge0
trunkport iwn0
The trunk is set up to be in failover mode, so either interface can be used. If both are available, it will prefer the bge0 port, since that is the first one added to the trunk device.

Using NFS

The Network File System, NFS, is used to share a filesystem over the network.

This section will go through the steps for a simple setup of NFS. This example details a server on a LAN, with clients accessing NFS on the LAN. It does not cover securing NFS. We presume you have already set up packet filtering or other firewalling protection to prevent outside access. If you are allowing outside access to your NFS server, and you have any kind of sensitive data stored on it, we strongly recommend that you employ IPsec. Otherwise, people can potentially see your NFS traffic. Someone could also pretend to be the IP address which you are allowing into your NFS server. There are several attacks that can result. When properly configured, IPsec protects against these types of attacks.

Setting up an NFS server

The portmap(8), mountd(8) and nfsd(8) services must be enabled on the server:
# rcctl enable portmap mountd nfsd
# rcctl set nfsd flags -tun 4
The -t and -u flags for nfsd(8) enable TCP and UDP, respectively, and four server instances are created with -n 4. You should set an appropriate number of NFS server instances to handle the maximum number of concurrent client requests that you want to service.

Then configure the list of filesystems that will be made available.

In this example, we have a server with IP address This server will be serving NFS only to clients within its own subnet. This is configured in the following exports(5) file:

$ cat /etc/exports
/work -alldirs -ro -network=10.0.0 -mask=
The local filesystem /work will be made available via NFS. The -alldirs option specifies that clients will be able to mount at any point under /work as well as /work itself. For example, if there was a directory called /work/monday, clients could mount /work or they could mount /work/monday. The -ro option specifies that clients will only be granted read-only access. The last two arguments specify that only clients within the network using a netmask of will be authorized to mount this filesystem. This is important for some servers that are accessible by different networks.

Don't just add a filesystem to /etc/exports without some kind of list of allowed hosts, otherwise anyone who can reach your server will be able to mount your NFS exported directories.

Now you can start the server services.

# rcctl start portmap mountd nfsd
You're now ready to mount the exported filesystems from the clients.

If you make changes to /etc/exports while NFS is already running, you need to make mountd aware of this. Just HUP mountd and the changes will take effect.

# rcctl reload mountd

Mounting NFS Filesystems

NFS filesystems should be mounted via mount(8), or more specifically, mount_nfs(8).

To mount the /work filesystem on host to local filesystem /mnt, do:

# mount -t nfs /mnt
Note that you don't need to use an IP address; mount(8) will resolve host names.

To have that filesystem mounted at boot, append a line to your fstab(5):

# echo ' /mnt nfs rw,nodev,nosuid 0 0' >> /etc/fstab
It is important that you use 0 0 at the end of this line so that your computer does not try to fsck(8) the NFS filesystem on boot.

When accessing an NFS mount as the root user, the server automatically maps root's access to username nobody and group nobody. This is important to know when considering file permissions. For example, take a file with these permissions:

-rw-------    1 root     wheel           0 Dec 31 03:00 _daily.B20143
If this file was on an NFS share and the root user tried to access this file from the NFS client, access would be denied. This is because the server uses the credentials of the user nobody when root tries to access the file. Since the user nobody doesn't have permissions to access the file, access is denied.

The user and group that root are mapped to are configurable via the exports(5) file on the NFS server.

Checking Stats on NFS

One thing to check to ensure NFS is operating properly is that all the daemons have properly registered with RPC. To do this, use rpcinfo(8).
$ rpcinfo -p
   program vers proto   port
    100000    2   tcp    111  portmapper
    100000    2   udp    111  portmapper
    100005    1   udp    633  mountd
    100005    3   udp    633  mountd
    100005    1   tcp    916  mountd
    100005    3   tcp    916  mountd
    100003    2   udp   2049  nfs
    100003    3   udp   2049  nfs
    100003    2   tcp   2049  nfs
    100003    3   tcp   2049  nfs
There are a few utilities that allow you to see what is happening with NFS. showmount(8) allows you to view what is currently mounted by whom. There is also nfsstat(1), which shows much more verbose statistics.

Setting up a network bridge

A bridge(4) is a link between two or more separate networks. Unlike a router, packets transfer through the bridge "invisibly" -- logically, the two network segments appear to be one segment to nodes on either side of the bridge. Bridges will only forward packets that have to pass from one segment to the other. They provide, among other things, an easy way to reduce traffic in a complex network and yet allow any node to access any other node when needed.

Note that because of this "invisible" nature, an interface in a bridge may or may not have an IP address of its own. If it does, the interface has effectively two modes of operation, one as part of a bridge, the other as a normal, stand-alone NIC. If neither interface has an IP address, the bridge will pass network data, but will not be externally maintainable (which can be a feature).

A simple example of a bridge application

One of my computer racks has a number of older systems, none of which have a built-in 10BASE-TX NIC. While they all have an AUI or AAUI connector, my supply of transceivers is limited to coax. One of the machines on this rack is an OpenBSD-based terminal server which is always on and connected to the high-speed network. Adding a second NIC with a coax port will allow me to use this machine as a bridge to the coax network.

This system has two NICs in it now, an Intel EtherExpress/100 fxp0 and a 3c590-Combo card ep0 for the coax port. fxp0 is the link to the rest of my network and will thus have an IP address, while ep0 is going to be for bridging only, and will have no IP address. Machines attached to the coax segment will communicate as if they were on the rest of my network. So, how do we make this happen?

The file hostname.fxp0 contains the configuration info for the fxp0 card. This machine is set up using DHCP, so its file looks like this:

$ cat /etc/hostname.fxp0
The ep0 card is a bit different, as you might guess:
$ cat /etc/hostname.ep0
up media 10base2
Here, we are instructing the system to activate this interface using ifconfig(8) and setting it to 10BASE-2 (coax). No IP address or similar information needs to be specified for this interface. The options the ep card accepts are detailed in its man page.

Now, we need to set up the bridge. Bridges are initialized by the existence of a file named something like hostname.bridge0. Here is an example for my situation here:

$ cat /etc/hostname.bridge0
add fxp0
add ep0
This is saying "set up a bridge consisting of the two NICs, fxp0 and ep0, and activate it." Does the order in which the cards are listed matter? No; remember, a bridge is symmetrical -- packets flow in and out in both directions.

That's it! Reboot and you now have a functioning bridge.

A bridge acting as a DHCP server

Let's say we have a small system which has four vr(4) interfaces, vr0 through vr3. We want to bridge vr1, vr2 and vr3 together, leaving out vr0 for an uplink (a cable modem for instance). We also want to serve IP addresses through DHCP over the bridged interfaces. Being a DHCP server and an uplink router, the box needs to have an IP address on the bridged network (contrary to the previous example in which the bridging box was not visible on the network).

It is not possible to assign an IP address directly to a bridge interface. The IP address should be added to one of the member interfaces, but we cannot use a physical interface as the link might be down, in which case the address would not be reachable. Fortunately, there is the vether(4) virtual Ethernet interface driver that can be used for this purpose. We will add it to the bridge, assign the IP address to it and make dhcpd(8) listen there.


First, mark the vr1, vr2 and vr3 interfaces as up:
# echo up > /etc/hostname.vr1
# echo up > /etc/hostname.vr2
# echo up > /etc/hostname.vr3
Then create the vether0 configuration:
# echo 'inet' > /etc/hostname.vether0
We configure the bridge interface to contain all the above interfaces:
$ cat /etc/hostname.bridge0
add vether0
add vr1
add vr2
add vr3
And finally we make dhcpd(8) listen on the vether0 interface:
# rcctl set dhcpd flags vether0
Reboot, and voilà!

Filtering on a bridge

While there are certainly uses for a simple bridge like this, it is likely you might want to DO something with the packets as they go through your bridge. As you might expect, Packet Filter can be used to restrict what traffic goes through your bridge.

Keep in mind, by the nature of a bridge, the same data flows through both interfaces, so you only need to filter on one interface. Your default "pass all" statements would look something like this:

pass in  on ep0  all
pass out on ep0  all
pass in  on fxp0 all
pass out on fxp0 all
Now, let's say I wish to filter traffic hitting these old machines. I want only web and SSH traffic to reach them. In this case, we are going to let all traffic in and out of the ep0 interface, but filter on the fxp0 interface.
# Pass all traffic through ep0
pass in  quick on ep0 all
pass out quick on ep0 all

# Block fxp0 traffic
block in  on fxp0 all
block out on fxp0 all

pass in quick on fxp0 proto tcp from any to any port { 22 80 }
Note that this rule set will prevent anything but incoming HTTP and SSH traffic from reaching either the bridge machine or any of the other nodes "behind" it. Other results could be had by filtering the other interface.

To monitor and control the bridge you have created, use the ifconfig(8) command, which can also be used to create a bridge after boot.

Tips on bridging

Equal-cost multipath routing

Equal-cost multipath routing refers to having multiple routes in the routing table for the same network, such as the default route, When the kernel is doing a route lookup to determine where to send packets destined to that network, it can choose from any of the equal-cost routes. In most scenarios, multipath routing is used to provide redundant uplink connections, e.g., redundant connections to the internet.

The route(8) command is used to add/change/delete routes in the routing table. The -mpath argument is used when adding multipath routes.

# route add -mpath default
# route add -mpath default
Verify the routes:
# netstat -rnf inet | grep default
default      UGS       2      134      -     fxp1
default        UGS       0      172      -     fxp2
In this example we can see that one default route points to, which is accessible via the fxp1 interface, and the other points to, which is accessible via fxp2.

Since the mygate(5) file does not yet support multipath default routes, the above commands should be added to the bottom of the hostname.if(5) files for the fxp1 and fxp2 interfaces. The /etc/mygate file should then be deleted.

$ tail -1 /etc/hostname.fxp1
!route add -mpath default
$ tail -1 /etc/hostname.fxp2
!route add -mpath default
Lastly, don't forget to activate the use of multipath routes by enabling the proper sysctl(8) variable.
# sysctl net.inet.ip.multipath=1
# sysctl net.inet6.ip6.multipath=1
Be sure to edit sysctl.conf(5) to make the changes permanent.

Now try a traceroute to different destinations. The kernel will load balance the traffic over each multipath route.

# traceroute -n
traceroute to (, 64 hops max, 60 byte packets
 1  19.337 ms  18.194 ms  18.849 ms
 2  17.642 ms  18.176 ms  17.731 ms
 3  110.486 ms  19.478 ms  100.949 ms
 4  32.772 ms  33.534 ms  32.835 ms

# traceroute -n
traceroute to (, 64 hops max, 60 byte packets
 1  14.175 ms  14.503 ms  14.58 ms
 2  13.664 ms  13.962 ms  13.445 ms
 3  13.964 ms  13.347 ms  13.788 ms
 4  30.177 ms  30.95 ms  30.593 ms
For more information about how the route is chosen, please refer to RFC2992, "Analysis of an Equal-Cost Multi-Path Algorithm".

It's worth noting that if an interface used by a multipath route goes down (i.e., loses carrier), the kernel will still try to forward packets using the route that points to that interface. This traffic will of course be blackholed and end up going nowhere. It's highly recommended to use ifstated(8) to check for unavailable interfaces and adjust the routing table accordingly.

Adding and replacing NICs

You may have to replace or add a network adapter on an OpenBSD system, maybe upgrading the capabilities of the system or repairing failed hardware. This will require some reconfiguration. The good news is that it's relatively easy, though there are some things to be aware of.

The key is understanding how OpenBSD names NICs. Unlike some OSs that try to remember any network adapter the installed OS has ever seen, OpenBSD does not remember a NIC's identification between boots -- it names them in the order that they are found. In most cases, this is far simpler for you, as the system will always identify a NIC the same way in the same hardware configuration, and when configurations change, the results are easily understood.

Here are some cases:

In addition to the hostname.if files, any other file that deals with hardware interfaces will have to be adjusted. Some likely candidates might include: