[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ 13 ] [ 14 ] [ 15 ] [ A ] [ next ]

Debian Reference
Chapter 10 - Network configuration


This chapter focuses on network administration in Debian. For a general introduction to GNU/Linux networking read the Net-HOWTO.

In order for a Debian host to be able to access the Internet its network interfaces need to be supported by the kernel and properly configured.

The first requirement is kernel support for network interface devices such as Ethernet cards, Wi-Fi cards and modems. To obtain this support you may need to recompile the kernel or add modules to it as described in The Linux kernel under Debian, Chapter 7.

Configuration of network devices is explained below. The information in this chapter has been updated for Sarge. Much of it does not apply to earlier releases.


10.1 Basics of IP networking

A Debian host may have several interfaces each with a different Internet Protocol (IP) address. Interfaces may be of several different types, including:

There is a wide range of other network devices available, including SLIP, PLIP (serial and parallel line IP), "shaper" devices for controlling the traffic on certain interfaces, frame relay, AX.25, X.25, ARCnet, and LocalTalk.

Every network interface connected directly to the Internet (or to any IP-based network) is identified by a unique 32 bit IP address. [43] The IP address can be divided into the part that addresses the network and the part that addresses the host. If you take an IP address, set to 1 the bits that are part of the network address and set to 0 the bits that are part of the host address then you get the net mask of the network.

Traditionally, IP networks were grouped into classes whose net address parts were 8, 16 or 24 bits in length. [44]

               IP addresses                   net mask      length
     Class A   1.0.0.0     - 126.255.255.255  255.0.0.0     =  /8
     Class B   128.0.0.0   - 191.255.255.255  255.255.0.0   = /16
     Class C   192.0.0.0   - 223.255.255.255  255.255.255.0 = /24

IP addresses not in these ranges are used for special purposes.

There are address ranges in each class reserved for use on local area networks (LANs). These addresses are guaranteed not to conflict with any addresses on the Internet proper. (By the same token, if one of these addresses is assigned to a host then that host must not access the Internet directly but must access it through a gateway that acts as a proxy for individual services or else does Network Address Translation.) These address ranges are given in the following table along with the number of ranges in each class.

               network addresses            length  how many
     Class A   10.x.x.x                     /8      1
     Class B   172.16.x.x -  172.31.x.x     /16     16
     Class C   192.168.0.x - 192.168.255.x  /24     256

The first address in an IP network is the address of the network itself. The last address is the broadcast address for the network. [45] All other addresses may be allocated to hosts on the network. Of these, the first or the last address is usually allocated to the Internet gateway for the network.

The routing table contains the kernel's information on how to send IP packets to their destinations. Here is a sample routing table printout for a Debian host on a local area network (LAN) with IP address 192.168.50.x/24. Host 192.168.50.1 (also on the LAN) is a router for the corporate network 172.20.x.x/16 and host 192.168.50.254 (also on the LAN) is a router for the Internet at large.

     # route
     Kernel IP routing table
     Destination   Gateway        Genmask       Flags Metric Ref Use Iface
     127.0.0.0     *              255.0.0.0     U     0      0     2 lo
     192.168.50.0  *              255.255.255.0 U     0      0   137 eth0
     172.20.0.0    192.168.50.1   255.255.0.0   UG    1      0     7 eth0
     default       192.168.50.254 0.0.0.0       UG    1      0    36 eth0

IP addresses in the table may also appear as names that are obtained by looking up addresses in /etc/networks or by using the C Library resolver.

In addition to routing, the kernel can perform network address translation, traffic shaping and filtering.

See the Net-HOWTO and other networking HOWTOs for more background information.


10.2 Low level network configuration

The traditional low level network configuration tools on GNU/Linux systems are the ifconfig and route programs which come in the net-tools package. These tools have officially been superseded by ip which comes in the iproute package. The ip program works with Linux 2.2 and higher and is more capable than the old tools. However, the old tools still work and are more familiar to many users.


10.2.1 Low level network configuration – ifconfig and route

Here is an illustration of how to change the IP address of interface eth0 from 192.168.0.3 to 192.168.0.111 and to make eth0 the route to network 10.0.0.0 via 192.168.0.1. We begin by running ifconfig and route without interface arguments in order to display the current status of all network interfaces and routing.

     # ifconfig
     eth0 Link encap:Ethernet  HWaddr 08:00:46:7A:02:B0
          inet addr:192.168.0.3  Bcast:192.168.0.255  Mask:255.255.255.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:23363 errors:0 dropped:0 overruns:0 frame:0
          TX packets:21798 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:100
          RX bytes:13479541 (12.8 MiB)  TX bytes:20262643 (19.3 MiB)
          Interrupt:9
     
     lo   Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          UP LOOPBACK RUNNING  MTU:16436  Metric:1
          RX packets:230172 errors:0 dropped:0 overruns:0 frame:0
          TX packets:230172 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:0
          RX bytes:22685256 (21.6 MiB)  TX bytes:22685256 (21.6 MiB)
     # route
     Kernel IP routing table
     Destination  Gateway      Genmask          Flags Metric Ref Use Iface
     192.168.0.0  *            255.255.0.0      U     0      0     0 eth0
     default      192.168.0.1  255.255.255.255  UG    0      0     0 eth0

