[ 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 properly configured.

The first requirement is kernel support for the devices. Examples of such devices are: 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 was 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. [51] 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 so-called netmask of the network.

Traditionally, IP networks were grouped into classes whose net address parts were 8, 16 or 24 bits in length. This system was inflexible and wasted many IP addresses, so today IPv4 networks are allocated with network address parts of varying length.

               IP addresses                   net mask      length
     Class A     -     =  /8
     Class B   -   = /16
     Class C   - = /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. [52] 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 (also on the LAN) is a router for the corporate network 172.20.x.x/16 and host (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     *         U     0      0     2 lo  *     U     0      0   137 eth0   UG    1      0     7 eth0
     default       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 to and to make eth0 the route to network via 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:  Bcast:  Mask:
          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)
     lo   Link encap:Local Loopback
          inet addr:  Mask:
          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  *        U     0      0     0 eth0
     default  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 \
                netmask broadcast
     # route add -net netmask gw dev eth0

The result:

     # ifconfig
     eth0 Link encap:Ethernet  HWaddr 08:00:46:7A:02:B0
          inet addr:  Bcast:  Mask:
     lo   Link encap:Local Loopback
          inet addr:  Mask:
     # route
     Kernel IP routing table
     Destination  Gateway      Genmask        Flags Metric Ref Use Iface  *    U     0      0     0 eth0      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. 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 by the kernel 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
     init "/usr/sbin/chat -f /etc/chatscripts/setup-LT-modem"
     # cat > /etc/ppp/options.ttyS0 <<EOF
     init "/usr/sbin/chat -f /etc/chatscripts/setup-ttyS0"

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

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

Second, /etc/chatscripts/setup-ttyS0.

     '' 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. [53] 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
     user kpn
     ipparam KPN
     # cat > /etc/ppp/peers/Planet <<EOF
     remotename Planet
     user user3579@planet.nl
     mru 1000
     mtu 1000
     ipparam Planet

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

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
     OK-AT-OK ATDT 0676012321
     CONNECT \d\c
     # cat > /etc/chatscripts/Planet-DenHaag <<EOF
     OK-AT-OK ATDT 0676002505
     CONNECT \d\c

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

See /usr/share/doc/ppp/README.Debian.gz for more information. 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. 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

The kernel maintains a system hostname. The initscript /etc/init.d/hostname.sh sets the system hostname at boot time (using the hostname command) to the name stored in /etc/hostname. This file should contain only the system 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 a fully qualified domain name that resolves to one of the host's IP addresses. 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 and Configuring selective address rewriting for outgoing mail under Exim, Section, the e-mail address seen by the recipient can be changed to something else.

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).

Some software (e.g., GNOME) expects the system hostname to be resolvable to an IP address with a canonical fully qualified domain name. This is really improper because system hostnames and domain names are two very different things; but there you have it. In order to support that software, it is necessary to ensure that the system hostname can be resolved. Most often this is done by putting a line in /etc/hosts containing some IP address and the system hostname. If your system has a permanent IP address then use that; otherwise use the address localhost uranus

To see whether your system hostname can be resolved to an IP address with a fully qualified domain name, use the hostname --fqdn command.

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. There are others.

How the GNU 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. 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 – nscd, dnsmasq, pdnsd, bind9

If your nameserver is slow to respond then you may want to use nscd to cache the results of things that are looked up using the libc6 resolver.

If you want to cache results for other hosts on your local network then you may want to run a caching forwarding nameserver such as dnsmasq or pdnsd.

If you wish you can also use bind9's named as a caching forwarding nameserver. It is a heavy program, though, so unless you need its advanced features you are better off with one of the packages mentioned earlier.

All of these packages work well with resolvconf.

10.4.4 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 the bind9 package.

If you install bind9 you should also install 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. [54]

10.6 High level network configuration in Debian

10.6.1 High level network configuration using ifupdown

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. [55] If you choose to use ifupdown to do your network configuration then normally you should not use low-level commands too. This means also that you should not use other high level configuration tools such as whereami, divine, intuitively, etc., that call low level configuration tools. The ifupdown program was written with the intent that it alone 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). 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 This address begins with 192.168.0 so it must be on a LAN. Suppose further that 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

