release/src/router/bridge/doc/brctl.8

   1 .\"
   2 .\"     This program is free software; you can redistribute it and/or modify
   3 .\"     it under the terms of the GNU General Public License as published by
   4 .\"     the Free Software Foundation; either version 2 of the License, or
   5 .\"     (at your option) any later version.
   6 .\"
   7 .\"     This program is distributed in the hope that it will be useful,
   8 .\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
   9 .\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  10 .\"     GNU General Public License for more details.
  11 .\"
  12 .\"     You should have received a copy of the GNU General Public License
  13 .\"     along with this program; if not, write to the Free Software
  14 .\"     Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  15 .\"
  16 .\"
  17 .TH BRCTL 8 "November 7, 2001" "" ""
  18 .SH NAME
  19 brctl \- ethernet bridge administration
  20 .SH SYNOPSIS
  21 .BR "brctl [command]"
  22 .SH DESCRIPTION
  23 .B brctl
  24 is used to set up, maintain, and inspect the ethernet bridge
  25 configuration in the linux kernel.
  26
  27 An ethernet bridge is a device commonly used to connect different
  28 networks of ethernets together, so that these ethernets will appear as
  29 one ethernet to the participants.
  30
  31 Each of the ethernets being connected corresponds to one physical
  32 interface in the bridge. These individual ethernets are bundled into
  33 one bigger ('logical') ethernet, this bigger ethernet corresponds to
  34 the bridge network interface.
  35
  36
  37 .SH INSTANCES
  38 The command
  39 .B brctl addbr <name>
  40 creates a new instance of the ethernet bridge. The network interface
  41 corresponding to the bridge will be called <name>.
  42
  43 The command
  44 .B brctl delbr <name>
  45 deletes the instance <name> of the ethernet bridge. The network
  46 interface corresponding to the bridge must be down before it can be
  47 deleted!
  48
  49 The command
  50 .B brctl show
  51 shows all current instances of the ethernet bridge.
  52
  53
  54 .SH PORTS
  55 Each bridge has a number of ports attached to it. Network traffic
  56 coming in on any of these ports will be forwarded to the other ports
  57 transparently, so that the bridge is invisible to the rest of the
  58 network (i.e. it will not show up in
  59 .IR traceroute(8)
  60 ).
  61
  62 The command
  63 .B brctl addif <brname> <ifname>
  64 will make the interface <ifname> a port of the bridge <brname>. This
  65 means that all frames received on <ifname> will be processed as if
  66 destined for the bridge. Also, when sending frames on <brname>,
  67 <ifname> will be considered as a potential output interface.
  68
  69 The command
  70 .B brctl delif <brname> <ifname>
  71 will detach the interface <ifname> from the bridge <brname>.
  72
  73 The command
  74 .B brctl show <brname>
  75 will show some information on the bridge and it's attached ports.
  76
  77
  78 .SH AGEING
  79 The bridge keeps track of ethernet addresses seen on each port. When
  80 it needs to forward a frame, and it happens to know on which port the
  81 destination ethernet address (specified in the frame) is located, it
  82 can 'cheat' by forwarding the frame to that port only, thus saving a
  83 lot of redundant copies and transmits.
  84
  85 However, the ethernet address location data is not static
  86 data. Machines can move to other ports, network cards can be replaced
  87 (which changes the machine's ethernet address), etc.
  88
  89 .B brctl showmacs <brname>
  90 shows a list of learned MAC addresses for this bridge.
  91
  92 .B brctl setageingtime <brname> <time>
  93 sets the ethernet (MAC) address ageing time, in seconds. After <time>
  94 seconds of not having seen a frame coming from a certain address, the
  95 bridge will time out (delete) that address from the Forwarding
  96 DataBase (fdb).
  97
  98 .B brctl setgcint <brname> <time>
  99 sets the garbage collection interval for the bridge <brname> to <time>
 100 seconds. This means that the bridge will check the forwarding database
 101 for timed out entries every <time> seconds.
 102
 103
 104 .SH SPANNING TREE PROTOCOL
 105 Multiple ethernet bridges can work together to create even larger
 106 networks of ethernets using the IEEE 802.1d spanning tree
 107 protocol. This protocol is used for finding the shortest path between
 108 two ethernets, and for eliminating loops from the topology. As this
 109 protocol is a standard, linux bridges will interwork properly with
 110 other third party bridge products. Bridges communicate with eachother
 111 by sending and receiving BPDUs (Bridge Protocol Data Units). These
 112 BPDUs can be recognised by an ethernet destination address of
 113 01:80:c2:00:00:00.
 114
 115 The spanning tree protocol can also be turned off (for those
 116 situations where it just doesn't make sense, for example when this
 117 linux box is the only bridge on the LAN, or when you know that there
 118 are no loops in the topology.)
 119
 120 .IR brctl(8)
 121 can be used for configuring certain spanning tree protocol
 122 parameters. For an explanation of these parameters, see the IEEE
 123 802.1d specification (or send me an email). The default values should
 124 be just fine. If you don't know what these parameters mean, you
 125 probably won't feel the desire to tweak them.
 126
 127 .B brctl stp <bridge> <state>
 128 controls this bridge instance's participation in the spanning tree
 129 protocol. If <state> is "on" or "yes" the STP will be turned on,
 130 otherwise it will be turned off.  When turned off, the bridge will not
 131 send or receive BPDUs, and will thus not participate in the spanning
 132 tree protocol. If your bridge isn't the only bridge on the LAN, or if
 133 there are loops in the LAN's topology, DO NOT turn this option off. If
 134 you turn this option off, please know what you are doing.
 135
 136
 137 .B brctl setbridgeprio <bridge> <priority>
 138 sets the bridge's priority to <priority>. The priority value is an
 139 unsigned 16-bit quantity (a number between 0 and 65535), and has no
 140 dimension. Lower priority values are 'better'. The bridge with the
 141 lowest priority will be elected 'root bridge'.
 142
 143 .B brctl setfd <bridge> <time>
 144 sets the bridge's 'bridge forward delay' to <time> seconds.
 145
 146 .B brctl sethello <bridge> <time>
 147 sets the bridge's 'bridge hello time' to <time> seconds.
 148
 149 .B brctl setmaxage <bridge> <time>
 150 sets the bridge's 'maximum message age' to <time> seconds.
 151
 152 .B brctl setpathcost <bridge> <port> <cost>
 153 sets the port cost of the port <port> to <cost>. This is a
 154 dimensionless metric.
 155
 156 .B brctl setportprio <bridge> <port> <priority>
 157 sets the port <port>'s priority to <priority>. The priority value is
 158 an unsigned 8-bit quantity (a number between 0 and 255), and has no
 159 dimension. This metric is used in the designated port and root port
 160 selection algorithms.
 161
 162
 163 .SH NOTES
 164 .BR brctl(8)
 165 replaces the older brcfg tool.
 166
 167 .SH SEE ALSO
 168 .BR ipchains(8),
 169 .BR iptables(8)
 170
 171 .SH AUTHOR
 172 Lennert Buytenhek <buytenh@gnu.org>