First we bring down the interface.

     # ifconfig eth0 inet down
     # ifconfig
     lo   Link encap:Local Loopback
       ... (no more eth0 entry)
     # route
       ... (no more routing table entries)

Then we bring it up with the new IP address and new routing.

     # ifconfig eth0 inet up 192.168.0.111 \
                netmask 255.255.0.0 broadcast 192.168.255.255
     # route add -net 10.0.0.0 netmask 255.0.0.0 gw 192.168.0.1 dev eth0

The result:

     # ifconfig
     eth0 Link encap:Ethernet  HWaddr 08:00:46:7A:02:B0
          inet addr:192.168.0.111  Bcast:192.168.255.255  Mask:255.255.0.0
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          ...
     
     lo   Link encap:Local Loopback
          inet addr:127.0.0.1  Mask:255.0.0.0
          ...
     # route
     Kernel IP routing table
     Destination  Gateway      Genmask      Flags Metric Ref Use Iface
     192.168.0.0  *            255.255.0.0  U     0      0     0 eth0
     10.0.0.0     192.168.0.1  255.0.0.0    UG    0      0     0 eth0

For more information see ifconfig(8) and route(8).


10.2.2 Low level network configuration – ip

The ip equivalents of the preceding ifconfig and route commands are:

The ip program prints its command syntax when run with the argument help. For example, ip link help prints:

     Usage: ip link set DEVICE { up | down | arp { on | off } |
                          dynamic { on | off } |
                          multicast { on | off } | txqueuelen PACKETS |
                          name NEWNAME |
                          address LLADDR | broadcast LLADDR |
                          mtu MTU }
            ip link show [ DEVICE ]

See also ip(8).


10.2.3 Configuring a Wi-Fi interface

For Wi-Fi interfaces the iwconfig program which comes in the wireless-tools package is used in addition to either ifconfig or ip.

See iwconfig(8).


10.2.4 Configuring a PPP interface

If you access the Internet through a modem connected to a dial-up telephone line then the connection is negotiated using the Point-to-Point Protocol (PPP). Such connections are accessed as network interface ppp0, ppp1 and so on.

A PPP interface is managed by the PPP daemon pppd which comes in the ppp package. Thus, for the user, configuring a PPP interface means configuring pppd.


10.2.4.1 Configuring pppd manually

For a network link to be established, a communication port (usually a serial port) needs to be opened, commands have to be sent to a communication device (usually a modem), a telephone number may have to be dialed, identity has to be authenticated to a foreign PPP daemon, a PPP interface has to be created and then routing tables have to be modified so that traffic can be sent over the link. pppd can do all of this and consequently has a very long list of operating options. These options are described in pppd(8).

On a Debian system, global options are set up in /etc/ppp/options. User-specific options are set up in ~/.ppprc. Options that must depend on the communication port used are stored in /etc/ppp/options.portname. For example, suppose you have two modems—a built-in Lucent LT modem accessed through /dev/LT-modem and an external modem accessed through /dev/ttyS0. Create the following two options files.

     # cat > /etc/ppp/options.LT-modem <<EOF
     115200
     init "/usr/sbin/chat -f /etc/chatscripts/setup-LT-modem"
     EOF
     # cat > /etc/ppp/options.ttyS0 <<EOF
     115200
     init "/usr/sbin/chat -f /etc/chatscripts/setup-ttyS0"
     EOF

These refer to the following chat scripts. First, /etc/chatscripts/setup-LT-modem.

     ABORT ERROR
     '' ATZ
     OK 'ATW2X2 S7=70 S11=55'
     OK AT

Second, /etc/chatscripts/setup-ttyS0.

     ABORT ERROR
     '' ATZ
     OK 'ATL1M1Q0V1W2X4&C1&D2 S6=4 S7=70 S11=55 S95=63 S109=1 +FCLASS=0'
     OK AT

The contents of these files must depend on your hardware, of course.

Options can also be given to pppd as arguments.

In Debian pppd is usually started using the pon command. When pon is used its first argument names an options file in /etc/ppp/peers/ which is also read by pppd. [46] This is where you set up options that are specific to a particular peer—for example, a particular Internet Service Provider (ISP).

Suppose for example you commute between Amsterdam and Den Haag. In each city you have access to two ISP services—Planet and KPN. First create a basic options file for each ISP.

     # cat > /etc/ppp/peers/KPN <<EOF
     remotename KPN
     noauth
     user kpn
     noipdefault
     ipparam KPN
     EOF
     # cat > /etc/ppp/peers/Planet <<EOF
     remotename Planet
     auth
     user user3579@planet.nl
     noipdefault 
     mru 1000
     mtu 1000
     ipparam Planet
     EOF

These files set options that differ between the two ISPs. Options common to both ISPs can be placed in /etc/ppp/options or in one of the interface-specific options files as appropriate.