You can configure other aspects of the interface or perform other actions after the interface is brought up or before it is brought down by specifying appropriate commands on "up" and "down" lines.

     iface eth0 inet static
             up route add -net netmask gw dev $IFACE
             down route del -net netmask gw dev $IFACE
             up echo Interface $IFACE going up | /usr/bin/logger -t ifup
             down echo Interface $IFACE Going down | /usr/bin/logger -t ifdown

Alternatively, commands can be inserted into scripts in the /etc/network/if-up.d and /etc/network/if-down.d directories. Such scripts can also implement extended options. See interfaces(5) for details. For example, the resolvconf package includes scripts that allow you to add options specifying DNS information to be included in /etc/resolv.conf while the interface is up:

     iface eth0 inet static
             dns-search somedomain.org

The argument somedomain.org of the dns-search option corresponds to the argument of a search option in resolv.conf(5). The arguments and of the dns-nameservers option correspond to the arguments of nameserver options. Other recognized options are dns-domain and dns-sortlist. See Managing nameserver information – resolvconf, Section 10.4.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. 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

Note that you should not use this method of setting the ESSID and key if you are running waproamd for this interface. By the time ifup is run waproamd has already set the ESSID and key. See Triggering network configuration – waproamd, Section 10.8.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. [56]

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 [57] is fixed it remains necessary to do auxiliary configuration in /etc/ppp/ip-up or /etc/ppp/ip-up.d/. 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. 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 Edit /etc/network/interfaces so that it includes stanzas like these:

     iface eth0 inet dhcp
     iface eth1 inet static

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. 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
     iface eth0:0 inet dhcp

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

10.6.2 High level network configuration using ifupdown logical interface definitions

In the following it will be important for the reader to understand the difference between a physical interface and a logical interface. [58] A physical interface is what we have been calling "the interface", the thing that the kernel names eth0, eth1, ppp0, 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. [59] If you never want to reconfigure your interfaces then you can ignore this fact since the physical interface foo will by default be configured as logical interface foo.

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
     iface work inet static

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.6.3 Automatic network configuration using ifupdown

Interface names can be "mapped" to other 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 always run with the physical interface name as its argument and with the contents of all following "map" lines in the stanza (without the word "map" itself) 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:

     echo home

Because mapping is done with a script it is possible to select the logical interface automatically — based on some sort of test. See Logical interface selection using guessnet, Section for an example of this. Logical interface selection using 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.

10.6.4 Automatic network configuration using 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 ifup and ifdown to configure physical interfaces, though. For more information consult the well written documentation in laptop-net-doc.

10.6.5 Automatic network configuration using network-manager

The network-manager program is currently being developed by Fedora developers and has been packaged for Ubuntu. It may turn up in Debian someday and should render ifupdown and friends obsolete.

10.7 Dealing with inconsistent naming of interfaces by the kernel

The names eth0, eth1, etc. are assigned by the kernel in the order that the kernel creates the interfaces that go by those names. While adapters that are detected at boot time are usually detected in the same order every time, and are therefore assigned the same names every time, the same is not true of adapters that are hot plugged. These can be detected in any order and end up getting assigned different names by the kernel on different occasions.

Because of this fact, on a system into which network adapters are hot plugged it won't always do to define logical interfaces in /etc/network/interfaces with names eth0, eth1, etc., and to rely on the default mapping. Instead you must give distinct names to the logical interfaces and use one of the following two methods to restrict which logical interfaces can be assigned to which adapters.

This issue should be solved by using the current udev package and its configuration.

10.8 Triggering network configuration

We have seen how interfaces can be configured or reconfigured. This 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.8.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.8.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.8.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. [61] Suppose your PCMCIA network card has been inserted resulting in interface eth0 becoming available for use. /etc/hotplug/net.agent does the following [62] :

     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 High level network configuration using ifupdown logical interface definitions, Section 10.6.2 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 or waproamd instances started by hotplug to control the interface.)

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 Automatic network configuration using ifupdown, Section 10.6.3 and /usr/share/doc/hotplug/README.Debian for more tips.

