.\" -*- nroff -*-
.\" macros
.de EX \" Begin Example
.  IP
.  ft CW
.  nf
.  ne \\$1
..
.de EE \" End Example
.  ft P
.  fi
.  PP
..
.TH BRIDGE-UTILS-INTERFACES 5 "January 13 2008" "bridge-utils" "File formats"
.SH NAME
bridge-utils-interfaces \- bridge-utils extensions for the
.BR interfaces (5)
file format
.SH DESCRIPTION
/etc/network/interfaces contains network interface configuration
information for the
.BR ifup (8)
and
.BR ifdown (8)
commands.
This manpage describes the bridge extensions to the standard
.BR interfaces (5)
file format.
.P
The main extension is the bridge_ports option, with it you describe that the
interface is a bridge and what ports does it have. These ports are the
interfaces that are part of the bridge, and they shouldn't have any stanzas
defining them on the interfaces file. Other extensions allow you to tune the
bridge options or change a bridge behaviour.
.P
We'll see this with an example:
.EX
auto br0
iface br0 inet static
    address 192.168.1.2
    network 192.168.1.0
    netmask 255.255.255.0
    broadcast 192.168.1.255
    gateway 192.168.1.1
    bridge_ports all
.EE
Well, after setting this, an ifup br0, or the next reboot, should let you
have a bridge up and running, after waiting for the ports to get to the
forwarding status, of course. This bridge will be using all your ethX
interfaces, as we have stated on the bridge_ports line.
.P
The Debian bridge setup scripts will wait for it to get ready to
work. They do this by trying to guess the maximum time that the bridge
will need to get to the forwarding status, and by default, they will wait
for the bridge to get there, or for the estimated maximum time to go by.
This is done so that the services that are loaded after the bridge setup
have a working network interface and don't fail because the bridge is
still not working. See bridge_maxwait if you want to change this
behaviour.
.P
An example of how to setup a so called anonymous bridge (a bridge without
an assigned IP) would look like this:
.EX
iface br1 inet manual
	bridge_ports eth1 eth2
	bridge_maxwait 0