Now create options files for each ISP in each city. In our example the only difference between connecting to an ISP in one location versus connecting in another is the chatscript that is required. (The chatscript is different because the local access telephone number is different.)

     # cat > /etc/ppp/peers/KPN-Amsterdam <<EOF
     connect "/usr/sbin/chat -v -f /etc/chatscripts/KPN-Amsterdam"
     file /etc/ppp/peers/KPN
     EOF
     # cat > /etc/ppp/peers/KPN-DenHaag <<EOF
     connect "/usr/sbin/chat -v -f /etc/chatscripts/KPN-DenHaag"
     file /etc/ppp/peers/KPN
     EOF
     # cat > /etc/ppp/peers/Planet-Amsterdam <<EOF
     connect "/usr/sbin/chat -v -f /etc/chatscripts/Planet-Amsterdam"
     file /etc/ppp/peers/Planet
     EOF
     # cat > /etc/ppp/peers/Planet-DenHaag <<EOF
     connect "/usr/sbin/chat -v -f /etc/chatscripts/Planet-DenHaag"
     file /etc/ppp/peers/Planet
     EOF

The file directives each include one of the options files shown earlier. The connect directive specifies the command that pppd uses to make the connection. Normally one uses the chat program for this, adapting the chatscript to the ISP. Here are the chatscripts for Den Haag; the chatscripts for Amsterdam might be similar except for the telephone number or they might be different if the ISP offers service through another company there.

     # cat > /etc/chatscripts/KPN-DenHaag <<EOF
     ABORT BUSY
     ABORT 'NO CARRIER'
     ABORT VOICE
     ABORT 'NO DIALTONE'
     ABORT 'NO DIAL TONE'
     ABORT 'NO ANSWER'
     ABORT ERROR
     OK-AT-OK ATDT 0676012321
     CONNECT \d\c
     EOF
     # cat > /etc/chatscripts/Planet-DenHaag <<EOF
     ABORT BUSY
     ABORT 'NO CARRIER'
     ABORT VOICE
     ABORT 'NO DIALTONE'
     ABORT 'NO DIAL TONE'
     ABORT 'NO ANSWER'
     ABORT ERROR
     OK-AT-OK ATDT 0676002505
     CONNECT \d\c
     EOF

To be able to connect to these ISPs you need client names and passwords that pppd can supply to the peer on demand. This information is stored either in /etc/ppp/pap-secrets (if the PAP protocol is used) or in /etc/ppp/chap-secrets (if the CHAP protocol is used). Although CHAP is more secure, PAP is still more widely used. Because these files contain secrets, group and world should not have permission to read or write them. The format of these files is explained in pppd(8). A "secret" (third field) is looked up in the file by finding the client name (first field) and/or the server name (second field). When connecting to an ISP one generally doesn't know the server name, so one supplies a client name instead; this was done on the user lines in peers/KPN and peers/Planet above.

     # client name       server name  secret
     kpn                 *            kpn
     user3579@planet.nl  *            myfavoritepet

10.2.4.2 Configuring pppd using pppconfig

A quick way to configure pppd is to use the pppconfig program which comes in the package of the same name. pppconfig sets up files like those above after asking the user questions through a menu interface.

If you choose to use the resolvconf then be sure to select "None" in the "Configure Nameservers" screen.


10.2.4.3 Configuring a PPP interface using wvdial

A different approach to using pppd is to run it from wvdial which comes in the wvdial package. Instead of pppd running chat to dial in and negotiate the connection, wvdial does the dialing and initial negotiating and then starts pppd to do the rest. Given only phone number, username, and password wvdial succeeds in making the connection in most cases.


10.3 Naming the computer


10.3.1 Hostname

A Debian system sometimes needs to identify itself by name. For this purpose a hostname is maintained by the kernel.

The initscript /etc/init.d/hostname.sh sets the hostname at boot time (using the hostname command) to the name stored in /etc/hostname. This file should contain only the hostname, not a fully qualified domain name.

To print out the current hostname run hostname without an argument.


10.3.2 Mailname

The mailname of a host is the name that mail-related programs use to identify the host. The file /etc/mailname contains of this name followed by a newline. The mailname is usually one of the host's fully qualified domain names. See mailname(5).

What the recipient of e-mail sees in the From: header of mail sent by your Debian host depends on how Mail User Agents (MUA) and Mail Transfer Agents (MTA) are configured. Suppose a local user foo sends a mail from a host with mailname myhost.dom. The From: header of outgoing e-mail will be:

Even when the MUA has a From: header set the MTA may add a "Sender:foo@herman.dom" header to indicate its true origin.

Of course when any involved MTA performs address rewriting as discussed in Setting up a catchall for nonexistent email addresses under Exim, Section 9.6.1.3 and Configuring selective address rewriting for outgoing mail under Exim, Section 9.6.1.4, the e-mail address seen by the recipient can be changed to anything.


10.4 Domain Name Service (DNS)

Hosts are referred to by domain name as well as by IP address. DNS is a client-server system in which name resolvers consult nameservers in order to associate domain names with IP addresses and other properties of hosts. The GNU C Library resolver(3) can also look up IP addresses in files or consult Network Information Services (NIS).

To see what domain name is associated with the local host, use the hostname --fqdn command. This prints out the first fully qualified domain name that the resolver finds for the local hostname. [47]


10.4.1 The resolver

The job of finding out what IP addresses are associated with a particular domain name is the job of a resolver. The most commonly used resolver is the set of functions that go by that name (resolver(3)) in the GNU C Library. Another is the FireDNS resolver which comes in the libfiredns package.

