6.0 - Networking

6.0.1 - Before we go any further

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

If you are a network administrator, and you are setting up routing protocols, if you are using your OpenBSD box as a router, if you need to go in depth into IP networking, you really need to read Understanding IP addressing. This is an excellent document. Understanding IP addressing contains fundamental knowledge to build upon when working with IP networks, especially when you deal with or are responsible for more then one network.

If you are working with applications such as web servers, ftp servers, and mail servers, you may benefit greatly by reading the RFCs. Most likely, you can't read all of them. Pick some topics that you are interested in, or that you use in your network environment. Look them up, find out how they are intended to work. The RFCs define many (thousands) of standards for protocols on the internet and how they are supposed to work.

6.1 - Initial Network Setup

6.1.1 - Identifying and Setting Up Your Network Interfaces

To start off, you must first identify your network interface. In OpenBSD, interfaces are named for the type of card, not for the type of connection. You can see your network card get initialized during boot, or after boot using the dmesg(8) command. You also have the ability of seeing your network interface using the ifconfig(8) command. For example, Here is the output in dmesg for a ne2k network card, which uses the device name ne.

If you don't know what your device name is, here is a list of common cards and their device names.

Again, you can check to see what interfaces have been identified by using the ifconfig(8) utility. Here is output which will show an ne2k device.

As you can see here, ifconfig(8) gives us a lot more information than we are needing at this point. But it still allows us to see our interface. In the above example, the interface card is already configured. You can tell this by seeing that vaulues are already set in "inet netmask 0xffffff00 broadcast", and that the UP and RUNNING flags are turned on. Also, you will notice many other interfaces. Here is a list of interfaces that will be expected to be there.

If you don't have your interface configured the first step is to create the /etc/hostname.${IF} file. Where the name of your interface will take the place of ${IF}. From the information in the examples above, the name would be /etc/hostname.ne3. The layout of this file is like so: To read more about the format of this file, reference the hostname.if(5) man page.

So for the above example, a proper file would look like this:

Next step from here is to setup your gateway. To do this, simply put the IP of your gateway in the file /etc/mygate. This will allow for your gateway to be set upon boot. From here you should setup your nameservers, and your /etc/hosts file. To setup your nameservers, you will create a file called /etc/resolv.conf. You can read more about the format of this file in the resolv.conf(5) man page. But for a standard usage, here is an example. In this example your domain servers are and You also belong in the domain "yourdomain.com".

From here, you can either reboot or run the /etc/netstart script. You can do this by simply Typing (as root):

Notice that a few errors were produced, but this is in regards to the loopback interface. So this can be ignored. From here your system should be up and running. Again you can check to make sure that your interface was setup correctly with ifconfig(8). You can also check your routes via netstat(1) or route(8). Here is an example of viewing your routing tables using both.

6.1.2 - Setting up your OpenBSD box as a Gateway

This is the basic information you need to set up your OpenBSD box as a gateway (also called a router). If you are using OpenBSD as a router on the Internet, we suggest that you also read the IP Filter setup instructions below to block potentially malicious traffic. Also, due to the low availability of IPv4 addresses from network service providers and regional registries, you may want to look at Network Address Translation for information on conserving your IP address space.

The GENERIC kernel already has the ability to allow IP Forwarding, but needs to be turned on. You should do this using the sysctl(8) utility. To change this permanently you should edit the file /etc/sysctl.conf to allow for IP Forwarding. To do so add this line in that configuration file.

To make this change without rebooting you would use the sysctl(8) utility directly. Remember though that this change will not still exist after a reboot, and needs to be run as root.

Now modify the routes on the other hosts on both sides. There are many possible uses of OpenBSD as a router, using software such as routed(8), gated, mrtd, and zebra. OpenBSD has support in the ports collection for both gated and mrtd. OpenBSD supports several T1, HSSI, ATM, FDDI, Ethernet, and serial (PPP/SLIP) interfaces.

6.1.3 - Setting up aliases on an interface.

Starting with OpenBSD 2.8, /etc/ifaliases is no longer used!

OpenBSD has a simple mechanism for setting up ip aliases on an interface. To do this simply edit the file /etc/hostname.<if>. This file is read upon boot by the /etc/rc script, which is part of the rc startup hierarchy. For the example, we assume that the user has an interface dc0 and is on the network Other important information:

A few notes about aliases, in OpenBSD you use the interface name only. There is no differences between the first alias and the second alias. Unlike some other operating systems, OpenBSD doesn't refer to them as dc0:0, dc0:1. If you are referring to a specific aliased IP address with ifconfig, or adding an alias, be sure to say "ifconfig int alias" instead of just "ifconfig int" at the command line. You can delete aliases with "ifconfig int delete".

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 need to not follow the netmask of the first IP bound to the interface. In this example /etc/hostname.dc0, two aliases are added to the device dc0, which, by the way, was configured as netmask

Once you've made this file, it does take a reboot for it to take effect. You can, however, bring up the aliases by hand using the ifconfig(8) utility. To bring up the first alias you would use the command:

To view these aliases you must use the command:

6.2 - IP Filter

