Merge pull request #80 from BarbarossaTM/tunnel-fixes-master

[mirror_ifupdown2.git] / man / interfaces.5

.\" Man page generated from reStructeredText.
.
.TH INTERFACES 5 "2014-02-05" "0.1" ""
.SH NAME
interfaces \- network interface configuration for ifupdown
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.SH DESCRIPTION
.INDENT 0.0
.INDENT 3.5
\fB/etc/network/interfaces\fP contains network interface configuration
information for the \fBifup(8)\fP, \fBifdown(8)\fP and \fBifquery(8)\fP commands.
.sp
This is where you configure how your system is connected to the network.
.sp
Lines starting with # are ignored. Note that end\-of\-line comments are
NOT supported, comments must be on a line of their own.
.sp
A line may be extended across multiple lines by making the last character
a backslash.
.sp
The file consists of zero or more "iface", "auto",  "allow\-"
and "source" stanzas. Here is an example:
.sp
.nf
.ft C
auto lo eth0
allow\-hotplug eth1

iface lo inet loopback

source /etc/network/interfaces.d/bridges

iface eth0 inet static
    address 192.168.1.1/24
    up flush\-mail

iface eth1 inet dhcp
.ft P
.fi
.sp
Lines beginning with the word "auto" are used to identify the physical
interfaces to be brought up when ifup is run with the \-a option.
(This option is used by the system boot scripts.) Physical interface names
should follow the word "auto" on the same line.  There can be  multiple
"auto"  stanzas.
.sp
Lines beginning with "allow\-" are  used  to  identify  interfaces  that
should  be  brought  up automatically by various subsystems. This may be
done using a command such as "ifup \-\-allow=hotplug  eth0  eth1",  which
will  only  bring up eth0 or eth1 if it is listed in an "allow\-hotplug"
line. Note that "allow\-auto" and "auto" are synonyms.
.sp
Lines beginning with "source" are used to include  stanzas  from  other
files, so configuration can be split into many files. The word "source"
is followed by the path of file to be sourced. Shell wildcards  can  be
used. Currently only supports absolute
path names.
.sp
iface is normally given a interface name as its first non\-option
argument.
.sp
The interface name is followed by the name of the address family that the
interface uses. This will be "inet" for TCP/IP networking and inet6 for
ipv6. Following that is the name of the method used to configure the
interface.
.sp
ifupdown supports iface stanzas without a family or a method. This enables
using the same stanza for inet and inet6 family addresses. And the method
defaults to "static"
.sp
Additional interface options/attributes can be given on subsequent lines
in the iface stanza. These options come from addon modules. see
\fBifupdown\-addons\-interfaces(5)\fP for these options.
.sp
example bridge interface with additional attributes listed in the
\fBifupdown\-addons\-interfaces(5)\fP man page:
.sp
.nf
.ft C
auto br0
iface br0
    address 12.0.0.4/24
    address 2000:1000:1000:1000:3::5/128
    bridge\-ports swp1 swp2 swp3
    bridge\-stp on
.ft P
.fi
.sp
ifupdown supports python\-mako style templates in the interfaces file.
See examples section for details.
.sp
See \fB/usr/share/doc/python\-ifupdown2/examples/\fP for \fBinterfaces(5)\fP
file examples and interfaces file generation scripts.
.UNINDENT
.UNINDENT
.SH METHODS
.INDENT 0.0
.INDENT 3.5
Both \fBinet\fP and \fBinet6\fP address family interfaces can use the following
methods (However they are not required):
.INDENT 0.0
.TP
.B The loopback Method
This method may be used to define the loopback interface.
.TP
.B The static Method
This method may be used to define ethernet interfaces with
statically allocated addresses.
.TP
.B The dhcp Method
This method may be used to obtain an address via DHCP.
.UNINDENT
.UNINDENT
.UNINDENT
.SH BUILTIN INTERFACES
.INDENT 0.0
.INDENT 3.5
\fBiface\fP sections for some interfaces like physical interfaces or vlan
interfaces in dot notation (like eth1.100) are understood by ifupdown.
These interfaces do not need an entry in the interfaces file if
they are dependents of other interfaces and dont need any specific
configurations like addresses etc.
.UNINDENT
.UNINDENT
.SH EXAMPLES
.INDENT 0.0
.INDENT 3.5
Sample /etc/network/interfaces file:
.sp
.nf
.ft C
auto lo
iface lo
    address 192.168.2.0/24
    address 2001:dee:eeee:1::4/128

auto eth0
iface eth0 inet dhcp

auto eth1
iface eth1 inet manual
    address 192.168.2.0/24
    address 2001:dee:eeee:1::4/128

# source files from a directory /etc/network/interfaces.d
source /etc/network/interfaces.d/*

# Using mako style templates
% for v in [11,12]:
    auto vlan${v}
    iface vlan${v} inet static
        address 10.20.${v}.3/24
% endfor
.ft P
.fi
.sp
For additional syntax and examples see \fBifupdown\-addons\-interfaces(5)\fP
.UNINDENT
.UNINDENT
.SH FILES
.INDENT 0.0
.INDENT 3.5
/etc/network/interfaces
.UNINDENT
.UNINDENT
.SH SEE ALSO
.INDENT 0.0
.INDENT 3.5
ifupdown\-addons\-interfaces(5),
ifup(8),
ifquery(8),
ifreload(8)
.UNINDENT
.UNINDENT
.SH AUTHOR
Roopa Prabhu <roopa@cumulusnetworks.com>
.SH COPYRIGHT
Copyright 2014 Cumulus Networks, Inc.  All rights reserved.
.\" Generated by docutils manpage writer.
.\" 
.