How the LIBC resolver resolves names is governed by the hosts line in the /etc/nsswitch.conf configuration file. This line lists the services that should be used to resolve a name: e.g., dns, files, nis, nisplus. [48] See nsswitch.conf(5). Insofar as the files service is used, the behavior of the resolver is also governed by the /etc/hosts configuration file. See hosts(5).

All of the above files are static and can be edited with your favorite editor.

Insofar as the dns service is used, the behavior of the resolver is also governed by the /etc/resolv.conf configuration file. See resolv.conf(5). One of the important functions of resolv.conf is to list the IP addresses of nameservers that will be contacted to resolve the name. This list often has to depend upon the network environment and the network environment may change from time to time while your computer is running. Programs such as pppd and dhclient are able to manipulate resolv.conf to add and remove lines, but these features do not always work properly and they conflict with one another. The resolvconf package solves the problem better by providing a standard framework for updating this file. See Managing nameserver information – resolvconf, Section 10.4.2.


10.4.2 Managing nameserver information – resolvconf

The resolvconf package provides a framework for dynamic management of information about available nameservers. It solves the long standing problem of how to maintain dynamic lists of nameservers for the resolver and DNS caches to use. Resolvconf sets itself up as the intermediary between programs that control network interfaces and supply nameserver information, and applications that need nameserver information.

resolvconf is designed to work without any manual configuration needing to be done. However, the package is quite new and may require some manual intervention to get it to work properly. This is certainly true if you have ever customized packages so that they update /etc/resolv.conf: you will need to disable your customizations.

See /usr/share/doc/resolvconf/README.gz for details.


10.4.3 Caching looked-up names – dnsmasq

Unless your nameserver has to be authoritative for a domain you are better off running a caching forwarding local nameserver such as dnsmasq. It works well with resolvconf.


10.4.4 Caching looked-up names – bind

If you wish you can also use bind9 or bind as a caching forwarding local nameserver. It also works with resolvconf, but at the time of writing this (October 2003) you have to set it up manually to do so. See /usr/share/doc/resolvconf/README.gz for instructions.


10.4.5 Providing Domain Name Service – bind

If you need to provide authoritative name service for a domain then you need a fully fledged nameserver such as named which comes in either the bind9 or the bind package. bind9 is recommended for new installations.

To install bind9, install these basic packages: bind9; dnsutils. You may also want to install these utility packages: bind9-host; dns-browse; dnscvsutil; nslint. You may also want to install this documentation package: bind9-doc. You may also want to install these development packages: libbind-dev; libnet-dns-perl. If you configure interfaces using DHCP then you may find this package useful: dhcp-dns.

Install bind9 or dpkg-reconfigure it to do the basic set-up. Configuration consists of editing named.conf. In Debian this file is found in /etc/bind/ and is used mainly to define the basic DNS zones; it includes two other files: named.conf.local, used for defining local zones, and named.conf.options, used for setting options. (The latter is processed by resolvconf to produce /var/run/bind/named.options which is the same as the original except that the forwarders specification is a list of the currently available non-local nameservers. To make use of this, change the include line in named.conf so that it includes /var/run/bind/named.options. See Managing nameserver information – resolvconf, Section 10.4.2.)

Database files named in named.conf* without a full pathname will be stored in /var/cache/bind/. This is the right place to store files generated by named: for example, database files for zones for which the daemon is secondary. Static database files in /etc/bind/ are and must be referred to in named.conf by their full path names. See /usr/share/doc/bind9/README.Debian.gz for details.


10.5 Configuring network interfaces using DHCP

Low-level configuration of network interfaces can be automated by means of the Dynamic Host Configuration Protocol (DHCP). Your firewall or router box or your broadband ISP may furnish IP addresses and other parameters this way.

To make this work you must install one of the following packages:

pump is simple and widely used. dhcp3-client is complex but more configurable. [49]


10.6 High level network configuration in Debian

In order to make network configuration easier Debian provides a standard high level network configuration tool consisting of the ifup and ifdown programs and the /etc/network/interfaces file. [50] If you choose to use ifupdown to do your network configuration then normally you should not use low-level commands too. [51] Ifupdown is written under the assumption that it alone will be used to configure and deconfigure network interfaces.

To update interface configuration do this:

     # ifdown eth0
     # editor /etc/network/interfaces  # tweak as you wish
     # ifup eth0

For more information see interfaces(5), /usr/share/doc/ifupdown/examples/network-interfaces.gz and ifup(8).


10.6.1 Configuring an interface with a static IP address

Suppose you want to configure an Ethernet interface such that it has a fixed IP address of 192.168.0.123. This address begins with 192.168.0 so it must be on a LAN. Suppose further that 192.168.0.1 is the address of the LAN's gateway to the Internet. Edit /etc/network/interfaces so that it includes a stanza like this:

     iface eth0 inet static
             address 192.168.0.123
             netmask 255.255.255.0
             gateway 192.168.0.1

If you have resolvconf installed then you can add lines that specify DNS information. For example:

     iface eth0 inet static
             address 192.168.0.123
             netmask 255.255.255.0
             gateway 192.168.0.1
             dns-search nicedomain.org
             dns-nameservers 195.238.2.21 195.238.2.22

