man.rst/interfaces.5.rst

   1 ==========
   2 interfaces
   3 ==========
   4
   5 --------------------------------------------
   6 network interface configuration for ifupdown
   7 --------------------------------------------
   8
   9 :Author: Roopa Prabhu <roopa@cumulusnetworks.com>
  10 :Date:   2014-02-05
  11 :Copyright: Copyright 2014 Cumulus Networks, Inc.  All rights reserved.
  12 :Version: 0.1
  13 :Manual section: 5
  14
  15 DESCRIPTION
  16 ===========
  17     **/etc/network/interfaces** contains network interface configuration
  18     information for the **ifup(8)**, **ifdown(8)** and **ifquery(8)** commands.
  19
  20     This is where you configure how your system is connected to the network.
  21
  22     Lines starting with # are ignored. Note that end-of-line comments are
  23     NOT supported, comments must be on a line of their own.
  24
  25     A line may be extended across multiple lines by making the last character
  26     a backslash.
  27
  28     The file consists of zero or more "iface", "auto",  "allow-"
  29     and "source" stanzas. Here is an example::
  30
  31         auto lo eth0
  32         allow-hotplug eth1
  33
  34         iface lo inet loopback
  35
  36         source /etc/network/interfaces.d/bridges
  37
  38         iface eth0 inet static
  39             address 192.168.1.1/24
  40             up flush-mail
  41
  42         iface eth1 inet dhcp
  43
  44     Lines beginning with the word "auto" are used to identify the physical
  45     interfaces to be brought up when ifup is run with the -a option.
  46     (This option is used by the system boot scripts.) Physical interface names
  47     should follow the word "auto" on the same line.  There can be  multiple
  48     "auto"  stanzas.
  49
  50     Lines beginning with "allow-" are  used  to  identify  interfaces  that
  51     should  be  brought  up automatically by various subsytems. This may be
  52     done using a command such as "ifup --allow=hotplug  eth0  eth1",  which
  53     will  only  bring up eth0 or eth1 if it is listed in an "allow-hotplug"
  54     line. Note that "allow-auto" and "auto" are synonyms.
  55
  56     Lines beginning with "source" are used to include  stanzas  from  other
  57     files, so configuration can be split into many files. The word "source"
  58     is followed by the path of file to be sourced. Shell wildcards  can  be
  59     used. Currently only supports absolute
  60     path names.
  61
  62     iface is normally given a interface name as its first non-option
  63     argument.
  64
  65     The interface name is followed by the name of the address family that the
  66     interface uses. This will be "inet" for TCP/IP networking and inet6 for
  67     ipv6. Following that is the name of the method used to configure the
  68     interface.
  69
  70     ifupdown supports iface stanzas without a family or a method. This enables
  71     using the same stanza for inet and inet6 family addresses. And the method
  72     defaults to "static"
  73
  74     Additional interface options/attributes can be given on subsequent lines
  75     in the iface stanza. These options come from addon modules. see
  76     **ifupdown-addons-interfaces(5)** for these options.
  77
  78     example bridge interface with additional attributes listed in the
  79     **ifupdown-addons-interfaces(5)** man page::
  80
  81         auto br0
  82         iface br0
  83             address 12.0.0.4/24
  84             address 2000:1000:1000:1000:3::5/128
  85             bridge-ports swp1 swp2 swp3
  86             bridge-stp on
  87
  88     ifupdown supports python-mako style templates in the interfaces file.
  89     See examples section for details.
  90
  91     See **/usr/share/doc/python-ifupdown2/examples/** for **interfaces(5)**
  92     file examples and interfaces file generation scripts.
  93
  94 METHODS
  95 =======
  96     Both **inet** and **inet6** address family interfaces can use the following
  97     methods (However they are not required):
  98
  99     The loopback Method
 100            This method may be used to define the loopback interface.
 101
 102     The static Method
 103            This method may be used to define ethernet interfaces with
 104            statically allocated addresses.
 105
 106     The dhcp Method
 107            This method may be used to obtain an address via DHCP.
 108
 109 BUILTIN INTERFACES
 110 ==================
 111     **iface** sections for some interfaces like physical interfaces or vlan
 112     interfaces in dot notation (like eth1.100) are understood by ifupdown.
 113     These interfaces do not need an entry in the interfaces file if
 114     they are dependents of other interfaces and dont need any specific
 115     configurations like addresses etc.
 116
 117 EXAMPLES
 118 ========
 119     Sample /etc/network/interfaces file::
 120
 121         auto lo
 122         iface lo
 123             address 192.168.2.0/24
 124             address 2001:dee:eeee:1::4/128
 125
 126         auto eth0
 127         iface eth0 inet dhcp
 128
 129         auto eth1
 130         iface eth1 inet manual
 131             address 192.168.2.0/24
 132             address 2001:dee:eeee:1::4/128
 133
 134         # source files from a directory /etc/network/interfaces.d
 135         source /etc/network/interfaces.d/*
 136
 137         # Using mako style templates
 138         % for v in [11,12]:
 139             auto vlan${v}
 140             iface vlan${v} inet static
 141                 address 10.20.${v}.3/24
 142         % endfor
 143
 144     For additional syntax and examples see **ifupdown-addons-interfaces(5)**
 145
 146 FILES
 147 =====
 148     /etc/network/interfaces
 149
 150 SEE ALSO
 151 ========
 152     ifupdown-addons-interfaces(5),
 153     ifup(8),
 154     ifquery(8),
 155     ifreload(8)