.EE
Here we select the interfaces eth1 and eth2 to be added to the bridge
interface br1, which will be an anonymous bridge, we also tell the
scripts not to wait, as we won't be having any service running on that
interface (it doesn't even have an IP).
.P
An example of a little more complex bridge setup could be:
.EX
auto br0
iface br0 inet static
    address 192.168.1.2
    network 192.168.1.0
    netmask 255.255.255.0
    broadcast 192.168.1.255
    bridge_ports all weird0
    bridge_bridgeprio 32767
    bridge_portprio eth0 129
    bridge_fd 5
    pre-up ip addr flush dev eth0
.EE
In this example we select all the eth* devices plus a weird device to be
added to the bridge, also we change the bridge default priority to a
higher one so that this bridge becomes the root (if there are no bridges
with higher priority on the net, that is) and also we lower priority of
port eth0 so that it is not used if there are other ports with higher
priority to reach the same destination, at the end we lower the default
forward delay and we add a pre-up command to remove all addresses on
eth0 as this interface had an address set up before (needed only on
weird/broken setups).
.P
If there is a need to set up any of the interfaces participating on the
bridge and not the bridge itself, then we must add the commands to set up
those settings in a "pre-up" or "up" statement. This means that if we
have a wireless card that we want to add to a bridge and we want to set
it to master, and select the essid, instead of using the typical
wireless_* commands we could add to the bridge definition something like
this:
.EX
pre-up iwconfig wlan0 mode master essid myESSID
.EE
Be aware, however, that using wireless cards as part of a bridge is not a
good idea if the card belonging to the bridge is in managed mode. 
Trying to bridge packets coming out of our LAN through a wireless card
that is set in managed mode (the card is a client of an AP) is bound to
give problems, as the AP will probably refuse packets with source MAC
addresses which are not associated (this will be the case of other
machines going through the wireless card of the bridge into the AP).
.P
Multiple stanzas of a bridge definition are currently not supported, so
if you want to add a ipv6 and a ipv4 to a bridge do it all in one
definition by using the "up" option. If however you still want to use
multiple stanzas or would like to read more on this bug you can see it
at http://bugs.debian.org/319832
.SH IFACE OPTIONS
A little explanation on the new options that can be used on
/etc/network/interfaces to setup the bridge, so you don't have to go and
look at the scripts...
.TP
.BI bridge_ports " interface specification"
this option must exist for the scripts to setup the bridge, with
it you specify the ports you want to add to your bridge, either
using "none" if you want a bridge without any interfaces or you
want to add them later using brctl, or a list of the interfaces
you want to add separated by spaces, for example:
.RS
.EX
bridge_ports eth0 eth4
.EE
You should not put any lines to configure the interfaces that
will be used by the bridge, as this will be setup automatically
by the scripts when bringing the bridge up.
.P
If you need to specify the interfaces more flexibly, you can
use the following syntax (most useful on a Xen dom0):
.EX
bridge_ports regex (eth|vif).*
.EE
This means to evaluate (as in
.BR egrep (1))
the expressions that
follow after "regex" until either the end or a "noregex" statement
is reached.  The regular expressions are evaluated against all
local interfaces and those that match are added.
.P
Specifying "all" is short for "regex eth.* em.* p[0-9].* noregex" and will
get all the ethX and biosdevname-format (emX and pX) interfaces added to the
bridge.
.P
Carrying this to the extremes, the following is valid syntax:
.EX
bridge_ports all regex if.0 noregex ext0 regex vif.*
.EE
This will add all ethX interfaces, the ifX0 interfaces, the ext0
interface and all vifX interfaces.
.SS
.TP
.BI bridge_ageing " time"
set ageing time, default is 300, can have a fractional part.
.TP
.BI bridge_bridgeprio " priority"
set bridge priority, \fIpriority\fP is between 0 and 65535, default is
32768, affects bridge id, lowest priority bridge will be the root.
.TP
.BI bridge_fd " time"
set bridge forward delay to \fItime\fP seconds, default is 15, can
have a fractional part.
.TP                                
.BI bridge_gcint " time"
set garbage collection interval to \fItime\fP seconds, default is 4,
can have a fractional part.
.TP                    
.BI bridge_hello " time"
set hello time to \fItime\fP seconds, default is 2, can have a
fractional part.
.TP                    
.BI bridge_hw " MAC_address|interface"
set the Ethernet MAC address of the bridge to the specified one or to
the address of the specified interface.
There were some concerns of how this was done in the past but we are
doing it on a new way now, it is currently not only considered safe but
also necessary or recommended in a lot of scenarios like IPv6, DHCP
reservations, ... the ussage of bridge_hw setting if the recommended
way of doing this.
.TP                    
.BI bridge_maxage " time"
set max message age to \fItime\fP seconds, default is 20, can have a
fractional part.
.TP                    
.BI bridge_maxwait " time"
forces to \fItime\fP seconds the maximum time that the Debian bridge
setup scripts will wait for the bridge ports to get to the
forwarding status, doesn't allow factional part. If it is equal
to 0 then no waiting is done.
.TP                    
.BI bridge_pathcost " port cost"
set path cost for a port, from 1 to 65535, default is 100, \fIport\fP is the
name of the interface to which this setting applies.
.TP                    
.BI bridge_portprio " port priority"
set port priority, from 0 (max) to 63 (min), default is 32, affects port id,
\fIport\fP is the name of the interface to which this setting applies.
.TP                    
.BI bridge_stp " state"
turn spanning tree protocol on/off, \fIstate\fP values are on or yes
to turn stp on and any other thing to set it off, default has
changed to off for security reasons in latest kernels, so you
should specify if you want stp on or off with this option, and not
rely on your kernel's default behaviour.
.TP                    
.BI bridge_token " token"
set IPv6 tokenized interface identifier for the bridge to token, see
.BR ip-token (8)
for more info on this.
.TP                    
.BI bridge_vlan_aware " yes/no"
specify if the bridge is vlan aware an thus needs vlan filtering
to be activated or not.
.TP                    
.BI bridge_waitport " time [ports]"
wait for a max of \fItime\fP seconds for the specified \fIports\fP to
become available, if no ports are specified then those specified on
bridge_ports will be used here. Specifying no ports here should not be used
if we are using regex or "all" on bridge_ports, as it wouldn't work.
.RE
.SH FILES
.TP
.I /etc/network/interfaces
definitions of network interfaces
See
.BR interfaces (5)
for more information.
.TP
.RE
.SH KNOWN BUGS/LIMITATIONS
The default values shown here are current values as of this writing, but
as they are not related to this package but to the bridge code itself, can
change anytime.
.SH AUTHOR
This manpage was written by Santiago Garcia Mantinan <manty@debian.org> based
on \fIinterfaces\fP(5).
.SH "SEE ALSO"
.BR brctl (8),
.BR interfaces (5),
.BR ifup (8),
.BR ip-token (8),
.BR iwconfig (8),
.BR run\-parts (8).