After the interface is brought up, the arguments of the dns-search and dns-nameservers options are made available to resolvconf for inclusion in resolv.conf. The argument nicedomain.org of the dns-search option corresponds to the argument of a search option in resolv.conf(5). The arguments 195.238.2.21 and 195.238.2.22 of the dns-nameservers option correspond to the arguments of nameserver options in resolv.conf(5). Other recognized option words are dns-domain and dns-sortlist. See Managing nameserver information – resolvconf, Section 10.4.2.


10.6.2 Configuring an interface using DHCP

To configure an interface using DHCP edit /etc/network/interfaces so that it includes a stanza like this:

     iface eth0 inet dhcp

In order for this to work you must have installed one of the DHCP clients mentioned in Configuring network interfaces using DHCP, Section 10.5.


10.6.3 Configuring a Wi-Fi interface

The wireless-tools package includes a hook script /etc/network/if-pre-up.d/wireless-tools which makes it possible to configure Wi-Fi (802.11a/b/g) hardware before the interface is brought up. Configuration is done using the iwconfig program; see iwconfig(8). For each possible command parameter of iwconfig you can include an option in /etc/network/interfaces named like that parameter with a "wireless-" prefix. For example, to set the ESSID of eth0 to myessid and the encryption key to 123456789e prior to bringing eth0 up using DHCP, edit /etc/network/interfaces so that it includes a stanza like this:

     iface eth0 inet dhcp
             wireless-essid myessid
             wireless-key 123456789e

10.6.4 Configuring a PPP interface

The ifup and ifdown programs use pon and poff to add and remove PPP interfaces so first read Configuring a PPP interface, Section 10.2.4.

Suppose you have set up PPP to work with peer myisp. Edit /etc/network/interfaces so that it includes a stanza like this:

     iface ppp0 inet ppp
             provider myisp

With this stanza in place, ifup ppp0 does

     pon myisp

Unfortunately it is currently not possible to provide additional pppd options in a ppp stanza in /etc/network/interfaces. [52]

It is currently not possible to use ifupdown to perform auxiliary configuration of PPP interfaces. Because pon exits before pppd has finished making the connection, ifup runs up scripts before the PPP interface is ready for use. Until this bug [53] is fixed it remains necessary to do auxiliary configuration in /etc/ppp/ip-up or /etc/ppp/ip-up.d/.


10.6.5 Configuring a PPPoE interface

Many broadband Internet Service Providers (ISPs) use PPP to negotiate connections even though customer machines are connected to them through Ethernet and/or ATM networks. This is accomplished by means of PPP over Ethernet (PPPoE) which is a technique for the encapsulation of PPP streams inside of Ethernet frames. Suppose your ISP is called myisp. First configure PPP and PPPoE for peer myisp. The easiest way to do this is to install the pppoeconf package and to run pppoeconf from the console. Then edit /etc/network/interfaces so that it includes a stanza like this:

     iface eth0 inet ppp
             provider myisp

There are sometimes Maximum Transmit Unit (MTU) issues with PPPoE over Digital Subscriber Line (DSL). See DSL-HOWTO for details.

Note that if your broadband modem contains a router then the modem/router handles the PPPoE connection itself and appears on the LAN side as a simple Ethernet gateway to the Internet.


10.6.6 Configuring multiple Ethernet interfaces for a gateway

Suppose eth0 is connected to the Internet with a DHCP-configured IP address and eth1 is connected to the LAN with static IP address 192.168.1.1. Edit /etc/network/interfaces so that it includes stanzas like these:

     iface eth0 inet dhcp
     
     iface eth1 inet static
             address 192.168.1.1
             netmask 255.255.255.0

If you activate NAT on this host as described in Building a gateway router, Section 10.12 then you can share the Internet connection with all the hosts on the LAN.


10.6.7 Configuring virtual interfaces

Using virtual interfaces you can configure a single Ethernet card to be an interface to several IP subnetworks. For example, suppose your host is on LAN network 192.168.0.x/24. You want to connect the host to the Internet using a public IP address provided via DHCP using your existing Ethernet card. Edit /etc/network/interfaces so that it includes stanzas like these:

     iface eth0 inet static
             address 192.168.0.1
             netmask 255.255.255.0
             network 192.168.0.0
             broadcast 192.168.0.255
     
     iface eth0:0 inet dhcp

The interface eth0:0 is a virtual interface. When it is brought up, so will its parent eth0.


10.7 Network reconfiguration

In the following it will be important for the reader to understand the difference between a physical interface and a logical interface. [54] A physical interface is what we have been calling "the interface", the thing that is named eth0, ppp1, or what have you. A logical interface is a set of values that can be assigned to the variable parameters of a physical interface. If you find that confusing, replace the expression "configured as logical interface X" with the expression "configured with interface profile X" as you read.

The iface definitions in /etc/network/interfaces are actually definitions of logical interfaces, not of physical interfaces. [55] If you never want to reconfigure your interfaces then you can ignore this fact since the physical interface X will by default be configured as logical interface X.

However, suppose your computer is a laptop that you transport between home and work. When you connect the computer to the corporate network or to your home LAN you need to configure eth0 accordingly.