10.8.3 Triggering network configuration – ifplugd

The ifplugd daemon brings an interface up or down according to whether or not its underlying hardware is 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 (although waproamd is probably what you want to use in the latter case). When ifplugd sees that the state of the link has changed it runs a proxy script which by default calls ifup or ifdown.

10.8.4 Triggering network configuration – waproamd

The waproamd daemon is just like ifplugd except that it is designed to be used with Wi-Fi cards. It actively scans for access points to which the Wi-Fi hardware is able to associate. When association is achieved, waproamd runs ifup.

If you are using waproamd then in general you configure the Wi-Fi card via waproamd and not via wireless-* options in /etc/network/interfaces.

10.8.5 Network configuration and PCMCIA

There are several possible approaches to configuring PCMCIA network interfaces (for 2.4 and 2.6 kernels).

The recommended approach for 16 bit cards takes advantage of the fact that the Linux 2.4 hotplug subsystem now supports PCMCIA. [63]

PCMCIA network cards are hot pluggable. Accordingly, any services that require networking through a PCMCIA card should be so configured that they get started on card insertion and get stopped on card removal. This is usually accomplished by arranging for the service to start on ifup and stop on ifdown. Some people, however, choose to confine themselves to cold plugging their PCMCIA network card: they insert the card before booting the system and they start services that require networking through the card in the boot sequence. If you are such a person then in order to ensure that the card is fully configured before the services are started you should do the following:

This hack only works for 16 bit PCMCIA cards.

Note that pcmcia-cs is still needed if you use 16 bit PCMCIA cards. The cardmgr daemon that the package contains is responsible for managing the sockets and loading driver modules. We just don't want it to call network configuration programs via /etc/pcmcia/network.

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 the Linux PCMCIA HOWTO for more information.

10.9 Multi-stage mapping

Suppose your network adapters are hotplugged and you enable automatic configuration as described in Triggering network configuration – hotplug, Section 10.8.2. Suppose further that you need to map logical interfaces to "physical" interfaces depending both on the adapter underlying the physical interface (as described in Dealing with inconsistent naming of interfaces by the kernel, Section 10.7) and on the network connected to the interface (as described, for example, in Logical interface selection using guessnet, Section You can accomplish this with multi-stage mapping.

The first mapping stage takes the hotplug group name and outputs the kernel-assigned interface name if the interface is to be hot plugged. The second mapping stage takes a kernel-assigned interface name and outputs an adapter name. The third mapping stage maps adapter names to logical interface names based on the network environment.

     # Allow hotplug to bring up interfaces
     mapping hotplug
     	script echo
     # Determine whether interface is wired or Wi-Fi
     mapping eth?
             script /usr/local/sbin/get-mac-address.sh
             map 02:23:45:3C:45:3C wired
             map 00:A3:03:63:26:93 wifi
     # Detect which wired network is available
     mapping wired
             script guessnet-ifupdown
             map work-wired
             map home
     # Detect which Wi-Fi network is available
     mapping wifi
             script ifscout
             map starbucks
             map work-wireless
     iface work-wired inet static

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.29.

If you have problems with certain websites, see Strange access problems with some websites, Section 3.8.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. Basics of netfilter

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

     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 Netfilter table

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

Firewall rules have several targets: 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 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.

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.8.5 and Triggering network configuration, Section 10.8). 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 -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.


     eth0:; gateway
     eth1:; gateway
     No masquerading on this machine.

Special magic:

  • ip rule add from lookup 1

  • ip rule add from lookup 2

  • ip route add to default via metric 0

  • ip route add to default via metric 1

  • ip route add table 1 to via eth0

  • ip route add table 1 to via eth1

  • ip route add table 1 to default via

  • ip route add table 2 to via eth0

  • ip route add table 2 to via eth1

  • ip route add table 2 to default via

  • [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

    CVS, Thu Jan 18 11:52:15 UTC 2007

    Osamu Aoki osamu#at#debian.org
    Authors, Section A.1