Before we dive into configuring various aspects of network setup, we want to walk through the necessary bits that have to or can be present in the kernel. See Chapter 28, Compiling the kernel for more details on compiling the kernel, we will concentrate on the configuration of the kernel here. We will take the i386/GENERIC config file as an example here. Config files for other platforms should contain similar information, the comments in the config files give additional hints. Besides the information given here, each kernel option is also documented in the options(4) manpage, and there is usually a manpage for each driver too, e.g. tlp(4).

The first line of each config file shows the version. It can be used to compare against other versions via CVS, or when reporting bugs.

options         NTP             # NTP phase/frequency locked loop

If you want to run the Network Time Protocol (NTP), this option can be enabled for maximum precision. If the option is not present, NTP will still work. See ntpd(8) for more information.

file-system     NFS             # Network File System client

If you want to use another machine's hard disk via the Network File System (NFS), this option is needed. Section 25.2, “Network File System (NFS)” gives more information on NFS.

options         NFSSERVER       # Network File System server

This option includes the server side of the NFS remote file sharing protocol. Enable if you want to allow other machines to use your hard disk. Section 25.2, “Network File System (NFS)” contains more information on NFS.

#options        GATEWAY         # packet forwarding

If you want to setup a router that forwards packets between networks or network interfaces, setting this option is needed. If doesn't only switch on packet forwarding, but also increases some buffers. See options(4) for details.

options         INET            # IP + ICMP + TCP + UDP

This enables the TCP/IP code in the kernel. Even if you don't want/use networking, you will still need this for machine-internal communication of subsystems like the X Window System. See inet(4) for more details.

options         INET6           # IPV6

If you want to use IPv6, this is your option. If you don't want IPv6, which is part of NetBSD since the 1.5 release, you can remove/comment out that option. See the inet6(4) manpage and Section 20.7, “Next generation Internet protocol - IPv6” for more information on the next generation Internet protocol.

#options        IPSEC           # IP security

Includes support for the IPsec protocol, including key and policy management, authentication and compression. This option can be used without the previous option INET6, if you just want to use IPsec with IPv4, which is possible. See ipsec(4) for more information.

#options        IPSEC_ESP       # IP security (encryption part; define w/IPSEC)

This option is needed in addition to IPSEC if encryption is wanted in IPsec.

#options        MROUTING        # IP multicast routing

If multicast services like the MBone services should be routed, this option needs to be included. Note that the routing itself is controlled by the mrouted(8) daemon.

options         NS              # XNS
#options        NSIP            # XNS tunneling over IP

These options enable the Xerox Network Systems(TM) protocol family. It's not related to the TCP/IP protocol stack, and in rare use today. The ns(4) manpage has some details.

options         ISO,TPIP        # OSI
#options        EON             # OSI tunneling over IP

These options include the OSI protocol stack, which was said for a long time to be the future of networking. It's mostly history these days. :-) See the iso(4) manpage for more information.

options         CCITT,LLC,HDLC  # X.25

These options enable the X.25 protocol set for transmission of data over serial lines. It is/was used mostly in conjunction with the OSI protocols and in WAN networking.

options         NETATALK        # AppleTalk networking protocols

Include support for the AppleTalk protocol stack. Userland server programs are needed to make use of that. See pkgsrc/net/netatalk and pkgsrc/net/netatalk-asun for such packages. More information on the AppleTalk protocol and protocol stack are available in the atalk(4) manpage.

options         PPP_BSDCOMP     # BSD-Compress compression support for PPP
options         PPP_DEFLATE     # Deflate compression support for PPP
options         PPP_FILTER      # Active filter support for PPP (requires bpf)

These options tune various aspects of the Point-to-Point protocol. The first two determine the compression algorithms used and available, while the third one enables code to filter some packets.

options         PFIL_HOOKS      # pfil(9) packet filter hooks
options         IPFILTER_LOG    # ipmon(8) log support

These options enable firewalling in NetBSD, using IPfilter. See the ipf(4) and ipf(8) manpages for more information on operation of IPfilter, and Section 21.5.1, “Configuring the gateway/firewall” for a configuration example.

# Compatibility with 4.2BSD implementation of TCP/IP.  Not recommended.
#options        TCP_COMPAT_42

This option is only needed if you have machines on the network that still run 4.2BSD or a network stack derived from it. If you've got one or more 4.2BSD-systems on your network, you've to pay attention to set the right broadcast-address, as 4.2BSD has a bug in its networking code, concerning the broadcast address. This bug forces you to set all host-bits in the broadcast-address to “0”. The TCP_COMPAT_42 option helps you ensuring this.