First define two logical interfaces home and work (instead of eth0 as we did earlier) which describe how the interface should be configured for the home network and the work network, respectively.

     iface home inet static
             address 192.168.0.123
             netmask 255.255.255.0
             gateway 192.168.0.1
     
     iface work inet static
             address 81.201.3.123
             netmask 255.255.0.0
             gateway 81.201.1.1

Then physical interface eth0 can be brought up for the home network with the appropriate configuration by specifying it on the command line:

     # ifup eth0=home

To reconfigure eth0 for the work network issue the commands:

     # ifdown eth0
     # ifup eth0=work

Note that with the interfaces file written as above it will no longer be possible to bring up eth0 by doing ifup eth0 alone. The reason is that ifup uses the physical interface name as the default logical interface name and now in our example no eth0 logical interface is defined.


10.8 Magic network reconfiguration

Logical interface names can be "mapped" to other logical interface names when ifup runs. How names are mapped can be made to depend on circumstances. Thus ifup can be so configured that it brings up a given physical interface as the appropriate logical interface among a set of predefined alternatives.

Logical interface name mapping occurs as follows:

The syntax of a mapping stanza is:

     mapping glob-pattern
             script script-name
             [map script input]

The script named in the mapping stanza is run with the physical interface name as its argument and with the contents of all following "map" lines in the stanza provided to it on its standard input. The script prints the result of the mapping on its standard output before exiting.

For example, the following mapping stanza will cause ifup to bring up interface eth0 as the home logical interface.

     mapping eth0
             script /usr/local/sbin/echo-home

where /usr/local/sbin/echo-home is:

     #!/bin/sh
     echo home

Because mapping is done with a script it is possible to select the logical interface based on some sort of test. Let's start with an example. Suppose you have different network cards for home and work. The /usr/share/doc/ifupdown/examples/ directory contains a mapping script that can be used to select a logical interface based on the Media Access Controller address (MAC address). First install the script to an appropriate directory.

     # install -m770 /usr/share/doc/ifupdown/examples/match-mac-address.sh \
        /usr/local/sbin/

Then add a stanza like the following to /etc/network/interfaces:

     mapping eth0
             script /usr/local/sbin/match-mac-address.sh
             map 02:23:45:3C:45:3C home
             map 00:A3:03:63:26:93 work

More sophisticated mapping programs are described below in guessnet, Section 10.8.1, ifupdown-roam, Section 10.8.2, and laptop-net, Section 10.8.3.


10.8.1 guessnet

Install guessnet and then add a stanza like the following to /etc/network/interfaces:

     mapping eth0
             script guessnet-ifupdown
             map home
             map work

Now when you ifup eth0, guessnet will check whether eth0 can be brought up as home or work. To do this it uses information stored in the logical interface definitions. guessnet uses ARP requests to detect either the gateway or a host identified on a test-peer line.

guessnet is still under development.


10.8.2 ifupdown-roam

The ifupdown-roam package includes the ifscout program whose capabilities as a mapping script are a superset of those of guessnet. ifscout calls guessnet to look for hosts on wired Ethernet networks but it can also detect DHCP servers and wireless access points. ifscout is a shell script so it can be customized to suit your needs.

Currently (October 2003) ifupdown-roam is not part of Debian. It might have been uploaded to the Debian archives by the time you read this; otherwise it is available via the the ifupdown-roam home page where you will also find installation and usage information.


10.8.3 laptop-net

The laptop-net package takes a different approach to automagic network reconfiguration. Laptop-net does not make use of ifupdown's logical interfaces but instead has its own system of configuration "schemes" and system "profiles". Laptop-net still uses ifupdown to configure physical interfaces, though. For more information consult the well written documentation in laptop-net-doc.


10.9 Triggering network reconfiguration

We have seen how interfaces can be reconfigured. Reconfiguration needs to be done at appropriate times.

Traditionally the network was configured during the boot sequence via the /etc/rcS.d/S40networking initscript and was rarely reconfigured. Services that depended on networking were started later in the boot sequence. On shutdown or reboot the initscripts were run in the opposite order.

Currently, however, there is a trend in GNU and Linux toward supporting hardware and circumstances that change dynamically. First support was added for hot swappable PCMCIA cards; more recently the hotplug mechanism has been added so that many more peripherals can be swapped in and out while the computer is running. This includes networking hardware. Note that services that depend on hardware that is hot swapped must only be started after the hardware is inserted and must be stopped when the hardware is removed. This means that such services must be removed from the control of the System V init system and put under the control of ifupdown instead.

For example, suppose service foo controlled by initscript /etc/init.d/foo depends on dynamically reconfigured network interface eth0.


10.9.1 Triggering network configuration at boot time

On boot the /etc/rcS.d/S40networking init script runs the command ifup -a. This brings up all physical interfaces listed in auto stanzas in /etc/network/interfaces.

These days it is often better to handle network configuration using dynamic methods. Once mechanisms for supporting dynamically changing hardware are in place it becomes simplest to treat static hardware as if it were dynamic too. Booting can then be treated as just another hotplug event. (See Triggering network configuration – hotplug, Section 10.9.2.)