The IP Filter package was created to handle two tasks, dealing with packet level forwarding permissions ipf(8) and mapping hosts/subnets to a range of external addresses ipnat(8). The configuration files for these two services are /etc/ipf.rules and /etc/ipnat.rules.

You need to edit /etc/rc.conf to activate them at boot time. You also need to have net.inet.ip.forwarding=1 in your /etc/sysctl.conf (or your kernel needs to have IPFORWARDING or GATEWAY options turned on.) You also need a kernel compiled with option IPFILTER and IPFILTER_LOG (the GENERIC kernels do have these options).

If you have IP Filter compiled into your kernel, but you don't have it turned on in your /etc/rc.conf file, you can still activate it easily.

The -E flag on ipf 'enables' IP Filter. -Fa clears out any rules that you may have in there. -f /etc/ipf.rules loads the rules from /etc/ipf.rules.

If you make changes to /etc/ipf.rules after ipf is loaded, you can reload your rules pretty easily!

Same for ipnat... You will also want to enable ipmon for debugging.

This document will cover some basic ipf and ipnat configurations below. There are a lot of nice examples in /usr/share/ipf/ for ipnat and ipf. We recommend you choose the one closest to what you want, and modify it to fit your needs. You can find other IP Filter information at the IP Filter mailing list archive, the IP Filter web site, and finally the IP Filter HOWTO.


In order to enable ipf at boot, you will need to modify /etc/rc.conf so it reads IPFILTER=YES. IP Filter (ipf) is controlled by /etc/ipf.rules, which is read at boot. For a more detailed explanation, see ipf(5). In the examples that follow, fxp0 will represent the external interface to the internet. It will be different for you, based on the ethernet adaptor present in your computer. These rules will assume full-time internet connectivity, such as you would see on a webserver.

IP Filter rules are processed sequentially from top to bottom, it helps to visualize each packet having to traverse every rule before it reaches it's destination.

For example, the default ruleset provided allows all packets to travel in, and all packets to travel out:

Now lets say we don't want to allow any incoming connections to port 3306 (mysql) because the database should only be connected to from localhost. Our ruleset would look like this: This says "block in all incoming packets, from anywhere to anywhere whose destination is 3306." Essentially a packet destined for port 3306 on interface fxp0 will pass the first "pass in" rule and then be dropped by the "block in port = 3306" rule. If you reversed the order of our incoming rules (remember, order is important): Packets destined for port 3306 would pass because the last rule in the set allows all packets to pass. It is important to keep this in mind when writing packet filter rules: The last matching rule wins.

Of course, there are exceptions to every rule. the quick option drops the packet at the first rule that matches. Let's look at our above flawed example, if we add quick to the "block in" rule:

A packet destined for our host on port 3306 will hit the "block in quick" rule and be dropped immediately. All packets destined for other ports wont find a rule match until they reach our "pass in" rule that allows all packets to pass.

Default Deny

The safest packet filtering policy is a default deny policy. All traffic not explicitly allowed is denied. This policy is far safer than explicitly denying each protected service, allows for smaller rulesets, and can protect from an accidentally misconfigured service that has been left exposed.

Let's now look at another real world example ruleset and explain things line by line. Here's an example for a webserver with a default deny policy that only allows ssh connections (for administration) and connections to http (port 80) and https (port 443).

This will allow incoming connections from anywhere to ports 22(ssh), 80(http), and 443(https). It will drop all other connection attempts, and allow all outgoing connections. This is a pretty tight ruleset. But what if you only wanted to allow internal hosts on your address block to connect to ssh, but allow outside connections to http and https?

