_darcs/current/interfaces.5.pre

   1 .\" -*- nroff -*-
   2 .\" macros
   3 .de EX \" Begin Example
   4 .  IP
   5 .  ft CW
   6 .  nf
   7 .  ne \\$1
   8 ..
   9 .de EE \" End Example
  10 .  ft P
  11 .  fi
  12 .  PP
  13 ..
  14 .TH INTERFACES 5 "5 April 2004" "ifupdown" "File formats"
  15 .SH NAME
  16 /etc/network/interfaces \- network interface configuration for ifup and ifdown
  17 .SH DESCRIPTION
  18 /etc/network/interfaces contains network interface configuration
  19 information for the
  20 .BR ifup (8)
  21 and
  22 .BR ifdown (8)
  23 commands.
  24 This is where you configure how your system is connected to the network.
  25 .P
  26 Lines starting with `#' are ignored. Note that end-of-line comments are
  27 NOT supported, comments must be on a line of their own.
  28 .P
  29 A line may be extended across multiple lines by making the last character
  30 a backslash.
  31 .P
  32 The file consists of zero or more "iface", "mapping", "auto" and "allow-"
  33 stanzas. Here is an example.
  34 .EX
  35 auto lo eth0
  36 allow-hotplug eth1
  37
  38 iface lo inet loopback
  39
  40 mapping eth0
  41         script /usr/local/sbin/map\-scheme
  42         map HOME eth0\-home
  43         map WORK eth0\-work
  44
  45 iface eth0\-home inet static
  46         address 192.168.1.1
  47         netmask 255.255.255.0
  48         up flush\-mail
  49
  50 iface eth0\-work inet dhcp
  51
  52 iface eth1 inet dhcp
  53 .EE
  54 Lines beginning with the word "auto" are used to identify the physical
  55 interfaces to be brought up when
  56 .B ifup
  57 is run with the
  58 .B \-a
  59 option.  (This option is used by the system boot scripts.)
  60 Physical interface names should follow the word "auto" on the same line.
  61 There can be multiple "auto" stanzas.
  62 .B ifup
  63 brings the named interfaces up in the order listed.
  64 .P
  65 Lines beginning with "allow-" are used to identify interfaces that should
  66 be brought up automatically by various subsytems. This may be done using
  67 a command such as "ifup --allow=hotplug eth0 eth1", which will only bring
  68 up eth0 or eth1 if it is listed in an "allow-hotplug" line. Note that
  69 "allow-auto" and "auto" are synonyms.
  70 .P
  71 Stanzas beginning with the word "mapping" are used to determine how a
  72 logical interface name is chosen for a physical interface that is to be
  73 brought up.  The first line of a mapping stanza consists of the word
  74 "mapping" followed by a pattern in shell glob syntax.  Each mapping stanza
  75 must contain a
  76 .BR script
  77 definition.  The named script is run with the physical interface name as
  78 its argument and with the contents of all following "map" lines
  79 (\fBwithout\fR the leading "map") in the
  80 stanza provided to it on its standard input. The script must print a
  81 string on its standard output before exiting. See
  82 .IR /usr/share/doc/ifupdown/examples
  83 for examples of what the script must print.
  84 .P
  85 Mapping a name consists of searching the remaining mapping
  86 patterns and running the script corresponding to the first match;
  87 the script outputs the name to which the original is mapped.
  88 .P
  89 .B ifup
  90 is normally given a physical interface name as its first non\-option argument.
  91 .B ifup
  92 also uses this name as the initial logical name for the interface unless
  93 it is accompanied by a  suffix of the form \fI=LOGICAL\fR, in which case
  94 ifup chooses \fILOGICAL\fR as the initial logical name for the interface.
  95 It then maps this name, possibly more than once according to successive
  96 mapping specifications,  until no further mappings are possible.  If the
  97 resulting name is the name of some defined logical interface then
  98 .B ifup
  99 attempts to bring up the physical interface
 100 as that logical interface.  Otherwise
 101 .B ifup
 102 exits with an error.
 103 .P
 104 Stanzas defining logical interfaces start with a line consisting of the
 105 word "iface" followed by the name of the logical interface.
 106 In simple configurations without mapping stanzas this name should simply
 107 be the name of the physical interface to which it is to be applied.
 108 (The default mapping script is, in effect, the
 109 .B echo
 110 command.)
 111 The interface name is followed by the name of the address family that the
 112 interface uses.  This will be "inet" for TCP/IP networking, but there is
 113 also some support for IPX networking ("ipx"), and IPv6 networking ("inet6").
 114 Following that is the name of the method used to configure the interface.
 115 .P
 116 Additional options can be given on subsequent lines in the stanza.
 117 Which options are available depends on the family and method,
 118 as described below.
 119 Additional options can be made available by other Debian packages.
 120 For example, the wireless\-tools package makes available a number of
 121 options prefixed with "wireless\-" which can be used to configure the
 122 interface using
 123 .BR iwconfig (8) .
 124 (See
 125 .BR wireless (7)
 126 for details.)
 127 .P
 128 Options are usually indented for clarity (as in the example above)
 129 but are not required to be.
 130 .SH IFACE OPTIONS
 131 The following "command" options are available for every family and method.
 132 Each of these options can be given multiple times in a single stanza,
 133 in which case the commands are executed in the order in which they appear
 134 in the stanza.
 135 (You can ensure a command never fails by suffixing "|| true".)
 136 .TP
 137 .BI pre\-up " command"
 138 Run
 139 .I command
 140 before bringing the interface up.
 141 If this command fails then
 142 .B ifup
 143 aborts,
 144 refraining from marking the interface as configured,
 145 prints an error message,
 146 and exits with status 0.
 147 This behavior may change in the future.
 148 .TP
 149 .BI up " command"
 150 .TP
 151 .BI post\-up " command"
 152 Run
 153 .I command
 154 after bringing the interface up.
 155 If this command fails then
 156 .B ifup
 157 aborts,
 158 refraining from marking the interface as configured
 159 (even though it has really been configured),
 160 prints an error message,
 161 and exits with status 0.
 162 This behavior may change in the future.
 163 .TP
 164 .BI down " command"
 165 .TP
 166 .BI pre\-down " command"
 167 Run
 168 .I command
 169 before taking the interface down.
 170 If this command fails then
 171 .B ifdown
 172 aborts,
 173 marks the interface as deconfigured
 174 (even though it has not really been deconfigured),
 175 and exits with status 0.
 176 This behavior may change in the future.
 177 .TP
 178 .BI post\-down " command"
 179 Run
 180 .I command
 181 after taking the interface down.
 182 If this command fails then
 183 .B ifdown
 184 aborts,
 185 marks the interface as deconfigured,
 186 and exits with status 0.
 187 This behavior may change in the future.
 188 .P
 189 There exists for each of the above mentioned options a directory
 190 .IR /etc/network/if\-\fB<option>\fI.d/
 191 the scripts in which are run (with no arguments) using
 192 .BR run\-parts (8)
 193 after the option itself has been processed.
 194 .P
 195 All of these commands have access to the following environment variables.
 196 .TP
 197 .B IFACE
 198 physical name of the interface being processed
 199 .TP
 200 .B LOGICAL
 201 logical name of the interface being processed
 202 .TP
 203 .B ADDRFAM
 204 address family of the interface
 205 .TP
 206 .B METHOD
 207 method of the interface (e.g.,
 208 .IR static )
 209 .TP
 210 .B MODE
 211 .IR start " if run from ifup, " stop " if run from ifdown"
 212 .TP
 213 .B PHASE
 214 as per MODE, but with finer granularity, distinguishing the
 215 \fIpre-up\fR, \fIpost-up\fR, \fIpre-down\fR and \fIpost-down\fR phases.
 216 .TP
 217 .B VERBOSITY
 218 indicates whether \fB--verbose\fR was used; set to 1 if so, 0 if not.
 219 .TP
 220 .B PATH
 221 the command search path:
 222 .I /usr/local/sbin:\%/usr/local/bin:\%/usr/sbin:\%/usr/bin:\%/sbin:\%/bin
 223 .P
 224 Additionally, all options given in an interface definition stanza are
 225 exported to the environment in upper case with "IF_" prepended and with
 226 hyphens converted to underscores and non\-alphanumeric characters discarded.
 227 ##ADDRESSFAM##
 228 .SH KNOWN BUGS/LIMITATIONS
 229 The
 230 .B ifup
 231 and
 232 .B ifdown
 233 programs work with so-called "physical" interface names.
 234 These names are assigned to hardware by the kernel.
 235 Unfortunately it can happen that the kernel assigns different
 236 physical interface names to the same hardware at different
 237 times; for example, what was called "eth0" last time you booted
 238 is now called "eth1" and vice versa.
 239 This creates a problem if you want to configure the interfaces
 240 appropriately.
 241 A way to deal with this problem is to use mapping scripts that
 242 choose logical interface names according to the properties of
 243 the interface hardware.
 244 See the
 245 .B get-mac-address.sh
 246 script in the examples directory for an example of such a mapping
 247 script.  See also Debian bug #101728.
 248 .P
 249 It is not currently possible to divide up
 250 .B /etc/network/interfaces
 251 into multiple files.  A feature that would make this possible is
 252 some sort of inclusion directive.  No such feature exists in the
 253 current ifupdown program.  For more information see Debian
 254 bug #159884.
 255 .SH AUTHOR
 256 The ifupdown suite was written by Anthony Towns <aj@azure.humbug.org.au>.
 257 This manpage was contributed by Joey Hess <joey@kitenet.net>.
 258 .SH "SEE ALSO"
 259 .BR ifup (8),
 260 .BR iwconfig (8),
 261 .BR run\-parts (8).
 262 .P
 263 For advice on configuring this package read the
 264 .B Network Configuration
 265 chapter of the \fIDebian Reference\fR manual,
 266 available at
 267 \fIhttp://www.debian.org/doc/manuals/reference/ch-gateway.en.html\fR
 268 or in the \fBdebian-reference-en\fR package.
 269 .P
 270 Examples of how to set up interfaces can be found in
 271 .BR /usr/share/doc/ifupdown/examples/network-interfaces .