However, in almost all cases one wants at least the loopback interface lo to be brought up on boot. Therefore, make sure that /etc/network/interfaces includes the following stanzas.

     auto lo
     
     iface lo inet loopback

You can list additional physical interface names in auto stanzas if you want them to be brought up on boot too. Never list PCMCIA interfaces in auto stanzas. The PCMCIA cardmgr is started later in the boot sequence than when /etc/rcS.d/S40networking runs.


10.9.2 Triggering network configuration – hotplug

For hot plug support install the hotplug package.

Networking hardware can be hot plugged either at boot time or after a card (e.g., a PCMCIA card) is inserted into the machine or after a utility such as discover runs and loads necessary driver modules.

When the kernel detects new hardware it initializes the driver for the hardware and then runs the hotplug program to configure it. Later if the hardware is removed then the kernel runs hotplug again with different environment variable settings. In Debian, when hotplug is called it runs scripts in /etc/hotplug/ and /etc/hotplug.d/. See hotplug(8) for details.

Newly inserted network hardware is configured by the script /etc/hotplug/net.agent. [56] Suppose your PCMCIA network card has been inserted resulting in interface eth0 becoming available for use. /etc/hotplug/net.agent does the following:

     ifup eth0=hotplug

Unless you have added a logical interface definition or mapping named hotplug to /etc/network/interfaces, this command will do nothing. To make it so that the command will configure eth0, add the following stanza to /etc/network/interfaces:

     mapping hotplug
             script echo

As explained in Network reconfiguration, Section 10.7 this will map the command shown above so that it is equivalent to the following:

     ifup eth0=eth0

(Do not include a mapping stanza like this if you are using ifplugd instances started by hotplug to control the interface, as described in Triggering network configuration – ifplugd, Section 10.9.3.)

If you want only eth0 and no other interfaces to be brought up on hot plug then use grep instead of echo as follows:

     mapping hotplug
             script grep
             map eth0

See Magic network reconfiguration, Section 10.8 and /usr/share/doc/hotplug/README.Debian for more tips.


10.9.3 Triggering network configuration – ifplugd

ifplugd brings an interface up or down according to whether its underlying hardware is or is not plugged in to a network. The program can detect a live cable connected to an Ethernet interface or an access point associated to a Wi-Fi interface. When ifplugd sees that the state of the link has changed it runs a proxy script which by default calls ifup or ifdown for the interface.

ifplugd works well in combination with hotplug. When a card has been inserted resulting in an interface becoming available for use, /etc/hotplug.d/net/ifplugd.hotplug starts an instance of ifplugd for that interface. When ifplugd detects that the card is plugged into a network it ifups the interface.


10.9.4 Triggering network configuration – waproamd

In order to associate to an access point a Wi-Fi card may have to be programmed with an appropriate WEP encryption key. If you are using ifplugd to control ifup as described in Triggering network configuration – ifplugd, Section 10.9.3 then obviously you cannot set the encryption key using ifup because ifup only gets called after the card has associated. One possible solution is to program all required keys into the Wi-Fi card's nonvolatile memory. If you roam among many networks then your Wi-Fi card may not be able to store enough keys.

Another solution is to use waproamd which sets the WEP encryption key according to the access points that are available, as revealed by scanning.

waproamd works well in combination with hotplug. When a card has been inserted resulting in an interface becoming available for use, /etc/hotplug.d/net/waproamd.hotplug starts an instance of waproamd for that interface. waproamd works nicely in combination with ifplugd.

See the waproamd package README file for more information.


10.9.5 Network configuration and PCMCIA

If you use 16 bit PCMCIA network cards then you should set CARDMGR_OPTS="-f" in /etc/defaults/pcmcia. This slows down initialization slightly but it prevents a race condition by running cardmgr in the foreground until all 16 bit PCMCIA cards are configured.

Although by default /etc/init.d/pcmcia is started from /etc/rc2.d/S20pcmcia you may want to move this earlier, e.g., to /etc/rc2.d/S12pcmcia in order to ensure that the PCMCIA subsystem is initialized before network services are started at S20.

There are several possible approaches to configuring PCMCIA network interfaces.

The recommended approach for 16 bit cards takes advantage of the fact that the Linux 2.4 hot plug subsystem now supports PCMCIA. Simply follow the directions in Triggering network configuration – hotplug, Section 10.9.2. [57] Note, however, that in order to prevent cardmgr's hook script /etc/pcmcia/network from interfering with hotplug you must locally add the line:

     exit 0

to the beginning of /etc/pcmcia/network in order to disable its default behavior.

Note that there is nothing wrong with running cardmgr. We just don't want it to call network configuration programs.

In order for cardmgr to work properly you may need to edit /etc/pcmcia/config.opts in order to configure resources assigned to 16 bit PCMCIA cards. See PCMCIA, Section 7.2.1 and the Linux PCMCIA HOWTO for more information.


10.10 Network service configuration

Typical network service configuration on the desktop or home server environment involves:


10.11 Network troubleshooting

If you encounter problems then check the output of the following as the first reality check:

     # ifconfig
     # cat /proc/pci
     # cat /proc/interrupts
     # dmesg | more

Also see the sections following Network testing basics, Section 8.6.28.

If you have problems with certain websites, see Strange access problems with some websites, Section 3.7.5.