options         NFS_BOOT_DHCP,NFS_BOOT_BOOTPARAM

These options enable lookup of data via DHCP or the BOOTPARAM protocol if the kernel is told to use a NFS root file system. See the diskless(8) manpage for more information.

# Kernel root file system and dump configuration.
config          netbsd  root on ? type ?
#config         netbsd  root on sd0a type ffs
#config         netbsd  root on ? type nfs

These lines tell where the kernel looks for its root file system, and which filesystem type it is expected to have. If you want to make a kernel that uses a NFS root filesystem via the tlp0 interface, you can do this with “root on tlp0 type nfs”. If a ? is used instead of a device/type, the kernel tries to figure one out on its own.

# ISA serial interfaces
com0    at isa? port 0x3f8 irq 4        # Standard PC serial ports
com1    at isa? port 0x2f8 irq 3
com2    at isa? port 0x3e8 irq 5

If you want to use PPP or SLIP, you will need some serial (com) interfaces. Others with attachment on USB, PCMCIA or PUC will do as well.

# Network Interfaces

This rather long list contains all sorts of network drivers. Please pick the one that matches your hardware, according to the comments. For most drivers, there's also a manual page available, e.g. tlp(4), ne(4), etc.

# MII/PHY support

This section lists media independent interfaces for network cards. Pick one that matches your hardware. If in doubt, enable them all and see what the kernel picks. See the mii(4) manpage for more information.

# USB Ethernet adapters
aue*    at uhub? port ?         # ADMtek AN986 Pegasus based adapters
cue*    at uhub? port ?         # CATC USB-EL1201A based adapters
kue*    at uhub? port ?         # Kawasaki LSI KL5KUSB101B based adapters

USB-ethernet adapters only have about 2MBit/s bandwidth, but they are very convenient to use. Of course this needs other USB related options which we won't cover here, as well as the necessary hardware. See the corresponding manpages for more information.

# network pseudo-devices
pseudo-device   bpfilter        8       # Berkeley packet filter

This pseudo-device allows sniffing packets of all sorts. It's needed for tcpdump, but also rarpd and some other applications that need to know about network traffic. See bpf(4) for more information.

pseudo-device   ipfilter                # IP filter (firewall) and NAT

This one enables the IPfilter's packet filtering kernel interface used for firewalling, NAT (IP Masquerading) etc. See ipf(4) and Section 21.5.1, “Configuring the gateway/firewall” for more information.

pseudo-device   loop                    # network loopback

This is the “lo0” software loopback network device which is used by some programs these days, as well as for routing things. It should not be omitted. See lo(4) for more details.

pseudo-device   ppp             2       # Point-to-Point Protocol

If you want to use PPP either over a serial interface or ethernet (PPPoE), you will need this option. See ppp(4) for details on this interface.

pseudo-device   sl              2       # Serial Line IP

Serial Line IP is a simple encapsulation for IP over (well :) serial lines. It does not include negotiation of IP addresses and other options, which is the reason that it's not in widespread use today any more. See sl(4).

pseudo-device   strip           2       # Starmode Radio IP (Metricom)

If you happen to have one of the old Metricon Ricochet packet radio wireless network devices, use this pseudo-device to use it. See the strip(4) manpage for detailed information.

pseudo-device   tun             2       # network tunneling over tty

This network device can be used to tunnel network packets to a device file, /dev/tun*. Packets routed to the tun0 interface can be read from /dev/tun0, and data written to /dev/tun0 will be sent out the tun0 network interface. This can be used to implement e.g. QoS routing in userland. See tun(4) for details.

pseudo-device   gre             2       # generic L3 over IP tunnel

The GRE encapsulation can be used to tunnel arbitrary layer 3 packets over IP, e.g. to implement VPNs. See gre(4) for more.

pseudo-device   ipip            2       # IP Encapsulation within IP (RFC 2003)

Another IP-in-IP encapsulation device, with a different encapsulation format. See the ipip(4) manpage for details.

pseudo-device   gif             4       # IPv[46] over IPv[46] tunnel (RFC 1933)

Using the GIF interface allows to tunnel e.g. IPv6 over IPv4, which can be used to get IPv6 connectivity if no IPv6-capable uplink (ISP) is available. Other mixes of operations are possible, too. See the gif(4) manpage for some examples.

#pseudo-device  faith           1       # IPv[46] tcp relay translation i/f

