BRIDGE-UTILS-INTERFACES(5)					   File formats 					BRIDGE-UTILS-INTERFACES(5)

NAME

       bridge-utils-interfaces - bridge-utils extensions for the interfaces(5) file format

DESCRIPTION

       /etc/network/interfaces	contains  network  interface  configuration  information  for  the  ifup(8)  and ifdown(8) commands.  This manpage
       describes the bridge extensions to the standard interfaces(5) file format.

       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.

       We'll see this with an example:
       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
       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.

       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.

       An example of how to setup a so called anonymous bridge (a bridge without an assigned IP) would look like this:
       iface br1 inet manual
	    bridge_ports eth1 eth2
	    bridge_maxwait 0
       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).

       An example of a little more complex bridge setup could be:
       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
       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 pri-
       ority  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.

       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:
       pre-up iwconfig wlan0 mode master essid myESSID
       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).

       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

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

       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:
	      bridge_ports eth0 eth4
	      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.

	      If you need to specify the interfaces more flexibly, you can use the following syntax (most useful on a Xen dom0):
	      bridge_ports regex (eth|vif).*
	      This means to evaluate (as in 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.

	      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.

	      Carrying this to the extremes, the following is valid syntax:
	      bridge_ports all regex if.0 noregex ext0 regex vif.*
	      This will add all ethX interfaces, the ifX0 interfaces, the ext0 interface and all vifX interfaces.

       bridge_ageing time
	      set ageing time, default is 300, can have a fractional part.

       bridge_bridgeprio priority
	      set bridge priority, priority is between 0 and 65535, default is 32768, affects bridge id, lowest priority bridge will be the root.

       bridge_fd time
	      set bridge forward delay to time seconds, default is 15, can have a fractional part.

       bridge_gcint time
	      set garbage collection interval to time seconds, default is 4, can have a fractional part.

       bridge_hello time
	      set hello time to time seconds, default is 2, can have a fractional part.

       bridge_hw MAC address
	      set the Ethernet MAC address of all the bridge interfaces to the specified one so that the  bridge  ends	up  having  this  hardware
	      address  as  well. WARNING: use this only if you know what you are doing, changing the MAC address of the cards may cause trouble if
	      you don't know what you are doing. To see the discussion about this feature and the problems that can cause you can try  to  have  a
	      look at the bug that asked for this feature visiting http://bugs.debian.org/271406

       bridge_maxage time
	      set max message age to time seconds, default is 20, can have a fractional part.

       bridge_maxwait time
	      forces to time 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.

       bridge_pathcost port cost
	      set path cost for a port, default is 100, port is the name of the interface to which this setting applies.

       bridge_portprio port priority
	      set port priority, default is 128, affects port id, port is the name of the interface to which this setting applies.

       bridge_stp state
	      turn spanning tree protocol on/off, state 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.

       bridge_waitport time [ports]
	      wait for a max of time seconds for the specified ports 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.

FILES

       /etc/network/interfaces
	      definitions of network interfaces See interfaces(5) for more information.

       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.

AUTHOR

       This manpage was written by Santiago Garcia Mantinan <manty@debian.org> based on interfaces(5).

SEE ALSO

       brctl(8), interfaces(5), ifup(8), iwconfig(8), run-parts(8).

bridge-utils							  January 13 2008					BRIDGE-UTILS-INTERFACES(5)