10.12 Building a gateway router

A Debian host can be an all-purpose gateway machine that does Network Address Translation (NAT, also known as masquerading), mail transfer, DHCP, DNS caching, HTTP proxy caching, CVS service, NFS serving, and Samba serving. See Hosts and IP to use for LAN, Section 3.1.9 for the example of such set up.


10.12.1 Netfilter configuration

The netfilter/iptables project is a firewalling subsystem for Linux 2.4 and after. See Netfilter, where many network configuration issues are explained.


10.12.1.1 Basics of netfilter

Netfilter process packets use five built-in chains: PREROUTING, INPUT, FORWARD, OUTPUT, and POSTROUTING.

                     routing
                     decision
     IN ------> PRE ---> ------> FORWARD -----> ----> POST -----> OUT
     interface  ROUTING  \       filter       /       ROUTING     interface
                DNAT     |       tracking     ^       SNAT
                REDIRECT |                    |       MASQUERADE
                         v                    |
                       INPUT                OUTPUT
                         | filter             ^ filter,DNAT 
                         v                    |
                         \--> Local Process --/
                              user-space programs

10.12.1.2 Netfilter table

Packets are processed at each built-in chain using the following tables.


10.12.1.3 Netfilter target

Firewall rules have several targets:


10.12.1.4 Netfilter commands

The basic commands of iptables are:

     iptables -N chain                   # create a chain
     
     iptables -A chain \                 # add rule to chain
              -t table \                 # use table (filter, nat, mangle)
              -p protocol \              # tcp, udp, icmp, or all,
              -s source-address[/mask] \
              --sport port[:port] \      # source port if -p is tcp or udp
              -d destination-address[/mask] \
              --dport port[:port] \      # dest. port if -p is tcp or udp
              -j target \                # what to do if match
              -i in-interface-name \     # for INPUT,  FORWARD, PREROUTING
              -o out-interface-name      # for FORWARD, OUTPUT, POSTROUTING

10.12.1.5 Network Address Translation

Machines on a LAN can access Internet resources through a gateway that translates IP address on the LAN to IP addresses usable on the Internet.

     # apt-get install ipmasq

Apply example rules to strengthen the ipmasq protection. See /usr/share/doc/ipmasq/examples/stronger/README. For Debian kernel-image-2.4 under woody, make sure to load the proper modules. Sarge version of ipmasq fixed this issue. See Network function, Section 7.2.3 for configuration instructions.

For Debian kernel-image-2.2, edit Z92timeouts.rul in /etc/masq/rules as follows to ensure a longer connection to remote sites (good for large emails, etc.):

     # tcp, tcp-fin, udp
     # 2hr, 10 sec, 160 sec - default
     # 1 day, 10 min, 10 min - longer example
     $IPCHAINS -M -S 86400 600 600

Also, if the network is accessed through a PCMCIA NIC, ipmasq needs to be started either from /etc/pcmcia/network.opts (read: /usr/share/doc/ipmasq/ipmasq.txt.gz) or from /etc/network/interfaces (read: Network configuration and PCMCIA, Section 10.9.5 and Triggering network reconfiguration, Section 10.9).


10.12.1.6 Redirect SMTP connection (2.4)

Suppose you have a notebook PC which is configured to use other LAN environments and you want to use your mail user agent on the notebook PC without reconfiguring it.

Adding the following rules through the iptables command to the gateway machine will redirect the SMTP connection to the gateway machine.

     # iptables -t nat -A PREROUTING -s 192.168.1.0/24 -j REDIRECT \
                -p tcp --dport smtp --to-port 25 # smtp=25, INPUT is open

For a more thorough redirect rule set consider installing the ipmasq package and adding M30redirect.def to the /etc/ipmasq/rules/ directory.


10.12.2 Manage multiple net connections

[FIXME] Policy routing (by Phil Brutsche pbrutsch@tux.creighton.edu): See the iproute manual for details. Traffic control (tc) may also be interesting.

Environment:

     eth0: 192.168.1.2/24; gateway 192.168.1.1
     eth1: 10.0.0.2/24; gateway 10.0.0.1
     No masquerading on this machine.

Special magic:

  1. ip rule add from 192.168.1.2 lookup 1
  2. ip rule add from 10.0.0.2 lookup 2
  3. ip route add to default via 10.0.0.1 metric 0
  4. ip route add to default via 192.168.1.1 metric 1
  5. ip route add table 1 to 192.168.1.0/24 via eth0
  6. ip route add table 1 to 10.0.0.2/24 via eth1
  7. ip route add table 1 to default via 192.168.1.1
  8. ip route add table 2 to 192.168.1.0/24 via eth0
  9. ip route add table 2 to 10.0.0.2/24 via eth1
  10. ip route add table 2 to default via 10.0.0.2

[FIXME] I've never done this. How to set up dialup as backup to a fast connection with autodial features? Please send me a patch here :)


[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ 10 ] [ 11 ] [ 12 ] [ 13 ] [ 14 ] [ 15 ] [ A ] [ next ]

Debian Reference

1.06-17, Sat Jan 31 07:56:05 UTC 2004

Osamu Aoki osamu@debian.org
Editor: David Sewell dsewell@virginia.edu
Authors, Section A.1