The faith interface captures IPv6 TCP traffic, for implementing userland IPv6-to-IPv4 TCP relays e.g. for protocol transitions. See the faith(4) manpage for more details on this device.

#pseudo-device  stf             1       # 6to4 IPv6 over IPv4 encapsulation

This adds a network device that can be used to tunnel IPv6 over IPv4 without setting up a configured tunnel before. The source address of outgoing packets contains the IPv4 address, which allows routing replies back via IPv4. See the stf(4) manpage and Section 25.4, “IPv6 Connectivity & Transition via 6to4” for more details.

pseudo-device   vlan                    # IEEE 802.1q encapsulation

This interface provides support for IEEE 802.1Q Virtual LANs, which allows tagging Ethernet frames with a “vlan” ID. Using properly configured switches (that also have to support VLAN, of course), this can be used to build virtual LANs where one set of machines doesn't see traffic from the other (broadcast and other). The vlan(4) manpage tells more about this.

The following is a list of the files used to configure the network. The usage of these files, some of which have already been met the first chapters, will be described in the following sections.

There are many types of Internet connections: this section explains how to connect to a provider using a modem over a telephone line using the PPP protocol, a very common setup. In order to have a working connection, the following steps must be done:

Judging from the previous list it looks like a complicated procedure that requires a lot of work. Actually, the single steps are very easy: it's just a matter of modifying, creating or simply checking some small text files. In the following example it will be assumed that the modem is connected to the second serial port /dev/tty01 (COM2 in DOS).

