File:  [NetBSD Developer Wiki] / wikisrc / guide / net-practice.mdwn
Revision 1.6: download - view: text, annotated - select for diffs
Fri Jun 22 21:15:35 2018 UTC (5 years, 5 months ago) by maya
Branches: MAIN
CVS tags: HEAD
Refer to dhcpcd.

XXX why does this page suggest SLIP

    1: **Contents**
    3: [[!toc levels=3]]
    5: # Setting up TCP/IP on NetBSD in practice
    7: ## A walk through the kernel configuration
    9: Before we dive into configuring various aspects of network setup, we want to 
   10: walk through the necessary bits that have to or can be present in the kernel. 
   11: See [[Compiling the kernel|guide/kernel]] for more details on compiling the 
   12: kernel, we will concentrate on the configuration of the kernel here. We will 
   13: take the i386/GENERIC config file as an example here. Config files for other 
   14: platforms should contain similar information, the comments in the config files 
   15: give additional hints. Besides the information given here, each kernel option is 
   16: also documented in the 
   17: [[!template id=man name="options" section="4"]] 
   18: manpage, and there is usually a manpage for each driver too, e.g. 
   19: [[!template id=man name="tlp" section="4"]].
   21: The first line of each config file shows the version. It can be used to compare 
   22: against other versions via CVS, or when reporting bugs.
   24:     options         NTP             # NTP phase/frequency locked loop
   26: If you want to run the Network Time Protocol (NTP), this option can be enabled 
   27: for maximum precision. If the option is not present, NTP will still work. See 
   28: [[!template id=man name="ntpd" section="8"]] for 
   29: more information.
   31:     file-system     NFS             # Network File System client
   33: If you want to use another machine's hard disk via the Network File System 
   34: (NFS), this option is needed. The guide article about the
   35: [[Network File System|guide/net-services#nfs]] gives more information on NFS.
   37:     options         NFSSERVER       # Network File System server
   39: This option includes the server side of the NFS remote file sharing protocol. 
   40: Enable if you want to allow other machines to use your hard disk. The mentioned 
   41: article in the guide about [[NFS|guide/net-services#nfs]] contains more 
   42: information on NFS.
   44:     #options        GATEWAY         # packet forwarding
   46: If you want to setup a router that forwards packets between networks or network 
   47: interfaces, setting this option is needed. It doesn't only switch on packet 
   48: forwarding, but also increases some buffers. See 
   49: [[!template id=man name="options" section="4"]] 
   50: for details.
   52:     options         INET            # IP + ICMP + TCP + UDP
   54: This enables the TCP/IP code in the kernel. Even if you don't want/use 
   55: networking, you will still need this for machine-internal communication of 
   56: subsystems like the X Window System. See 
   57: [[!template id=man name="inet" section="4"]] for 
   58: more details.
   60:     options         INET6           # IPV6
   62: If you want to use IPv6, this is your option. If you don't want IPv6, which is 
   63: part of NetBSD since the 1.5 release, you can remove/comment out that option. 
   64: See the 
   65: [[!template id=man name="inet6" section="4"]] 
   66: manpage and [[Next generation Internet protocol - 
   67: IPv6|guide/net-intro#ipv6-intro]] for more information on the next generation 
   68: Internet protocol.
   70:     #options        IPSEC           # IP security
   72: Includes support for the IPsec protocol, including key and policy management, 
   73: authentication and compression. This option can be used without the previous 
   74: option INET6, if you just want to use IPsec with IPv4, which is possible. See 
   75: [[!template id=man name="ipsec" section="4"]] for 
   76: more information.
   78:     #options        IPSEC_ESP       # IP security (encryption part; define w/IPSEC)
   80: This option is needed in addition to IPSEC if encryption is wanted in IPsec.
   82:     #options        MROUTING        # IP multicast routing
   84: If multicast services like the MBone services should be routed, this option 
   85: needs to be included. Note that the routing itself is controlled by the 
   86: [[!template id=man name="mrouted" section="8"]] 
   87: daemon.
   89:     options         ISO,TPIP        # OSI
   90:     #options        EON             # OSI tunneling over IP
   92: These options include the OSI protocol stack, which was said for a long time to 
   93: be the future of networking. It's mostly history these days. :-) See the 
   94: [[!template id=man name="iso" section="4"]] manpage 
   95: for more information.
   97:     options         NETATALK        # AppleTalk networking protocols
   99: Include support for the AppleTalk protocol stack. Userland server programs are 
  100: needed to make use of that. See pkgsrc/net/netatalk and pkgsrc/net/netatalk-asun 
  101: for such packages. More information on the AppleTalk protocol and protocol stack 
  102: are available in the 
  103: [[!template id=man name="atalk" section="4"]] 
  104: manpage.
  106:     options         PPP_BSDCOMP     # BSD-Compress compression support for PPP
  107:     options         PPP_DEFLATE     # Deflate compression support for PPP
  108:     options         PPP_FILTER      # Active filter support for PPP (requires bpf)
  110: These options tune various aspects of the Point-to-Point protocol. The first two 
  111: determine the compression algorithms used and available, while the third one 
  112: enables code to filter some packets.
  114:     options         PFIL_HOOKS      # pfil(9) packet filter hooks
  115:     options         IPFILTER_LOG    # ipmon(8) log support
  117: These options enable firewalling in NetBSD, using IPFilter. See the 
  118: [[!template id=man name="ipf" section="4"]] and 
  119: [[!template id=man name="ipf" section="8"]] manpages 
  120: for more information on operation of IPFilter, and [[Configuring the 
  121: 	gateway/firewall|guide/net-practice#ipnat-configuring-gateway]] for a 
  122: 	configuration example.
  124:     # Compatibility with 4.2BSD implementation of TCP/IP.  Not recommended.
  125:     #options        TCP_COMPAT_42
  127: This option is only needed if you have machines on the network that still run 
  128: 4.2BSD or a network stack derived from it. If you've got one or more 
  129: 4.2BSD-systems on your network, you've to pay attention to set the right 
  130: broadcast-address, as 4.2BSD has a bug in its networking code, concerning the 
  131: broadcast address. This bug forces you to set all host-bits in the 
  132: broadcast-address to `0`. The `TCP_COMPAT_42` option helps you ensuring this.
  134:     options         NFS_BOOT_DHCP,NFS_BOOT_BOOTPARAM
  136: These options enable lookup of data via DHCP or the BOOTPARAM protocol if the 
  137: kernel is told to use a NFS root file system. See the 
  138: [[!template id=man name="diskless" section="8"]] 
  139: manpage for more information.
  141:     # Kernel root file system and dump configuration.
  142:     config          netbsd  root on ? type ?
  143:     #config         netbsd  root on sd0a type ffs
  144:     #config         netbsd  root on ? type nfs
  146: These lines tell where the kernel looks for its root file system, and which 
  147: filesystem type it is expected to have. If you want to make a kernel that uses a 
  148: NFS root filesystem via the tlp0 interface, you can do this with
  150:     root on tlp0 type       nfs
  152: If a `?` is used instead of a device/type, the kernel tries to 
  153: figure one out on its own.
  155:     # ISA serial interfaces
  156:     com0    at isa? port 0x3f8 irq 4        # Standard PC serial ports
  157:     com1    at isa? port 0x2f8 irq 3
  158:     com2    at isa? port 0x3e8 irq 5
  160: If you want to use PPP or SLIP, you will need some serial (com) interfaces. 
  161: Others with attachment on USB, PCMCIA or PUC will do as well.
  163:     # Network Interfaces
  165: This rather long list contains all sorts of network drivers. Please pick the one 
  166: that matches your hardware, according to the comments. For most drivers, there's 
  167: also a manual page available, e.g. 
  168: [[!template id=man name="tlp" section="4"]], 
  169: [[!template id=man name="ne" section="4"]], etc.
  171:     # MII/PHY support
  173: This section lists media independent interfaces for network cards. Pick one that 
  174: matches your hardware. If in doubt, enable them all and see what the kernel 
  175: picks. See the 
  176: [[!template id=man name="mii" section="4"]] manpage 
  177: for more information.
  179:     # USB Ethernet adapters
  180:     aue*    at uhub? port ?         # ADMtek AN986 Pegasus based adapters
  181:     cue*    at uhub? port ?         # CATC USB-EL1201A based adapters
  182:     kue*    at uhub? port ?         # Kawasaki LSI KL5KUSB101B based adapters
  184: USB-ethernet adapters only have about 2MBit/s bandwidth, but they are very 
  185: convenient to use. Of course this needs other USB related options which we won't 
  186: cover here, as well as the necessary hardware. See the corresponding manpages 
  187: for more information.
  189:     # network pseudo-devices
  190:     pseudo-device   bpfilter        8       # Berkeley packet filter
  192: This pseudo-device allows sniffing packets of all sorts. It's needed for 
  193: tcpdump, but also rarpd and some other applications that need to know about 
  194: network traffic. See 
  195: [[!template id=man name="bpf" section="4"]] for more 
  196: information.
  198:     pseudo-device   ipfilter                # IP filter (firewall) and NAT
  200: This one enables the IPFilter's packet filtering kernel interface used for 
  201: firewalling, NAT (IP Masquerading) etc. See 
  202: [[!template id=man name="ipf" section="4"]] and 
  203: [Configuring the gateway/firewall|guide/net-practice#ipnat-configuring-gateway]] 
  204: for more information.
  206:     pseudo-device   loop                    # network loopback
  208: This is the `lo0` software loopback network device which is used by some 
  209: programs these days, as well as for routing things. It should not be omitted. 
  210: See [[!template id=man name="lo" section="4"]] for 
  211: more details.
  213:     pseudo-device   ppp             2       # Point-to-Point Protocol
  215: If you want to use PPP either over a serial interface or ethernet (PPPoE), you 
  216: will need this option. See 
  217: [[!template id=man name="ppp" section="4"]] for 
  218: details on this interface.
  220:     pseudo-device   sl              2       # Serial Line IP
  222: Serial Line IP is a simple encapsulation for IP over (well :) serial lines. It 
  223: does not include negotiation of IP addresses and other options, which is the 
  224: reason that it's not in widespread use today any more. See 
  225: [[!template id=man name="sl" section="4"]].
  227:     pseudo-device   strip           2       # Starmode Radio IP (Metricom)
  229: If you happen to have one of the old Metricom Ricochet packet radio wireless 
  230: network devices, use this pseudo-device to use it. See the 
  231: [[!template id=man name="strip" section="4"]] 
  232: manpage for detailed information.
  234:     pseudo-device   tun             2       # network tunneling over tty
  236: This network device can be used to tunnel network packets to a device file, 
  237: `/dev/tun*`. Packets routed to the tun0 interface can be read from `/dev/tun0`, 
  238: and data written to `/dev/tun0` will be sent out the tun0 network interface. 
  239: This can be used to implement e.g. QoS routing in userland. See 
  240: [[!template id=man name="tun" section="4"]] for 
  241: details.
  243:     pseudo-device   gre             2       # generic L3 over IP tunnel
  245: The GRE encapsulation can be used to tunnel arbitrary layer 3 packets over IP, 
  246: e.g. to implement VPNs. See 
  247: [[!template id=man name="gre" section="4"]] for more.
  249:     pseudo-device   gif             4       # IPv[46] over IPv[46] tunnel (RFC 1933)
  251: Using the GIF interface allows to tunnel e.g. IPv6 over IPv4, which can be used 
  252: to get IPv6 connectivity if no IPv6-capable uplink (ISP) is available. Other 
  253: mixes of operations are possible, too. See the 
  254: [[!template id=man name="gif" section="4"]] manpage 
  255: for some examples.
  257:     #pseudo-device  faith           1       # IPv[46] tcp relay translation i/f
  259: The faith interface captures IPv6 TCP traffic, for implementing userland 
  260: IPv6-to-IPv4 TCP relays e.g. for protocol transitions. See the 
  261: [[!template id=man name="faith" section="4"]] 
  262: manpage for more details on this device.
  264:     #pseudo-device  stf             1       # 6to4 IPv6 over IPv4 encapsulation
  266: This adds a network device that can be used to tunnel IPv6 over IPv4 without 
  267: setting up a configured tunnel before. The source address of outgoing packets 
  268: contains the IPv4 address, which allows routing replies back via IPv4. See the 
  269: [[!template id=man name="stf" section="4"]] manpage 
  270: and [IPv6 Connectivity & Transition via 6to4|guide/net-practice#ipv6-6to4]] for 
  271: more details.
  273:     pseudo-device   vlan                    # IEEE 802.1q encapsulation
  275: This interface provides support for IEEE 802.1Q Virtual LANs, which allows 
  276: tagging Ethernet frames with a `vlan` ID. Using properly configured switches 
  277: (that also have to support VLAN, of course), this can be used to build virtual 
  278: LANs where one set of machines doesn't see traffic from the other (broadcast and 
  279: other). The 
  280: [[!template id=man name="vlan" section="4"]] manpage 
  281: tells more about this.
  283: ## Overview of the network configuration files
  285: The following is a list of the files used to configure the network. The usage of 
  286: these files, some of which have already been met the first chapters, will be 
  287: described in the following sections.
  289:  * `/etc/hosts` -- Local hosts database file. Each line contains information 
  290:    regarding a known host and contains the internet address, the host's name and 
  291:    the aliases. Small networks can be configured using only the hosts file, 
  292:    without a *name server*.
  294:  * `/etc/resolv.conf` -- This file specifies how the routines which provide 
  295:    access to the Internet Domain Name System should operate. Generally it 
  296:    contains the addresses of the name servers.
  298:  * `/etc/` -- This file is used for the automatic configuration of 
  299:    the network card at boot.
  301:  * `/etc/mygate` -- Contains the IP address of the gateway.
  303:  * `/etc/nsswitch.conf` -- Name service switch configuration file. It controls 
  304:    how a process looks up various databases containing information regarding 
  305:    hosts, users, groups, etc. Specifically, this file defines the order to look 
  306:    up the databases. For example, the line:
  308:        hosts:    files dns
  310:    specifies that the hosts database comes from two sources, *files* (the local 
  311:    `/etc/hosts` file) and *DNS*, (the Internet Domain Name System) and that the 
  312:    local files are searched before the DNS.
  314:    It is usually not necessary to modify this file.
  316: ## Connecting to the Internet with a modem
  318: There are many types of Internet connections: this section explains how to 
  319: connect to a provider using a modem over a telephone line using the PPP 
  320: protocol, a very common setup. In order to have a working connection, the 
  321: following steps must be done:
  323:  1. Get the necessary information from the provider.
  324:  2. Edit the file `/etc/resolv.conf` and check `/etc/nsswitch.conf`.
  325:  3. Create the directories `/etc/ppp` and `/etc/ppp/peers` if they don't exist.
  326:  4. Create the connection script, the chat file and the pppd options file.
  327:  5. Created the user-password authentication file.
  329: Judging from the previous list it looks like a complicated procedure that 
  330: requires a lot of work. Actually, the single steps are very easy: it's just a 
  331: matter of modifying, creating or simply checking some small text files. In the 
  332: following example it will be assumed that the modem is connected to the second 
  333: serial port `/dev/tty01` (COM2 in DOS).
  335: A few words on the difference between `com`, `COM` and `tty`. For NetBSD, `com` 
  336: is the name of the serial port driver (the one that is displayed by `dmesg`) and 
  337: `tty` is the name of the port. Since numbering starts at 0, `com0` is the driver 
  338: for the first serial port, named `tty00`. In the DOS world, instead, `COM1` 
  339: refers to the first serial port (usually located at 0x3f8), `COM2` to the 
  340: second, and so on. Therefore `COM1` (DOS) corresponds to `/dev/tty00` (NetBSD).
  342: Besides external modems connected to COM ports (using `/dev/tty0[012]` on i386, 
  343: `/dev/tty[ab]` on sparc, ...) modems on USB (`/dev/ttyU*`) and pcmcia/cardbus 
  344: (`/dev/tty0[012]`) can be used.
  346: ### Getting the connection information
  348: The first thing to do is ask the provider the necessary information for the 
  349: connection, which means:
  351:  * The phone number of the nearest POP.
  352:  * The authentication method to be used.
  353:  * The username and password for the connection.
  354:  * The IP addresses of the name servers.
  356: ### resolv.conf and nsswitch.conf
  358: The `/etc/resolv.conf` file must be configured using the information supplied by 
  359: the provider, especially the addresses of the DNS. In this example the two DNS 
  360: will be `` and ``:
  362:     nameserver
  363:     nameserver
  365: And now an example of the `/etc/nsswitch.conf` file:
  367:     # /etc/nsswitch.conf
  368:     group:         compat
  369:     group_compat:  nis
  370:     hosts:         files dns
  371:     netgroup:      files [notfound=return] nis
  372:     networks:      files
  373:     passwd:        compat
  374:     passwd_compat: nis
  375:     shells:        files
  377: The defaults of doing hostname lookups via `/etc/hosts` followed by the DNS 
  378: works fine and there's usually no need to modify this.
  380: ### Creating the directories for pppd
  382: The directories `/etc/ppp` and `/etc/ppp/peers` will contain the configuration 
  383: files for the PPP connection. After a fresh install of NetBSD they don't exist 
  384: and must be created (chmod 700).
  386:     # mkdir /etc/ppp
  387:     # mkdir /etc/ppp/peers 
  389: ### Connection script and chat file
  391: The connection script will be used as a parameter on the pppd command line; it 
  392: is located in `/etc/ppp/peers` and has usually the name of the provider. For 
  393: example, if the provider's name is BigNet and your user name for the connection 
  394: to the provider is alan, an example connection script could be:
  396:     # /etc/ppp/peers/bignet
  397:     connect '/usr/sbin/chat -v -f /etc/ppp/peers/'
  398:     noauth
  399:     user alan
  400:     remotename
  402: In the previous example, the script specifies a *chat file* to be used for the 
  403: connection. The options in the script are detailed in the 
  404: [[!template id=man name="pppd" section="8"]] man 
  405: page.
  407: ### Note
  409: If you are experiencing connection problems, add the following two lines to the 
  410: connection script
  412:     debug
  413:     kdebug 4
  415: You will get a log of the operations performed when the system tries to connect. 
  416: See [[!template id=man name="pppd" section="8"]], 
  417: [[!template id=man name="syslog.conf" section="5"]].
  419: The connection script calls the chat application to deal with the physical 
  420: connection (modem initialization, dialing, ...) The parameters to chat can be 
  421: specified inline in the connection script, but it is better to put them in a 
  422: separate file. If, for example, the telephone number of the POP to call is
  423: `02 99999999`, an example chat script could be:
  425:     # /etc/ppp/peers/
  426:     ABORT BUSY
  427:     ABORT "NO CARRIER"
  428:     ABORT "NO DIALTONE"
  429:     '' ATDT0299999999
  430:     CONNECT ''
  432: *Note*: If you have problems with the chat file, you can try connecting manually 
  433: to the POP with the 
  434: [[!template id=man name="cu" section="1"]] program and 
  435: verify the exact strings that you are receiving.
  437: ### Authentication
  439: During authentication each of the two systems verifies the identity of the other 
  440: system, although in practice you are not supposed to authenticate the provider, 
  441: but only to be verified by him, using one of the following methods:
  443:  * PAP/CHAP
  444:  * login
  446: Most providers use a PAP/CHAP authentication.
  448: #### PAP/CHAP authentication
  450: The authentication information (speak: password) is stored in the 
  451: `/etc/ppp/pap-secrets` for PAP and in `/etc/ppp/chap-secrets` for CHAP. The 
  452: lines have the following format:
  454:     user * password
  456: For example:
  458:     alan * pZY9o
  460: For security reasons the `pap-secrets` and `chap-secrets` files should be owned 
  461: by root and have permissions 600.
  463:     # chown root /etc/ppp/pap-secrets
  464:     # chown root /etc/ppp/chap-secrets
  465:     # chmod 600 /etc/ppp/pap-secrets
  466:     # chmod 600 /etc/ppp/chap-secrets
  468: #### Login authentication
  470: This type of authentication is not widely used today; if the provider uses login 
  471: authentication, user name and password must be supplied in the chat file instead 
  472: of the PAP/CHAP files, because the chat file simulates an interactive login. In 
  473: this case, set up appropriate permissions for the chat file.
  475: The following is an example chat file with login authentication:
  477:     # /etc/ppp/peers/
  478:     ABORT BUSY
  479:     ABORT "NO CARRIER"
  480:     ABORT "NO DIALTONE"
  481:     '' ATDT0299999999
  482:     CONNECT ''
  483:     TIMEOUT 50
  484:     ogin: alan
  485:     ssword: pZY9o
  487: ### pppd options
  489: The only thing left to do is the creation of the pppd options file, which is 
  490: `/etc/ppp/options` (chmod 644):
  492:     /dev/tty01
  493:     lock
  494:     crtscts
  495:     57600
  496:     modem
  497:     defaultroute
  498:     noipdefault
  500: Check the 
  501: [[!template id=man name="pppd" section="8"]] man 
  502: page for the meaning of the options.
  504: ### Testing the modem
  506: Before activating the link it is a good idea to make a quick modem test, in 
  507: order to verify that the physical connection and the communication with the 
  508: modem works. For the test the 
  509: [[!template id=man name="cu" section="1"]] program can 
  510: be used, as in the following example.
  512:  1. Create the file `/etc/uucp/port` with the following lines:
  514:         type modem
  515:         port modem
  516:         device /dev/tty01
  517:         speed 115200
  519:     (substitute the correct device in place of `/dev/tty01`).
  521:  2. Write the command `cu -p modem` to start sending commands to the modem. For 
  522:     example:
  524:         # cu -p modem
  525:         Connected.
  526:         ATZ
  527:         OK
  528:         ~.
  530:         Disconnected.
  531:         #
  533: 	In the previous example the reset command (ATZ) was sent to the modem, which 
  534: 	replied with OK: the communication works. To exit 
  535: 	[[!template id=man name="cu" section="1"]], write 
  536: 	`~` (tilde) followed by `.` (dot), as in the example.
  538: If the modem doesn't work, check that it is connected to the correct port (i.e. 
  539: you are using the right port with 
  540: [[!template id=man name="cu" section="1"]]. Cables are 
  541: a frequent cause of trouble, too.
  543: When you start 
  544: [[!template id=man name="cu" section="1"]] and a 
  545: message saying `Permission denied` appears, check who is the owner of the 
  546: `/dev/tty##` device, it must be "uucp". For example:
  548:     $ ls -l /dev/tty00
  549:     crw-------  1 uucp  wheel  8, 0 Mar 22 20:39 /dev/tty00
  551: If the owner is root, the following happens:
  553:     $ ls -l /dev/tty00
  554:     crw-------  1 root  wheel  8, 0 Mar 22 20:39 /dev/tty00
  555:     $ cu -p modem
  556:     cu: open (/dev/tty00): Permission denied
  557:     cu: All matching ports in use
  559: ### Activating the link
  561: At last everything is ready to connect to the provider with the following 
  562: command:
  564:     # pppd call bignet
  566: where `bignet` is the name of the already described connection script. To see 
  567: the connection messages of pppd, give the following command:
  569:     # tail -f /var/log/messages
  571: To disconnect, do a `kill -HUP` of `pppd`.
  573:      # pkill -HUP pppd 
  575: ### Using a script for connection and disconnection
  577: When the connection works correctly, it's time to write a couple of scripts to 
  578: avoid repeating the commands every time. These two scripts can be named, for 
  579: example, `ppp-start` and `ppp-stop`.
  581: `ppp-start` is used to connect to the provider:
  583:     #!/bin/sh
  584:     MODEM=tty01
  585:     POP=bignet
  586:     if [ -f /var/spool/lock/LCK..$MODEM ]; then
  587:     echo ppp is already running...
  588:     else
  589:     pppd call $POP
  590:     tail -f /var/log/messages
  591:     fi
  593: `ppp-stop` is used to close the connection:
  595:     #!/bin/sh
  596:     MODEM=tty01
  597:     if [ -f /var/spool/lock/LCK..$MODEM ]; then
  598:     echo -f killing pppd...
  599:     kill -HUP `cat /var/spool/lock/LCK..$MODEM`
  600:     echo done
  601:     else
  602:     echo ppp is not active
  603:     fi
  605: The two scripts take advantage of the fact that when pppd is active, it creates 
  606: the file `LCK..tty01` in the `/var/spool/lock` directory. This file contains the 
  607: process ID (*pid*) of the pppd process.
  609: The two scripts must be executable:
  611:     # chmod u+x ppp-start ppp-stop
  613: ### Running commands after dialin
  615: If you find yourself to always run the same set of commands each time you dial 
  616: in, you can put them in a script `/etc/ppp/ip-up` which will be called by 
  617: [[!template id=man name="pppd" section="8"]] after 
  618: successful dial-in. Likewise, before the connection is closed down, 
  619: `/etc/ppp/ip-down` is executed. Both scripts are expected to be executable. See 
  620: [[!template id=man name="pppd" section="8"]] for 
  621: more details.
  623: ## Creating a small home network
  625: Networking is one of the main strengths of Unix and NetBSD is no exception: 
  626: networking is both powerful and easy to set up and inexpensive too, because 
  627: there is no need to buy additional software to communicate or to build a server. 
  628: [[Setting up an Internet gateway with IPNAT|guide/net-practice#ipnat]] explains 
  629: how to configure a NetBSD machine to act as a gateway for a network: with IPNAT 
  630: all the hosts of the network can reach the Internet with a single connection to 
  631: a provider made by the gateway machine. The only thing to be checked before 
  632: creating the network is to buy network cards supported by NetBSD (check the 
  633: `INSTALL.*` files for a list of supported devices).
  635: First, the network cards must be installed and connected to a hub, switch or 
  636: directly (see the next image for an example configuration).
  638: Next, check that the network cards are recognized by the kernel, studying the 
  639: output of the `dmesg` command. In the following example the kernel recognized 
  640: correctly an NE2000 clone:
  642:     ...
  643:     ne0 at isa0 port 0x280-0x29f irq 9
  644:     ne0: NE2000 Ethernet
  645:     ne0: Ethernet address 00:c2:dd:c1:d1:21
  646:     ...
  648: If the card is not recognized by the kernel, check that it is enabled in the 
  649: kernel configuration file and then that the card's IRQ matches the one that the 
  650: kernel expects. For example, this is the isa NE2000 line in the configuration 
  651: file; the kernel expects the card to be at IRQ 9.
  653:     ...
  654:     ne0 at isa? port 0x280 irq 9 # NE[12]000 ethernet cards
  655:     ...
  657: If the card's configuration is different, it will probably not be found at boot. 
  658: In this case, either change the line in the kernel configuration file and 
  659: compile a new kernel or change the card's setup (usually through a setup disk 
  660: or, for old cards, a jumper on the card).
  662: The following command shows the network card's current configuration:
  664:     # ifconfig ne0
  665:     ne0: flags=8822<BROADCAST,NOTRAILERS,SIMPLEX,MULTICAST> mtu 1500
  666:     address: 00:50:ba:aa:a7:7f
  667:     media: Ethernet autoselect (10baseT)
  668:     inet6 fe80::250:baff:feaa:a77f%ne0 prefixlen 64 scopeid 0x1 
  670: The software configuration of the network card is very easy. The IP address 
  671: is assigned to the card.
  673:     # ifconfig ne0 inet netmask 0xffffff00
  675: Note that the networks and are reserved for private 
  676: networks, which is what we're setting up here.
  678: Repeating the previous command now gives a different result:
  680:     # ifconfig ne0
  682:     address: 00:50:ba:aa:a7:7f
  683:     media: Ethernet autoselect (10baseT)
  684:     inet netmask 0xffffff00 broadcast
  685:     inet6 fe80::250:baff:feaa:a77f%ne0 prefixlen 64 scopeid 0x1 
  687: The output of `ifconfig` has now changed: the IP address is now printed and 
  688: there are two new flags, `UP` and `RUNNING` If the interface isn't `UP`, it will 
  689: not be used by the system to send packets.
  691: The host was given the IP address, which belongs to the set of 
  692: addresses reserved for internal networks which are not reachable from the 
  693: Internet. The configuration is finished and must now be tested; if there is 
  694: another active host on the network, a `ping` can be tried. For example, if 
  695: is the address of the active host:
  697:     # ping
  698:     PING ape ( 56 data bytes
  699:     64 bytes from icmp_seq=0 ttl=255 time=1.286 ms
  700:     64 bytes from icmp_seq=1 ttl=255 time=0.649 ms
  701:     64 bytes from icmp_seq=2 ttl=255 time=0.681 ms
  702:     64 bytes from icmp_seq=3 ttl=255 time=0.656 ms
  703:     ^C
  704:     ----ape PING Statistics----
  705:     4 packets transmitted, 4 packets received, 0.0% packet loss
  706:     round-trip min/avg/max/stddev = 0.649/0.818/1.286/0.312 ms
  708: With the current setup, at the next boot it will be necessary to repeat the 
  709: configuration of the network card. In order to avoid repeating the card's 
  710: configuration at each boot, add the following lines to `/etc/rc.conf`:
  712:     auto_ifconfig=yes
  713:     ifconfig_ne0="inet netmask 0xffffff00" 
  715: In this example the variable `ifconfig_ne0` was set because the network card was 
  716: recognized as *ne0* by the kernel; if you are using a different adapter, 
  717: substitute the appropriate name in place of ne0.
  719: At the next boot the network card will be configured automatically.
  721: If you have a router that is connected to the internet, you can use it as 
  722: default router, which will handle all your packets. To do so, set `defaultroute` 
  723: to the router's IP address in `/etc/rc.conf`:
  725:     defaultroute=
  727: Be sure to use the default router's IP address instead of name, in case your DNS 
  728: server is beyond the default router. In that case, the DNS server couldn't be 
  729: reached to resolve the default router's hostname and vice versa, creating a 
  730: chicken-and-egg problem.
  732: To reach hosts on your local network, and assuming you really have very few 
  733: hosts, adjust `/etc/hosts` to contain the addresses of all the hosts belonging 
  734: to the internal network. For example:
  736:     #
  737:     # Host Database
  738:     # This file should contain the addresses and aliases
  739:     # for local hosts that share this file.
  740:     # It is used only for "ifconfig" and other operations
  741:     # before the nameserver is started.
  742:     #
  743:     #
  744:             localhost
  745:     ::1                   localhost
  746:     #
  747:     # RFC 1918 specifies that these networks are "internal".
  748:     #
  749:     #
  750:     #
  752: ape
  753: vespa
  756: If you are dialed in via an Internet Service Provider, or if you have a local 
  757: Domain Name Server (DNS) running, you may want to use it to resolve hostnames to 
  758: IP addresses, possibly in addition to `/etc/hosts`, which would only know your 
  759: own hosts. To configure a machine as DNS client, you need to edit 
  760: `/etc/resolv.conf`, and enter the DNS server's address, in addition to an 
  761: optional domain name that will be appended to hosts with no domain, in order to 
  762: create a FQDN for resolving. Assuming your DNS server's IP address is 
  763: and it is setup to serve for "", put the following into 
  764: `/etc/resolv.conf`:
  766:     # /etc/resolv.conf
  767:     domain
  768:     nameserver
  770: The `/etc/nsswitch.conf` file should be checked as explained in the previous 
  771: [[nsswitch.conf example|guide/net-practice#rc.conf_and_nsswitch.conf]].
  773: Summing up, to configure the network the following must be done: the network 
  774: adapters must be installed and physically connected. Next they must be 
  775: configured (with `ifconfig`) and, finally, the file `/etc/rc.conf` must be 
  776: modified to configure the interface and possibly default router, and 
  777: `/etc/resolv.conf` and `/etc/nsswitch.conf` should be adjusted if DNS should be 
  778: used. This type of network management is sufficient for small networks without 
  779: sophisticated needs.
  781: ## Setting up an Internet gateway with IPNAT
  783: The mysterious acronym IPNAT hides the Internet Protocol Network Address 
  784: Translation, which enables the routing of an internal network (e.g. your home 
  785: network as described in the previous section) on a real network (Internet). This 
  786: means that with only one *real* IP, static or dynamic, belonging to a gateway 
  787: running IPNAT, it is possible to create simultaneous connections to the Internet 
  788: for all the hosts of the internal network.
  790: Some usage examples of IPNAT can be found in the subdirectory 
  791: `/usr/share/examples/ipf`: look at the files `BASIC.NAT` and `nat-setup`.
  793: The setup for the example described in this section is detailed in the following 
  794: figure: *host 1* can connect to the Internet calling a provider with a modem and 
  795: getting a dynamic IP address. *host 2* and *host 3* can't communicate with the 
  796: Internet with a normal setup: IPNAT allows them to do it: host 1 will act as a 
  797: Internet gateway for hosts 2 and 3. Using host 1 as default router, hosts 2 and 
  798: 3 will be able to access the Internet.
  800: ![Network with gateway](/guide/images/net1.gif)  
  801: **Network with gateway**
  803: ### Configuring the gateway/firewall
  805: To use IPNAT, the *pseudo-device ipfilter* must be compiled into the kernel, and 
  806: IP packet forwarding must be enabled in the kernel. To check, run:
  808:     # sysctl net.inet.ip.forwarding
  809:     net.inet.ip.forwarding = 1
  811: If the result is `1` as in the previous example, the option is enabled, 
  812: otherwise, if the result is `0` the option is disabled. You can do two things:
  814:  1. Compile a new kernel, with the GATEWAY option enabled.
  816:  2. Enable the option in the current kernel with the following command:
  818:         # sysctl -w net.inet.ip.forwarding=1
  820: 	You can add sysctl settings to `/etc/sysctl.conf` to have them set 
  821: 	automatically at boot. In this case you would want to add
  823:         net.inet.ip.forwarding=1
  826: The rest of this section explains how to create an IPNAT configuration that is 
  827: automatically started every time that a connection to the provider is activated 
  828: with the PPP link. With this configuration all the host of a home network (for 
  829: example) will be able to connect to the Internet through the gateway machine, 
  830: even if they don't use NetBSD.
  832: For the setup, first, create the `/etc/ipnat.conf` file containing the following 
  833: rules:
  835:     map ppp0 -> 0/32 proxy port ftp ftp/tcp
  836:     map ppp0 -> 0/32 portmap tcp/udp 40000:60000
  837:     map ppp0 -> 0/32
  839: are the network addresses that should be mapped. The first line 
  840: of the configuration file is optional: it enables active FTP to work through the 
  841: gateway. The second line is used to handle correctly tcp and udp packets; the 
  842: portmapping is necessary because of the many to one relationship). The third 
  843: line is used to enable ICMP, ping, etc.
  845: Next, create the `/etc/ppp/ip-up` file; it will be called automatically every 
  846: time that the PPP link is activated:
  848:     #!/bin/sh
  849:     # /etc/ppp/ip-up
  850:     /etc/rc.d/ipnat forcestart
  852: Create the file `/etc/ppp/ip-down`; it will be called automatically when the PPP 
  853: link is closed:
  855:     #!/bin/sh
  856:     # /etc/ppp/ip-down
  857:     /etc/rc.d/ipnat forcestop
  859: Both `ip-up` and `ip-down` must be executable:
  861:     # chmod u+x ip-up ip-down
  863: The gateway machine is now ready.
  865: ### Configuring the clients
  867: Create a `/etc/resolv.conf` file like the one on the gateway machine, to make 
  868: the clients access the same DNS server as the gateway.
  870: Next, make all clients use the gateway as their default router. Use the 
  871: following command:
  873:     # route add default
  875: is the address of the gateway machine configured in the previous 
  876: section.
  878: Of course you don't want to give this command every time, so it's better to 
  879: define the `defaultroute` entry in the `/etc/rc.conf` file: the default route 
  880: will be set automatically during system initialization, using the defaultroute 
  881: option as an argument to the `route add default` command.
  883: If the client machine is not using NetBSD, the configuration will be different. 
  884: On Windows PCs you need to set the gateway property of the TCP/IP protocol to 
  885: the IP address of the NetBSD gateway.
  887: That's all that needs to be done on the client machines.
  889: ### Some useful commands
  891: The following commands can be useful for diagnosing problems:
  893:  * `ping` -- tries to connect to other computers via ICMP (usually used for 
  894:    testing if a connection exists).
  895:  * `netstat -r` -- Displays the routing tables (similar to `route show`).
  896:  * `traceroute` -- On the client it shows the route followed by the packets to 
  897:    their destination.
  898:  * `tcpdump` -- Use on the gateway to monitor TCP/IP traffic.
  900: ## Setting up a network bridge device
  902: A bridge can be used to combine different physical networks into one logical 
  903: network, i.e. connect them at layer 2 of the ISO-OSI model, not at layer 3, 
  904: which is what a router would do. The NetBSD `bridge` driver provides bridge 
  905: functionality on NetBSD systems.
  907: ### Bridge example
  909: In this example two physical networks are going to be combined in one logical 
  910: network,, using a NetBSD bridge. The NetBSD machine which is going 
  911: to act as bridge has two interfaces, ne0 and ne1, which are each connected to 
  912: one physical network.
  914: The first step is to make sure support for the `bridge` is compiled in the 
  915: running kernel. Support is included in the GENERIC kernel.
  917: When the system is ready the bridge can be created, this can be done using the 
  918: [[!template id=man name="brconfig" section="8"]]
  919: command. First of a bridge interface has to be created. With the following 
  920: `ifconfig` command the `bridge0` interface will be created:
  922:     $ ifconfig bridge0 create
  924: Please make sure that at this point both the ne0 and ne1 interfaces are up. The 
  925: next step is to add the ne0 and ne1 interfaces to the bridge.
  927:     $ brconfig bridge0 add ne0 add ne1 up
  929: This configuration can be automatically set up by creating an 
  930: `/etc/ifconfig.interface` file, in this case `/etc/ifconfig.bridge0`, with the 
  931: following contents:
  933:     create
  934:             !brconfig $int add ne0 add ne1 up
  936: After setting up the bridge the bridge configuration can be displayed using the 
  937: `brconfig -a` command. Remember that if you want to give the bridge machine an 
  938: IP address you can only allocate an IP address to one of the interfaces which 
  939: are part of the bridge.
  941: ## A common LAN setup
  943: The small home network discussed in the previous section contained many items 
  944: that were configured manually. In bigger LANs that are centrally managed, one 
  945: can expect Internet connectivity being available via some router, a DNS server 
  946: being available, and most important, a DHCP server which hands out IP addresses 
  947: to clients on request. To make a NetBSD client run in such an environment, it's 
  948: usually enough to set
  950:     dhcpcd=yes
  952: in `/etc/rc.conf`, and the IP address will be set automatically, 
  953: `/etc/resolv.conf` will be created and routing setup to the default router.
  955: ## Connecting two PCs through a serial line
  957: If you need to transfer files between two PCs which are not networked there is a 
  958: simple solution which is particularly handy when copying the files to a floppy 
  959: is not practical: the two machines can be networked with a serial cable (a *null 
  960: modem* cable). The following sections describe some configurations.
  962: ### Connecting NetBSD with BSD or Linux
  964: The easiest case is when both machines run NetBSD: making a connection with the 
  965: SLIP protocol is very easy. On the first machine write the following commands:
  967:     # slattach /dev/tty00
  968:     # ifconfig sl0 inet
  970: On the second machine write the following commands:
  972:     # slattach /dev/tty00
  973:     # ifconfig sl0 inet
  975: Now you can test the connection with `ping`; for example, on the second PC 
  976: write:
  978:     # ping
  980: If everything worked there is now an active network connection between the two 
  981: machines and ftp, telnet and other similar commands can be executed. The textual 
  982: aliases of the machines can be written in the `/etc/hosts` file.
  984:  * In the previous example both PCs used the first serial port (`/dev/tty0`). 
  985:    Substitute the appropriate device if you are using another port.
  987:  * IP addresses like 192.168.x.x are reserved for `internal` networks. The first 
  988:    PC has address and the second
  990:  * To achieve a faster connection the `-s speed` option to `slattach` can be 
  991:    specified.
  993:  * `ftp` can be used to transfer files only if inetd is active and the ftpd 
  994:  * server is enabled.
  996: ### Linux
  998: If one of the two PCs runs Linux, the commands are slightly different (on the 
  999: Linux machine only). If the Linux machine gets the address, the 
 1000: following commands are needed:
 1002:     # slattach -p slip -s 115200 /dev/ttyS0 &
 1003:     # ifconfig sl0 pointopoint up
 1004:     # route add dev sl0
 1006: Don't forget the `&` in the first command.
 1008: ### Connecting NetBSD and Windows NT
 1010: NetBSD and Windows NT can be (almost) easily networked with a serial *null 
 1011: modem* cable. Basically what needs to be done is to create a *Remote Access* 
 1012: connection under Windows NT and to start pppd on NetBSD.
 1014: Start pppd as root after having created a `.ppprc` in `/root`. Use the following 
 1015: example as a template.
 1017:     connect '/usr/sbin/chat -v CLIENT CLIENTSERVER'
 1018:     local
 1019:     tty00
 1020:     115200
 1021:     crtscts
 1022:     lock
 1023:     noauth
 1024:     nodefaultroute
 1025:     :
 1027: The meaning of the first line will be explained later in this section; 
 1028: is the IP address that will be assigned by NetBSD to the Windows NT 
 1029: host; `tty00` is the serial port used for the connection (first serial port).
 1031: On the NT side a *null modem* device must be installed from the Control Panel 
 1032: (Modem icon) and a Remote Access connection using this modem must be created. 
 1033: The null modem driver is standard under Windows NT 4 but it's not a 100% null 
 1034: modem: when the link is activated, NT sends the string CLIENT and expects to 
 1035: receive the answer CLIENTSERVER. This is the meaning of the first line of the 
 1036: `.ppprc` file: `chat` must answer to NT when the connection is activated or 
 1037: the connection will fail.
 1039: In the configuration of the Remote Access connection the following must be 
 1040: specified: use the null modem, telephone number `1` (it's not used, anyway), PPP 
 1041: server, enable only TCP/IP protocol, use IP address and nameservers from the 
 1042: server (NetBSD in this case). Select the hardware control flow and set the port 
 1043: to 115200 8N1.
 1045: Now everything is ready to activate the connection.
 1047:  * Connect the serial ports of the two machines with the null modem cable.
 1048:  * Launch pppd on NetBSD. To see the messages of pppd:
 1049:    `tail -f /var/log/messages`).
 1050:  * Activate the Remote Access connection on Windows NT.
 1052: ### Connecting NetBSD and Windows 95
 1054: The setup for Windows 95 is similar to the one for Windows NT: Remote Access on 
 1055: Windows 95 and the PPP server on NetBSD will be used. Most (if not all) Windows 
 1056: 95 releases don't have the *null modem* driver, which makes things a little more 
 1057: complicated. The easiest solution is to find one of the available null modem 
 1058: drivers on the Internet (it's a small `.INF` file) and repeat the same steps as 
 1059: for Windows NT. The only difference is that the first line of the `.ppprc` file 
 1060: (the one that calls `chat`) can be removed.
 1062: If you can't find a real null modem driver for Windows 95 it's still possible to 
 1063: use a little trick:
 1065:  * Create a Remote Access connection like the one described before for Windows 
 1066:    NT, but using the *Standard Modem*.
 1068:  * In `.ppprc` substitute the line that calls `chat` with the following line
 1070:        connect '/usr/sbin/chat -v ATH OK AT OK ATE0V1 OK AT OK ATDT CONNECT'
 1072:  * Activate the connection as described in the section before for Windows NT.
 1075: In this way the `chat` program, called when the connection is activated, 
 1076: emulates what Windows 95 thinks is a standard modem, returning to Windows 95 the 
 1077: same answers that a standard modem would return. Whenever Windows 95 sends a 
 1078: modem command string, `chat` returns OK.
 1080: ## IPv6 Connectivity & Transition via 6to4
 1082: This section will concentrate on how to get network connectivity for IPv6 and - 
 1083: as that is rarely available directly - talk at length about the alternatives to 
 1084: native IPv6 connectivity as a transitional method until native IPv6 peers are 
 1085: available.
 1087: Finding an ISP that offers IPv6 natively needs quite some luck. What you need 
 1088: next is a router that will be able to handle the traffic. To date, not all 
 1089: router manufacturers offer IPv6 or hardware accelerated IPv6 features, and 
 1090: gateway NAT boxes only rarely support IPv6 and also block IPv6 tunnels. An 
 1091: alternative approach involves configuring a standard PC running NetBSD to act as 
 1092: a router. The base NetBSD system contains a complete IPv6 routing solution, and 
 1093: for special routing needs software like Zebra can provide additional routing 
 1094: protocols. This solution is rather common for sites that want IPv6 
 1095: connectivity today. The drawbacks are that you need an ISP that supports 
 1096: IPv6 and that you may need a dedicated uplink only for IPv6.
 1098: IPv6 to-the-door may be rare, but you can still get IPv6 connectivity by using 
 1099: tunnels. Instead of talking IPv6 on the wire, the IPv6 packets are encapsulated 
 1100: in IPv4 packets, as shown in the next image. Using the existing IPv4 
 1101: infrastructure, the encapsulated packets are sent to a IPv6-capable uplink that 
 1102: will then remove the encapsulation, and forward the IPv6 packets.
 1104: ![A frequently used method for transition is tunneling IPv6 in IPv4 packets](/guide/images/ipv6-en-2tunnel.gif)  
 1105: **A frequently used method for transition is tunneling IPv6 in IPv4 packets**
 1107: When using tunnels, there are two possibilities. One is to use a so-called 
 1108: *configured* tunnel, the other is called an *automatic* tunnel. A *configured* 
 1109: tunnel is one that required preparation from both ends of the tunnel, usually 
 1110: connected with some kind of registration to exchange setup information. An 
 1111: example for such a configured tunnel is the IPv6-over-IPv4 encapsulation 
 1112: described in
 1113: [RFC1933]( ("RFC 1933: Transition Mechanisms 
 1114: for IPv6 Hosts and Routers"), and that's implemented e.g. by the 
 1115: [[!template id=man name="gif" section="4"]] 
 1116: device found in NetBSD.
 1118: An *automatic* tunnel consists of a public server that has some kind of IPv6 
 1119: connectivity, e.g. via 6Bone. That server has made its connectivity data public, 
 1120: and also runs a tunneling protocol that does not require an explicit 
 1121: registration of the sites using it as uplink. A well-used example of such a 
 1122: protocol is the 6to4 mechanism described in
 1123: [RFC3056]( ("RFC 3056: Connection of IPv6 
 1124: Domains via IPv4 Clouds"), and that is implemented in the 
 1125: [[!template id=man name="stf" section="4"]] device 
 1126: found in NetBSD's. Another mechanism that does not require registration of 
 1127: IPv6-information is the 6over4 mechanism, which implements transporting of IPv6 
 1128: over a multicast-enabled IPv4 network, instead of e.g. ethernet or FDDI.  6over4 
 1129: is documented in [RFC2529]( ("RFC 2529: 
 1130: Transmission of IPv6 over IPv4 Domains without Explicit Tunnels"). It's main 
 1131: drawback is that you do need existing multicast infrastructure. If you don't 
 1132: have that, setting it up is about as much effort as setting up a configured IPv6 
 1133: tunnel directly, so it's usually not worth bothering in that case.
 1135: ### Getting 6to4 IPv6 up & running
 1137: 6to4 is an easy way to get IPv6 connectivity for hosts that only have an IPv4 
 1138: uplink, especially if you have the background given in
 1139: [[the chapter about IPv6|guide/net-intro#ipv6-intro]]. It can be used with 
 1140: static as well as dynamically assigned IPv4 addresses, e.g. as found in modem 
 1141: dialup scenarios today. When using dynamic IPv4 addresses, a change of IP 
 1142: addresses will be a problem for incoming traffic, i.e. you can't run persistent 
 1143: servers.
 1145: Example configurations given in this section are for NetBSD 1.5.2.
 1147: ### Obtaining IPv6 Address Space for 6to4
 1149: The 6to4 IPv6 setup on your side doesn't consist of a single IPv6 address; 
 1150: Instead, you get a whole /48 network! The IPv6 addresses are derived from your 
 1151: (single) IPv4 address. The address prefix *2002:` is reserved for 6to4 based 
 1152: addresses (i.e. IPv6 addresses derived from IPv4 addresses). The next 32 bits 
 1153: are your IPv4 address. This results in a /48 network that you can use for your 
 1154: very own purpose. It leaves 16 bits space for 2^16^ IPv6 subnets, which can take 
 1155: up to 2^64^ nodes each. The next figure illustrates the building of your IPv6 
 1156: address (range) from your IPv4 address.
 1158: Thanks to the 6to4 prefix and your worldwide unique IPv4 address, this address 
 1159: block is unique, and it's mapped to your machine carrying the IPv4 address in 
 1160: question.
 1162: ![6to4 derives an IPv6 from an IPv4 address](/guide/images/ipv6-en-3adr.gif)  
 1163: **6to4 derives an IPv6 from an IPv4 address**
 1165: ### How to get connected
 1167: In contrast to the configured *IPv6-over-IPv4 tunnel* setup, you do not have to 
 1168: register at a 6bone-gateway, which would only then forward your IPv6 traffic 
 1169: encapsulated in IPv4. Instead, as your IPv6 address is derived from your IPv4 
 1170: address, inbound traffic can be sent through the nearest 6to4 relay router. 
 1171: De-encapsulation of the packet is done via a 6to4-capable network interface, 
 1172: which then forwards the resulting IPv6 packet according to your routing setup 
 1173: (in case you have more than one machine connected on your 6to4 assigned 
 1174: network).
 1176: To transmit IPv6 packets, the 6to4 router will encapsulate them inside IPv4 
 1177: packets; a system performing these functions is called a 6to4 border router. 
 1178: These packets have a default route to the *6to4 relay anycast prefix*. This 
 1179: anycast prefix will route the tunnel to a *6to4 relay router*.
 1181: ![Request and reply can be routed via different gateways in 6to4](/guide/images/ipv6-en-1scene.gif)  
 1182: **Request and reply can be routed via different gateways in 6to4**
 1184: ### Security Considerations
 1186: In contrast to the *configured tunnel* setup, you usually can't setup packet 
 1187: filters to block 6to4-packets from unauthorized sources, as this is exactly how 
 1188: (and why) 6to4 works at all. As such, malicious users can send packets with 
 1189: invalid/hazardous IPv6 payload. If you don't already filter on your border 
 1190: gateways anyways, packets with the following characteristics should not be 
 1191: allowed as valid 6to4 packets, and some firewalling seems to be justified for 
 1192: them:
 1194:  * unspecified IPv4 source/destination address:
 1195:  * loopback address in outer (v4) source/destination:
 1196:  * IPv4 multicast in source/destination:
 1197:  * limited broadcasts:
 1198:  * subnet broadcast address as source/destination: depends on your IPv4 setup
 1200: The NetBSD 
 1201: [[!template id=man name="stf" section="4"]] manual 
 1202: page documents some common configuration mistakes intercepted by default by the 
 1203: KAME stack as well as some further advice on filtering, but keep in mind that 
 1204: because of the requirement of these filters, 6to4 is not perfectly secure. 
 1205: Still, if forged 6to4 packets become a problem, you can use IPsec authentication 
 1206: to ensure the IPv6 packets are not modified.
 1208: ### Data Needed for 6to4 Setup
 1210: In order to setup and configure IPv6 over 6to4, a few bits of configuration data 
 1211: must be known in advance. These are:
 1213:  * Your local IPv4 address. It can be determined using either the `ifconfig -a` 
 1214:    or `netstat -i` commands on most Unix systems. If you use a NATing gateway or 
 1215:    something, be sure to use the official, outside-visible address, not your 
 1216:    private (10/8 or 192.168/16) one.
 1218:    We will use as the local IPv4 address in our example.
 1220:  * Your local IPv6 address, as derived from the IPv4 address. See the previous 
 1221:    figure ("6to4 derives an IPv6 from an IPv4 address") about how to do so.
 1223:    For our example, this is 2002:3ee0:3972:0001::1 ( == 0x3ee03972, 
 1224:    0001::1 arbitrarily chosen).
 1226:  * The *6to4 IPv6 relay anycast address*. which is 2002:c058:6301::, or the IPv6 
 1227:    address of a specific 6to4 relay router you want to use. The IPv6 address 
 1228:    will do, as it also contains the IPv4 address in the usual 6to4 translation.
 1230: ### Kernel Preparation
 1232: To process 6to4 packets, the operating system kernel needs to know about them. 
 1233: For that a driver has to be compiled in that knows about 6to4, and how to handle 
 1234: it. In NetBSD 4.0 and newer, the driver is already present in GENERIC kernel 
 1235: configurations, so the procedure below is usually unnecessary.
 1237: For a NetBSD kernel, put the following into your kernel config file to prepare 
 1238: it for using IPv6 and 6to4, e.g. on NetBSD use:
 1240:     options INET6                 # IPv6
 1241:     pseudo-device stf             # 6to4 IPv6 over IPv4 encapsulation
 1243: Note that the 
 1244: [[!template id=man name="stf" section="4"]] device is 
 1245: not enabled by default on NetBSD releases older than 4.0. Rebuild your kernel, 
 1246: then reboot your system to use the new kernel. Please consult
 1247: [[Compiling the kernel|guide/kernel]] for further information on configuring, 
 1248: building and installing a new kernel!
 1250: ### 6to4 Setup
 1252: This section describes the commands to setup 6to4. In short, the steps performed 
 1253: here are:
 1255:  1. Configure interface
 1256:  2. Set default route
 1257:  3. Setup Router Advertisement, if wanted
 1259: The first step in setting up 6to4 is creating the 6to4 interface and assigning 
 1260: an IPv6 address to it. This is achieved with the 
 1261: [[!template id=man name="ifconfig" section="8"]] 
 1262: command. Assuming the example configuration above, the commands for NetBSD are:
 1264:     # ifconfig stf0 create
 1265:     # ifconfig stf0 inet6 2002:3ee0:3972:1::1 prefixlen 16 alias
 1267: After configuring the 6to4 device with these commands, routing needs to be 
 1268: setup, to forward all tunneled IPv6 traffic to the 6to4 relay router. The best 
 1269: way to do this is by setting a default route, the command to do so is, for 
 1270: NetBSD:
 1272:     # route add -inet6 default 2002:c058:6301::
 1274: Note that NetBSD's 
 1275: [[!template id=man name="stf" section="4"]] device 
 1276: determines the IPv4 address of the 6to4 uplink from the routing table. Using 
 1277: this feature, it is easy to setup your own 6to4 (uplink) gateway if you have an 
 1278: IPv6 uplink, e.g. via 6Bone.
 1280: After these commands, you are connected to the IPv6-enabled world - 
 1281: Congratulations! Assuming name resolution is still done via IPv4, you can now 
 1282: ping an IPv6-site like or
 1284:     # /sbin/ping6
 1286: As a final step in setting up IPv6 via 6to4, you will want to setup Router 
 1287: Advertisement if you have several hosts on your network. While it is possible to 
 1288: setup 6to4 on each node, doing so will result in very expensive routing from one 
 1289: node to the other - packets will be sent to the remote 6to4 gateway, which will 
 1290: then route the packets back to the neighbor node. Instead, setting up 6to4 on 
 1291: one machine and talking native IPv6 on-wire is the preferred method of handling 
 1292: things.
 1294: The first step to do so is to assign an IPv6-address to your ethernet. In the 
 1295: following example we will assume subnet `2` of the IPv6-net is used for the 
 1296: local ethernet and the MAC address of the ethernet interface is 
 1297: 12:34:56:78:9a:bc, i.e. your local gateway's ethernet interface's IP address 
 1298: will be 2002:3ee0:3972:2:1234:56ff:fe78:9abc. Assign this address to your 
 1299: ethernet interface, e.g.
 1301:     # ifconfig ne0 inet6 alias 2002:3ee0:3972:2:1234:56ff:fe78:9abc
 1303: Here, `ne0` is an example for your ethernet card interface. This will most 
 1304: likely be different for your setup, depending on what kind of card is used.
 1306: Next thing that needs to be ensured for setting up the router is that it will 
 1307: actually forward packets from the local 6to4 device to the ethernet device and 
 1308: back. To enable IPv6 packet forwarding, set `ip6mode=router` in NetBSD's 
 1309: `/etc/rc.conf`, which will result in the `net.inet6.ip6.forwarding` sysctl being 
 1310: set to `1`:
 1312:     # sysctl -w net.inet6.ip6.forwarding=1
 1314: ![Enabling packet forwarding is needed for a 6to4 router](/guide/images/ipv6-en-5forward.gif)  
 1315: **Enabling packet forwarding is needed for a 6to4 router**
 1317: To setup router advertisement on BSD, the file `/etc/rtadvd.conf` needs to be 
 1318: checked. It allows configuration of many things, but usually the default config 
 1319: of not containing any data is ok. With that default, IPv6 addresses found on all 
 1320: of the router's network interfaces will be advertised.
 1322: After checking the router advertisement configuration is correct and IPv6 
 1323: forwarding is turned on, the daemon handling it can be started. Under NetBSD, it 
 1324: is called `rtadvd`. Start it up either manually (for testing it the first time) 
 1325: or via the system's startup scripts, and see all your local nodes automagically 
 1326: configure the advertised subnet address in addition to their already-existing 
 1327: link local address.
 1329:     # rtadvd
 1331: ### Quickstart using pkgsrc/net/hf6to4
 1333: So far, we have described how 6to4 works and how to set it up manually. For an 
 1334: automated way to make everything happen e.g. when going online, the 'hf6to4' 
 1335: package is convenient. It will determine your IPv6 address from the IPv4 address 
 1336: you got assigned by your provider, then set things up that you are connected.
 1338: Steps to setup the pkgsrc/net/hf6to4 package are:
 1340:  1. Install the package either by compiling it from pkgsrc, or by `pkg_add`'ing 
 1341:     the 6to4-1.2 package.
 1343:         # cd /usr/pkgsrc/net/hf6to4
 1344:         # make install
 1346:  2. Make sure you have the 
 1347:     [[!template id=man name="stf" section="4"]] 
 1348:     pseudo-device in your kernel, see above.
 1350:  3. Configure the 'hf6to4' package. First, copy 
 1351:     `/usr/pkg/share/examples/hf6to4/hf6to4.conf` to `/usr/pkg/etc/hf6to4.conf`, 
 1352:     then adjust the variables. Note that the file is in /bin/sh syntax.
 1354:         # cd /usr/pkg/etc
 1355:         # cp ../share/examples/hf6to4/hf6to4.conf hf6to4.conf
 1356:         # vi hf6to4.conf
 1358: 	Please see the 
 1359: 	[[!template id=man name="hf6to4" section="8"]] 
 1360: 	manpage for an explanation of all the variables you can set in 
 1361: 	`hf6to4.conf`. If you have dialup IP via PPP, and don't want to run Router 
 1362: 	Advertizing for other IPv6 machines on your home or office network, you 
 1363: 	don't need to configure anything. If you want to setup Router Advertising, 
 1364: 	you need to set the `in_if` to the internal (ethernet) interface, e.g.
 1366:         $in_if="rtk0";            # Inside (ethernet) interface
 1368:  4. Now dial up, then start the 6to4 command manually:
 1370:         # /usr/pkg/sbin/hf6to4 start
 1372:  5. After that, you should be connected, use 
 1373:     [[!template id=man name="ping6" section="8"]]: to 
 1374:     see if everything works:
 1376:         # ping6
 1377:         PING6(56=40+8+8 bytes) 2002:d954:110b:1::1 --> 2001:4f8:4:7:2e0:81ff:fe52:9a6b
 1378:         16 bytes from 2001:4f8:4:7:2e0:81ff:fe52:9a6b, icmp_seq=0 hlim=60 time=250.234 ms
 1379:         16 bytes from 2001:4f8:4:7:2e0:81ff:fe52:9a6b, icmp_seq=1 hlim=60 time=255.652 ms
 1380:         16 bytes from 2001:4f8:4:7:2e0:81ff:fe52:9a6b, icmp_seq=2 hlim=60 time=251.237 ms
 1381:         ^C
 1382:         --- ping6 statistics ---
 1383:         3 packets transmitted, 3 packets received, 0.0% packet loss
 1384:         round-trip min/avg/max/std-dev = 250.234/252.374/255.652/2.354 ms
 1386:         # traceroute6
 1387:         traceroute6 to (2001:4f8:4:7:2e0:81ff:fe52:9a6b)
 1388:         from 2002:d954:110b:1::1, 64 hops max, 12 byte packets
 1389:         1  2002:c25f:6cbf:1::1  66.31 ms  66.382 ms  69.062 ms
 1390:         2  76.134 ms *  76.87 ms
 1391:         3  76.371 ms  80.709 ms  79.482 ms
 1392:         4  92.763 ms  90.863 ms  94.322 ms
 1393:         5  116.115 ms  93.463 ms  96.331 ms
 1394:         6  103.347 ms  99.334 ms  100.803 ms
 1395:         7  99.481 ms  100.421 ms  100.119 ms
 1396:         8  2001:798:28:300::2  89.711 ms  90.435 ms  90.035 ms
 1397:         9  179.671 ms  185.141 ms  185.86 ms
 1398:         10  177.067 ms  179.086 ms  178.05 ms
 1399:         11  178.04 ms  179.727 ms  184.165 ms
 1400:         12  249.856 ms  247.476 ms  249.012 ms
 1401:         13  239.691 ms  241.404 ms  240.998 ms
 1402:         14  247.541 ms  246.661 ms  246.359 ms
 1403:         15  240.987 ms 239.056 ms  241.251 ms
 1404:         16  240.868 ms  241.29 ms  242.337 ms
 1405:         17  249.477 ms  250.4 ms  256.035 ms
 1406:         18  2001:4f8:4:7:2e0:81ff:fe52:9a6b  268.164 ms  252.97 ms  252.366 ms 
 1408: 	Please note that `traceroute6` shows the v6 hops only, any underlying 
 1409: 	tunnels are invisible and thus not displayed.
 1411:  6. If this works, you can put the following lines into your `/etc/ppp/ip-up` 
 1412:     script to run the command each time you go online:
 1414:         logger -p -t ip-up Configuring 6to4 IPv6
 1415:         /usr/pkg/sbin/hf6to4 stop
 1416:         /usr/pkg/sbin/hf6to4 start
 1418:  7. If you want to route IPv6 for your LAN, you can instruct `` to setup 
 1419:     Router Advertising for you too:
 1421:         # /usr/pkg/sbin/hf6to4 rtadvd-start
 1423:     You can put that command into `/etc/ppp/ip-up` as well to make it permanent.
 1425:  8. If you have changed `/etc/ppp/ip-up` to setup 6to4 automatically, you will 
 1426: 	most likely want to change `/etc/ppp/ip-down` too, to shut it down when you 
 1427: 	go offline. Here's what to put into `/etc/ppp/ip-down`:
 1429:         logger -p -t ip-down Shutting down 6to4 IPv6
 1430:         /usr/pkg/sbin/hf6to4 rtadvd-stop
 1431:         /usr/pkg/sbin/hf6to4 stop
 1433: ### Known 6to4 Relay Routers
 1435: It is normally not necessary to pick a specific 6to4 relay router, but if 
 1436: necessary, you may find a list of known working routers at 
 1437: [\~nsayer/6to4/]( In tests, 
 1438: only and were found working. Cisco has one 
 1439: that requires registration, see 
 1440: [](
 1442: There's also an experimental 6to4 server located in Germany, 
 1443: This server runs under NetBSD 1.6 and was setup 
 1444: using the configuration steps described above. The whole configuration of the 
 1445: machine can be seen at 
 1446: [](
 1448: ### Tunneling 6to4 through an IPFilter firewall
 1450: The 6to4 protocol encapsulates IPv6 packets in IPv4, and gives them their own IP 
 1451: type, which most firewalls block as unknown, as their payload type is directly 
 1452: `TCP`, `UDP` or `ICMP`. Usually, you want to setup your 6to4 gateway on the same 
 1453: machine that is directly connected to the (IPv4) internet, and which usually 
 1454: runs the firewall. For the case that you want to run your 6to4 gateway behind a 
 1455: firewall, you need to drill a hole into the firewall, to let 6to4 packets 
 1456: through. Here is how to do this!
 1458: The example assumes that you use the `ppp0` interface on your firewall to 
 1459: connect to the Internet.
 1461: Put the following lines into `/etc/ipf.conf` to allow your IPFilter firewall let 
 1462: all 6to4 packets pass (lines broken with `\` due to space restrictions; please 
 1463: put them lines continued that way all in one line):
 1465:     # Handle traffic by different rulesets
 1466:     block in  quick on ppp0 all head 1
 1467:     block out quick on ppp0 all head 2
 1469:     ### Incoming packets:
 1470:     # allow some IPv4:
 1471:     pass  in  log quick on ppp0 proto tcp from any to any \
 1472:     port = www flags S keep state keep frags  group 1
 1473:     pass  in      quick on ppp0 proto tcp from any to any \
 1474:     port = ssh keep state         group 1
 1475:     pass  in      quick on ppp0 proto tcp from any to any \
 1476:     port = mail keep state        group 1
 1477:     pass  in  log quick on ppp0 proto tcp from any to any \
 1478:     port = ftp keep state       group 1
 1479:     pass  in  log quick on ppp0 proto tcp from any to any \
 1480:     port = ftp-data keep state      group 1
 1481:     pass  in  log quick on ppp0 proto icmp from any to any        group 1
 1482:     # allow all IPv6:
 1483:     pass in       quick on ppp0 proto ipv6       from any to any  group 1
 1484:     pass in  log  quick on ppp0 proto ipv6-route from any to any  group 1
 1485:     pass in  log  quick on ppp0 proto ipv6-frag  from any to any  group 1
 1486:     pass in  log  quick on ppp0 proto ipv6-icmp  from any to any  group 1
 1487:     pass in  log  quick on ppp0 proto ipv6-nonxt from any to any  group 1
 1488:     pass in  log  quick on ppp0 proto ipv6-opts  from any to any  group 1
 1489:     # block rest:
 1490:     blockin  log  quick on ppp0 all                               group 1
 1492:     ### Outgoing packets:
 1493:     # allow usual stuff:
 1494:     pass  out     quick on ppp0 proto  tcp from any to any flags S \
 1495:     keep state keep frags group 2
 1496:     pass  out     quick on ppp0 proto  udp from any to any         \
 1497:     keep state keep frags group 2
 1498:     pass  out     quick on ppp0 proto icmp from any to any         \
 1499:     keep state            group 2
 1500:     # allow all IPv6:
 1501:     pass out      quick on ppp0 proto ipv6       from any to any  group 2
 1502:     pass out log  quick on ppp0 proto ipv6-route from any to any  group 2
 1503:     pass out log  quick on ppp0 proto ipv6-frag  from any to any  group 2
 1504:     pass out log  quick on ppp0 proto ipv6-icmp  from any to any  group 2
 1505:     pass out log  quick on ppp0 proto ipv6-nonxt from any to any  group 2
 1506:     pass out log  quick on ppp0 proto ipv6-opts  from any to any  group 2
 1507:     # block rest:
 1508:     block out log quick on ppp0 all             group 2
 1510: Now any host on your network can send (the `out` rules) and receive (the `in` 
 1511: rules) v4-encapsulated IPv6 packets, allowing setup of any of them as a 6to4 
 1512: gateway. Of course you only want to do this on one host and use native IPv6 
 1513: between your hosts, and you may also want to enforce this with more restrictive 
 1514: rulesets, please see 
 1515: [[!template id=man name="ipf.conf" section="5"]] 
 1516: for more information on IPFilter rules.
 1518: After your firewall lets pass encapsulated IPv6 packets, you may want to set up 
 1519: your 6to4 gateway to monitor the IPv6 traffic, or even restrict it. To do so, 
 1520: you need to setup IPFilter on your 6to4 gateway as well. For basic monitoring, 
 1521: enable `ipfilter=yes` in `/etc/rc.conf` and put the following into 
 1522: `/etc/ipf6.conf`:
 1524:     pass in  log quick on stf0 from any to any
 1525:     pass out log quick on stf0 from any to any
 1527: This logs all (IPv6) traffic going in and out of your `stf0` tunneling 
 1528: interface. You can add filter rules as well if needed.
 1530: If you are more interested in traffic stats than a general overview of your 
 1531: network traffic, using MRTG in conjunction with the `net-snmp` package is 
 1532: recommended instead of analyzing IPFilter log files.
 1534: ### Conclusion & Further Reading
 1536: Compared to where IPv4 is today, IPv6 is still in its early steps. It is 
 1537: working, there are all sort of services and clients available, only the userbase 
 1538: is missing. It is hoped the information provided here helps people better 
 1539: understand what IPv6 is, and to start playing with it.
 1541: A few links should be mentioned here for interested parties:
 1543:  * An example script to setup 6to4 on BSD based machines is available at 
 1544:    <>. The script determines your IPv6 
 1545:    address and sets up 6to4 and (if wanted) router advertising. It was designed 
 1546:    to work in dialup setups with changing IPv4 addresses.
 1548:  * Given that there isn't a standard for IPv6 in Linux land today, there are 
 1549:    different setup instructions for most distributions. The setup of IPv6 on 
 1550:    Debian GNU/Linux can be found at 
 1551:    [\~csmall/ipv6/setup.html](
 1553:  * The BSD Unix implementations have their own IPv6 documentation each, 
 1554:    interesting URLs are <> for NetBSD, 
 1555:    <\_US.ISO8859-1/books/handbook/network-ipv6.html> 
 1556:    for FreeBSD.
 1558:  * Projects working on implementing IPv6 protocol stacks for free Unix like 
 1559:    operating systems are KAME for BSD and USAGI for Linux. Their web sites can 
 1560:    be found at <> and <>. A list 
 1561:    of host and router implementations can be found at 
 1562:    <>.
 1564:  * Besides the official RFC archive at <>, information 
 1565:    on IPv6 can be found at several web sites. First and foremost, the 6Bone's 
 1566:    web page at <> must be mentioned. 6Bone was started as 
 1567:    the testbed for IPv6, and is now an important part of the IPv6-connected 
 1568:    world. Other web pages that contain IPv6-related contents include 
 1569:    <>, <> and 
 1570:    <>. Most of these sites carry further links - be 
 1571:    sure to have a look!

CVSweb for NetBSD wikisrc <> software: FreeBSD-CVSweb