--- ../../../2008/055/final.materials/bridging-spec.txt Fri Feb 20 14:28:02 2009 +++ bridging-spec.txt Fri Jun 12 09:14:53 2009 @@ -84,7 +84,7 @@ Options are: - -R + -R , --root-dir= Specify an alternate root directory. This allows the configuration of bridge instances in @@ -95,7 +95,7 @@ exist only in deferred commands in that alternate root. - -p + -p , --priority= Specify the Bridge Priority. This sets the STP priority value for determining the @@ -112,7 +112,7 @@ round downward to the next lower value divisible by 4096. - -m + -m , --max-age= Specify the maximum age for configuration information. This sets the STP Bridge Max Age parameter. @@ -122,7 +122,7 @@ from 6 to 40 seconds. (See the "-d " parameter for additional constraints.) - -h + -h , --hello-time= Specify the Bridge Hello Time. This sets the STP Bridge Hello Time parameter. If @@ -132,7 +132,7 @@ seconds. (See the "-d parameter for additional constraints.) - -d + -d , --forward-delay= Specify the Bridge Forward Delay. This sets the STP Bridge Forward Delay parameter. @@ -149,9 +149,10 @@ Any parameter setting that would violate those constraints will be treated as an error and cause the - command to fail with a diagnostic message. + command to fail with a diagnostic message. The + message provides hints suggesting suitable values. - -f + -f , --force-protocol= Specify the forced maximum supported protocol. This sets the MSTP maximum supported protocol number, @@ -162,7 +163,8 @@ when implemented, the parameter may be set to 0 (STP only) or 2 (allow STP or RSTP). - -l Add a link to the newly-created bridge. + -l , --link= + Add a link to the newly-created bridge. This is equivalent to creating the bridge and then adding one or more links, as with the "add-bridge" @@ -175,11 +177,14 @@ See the "add-bridge" subcommand for details on link assignment. Bridge creation and link assignment require PRIV_SYS_DL_CONFIG. + Bridge creation may fail if the optional bridging feature is not + installed on the system. If this happens, a suitably + descriptive error message will be presented to the user. (The TRILL enhancement, described separately, will add a "-P - " option to this interface and to the modify-bridge - interface described below. The default will be "stp", and users - may select "trill" if desired.) + " [--protect=] option to this interface and to the + modify-bridge interface described below. The default will be + "stp", and users may select "trill" if desired.) dladm modify-bridge [-R ] [-p ] [-m ] [-h ] [-d ] [-f ] @@ -205,8 +210,8 @@ Bridge deletion requires PRIV_SYS_DL_CONFIG. - The "-R" option is the same as for the "create-bridge" - subcommand. + The "-R" option (--root-dir) is the same as for the + "create-bridge" subcommand. dladm add-bridge [-R ] -l [-l ]... @@ -243,6 +248,8 @@ In this case, we will log an error and the bridge instance will go into maintenance state. The user may then remove or change the assigned links so that the MTU matches and then restart. + (The simplest way to change MTU is to disable the bridge with + svcadm, change the link MTUs as desired, and then reenable.) In this initial version, the links must also be Ethernet type, which includes 802.3 and 802.11 media. Bridging is well-defined @@ -286,10 +293,14 @@ one bridge. If no bridge name is given, then it shows summary status of all bridges on the system. - The '-o' option allows the user to specify a comma-separated - case-insensitive list of fields to display. The field name may - "all" to display all fields, or any combination of: + The '-p' (--parseable) option produces machine-parseable + (colon-delimited) data, as for all dladm commands. + The '-o' (--output=) option allows the user to specify a + comma-separated case-insensitive list of fields to display. The + field name may "all" to display all fields, or any combination + of: + BRIDGE Assigned name of the bridge (same as , if provided) ADDRESS Bridge Unique Identifier value (MAC) @@ -333,13 +344,14 @@ This variant of the show-bridge subcommand displays link-related status information for a single bridge instance. Note that - configured parameters are shown through show-linkprop. The - relevant field names for the "show-bridge -l" subcommand are: + configured parameters are shown through show-linkprop. The long + option form is "--link". The relevant field names for the + "show-bridge -l" subcommand are: LINK Link name INDEX Port (link) index number on the bridge - STATE "disabled", "listening", "learning", - "forwarding", or "blocking" + STATE "disabled", "discarding", "learning", + "forwarding", "non-stp", "bad-mtu" UPTIME Number of seconds since last reset or initialize OPERCOST Actual cost in use (1-65535) OPERP2P P2P mode flag ("yes" or "no") @@ -367,11 +379,18 @@ This variant shows statistics for the bridge given, or, if no bridge name is supplied, then for all bridges in the system. + The long option form is "--statistics". + + The '-i' (--interval=) option may be specified to watch bridge + statistics over a time interval, as with other existing dladm + subcommands. + The relevant field names are: BRIDGE Bridge name DROPS Number of packets dropped due to resource problems FORWARDS Number of packets forwarded to another link + MBCAST Number of multicast/broadcast packets RECV Number of packets received on all links SENT Number of packets sent on all links UNKNOWN Number of packets with unknown destination; @@ -415,7 +434,8 @@ This variant shows kernel forwarding entries for the bridge - named. The relevant field names are: + named. The long option form is "--forwarding". The relevant + field names are: DEST Destination address (MAC) AGE Age of entry in seconds and milliseconds @@ -515,6 +535,31 @@ Otherwise, the port mode is forced to point-to-point mode (for "true") or normal multipoint mode (for "false"). + "stp_mcheck" + + This is a boolean property. It defaults to 0 (false). If set + to 1 (true), the daemon will invoke the RSTP "Force BPDU + Migration Check" procedure and then reset the property back to + 0. The user can set this to 1 only if the force-protocol + value is 2 (RSTP) or higher. This somewhat unusual property + is documented in IEEE 802.1D-2004 section 17.19.13. Outside + of testing procedures, it is rarely (if ever) used. + + "learn_limit" + + This is an integer value, defaulting to 1000; legal values are + 0 or larger. When the number of new or changed sources seen + recently on a given link exceeds this value, learning via that + link is temporarily disabled. Only non-VLAN, non-VNIC type + links have this property. + + "learn_decay" + + This is an integer value, defaulting to 200; legal values are + greater than 0. This sets the rate at which the counter used + for the learn_limit decays. Only non-VLAN, non-VNIC type + links have this property. + 1.3 New Kstats Each bridge instance will have a set of statistics, named @@ -530,8 +575,12 @@ Name of statistic; at least the following: + recv Total bridge packet receives + sent Total bridge packet transmits + drops Total bridge packet drops learn_source Number of sources learned learn_expire Number of learnt entries expired + learn_moved Number of entries moved between links learn_size Current count of learnt entries forward_direct Directly forwarded packet count forward_unknown Forwarded with unknown destination @@ -544,6 +593,7 @@ xmit Packets forwarded to the link by bridging rcvd Packets received from the link (and forwarded elsewhere) by bridging + drops Packets dropped on link All of these statistics are considered Volatile for now. The existence of the statistics will be documented for users, but with @@ -558,11 +608,11 @@ name of the bridge of which it's a member. This field is shown by default, right before the larger "OVER" field. For links that are not part of a bridge, the field is displayed as a blank string (if - parseable output is selected) or as "--" if non-parseable. + parsable output is selected) or as "--" if non-parsable. The addition of the "BRIDGE" field in the default output format may require Minor release binding. The utility is intended to be - used in parseable mode when run in cases where the output format + used in parsable mode when run in cases where the output format matters, and in these cases the changes proposed here are compatible, but we should still err on the side of caution. @@ -585,18 +635,17 @@ 2.1 Packet Observability - Each bridge instance will be assigned an "observability device," - in a manner similar to the DLPI nodes created for "Clearview: IP - Observability Devices" (PSARC 2006/475). These nodes will appear - under the /dev/bridge/ directory, named by the bridge name plus a + Each bridge instance will be assigned a DLPI device intended for + observability purposes, using the /dev/net/ facility implemented + for "Clearview Nemo unification and vanity naming" (PSARC + 2006/499). These nodes will be named by the bridge name plus a trailing "0". - The observability node is intended for use with snoop and - wireshark. It behaves as a standard Ethernet interface, but does - not permit the transmission of packets. All transmitted packets - are silently dropped. It's not possible to plumb IP on top; - attempts to do DL_BIND_REQ without using the passive option will - fail. + This special node is intended for use with snoop and wireshark. + It behaves as a standard Ethernet interface, but does not permit + the transmission of packets. All transmitted packets are silently + dropped. It's not possible to plumb IP on top; attempts to do + DL_BIND_REQ without using the passive option will fail. The user of this node will get a single unmodified copy of every packet handled by the bridge, similar to a "monitoring" port on a @@ -624,7 +673,7 @@ 2.2 DLPI Behavior When a bridge is enabled on a datalink, the link behaves slightly - differently in order to accomodate bridging behavior. + differently in order to accommodate bridging behavior. a. Link up/down (DL_NOTE_LINK_{UP,DOWN}) are delivered in the aggregate. This means that when all external links are showing @@ -692,7 +741,7 @@ and (per section 2 above) an observability node named: - /dev/bridge/mybridge0 + /dev/net/mybridge0 By default, all ports run standard STP. This is done for safety reasons: a bridge that does not run some form of bridging protocol @@ -714,7 +763,7 @@ indicates a serious network misconfiguration. The link will be reenabled when link status goes down and then up again, or when the administrator manually reenables by removing the link and - readding it. (This implementation does not include Cisco's + re-adding it. (This implementation does not include Cisco's "portfast" feature.) If the SMF service instance for a bridge is disabled, then bridge @@ -856,13 +905,22 @@ protocol. In this project, the parameter will have no effect, as only STP is implemented. - An additional undocumented parameter is used to control debugging - features in the daemon and the RSTP library: + An additional pair of undocumented parameters are present: Property Name Type Default -------------- ---- ------- config/debug boolean false + config/table-maximum uint64_t 10000 + The "debug" parameter is used to control debugging features in the + daemon and the RSTP library. The "table-maximum" parameter sets a + maximum forwarding table size in the kernel. Forwarding table + entries consume 56 octets of RAM each, so 10000 of them should be + around 1/2MB of kernel memory at most. Note that with bridging + (unlike network layer forwarding), table overflow is harmless to + the client nodes; forwarding always works correctly even if table + entries are discarded, and the entries are just optimizations. + 5.2 Datalink Configuration Current storage for datalink configuration information is in @@ -1012,8 +1070,9 @@ In terms of functionality, bridging must impose on the hardware features reported back to clients (such as IP) so that features - that are not equivalent among all the links are not used, and it - must set all of the active links into promiscuous mode. + that are not equivalent among all the links are not used, must + disable Crossbow polling mode, and it must set all of the active + links into promiscuous mode. Additional details are available in the project design documents. @@ -1083,7 +1142,21 @@ the daemon to refresh (using the existing SMF "refresh" mechanism). +6.10 Dynamic Reconfiguration + DR will be supported by creating a new SUNW_bridge_rcm plug-in + module so that it removes a link from its assigned bridge (if any) + when the link is removed from the system, and updates links with + cached bridge information during a replacement. + +6.11 InfiniBand + + The MAC layer under IPoIB is not Ethernet, and thus cannot be + bridged by this project. If a future project introduces EoIB + (Ethernet over InfiniBand) to Solaris, then that will be able to + work with bridging. + + 7. Implementation Alternatives 7.1 Using A Separate Command @@ -1215,7 +1288,6 @@ link properties Committed dladm set-linkprop show-link BRIDGE Committed new field kstats Volatile Should be raised later - /dev/bridge/ Committed Observability node control ioctls Project Private /usr/lib/bridged Project Private Daemon executable svc:/network/bridge Committed SMF URI @@ -1226,3 +1298,6 @@ librstp.so.1 Project Private RSTP implementation mac, dls, dld Consolidation Private Kernel APIs ::dladm show-bridge Volatile mdb dcmd (debugging) + SUNWbridge[ru] Uncommitted package names + SUNWCbridge Uncommitted package cluster name + SUNW_bridge_rcm.so Project Private DR support