A few words on the difference between com, COM and tty. For NetBSD, “com” is the name of the serial port driver (the one that is displayed by dmesg) and “tty” is the name of the port. Since numbering starts at 0, com0 is the driver for the first serial port, named tty00. In the DOS world, instead, COM1 refers to the first serial port (usually located at (0x3f8), COM2 to the second, and so on. Therefore COM1 (DOS) corresponds to /dev/tty00 (NetBSD).

Besides external modems connected to COM ports (using /dev/tty0[012] on i386, /dev/tty[ab] on sparc, ...) modems on USB (/dev/ttyU*) and pcmcia/cardbus (/dev/tty0[012]) can be used.

nameserver 194.109.123.2
nameserver 191.200.4.52

# /etc/nsswitch.conf
group:         compat
group_compat:  nis
hosts:         files dns
netgroup:      files [notfound=return] nis
networks:      files
passwd:        compat
passwd_compat: nis
shells:        files

# mkdir /etc/ppp
# mkdir /etc/ppp/peers 

# /etc/ppp/peers/bignet
connect '/usr/sbin/chat -v -f /etc/ppp/peers/bignet.chat'
noauth
user alan
remotename bignet.it

debug
kdebug 4

# /etc/ppp/peers/bignet.chat
ABORT BUSY
ABORT "NO CARRIER"
ABORT "NO DIALTONE"
'' ATDT0299999999
CONNECT ''

user * password

alan * pZY9o

# chown root /etc/ppp/pap-secrets
# chown root /etc/ppp/chap-secrets
# chmod 600 /etc/ppp/pap-secrets
# chmod 600 /etc/ppp/chap-secrets

# /etc/ppp/peers/bignet.chat
ABORT BUSY
ABORT "NO CARRIER"
ABORT "NO DIALTONE"
'' ATDT0299999999
CONNECT ''
TIMEOUT 50
ogin: alan
ssword: pZY9o

/dev/tty01
lock
crtscts
57600
modem
defaultroute
noipdefault

$ ls -l /dev/tty00
crw-------  1 uucp  wheel  8, 0 Mar 22 20:39 /dev/tty00

$ ls -l /dev/tty00
crw-------  1 root  wheel  8, 0 Mar 22 20:39 /dev/tty00
$ cu -p modem
cu: open (/dev/tty00): Permission denied
cu: All matching ports in use

# pppd call bignet

# tail -f /var/log/messages

 # pkill -HUP pppd 

#!/bin/sh
MODEM=tty01
POP=bignet
if [ -f /var/spool/lock/LCK..$MODEM ]; then
echo ppp is already running...
else
pppd call $POP
tail -f /var/log/messages
fi

#!/bin/sh
MODEM=tty01
if [ -f /var/spool/lock/LCK..$MODEM ]; then
echo -f killing pppd...
kill -HUP `cat /var/spool/lock/LCK..$MODEM`
echo done
else
echo ppp is not active
fi

# chmod u+x ppp-start ppp-stop

Networking is one of the main strengths of Unix and NetBSD is no exception: networking is both powerful and easy to set up and inexpensive too, because there is no need to buy additional software to communicate or to build a server. Section 21.5, “Setting up an Internet gateway with IPNAT” explains how to configure a NetBSD machine to act as a gateway for a network: with IPNAT all the hosts of the network can reach the Internet with a single connection to a provider made by the gateway machine. The only thing to be checked before creating the network is to buy network cards supported by NetBSD (check the INSTALL.* files for a list of supported devices).

First, the network cards must be installed and connected to a hub, switch or directly (see Figure 21.1, “Network with gateway”).

Next, check that the network cards are recognized by the kernel, studying the output of the dmesg command. In the following example the kernel recognized correctly an NE2000 clone:

...
ne0 at isa0 port 0x280-0x29f irq 9
ne0: NE2000 Ethernet
ne0: Ethernet address 00:c2:dd:c1:d1:21
...

If the card is not recognized by the kernel, check that it is enabled in the kernel configuration file and then that the card's IRQ matches the one that the kernel expects. For example, this is the isa NE2000 line in the configuration file; the kernel expects the card to be at IRQ 9.

...
ne0 at isa? port 0x280 irq 9 # NE[12]000 ethernet cards
...

If the card's configuration is different, it will probably not be found at boot. In this case, either change the line in the kernel configuration file and compile a new kernel or change the card's setup (usually through a setup disk or, for old cards, a jumper on the card).

The following command shows the network card's current configuration:

# ifconfig ne0
ne0: flags=8822<BROADCAST,NOTRAILERS,SIMPLEX,MULTICAST> mtu 1500
      address: 00:50:ba:aa:a7:7f
      media: Ethernet autoselect (10baseT)
      inet6 fe80::250:baff:feaa:a77f%ne0 prefixlen 64 scopeid 0x1 

The software configuration of the network card is very easy. The IP address “192.168.1.1” is assigned to the card.

# ifconfig ne0 inet 192.168.1.1 netmask 0xffffff00

Note that the networks 10.0.0.0/8 and 192.168.0.0/16 are reserved for private networks, which is what we're setting up here.

Repeating the previous command now gives a different result:

# ifconfig ne0
ne0: flags=8863<UP,BROADCAST,NOTRAILERS,RUNNING,SIMPLEX,MULTICAST> mtu 1500
      address: 00:50:ba:aa:a7:7f
      media: Ethernet autoselect (10baseT)
      inet 192.168.1.1 netmask 0xffffff00 broadcast 192.168.1.255
      inet6 fe80::250:baff:feaa:a77f%ne0 prefixlen 64 scopeid 0x1 

The output of ifconfig has now changed: the IP address is now printed and there are two new flags, “UP” and “RUNNING” If the interface isn't “UP”, it will not be used by the system to send packets.

The host was given the IP address 192.168.1.1, which belongs to the set of addresses reserved for internal networks which are not reachable from the Internet. The configuration is finished and must now be tested; if there is another active host on the network, a ping can be tried. For example, if 192.168.1.2 is the address of the active host:

# ping 192.168.1.2
PING ape (192.168.1.2): 56 data bytes
64 bytes from 192.168.1.2: icmp_seq=0 ttl=255 time=1.286 ms
64 bytes from 192.168.1.2: icmp_seq=1 ttl=255 time=0.649 ms
64 bytes from 192.168.1.2: icmp_seq=2 ttl=255 time=0.681 ms
64 bytes from 192.168.1.2: icmp_seq=3 ttl=255 time=0.656 ms
^C
----ape PING Statistics----
4 packets transmitted, 4 packets received, 0.0% packet loss
round-trip min/avg/max/stddev = 0.649/0.818/1.286/0.312 ms

With the current setup, at the next boot it will be necessary to repeat the configuration of the network card. In order to avoid repeating the card's configuration at each boot, add the following lines to /etc/rc.conf:

auto_ifconfig=yes
ifconfig_ne0="inet 192.168.1.1 netmask 0xffffff00" 

In this example the variable ifconfig_ne0 was set because the network card was recognized as ne0 by the kernel; if you are using a different adapter, substitute the appropriate name in place of ne0.

At the next boot the network card will be configured automatically.

If you have a router that is connected to the internet, you can use it as default router, which will handle all your packets. To do so, set defaultroute to the router's IP address in /etc/rc.conf:

defaultroute=192.168.0.254

Be sure to use the default router's IP address instead of name, in case your DNS server is beyond the default router. In that case, the DNS server couldn't be reached to resolve the default router's hostname and vice versa, creating a chicken-and-egg problem.

To reach hosts on your local network, and assuming you really have very few hosts, adjust /etc/hosts to contain the addresses of all the hosts belonging to the internal network. For example:

#
# Host Database
# This file should contain the addresses and aliases
# for local hosts that share this file.
# It is used only for "ifconfig" and other operations
# before the nameserver is started.
#
#
127.0.0.1             localhost
::1                   localhost
#
# RFC 1918 specifies that these networks are "internal".
# 10.0.0.0    10.255.255.255
# 172.16.0.0  172.31.255.255
# 192.168.0.0 192.168.255.255

192.168.1.1   ape.insetti.net ape
192.168.1.2   vespa.insetti.net vespa
192.168.1.0   insetti.net

If you are dialed in via an Internet Service Provider, or if you have a local Domain Name Server (DNS) running, you may want to use it to resolve hostnames to IP addresses, possibly in addition to /etc/hosts, which would only know your own hosts. To configure a machine as DNS client, you need to edit /etc/resolv.conf, and enter the DNS server's address, in addition to an optional domain name that will be appended to hosts with no domain, in order to create a FQDN for resolving. Assuming your DNS server's IP address is 192.168.1.2 and it is setup to serve for "home.net", put the following into /etc/resolv.conf:

# /etc/resolv.conf
domain home.net
nameserver 192.168.1.2

The /etc/nsswitch.conf file should be checked as explained in Example 21.2, “nsswitch.conf”.

Summing up, to configure the network the following must be done: the network adapters must be installed and physically connected. Next they must be configured (with ifconfig) and, finally, the file /etc/rc.conf must be modified to configure the interface and possibly default router, and /etc/resolv.conf and /etc/nsswitch.confshould be adjusted if DNS should be used. This type of network management is sufficient for small networks without sophisticated needs.

The mysterious acronym IPNAT hides the Internet Protocol Network Address Translation, which enables the routing of an internal network (e.g. your home network as described in Section 21.4, “Creating a small home network ”) on a real network (Internet). This means that with only one “real” IP, static or dynamic, belonging to a gateway running IPNAT, it is possible to create simultaneous connections to the Internet for all the hosts of the internal network.

Some usage examples of IPNAT can be found in the subdirectory /usr/share/examples/ipf: look at the files BASIC.NAT and nat-setup.

The setup for the example described in this section is detailed in Figure 21.1, “Network with gateway”: host 1 can connect to the Internet calling a provider with a modem and getting a dynamic IP address. host 2 and host 3 can't communicate with the Internet with a normal setup: IPNAT allows them to do it: host 1 will act as a Internet gateway for hosts 2 and 3. Using host 1 as default router, hosts 2 and 3 will be able to access the Internet.

Figure 21.1. Network with gateway

# sysctl net.inet.ip.forwarding
net.inet.ip.forwarding = 1

map ppp0 192.168.1.0/24 -> 0/32 proxy port ftp ftp/tcp
map ppp0 192.168.1.0/24 -> 0/32 portmap tcp/udp 40000:60000
map ppp0 192.168.1.0/24 -> 0/32

#!/bin/sh
# /etc/ppp/ip-up
/etc/rc.d/ipnat forcestart

#!/bin/sh
# /etc/ppp/ip-down
/etc/rc.d/ipnat forcestop

# chmod u+x ip-up ip-down

# route add default 192.168.1.1

The small home network discussed in the previous section contained many items that were configured manually. In bigger LANs that are centrally managed, one can expect Internet connectivity being available via some router, a DNS server being available, and most important, a DHCP server which hands out IP addresses to clients on request. To make a NetBSD client run in such an environment, it's usually enough to set

dhclient=yes

in /etc/rc.conf, and the IP address will be set automatically, /etc/resolv.conf will be created and routing setup to the default router.

If you need to transfer files between two PCs which are not networked there is a simple solution which is particularly handy when copying the files to a floppy is not practical: the two machines can be networked with a serial cable (a null modem cable). The following sections describe some configurations.

# slattach /dev/tty00
# ifconfig sl0 inet 192.168.1.1 192.168.1.2

# slattach /dev/tty00
# ifconfig sl0 inet 192.168.1.2 192.168.1.1

# ping 192.168.1.1

# slattach -p slip -s 115200 /dev/ttyS0 &
# ifconfig sl0 192.168.1.2 pointopoint 192.168.1.1 up
# route add 192.168.1.1 dev sl0

connect '/usr/sbin/chat -v CLIENT CLIENTSERVER'
local
tty00
115200
crtscts
lock
noauth
nodefaultroute
:192.168.1.2