Pretty good, but what if we only want to allow one machine ( to administer the web server remotely? In that case, we can change this: to this: IP Filter supports both CIDR and dotted decimal forms of netmask address. You could also write the above as: but why would you?

Sample Rules

Here are some good rules for everyone to use (assuming that fxp0 is the external internet-connected interface). First we will set up simple address spoofing protection.

It's also a good idea to separate your loopback interface from your other rules. Our ruleset is starting to look pretty good, when we put it together, here's what it looks like:

Packet logging

Now that's pretty good, but it could be better. What if we want to log any connection attempts to port 22(ssh) that get blocked by our firewall? Easy, IP Filter can handle this with the log keyword:

This rule will allow our remote administration machine to connect to port 22, but deny and log all other attempts to connect to port 22.

Protocol based packet filtering

IP Filter can filter any IP protocol based on its number or name from /etc/protocols. For the sake of clarity, we will only concern ourselves with tcp, udp, and icmp. These are the most commonly used protocols. All basic internet applications rely on the availability and correct operation of these protocols.

In order for ipf to filter based on protocol, the keyword proto must be used. To examine our earlier ssh example rule, since ssh runs over tcp, we should only allow tcp packets to connect. by using the proto keyword to allow only tcp, we get a rule that looks like this:

But what if we need to allow connections to a service running over both tcp and udp like bind? Well, in the case of tcp/udp, IP Filter allows you to group both protocols together. Note: this only applies to tcp/udp. Using the bind example, a rule allowing tcp and udp connections in a default deny environment would look like:

Packet Filtering

In addition to filtering based on protocol, IP Filter is also capable of managing fragmented IP packets (a common method of defeating packet filters). There are two possible keywords that can be used when dealing with fragmented ip packets, frag for commonly fragmented IP packets, or short for IP packets with headers too small for comparison. Since fragmented packets can occur normally, depending on link conditions, it is best to only filter packets with headers too small for valid comparison. This can be accomplished with the following rule:

What about IP Options? IP Filter can handle those packets too. Packets can either be dropped if they have IP options set, or they can be dropped based on the specific IP options that are set. For example, the following rule will drop and log all packets with ip options set. This may however break some things such as traceroute(8). You can also specify which options not to allow. For instance a good rule is to block all packets with source routing options. This is accomplished with this rule: TCP Flags, established connections and keeping state

Now the filtering begins in earnest. IP Filter's greatest strengths are it's ability to filter packets based on TCP flags and to maintain established connections and connection state. It is recommend that all users who wish to filter packets based on TCP flags understand what role each flag plays. For instance, if you wanted to deny all packets with the FIN, URG, and PSH flags set (like for instance an nmap OS fingerprinting attempt) you could use a rule like this:

(Thanks to Kyle Hargraves for that tip)

IP Filter's next cool trick is it's ability to maintain state. Maintaining state has been described as "not speaking until spoken to", in other words, once a connection is established, packets no longer have to traverse rulesets. This is a very powerful feature allowing much simpler and more secure rule writing.

For example, let's see how we can apply state to our previous example ruleset (confused yet?). To review, we are allowing management access from our Class C to port 22(ssh) and allowing all incoming web traffic on ports 80(http) and 443(https). We are blocking all other traffic. But what if I want to ssh out of the webserver? What if I need to use lynx to look up something in the FAQ? Well, I can't because I have blocked all incoming connections other than on the specified ports. While this is the safest route, it can be quite inconvenient. By adding the keep state keywords to our "pass out" rule, we can automagically allow incoming connections in response to connections we initiate, such as when web browsing. Remember, we do need to specify what protocol we are keeping state for.

This little change will dramatically increase the flexibility and security of our ruleset because IP Filter is extremely flexible. For instance, in the above ruleset, we are allowing all tcp traffic into ports 80 & 443. We can tighten this up even more. In order for a tcp connection to be established, we only need to allow the initial handshake to occur, once that occurs, we can block traffic to that port and allow our "keep state" rule to manage the connection. To allow the initial handshake to complete, we need only allow packets with the SYN and SYNACK flags set. By passing only packets with SYN and SYNACK set, we can prevent many forms of portscanning such as FIN scanning. The rules now look like this:

Let's wrap this up by putting all of the rules we have so far into a ruleset. This ruleset will have a default deny policy, allow management connections from an internal network only (via ssh) and allow incoming traffic on ports 80(http) and 443(https). It will also protect against spoofed non-routeable ip addresses, and drop all packets that are too fragmented to inspect. A pretty comprehensive setup for a public webserver. Here's what /etc/ipf.rules should look like:

If you experience problems, you may want to enable logging on individual rules to effectively troubleshoot. ie: pass in log quick on fxp0 from to any port = 22
When you modify the configuration file to log packets, don't forget to ipf -Fa -f /etc/ipf.rules for the changes to take affect!
ipmon will write to ip log entries to /var/log/ipflog.
For further information on ipf, the IPF how-to is an excellent source, as are the resources available at the IP Filter homepage.

6.3 - IPNAT

Initial work done by Wayne Fergerstrom <wayne@methadonia.net>

6.3.1 NAT Introduction

Section Introduction

This section attempts to aid for those installing and configuring Network Address Translation ("NAT") on an OpenBSD machine. The user is assumed to have already set up and configured an OpenBSD machine with two network cards (one connected to the Internet and the other to the local network). IP Network Address Translation will work on machines with only one NIC, however since packets will be going in and out of the same interface, ethernet collisions will slow down performance considerably.

Based on RFC 1631, ipnat provides an easy way to map internal networks to a single routeable ("real") internet address. This is very useful if you don't have officially assigned addresses for every host on your internal network. When you set up private/internal networks, you can take advantage of reserved address blocks (assigned in RFC 1918), such as: ( - ( - ( -


The conventions used in this document are fairly straightforward. For documentation purposes I will review some of the terms and format for which this document adheres to.


This is how the computers are setup concerning this document. Your setup will vary from this, but the purpose of the document is to give you an overview so you can conform this information to your setup.

6.3.2 Network Address Translation

Introduction to NAT

As more and more businesses and users get on the Internet, each one must have an IP address. Public IP addresses are becoming harder and harder to get. The solution for a lot of people has been Network Address Translation (or "NAT"). NAT is a very simple, yet powerful way to get your LAN connected to the Internet without having to purchase or lease IP addresses for each machine. NAT is also known as "IP Masquerading" if you're a Linux user.

When NAT is up and running correctly, it allows users on the internal LAN to access the Internet through a different IP address (the one you set up with your provider). Each machine on the LAN uses the one IP address (transparently) of the one machine that is set up to use the ISP assigned IP address.

The way NAT works is amazingly simple. When a client on the LAN wants to connect to a machine on the Internet, it sends out a TCP packet with a request to connect. Inside the TCP packet header is the client's IP address (i.e. and the requested host's IP address (i.e. The machine running NAT intercepts this TCP packet and changes the client's IP address from to the IP address of the Internet-connected machine (i.e. This effectively tricks the host machine into thinking the actual connection is from the NAT machine, not the actual client's machine. The host then sends back responses to the NAT machine like it was the one connecting. When the NAT machine receives the responses it quickly translates the destination IP address back from itself to the client's machine and sends the packet to the client. The client didn't have any idea of what happened and spoofed Internet connectivity is totally transparent.

The example below shows NAT a little more clearly:

Why to use NAT

When presented with a cable modem in my new apartment I was also presented with another minor problem. How to get Internet access to my roommates, when the cable modem resides in my room? There were a few options I could implement ranging from obtaining extra IP addresses, to setting up a proxy server, to setting up NAT. (Don't let the cable modem example fool you. NAT is powerful enough to masquerade a large network with hundreds or even thousands of computers!)

There are many reasons why I wanted to set up NAT. The number one reason is for saving money. There are two roommates in my house (each with their own PC) and myself with 3 computers. My ISP only allows for three IP addresses per household. This means that there weren't enough IPs to allow every machine internet access.

By using NAT each machine will have a unique (internal) IP address but share the one IP address given to me by my ISP. The cost goes down.


In order to enable NAT on your OpenBSD machine you will need to turn on IPF and NAT. This is easily accomplished by editing the files listed below (make the changes to the file so it looks like the options below):

/etc/rc.conf (this file used to start services at boot time)


After these changes are made, the machine is now ready to for the configuration of NAT.


The first step is to configure the IPF rules file (/etc/ipf.rules). For the purposes of this document we will allow traffic to pass through this firewall option without any interference. The file should look like this:

Again for more information you can read FAQ 6.2

The NAT configuration file (/etc/ipnat.rules) has a very simple syntax. For the configuration set forth above, the file should contain the following entry:

Here is an explanation for the above lines.

The second line has almost the same entry except for the last portion. This tells ipnat to map anything else (not tcp/udp, those packets are already matched by the first line) to whatever port it requests (used for ICMP, and other protcols). Once this is in the file, all that's needed is to run the IPF daemon.


Executing NAT is a very simple process also. Once the configuration is complete, there are two ways to enable NAT. The first (and best way if possible-to test the setup stage) is to reboot your OpenBSD machine. This is accomplished with the command "reboot"

If you would like to run ipnat from the command line, use the following commands:

The first line is to enable IPF (remember that NAT piggy-backs on IPF therefore IPF must be initialized and running before NAT can be loaded). The options on the command line "-Fa" clear out any existing entries already in effect. "-f /etc/ipf.rules" tells ipf where the rules file can be found. "-E" is the switch to enable the IPF daemon.

The second command line is to enable NAT. "-CF" clears and flushes all existing entries in the NAT table. "-f /etc/ipnat.rules" tells NAT where the NAT rules file is at. NAT is now running. It's as simple as that.

Note: in order to reload the NAT settings (in case you edit the file but don't want to reboot) just execute the 2nd command over again. The settings will be flushed and reloaded.

6.3.3 Nat Knowledge Base

Checking NAT Status

To find out how NAT is doing or make sure the settings have taken effect, you use the "-l" option. This option will list all the settings and current sessions that ipnat is running:

The purpose of the first two lines is to confirm the settings that were entered in /etc/ipnat.rules earlier. The line(s) below will show you a list of the current NAT controlled connections.

Limitations of NAT (in FTP)

There are a few limitations of NAT. One is with FTP. When a user connects to a remote FTP server and requests information or file, the FTP server will make a connection to the client and transfer the info. This is done on a random free port. This is a problem for users attempting to gain access to FTP servers from within the LAN. When the FTP server sends its information it sends it to the external NIC at a random port. The NAT machine will receive this, but because it has no mappings for the unknown packet and doesn't have any mappings for that port, it will drop the packet and won't deliver it.

The solution to this is to place yourself in "passive mode" in your FTP client. This will tell the server that you want to connect to the server, and not what you just read. Then when you make that connection out NAT will correctly handle your connection.

IP Filter provides another solution for this situation, that is, an ftp proxy which is built-in to the NAT code. To activate it, put something like this before your other NAT mappings.

map dc0 -> proxy port ftp ftp/tcp
With this in place, the kernel will watch your FTP connections for the "PORT" command coming from the ftp client, and it will replace the IP address and port with it's own outside IP address, and a port of its own choosing. Then it will open up that port and tunnel the data to the port your ftp client asked for. Obviously, this is slightly more resource intensive. But, unless your NAT/IP Filter box is reaching critical mass, you should be fine.

Redirecting Traffic

At times you may need to redirect incoming or outgoing traffic for a certain protocol or port. A good example of this is if there were a server residing inside the LAN running a web server. Incoming connections to your valid Internet IP will find that unless your NAT box is running a web server, no connection can be made. For this purpose we use the NAT 'rdr' directive in the rules file to instruct where to redirect (or route) a particular connection to.

For our example, lets say a web server resides on the LAN with IP address of The NAT rules file needs a new directive to handle this. Add a line similar to the following one to your ipnat.conf:

The reason for each line is this:

When the addition is complete reload the NAT rules, and the redirection will start immediately.

NAT versus Proxy

The difference between NAT and an application-based proxy is that the proxy software acts as a middle-man between the Internet and the machines connected on the LAN. This is fine, however each application you want to run on your machine and connect to the Internet through the proxy server MUST be proxy-aware (be able to use a proxy server). Not all applications are able to do this (especially games). Furthermore, there simply are not proxy server applications for all of the Internet services out there. NAT transparently maps your internal network so that it may connect to the Internet. The only security advantage to using a proxy software over NAT is that the proxy software may have been made security aware, and can filter based on content, to keep your Windows machine from getting a macro virus, it can protect against buffer overflows to your client software, and more. To maintain these filters is often a high-maintenance job.

6.3.4 Links and X-References

OpenBSD files:

NAT Internet Links:

6.4 - DHCP

6.4.1 DHCP Client

To use the DHCP client dhclient(8) included with OpenBSD, edit /etc/hostname.xl0 (this is assuming your main ethernet interface is xl0. Yours might be ep0 or fxp0 or something else!) All you need to put in this hostname file is 'dhcp'

# echo dhcp >/etc/hostname.xl0
This will cause OpenBSD to automatically start the DHCP client on boot. 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, make sure /etc/dhclient.conf exists, then try:

# dhclient fxp0
Where fxp0 is the interface that you want to receive dhcp on.

No matter how you start the dhclient, you can edit the /etc/dhclient.conf file to not update your DNS according to the dhcp server's idea of DNS by first uncommenting the 'require' lines in it (they are examples of the default settings, but you need to uncomment them to override dhclient's defaults.)

request subnet-mask, broadcast-address, time-offset, routers,
      domain-name, domain-name-servers, host-name, lpr-servers, ntp-servers;
and then remove domain-name-servers. Of course, you may want to remove hostname, or other settings too.

6.4.2 DHCP Server

If you want to use OpenBSD as a DHCP server dhcpd(8), edit /etc/rc.conf. Set it up so that dhcpd_flags="-q" instead of dhcpd_flags=NO. Put the interfaces that you want dhcpd to listen on in /etc/dhcpd.interfaces.
# echo xl1 xl2 xl3 >/etc/dhcpd.interfaces
Then, edit /etc/dhcpd.conf. The options are pretty self explanatory.
        option  domain-name "xyz.mil";
        option  domain-name-servers,;

        subnet netmask {
                option routers;


This will tell your dhcp clients that the domain to append to DNS requests is xyz.mil (so, if the user types in 'telnet joe' then it will send them to joe.xyz.mil). It will point them to DNS servers and For hosts that are on the same network as an ethernet interface on the OpenBSD machine, which is in the range, it will assign them an IP address between and It will set their default gateway as

If you want to start dhcpd from the command line, after editing /etc/dhcpd.conf, try:

# dhcpd -q fxp0
Where fxp0 is an interface that you want to start serving dhcp on. The -q flag makes dhcpd quiet, otherwise it is very noisy.

If you are serving DHCP to a Windows box, you may want to dhcpd to give the client a 'WINS' server address. To make this happen, just the following line to your /etc/dhcpd.conf:

option	netbios-name-servers;
(where is the IP of your Windows or Samba server.) See dhcp-options(5) for more options that your DHCP clients may want.

6.5 - PPP

Point-to-Protocol is generally what is used to create a connection to your ISP via your modem. OpenBSD has 2 ways of doing this.

The first one we will cover will be the userland PPP daemon. To start off you will need some simple information about your isp. Here is a list of helpful information that you will need.

Some of these you can do without, but would be helpful in setting up your ppp. The userland PPP daemon uses the file /etc/ppp/ppp.conf as its configuration file. There are many helpful files in /etc/ppp that can have different setups for many different situations. You should take a browse though that directory.

Also, make sure, that if your not using a GENERIC kernel, that you have this line in your configuration file:

Initial Setup - for PPP(8)

Initial Setup for the userland PPP daemon consists of editing your /etc/ppp/ppp.conf file. This file doesn't exist by default, but there is a file /etc/ppp/ppp.conf.sample in which you can simply edit to create your own ppp.conf file. Here I will start with the simplist setup and probobly most used setup. Here is a quick ppp.conf file that will simply connect to your ISP and set your default routes and nameserver. With this file all the information you need is your ISP's phone number and your username and password.

NOTICE - On OpenBSD 2.6, the system shipped with a /etc/ppp/ppp.conf.example that had an incorrect setting for device. The device was "set device /dev/cuaa0". This should be /dev/cua00 which would correspond to serial device 1. (COM1). Your device might not be on COM1, however the nameing scheme was wrong.

The section under the default: tag will get executed each time. Here we setup all our critical information. Here with "set log" we set our logging levels. This can be changed, refer to ppp(8) for more info on setting up logging levels. Our device gets set with "set device". This is the device that the modem is on. In this example the modem is on com port 2. Therefore com port 1 would be /dev/cua00. With "set speed" we set the speed of our dialup connection and with "set dial" we set our dialup parameters. With this we can change our timeout time, etc. This line should stay pretty much as it is though.

Now we can move on and setup our information specific to our ISP. We do this by adding another tag under our default: section. This tag can be called anything you want, easiest to just use the name of your ISP. Here I will use myisp: as our tag refering to our ISP. Here is a simple setup incorporating all we need to get ourselves connected.

Here we have setup essential info for that specific ISP. The first option "set phone" sets your ISP's dialup number. The "set login" sets our login options. Here we have the timeout set to 5, this means that we will abort our login attempt after 5 seconds if no carrier. Otherwise it will wait for "login:" to be sent and send in your username and password. In this example our Username = ppp and Password = ppp. These values will need to be changed. The line "set timeout" sets the idle timeout for the entire connection duration to 120 seconds. The "set ifaddr" line is a little tricky. Here is a more extensive explanation.

In the above line, we have it set in the format of "set ifaddr [myaddr[/nn] [hisaddr[/nn] [netmask [triggeraddr]]]]". So the first IP specified is what we want as our IP. If you have a static IP address, you set it here. In our example we use /0 which says that no bits of this ip address need to match and the whole thing can be replaced. The second IP specified is what we expect as their IP. If you know this you can specify it. Again in our line we don't know what will be assigned, so we let them tell us. The third option is our netmask, here set to triggeraddr is specified, it is used in place of myaddr in the initial IPCP negotiation. However, only an address in the myaddr range will be accepted. This is useful when negotiating with some PPP implementations that will not assign an IP number unless their peer requests ``''.

The next option used "add default HISADDR" sets our default route to their IP. This is 'sticky', meaning that if their IP should change, our route will automatically be updated. With "enable dns" we are telling our ISP to authenticate our nameserver addresses. Do NOT do this if you are running an local DNS, as ppp will simply circumvent its use by entering some nameserver lines in /etc/resolv.conf.

Using PPP(8)

Now that we have our ppp.conf file setup we can start trying to make a connection to our ISP. I will detail some commonly used arguments with ppp.

By using /usr/sbin/ppp with no options will put you into interactive mode. From here you can interact directly with the modem, it is great for debugging problems in your ppp.conf file.

ppp(8) extra's

In some situations you might want commands executed as your connection is made or dropped. There are two files you can create for just these situations. /etc/ppp/ppp.linkup and /etc/ppp/ppp.linkdown. Sample configurations can be viewed here:

Extended information can be found at http://www.freebsd.org/handbook/userppp.html or http://www.freebsd.org/faq/userppp.html.

6.6 - Tuning networking parameters

6.6.1 - How can I tweak the kernel so that there are a higher number of retries and longer timeouts for TCP sessions?

You would normally use this to allow for routing or connection problems. Of course, for it to be most effective, both sides of the connection need to use similar values.

To tweak this, use sysctl and increase the values of:

Using sysctl -a, you can see the current values of these (and many other) parameters. To change one, use sysctl -w, as in sysctl -w net.inet.tcp.keepidle=28800.

6.6.2 - How can I turn on directed broadcasts?

Normally, you don't want to do this. This allows someone to send traffic to the broadcast address(es) of your connected network(s) if you are using your OpenBSD box as a router.

There are some instances, in closed networks, where this may be useful, particularly when using older implementations of the NetBIOS protocol. This is another sysctl. sysctl -w net.inet.ip.directed-broadcast=1 turns this on. Read about smurf attacks if you want to know why it is off by default.

6.6.3 - I don't want the kernel to dynamically allocate a certain port

There is a sysctl for this also. From sysctl(8):
Set the list of reserved TCP ports that should not be allocated by the
kernel dynamically.  This can be used to keep daemons from stealing a
specific port that another program needs to function.  List elements may
be separated by commas and/or whitespace.

   sysctl -w net.inet.tcp.baddynamic=749,750,751,760,761,871

It is also possible to add or remove ports from the current list.

   sysctl -w net.inet.tcp.baddynamic=+748
   sysctl -w net.inet.tcp.baddynamic=-871

6.7 - Simple NFS usage

NFS, or Network File System, is used to share a filesystem over the network. A few choice man pages to read before trying to setup a NFS server are:

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 talk about securing NFS. We presume you have already setup 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.

Another important security note. Don't just add a filesystem to /etc/exports without some kind of list of allowed host(s). Without a list of hosts which can mount a particular directory, anyone on who can reach your host will be able to mount your NFS exports.

The setup consists of a server with the ip This server will be serving NFS only to clients within that network. The first step to setting up NFS is to setup your /etc/exports file. This file lists which filesystems you wish to have accessable via NFS and defines who is able to access them. There are many options that you can use in your /etc/exports file, and it is best that you read the exports(5) man page. For this example we have an /etc/exports that looks like this:

This means that the local filesystem /work will be made available via NFS. -alldirs specifies that clients will be able to mount at any point under the /work mount point. -ro specifies that it will only be allowed to be mounted read-only. 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.

Once your /etc/exports file is setup, you can go ahead and setup your NFS server. You should first make sure that options NFSSERVER & NFSCLIENT are in your kernel configuration. (GENERIC kernel has these options included.) Next, you should set nfs_server=YES in /etc/rc.conf. This will bring up both nfsd(8) and mountd(8) when you reboot. Now, you can go ahead and start the daemons yourself. These daemons need to be started as root, and you need to make sure that portmap(8) is running on your system. Here is an example of starting nfsd(8) which serves on both TCP and UDP using 4 daemons. You should set an appropriate number of NFS server daemons to handle the maximum number of concurrent client requests that you want to service.

Not only do you have to start the nfsd(8) server, but you need to start mountd(8). This is the daemon that actually services the mount requests on NFS. To start mountd(8), simply type:

If you make changes to /etc/exports while NFS is already running, you need to make mountd aware of this! Just HUP it:

Checking Stats on NFS

From here, you can check to make sure that all these daemons are up and registered with RPC. To do this, use rpcinfo(8).

During normal usage, there are a few other utilities that allow you to see what is happening with NFS. One is showmount(8) , which allows you to view what is currently mounted and who is mounting it. There is also nfsstat(8) which shows much more verbose statistics. To use showmount(8), try /usr/bin/showmount -a host. For example:

Mounting NFS Filesystems

NFS filesystems should be mounted via mount(8), or more specifically, mount_nfs(8). To mount a filesystem /work on host to local filesystem /mnt, do this (note that you don't need to use an IP address, mount will resolve host names):

To have your system mount upon boot, add something like this to your /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 the NFS filesystem on boot!!!! The other standard security options, such as noexec, nodev, and nosuid, should also be used where applicable. Such as:

This way, no devices or setuid programs on the NFS server can subvert security measures on the NFS client. If you are not mounting programs which you expect to run on the NFS client, add noexec to this list.

6.8 - Domain Name Service - DNS, BIND, and named

6.8.1 What is DNS?

Domain Name Service is a network facility allowing IP network domains to provide name-to-IP address resolution and IP address-to-name resolution in response to a query. Your OpenBSD installation is configured by default as a DNS client but not as a DNS server. That is, your OpenBSD installation can perform a DNS query against a domain name server for the address of a machine, but it cannot answer such DNS queries itself unless you specifically configure it to do so.

My OpenBSD machine is currently connected to the Internet via my ISP, so I can use the nslookup(8) utility to execute the DNS query: is the name server which answered, because it is the nameserver that my ISP told me to use with my account and whose number is entered in /etc/resolv.conf. But the answer was not authoritative. For an authoritative answer, let's find which is the authoritative DNS server for the openbsd.org domain and ask it for the address of www.openbsd.org:

zeus.theos.com is, one would suppose, running OpenBSD and is properly configured to be a DNS server for the openbsd.org domain. Where can I learn all about DNS and its implementation under OpenBSD?

The dig(1) command is especially useful, because it can query a domain and return information in much the same record format as required in BIND configuration files. You can use dig(1) to examine name servers you know to be operating properly as a way of comparing your setup to theirs.

6.8.2 Does my machine need to be a domain name server?

If you aren't sure that you need your machine to perform the role of DNS server, don't configure it as one. The OpenBSD installation does not, by default, activate your machine as a domain name server, though all necessary files are installed. For most workstations, just the /etc/hosts file naming local machines' IP addresses and the /etc/resolv.conf file for indicating which DNS servers serve you out on the intranet or internet is sufficient.

On the other hand, you might need to set up a machine as a domain name server:

One more consideration is speed of execution. Since name resolution is an iterative process, in which the name server makes repeated queries to other nameservers for addresses in remote domains, name resolution may take slightly longer if you have a modem connection to the Internet and are querying your own DNS server for remote addresses (which will then iteratively query remote name servers via the modem) than if you are querying your ISP's name server (which probably has a faster connection to remote name servers).

6.8.3 What are the software components of the DNS server? What level of BIND is supported?

BIND is the name of the behavioral specification of a domain name server. Domain name server components exist to collectively implement BIND.

There are two distinct BIND specifications:

  1. BIND 4
  2. BIND 8

As installed, OpenBSD named supports BIND 4.x. What are some of the alternatives to providing DNS via the default BIND 4.x implementation? Security note

If you use these alternative implementations of domain name service, you are providing a critical network service using software which may not have been subject to quite the same level of scrutiny as the security-audited named name daemon in the base installation. This is a significant consideration, since if a domain name server is compromised, resolvers using that name server can be re-directed to impostor sites.

6.8.4 How much do I have to install?

If the default networking setup was installed properly at OpenBSD installation time, everything is already installed. You just have to configure the name daemon ("named").

6.8.5 How do I configure DNS?

You configure OpenBSD DNS by editing and/or creating files that control the name daemon named. These files reside by default in the directory /var/named and its subdirectories, especially the file /var/named/named.boot which is the initialization file for named. There are also a couple of other configuration steps to be taken in /etc.

In this document, we will configure the name daemon on nemo.yewtopia.com be the primary nameserver for the (very small!) domain yewtopia.com. The address of nemo.yewtopia.com is Two other machines are on that subnet, crater.yewtopia.com at and earhart.yewtopia.com at Configuration in /etc/named /var/named/named.boot

This tells the initialization process in what subdirectory and under which filenames to find the configuration files for yewtopia.com. /var/named/namedb/localhost.rev /var/named/namedb/yewtopia /var/named/namedb/yewtopia.rev Configuration in /etc /etc/resolv.conf

Make sure /etc/resolv.conf now points to the domain of local machine (instead of, for example, your ISP's name server) so that name resolution requests actually get sent to the named you have configured! /etc/hosts

If you previously had added the addresses of various machines to the /etc/hosts file, you might consider shortening your /etc/hosts file back to the default:

So that named isn't bypassed in favor of (possibly outdated) addresses in the /etc/hosts file. Make sure you have at least the default localhost entry or your network won't start properly! Note also nemo must appear in its own hosts file or you will see a (mostly harmless) error message at bootup when /etc/netstart invokes route(8) in order to add nemo (whose name appears in /etc/myname). Using dig(1) to examine the results.

6.8.6 How and when do I start and stop DNS? Starting DNS

The name daemon named is launched during system startup from /etc/rc if the line installed by default in /etc/rc.conf.

is changed to

Also, examine these lines in /etc/rc.conf:

These defaults will be correct for nearly all setups.

To start named by hand, use the ndc(8) command. For example: Stopping DNS

The best way to stop the name daemon is to use the ndc(8) command. For example:

If this fails to work, find the process id of named and use the kill(1) command to end that process. The PID for named while it is running is found as the first line in the file /var/named/named.pid Restarting DNS with an altered configuration

To cause a running instance of the name daemon to restart itself reloading its configuration after you have made changes, send it a "hangup" signal:

or by using the ndc(8) command. For example:

6.8.7 How do I block AXFR queries?


This information is useful for debugging DNS, but in some instances you may not want this output publically offered. If you are using classless in-addr(rfc2317) for reverse, host -l may report every domain that your system hosts! This can easily be remedied by the 'allow-transfer' clause in your zone file.

If you're using Bind8 you need to specify the hosts you want to allow to transfer zones in your individual zone file(s):

You can also block transfers for all domains by editting /var/named.conf and add the 'allow-transfer' parameter to the 'options' section of the configuration file: The Bind8 method also works with Bind9.
If you are using Bind 4 (default in OpenBSD) you can edit /var/named/named.boot and use the 'xfrnets' option.

Bind 4 allows transfers from entire classes so it is not as exact. Typically, the only hosts that need to perform transfers are your DNS slaves and hosts you may want to debug from ( is usually a good host to allow transfers from!) Blocking AXFR queries adds an extra level of privacy, but can hinder useful DNS debugging. (Thanks to Nicholas Tang for that tip)

6.8.8 What didn't you tell me about setting up DNS?

There's a lot we didn't tell you, for example, how to set up DNS so that queries for intranet domains that aren't visible from the root of the domain hierarchy get relayed to servers within your enterprise. Read the documents we recommended for more information on DNS.

6.9 - Setting up a PPTP connection in OpenBSD

NOTE: This does not apply to ALL ADSL providers, but much information can be gleamed from the setup here. This is known to work for Inode, an ADSL provider in Austria.

To start off, you need to install pptp. A port was added to the OpenBSD ports tree AFTER the release of OpenBSD 2.8 and works fine with with the OpenBSD 2.8 ports tree. The port is located at /ports/net/pptp. Read FAQ 8.6 for more information on the OpenBSD ports tree.

Because of a conflict between the In-Kernel gre(4) support and pptp, you will need to re-compile your kernel, removing support for gre(4).

To recompile your kernel, check out OpenBSD 2.8-stable via cvs (refer to OpenBSD Stable web page for more information), apply the following patch, and rebuild your kernel as per FAQ 5.3.

After you have the pptp package installed and a new kernel, you need to edit a few files to setup for your connection. This packages uses the in-house OpenBSD ppp(8), so if you are familiar with ppp(8), much of the setup is the same. Also, refer to FAQ 6.5.

For the /etc/ppp/options file, a setup like below will most likely do all that you need:

LOGINNAME should be replaced with your User-ID.

The /etc/ppp/pap-secrets a line like:

Where LOGINNAME is your User-ID and PASSWORD is your password. is the IP assigned to your MODEM in the case that you are using ADSL, etc. Make sure this file stays readonly by root (mode 600).

6.9.1 - Assigning an address to your Network Interface

In the above example, our modem came with a preconfigured interface of We now need to assign an address to OUR interface, It's best to pick an IP close to the one given by your MODEM, or use the static IP assigned to you. Read more about setting up interfaces in FAQ 6.1.

Once your interface is setup, you should be able to create a pptp connection with the command.

Since this uses the in-house OpenBSD ppp(8), two processes are started. You can kill pptp by killing both these processes:

It is recommended to open /var/log/messages in a extra terminal window, to recognize possible problems.

We also suggest that you put the startup command in /etc/rc.local so that you automatically connect on reboot.

[Back to Main Index] [To Section 5.0 - Kernel configuration and Disk Setup] [To Section 7.0 - Keyboard controls]

[back] www@openbsd.org
$OpenBSD: faq6.html,v 1.88 2001/01/27 22:19:47 ericj Exp $