Section 17.1.  User-Space Configuration Tools

17.1. User-Space Configuration Tools Bridging can be configured with brctl, a utility you can download at http://bridge.sourceforge.net/. With brctl, you can create bridge devices, enslave NICs to bridge devices, and configure bridge parameters and bridge port parameters for the STP. brctl uses the ioctl interface to talk to the kernel unless the libsysfs library is installed, in which case the sysfs interface becomes the preferred choice. The libsysfs library, which can be downloaded at http://linux-diag.sourceforge.net/Sysfsutils.html, provides all the necessary primitives to access and modify the content of the variables exported in /sys. See the section "Tuning via /sys Filesystem." In the section "Data Frames Versus BPDUs" in Chapter 16, we introduced ebtables. The user-space configuration tool can be downloaded at http://ebtables.sourceforge.net. We will not look at it in this chapter; you can find pretty good documentation on its home page. 17.1.1. Handling Configuration Changes Table 17-1 lists the brctl commands and the callback routines of the kernel bridging code that the configuration layer calls to notify bridging about the changes. For example, when you create the bridge device br0 with a command like brctl addbr br0, the kernel ends up calling br_add_bridge, the routine we described in the section "Creating Bridge Devices and Bridge Ports" in Chapter 16. Note that some commands do not need to invoke any callback routine. For example, if you change the Hello time with a command such as brctl sethello br0 3, the new value will be visible immediately to the bridging code: there is no need for any action to be taken by the STP. Table 17-1. brctl commands and associated kernel handlers brctl command Description Bridging callback routine addbr Create a bridge device. br_add_bridge delbr Delete a bridge device. br_del_bridge addif Create a bridge port. br_add_if delif Delete a bridge port. br_del_if setageing Set the aging time for the addresses in the forwarding database. N/A setbridgeprio Set the bridge priority. br_stp_set_bridge_priority setfd Set the Forward Delay timer. N/A sethello Set the Hello timer. N/A setmaxage Set the Max Age timer. N/A setpathcost Set the port path cost. br_stp_set_path_cost setportprio Set the port priority. br_stp_set_port_priority show Show the bridge device. N/A showmacs Show the forwarding database for a bridge. N/A showstp Show the spanning tree information for a bridge. N/A stp Enable or disable the STP on a bridge. N/A The routines in Table 17-1 are used regardless of whether brctl talks to the kernel with ioctl commands or via sysfs. Regardless of whether a given command requires the invocation of a bridging callback routine, a kernel routine is always called to take care of the brctl command. 17.1.2. Old Interface Versus New Interface Because the kernel code supports both the old and new interfaces, it must be able to handle both versions correctly. Unfortunately, this makes the ioctl code that takes care of bridging configuration commands a little messy. The old interface is completely based on ioctl commands, whereas the new one uses ioctl only for a subset of commands and sysfs for the others. Figures 17(a) and 17(b) show how ioctl commands for both interfaces are routed to the right routines for processing (I know, it's not really what you call clear and clean code). Figure 17-1a. Dispatching ioctl commands The top diamond is the initial dispatching done in sock_ioctl in net/socket.c. Note that the figure shows only the details needed to route bridging commands, even though some of the routines are shared by other features' commands, too. The commands with a lighter color are the ones used by the new interface. One detail worth mentioning is that br_ioctl_deviceless_stub TRies to load the bridge kernel module if it is not already in memory. The next two sections offer some more details on the two interfaces. Figure 17-1b. Dispatching ioctl commands 17.1.3. Creating Bridge Devices and Bridge Ports I would divide brctl commands into two classes: those used to create and delete bridge devices and bridge ports, and those used to configure or dump the configuration of bridge devices and bridge ports (including details on the STP). Both the old and the new interfaces use ioctl commands to implement the first class of commands. The exact ioctl command codes used by the old and new interfaces are listed in Table 17-2. Table 17-2. ioctl commands used for creating bridge devices and ports brctl command Old interface (ioctl command, argument) New interface (ioctl command) addbr SIOCSIFBR, BRCTL_ADD_BRIDGE SIOCBRADDBR delbr SIOCSIFBR, BRCTL_DEL_BRIDGE SIOCBRDELBR addif SIOCDEVPRIVATE, BRCTL_ADD_IF SIOCBRADDIF delif SIOCDEVPRIVATE, BRCTL_DEL_IF SIOCBRDELIF Note that the old interface needs to pass an argument with the ioctl command to identify the precise brctl command, whereas for the new interface the ioctl command is sufficient. 17.1.4. Configuring Bridge Devices and Ports The second class of commands is implemented differently in the old and new interfaces: the old interface uses ioctl commands, and the new interface uses sysfs. The exact ioctl command codes used by the old interface are listed in Table 17-3. Table 17-3. ioctl commands used by the old interface for configuring bridge devices and ports brctl command ioctl command, argument setageing SIOCDEVPRIVATE, BRCTL_SET_AGEING_TIME setbridgeprio SIOCDEVPRIVATE, BRCTL_SET_BRIDGE_PRIORITY setfd SIOCDEVPRIVATE, BRCTL_SET_FORWARD_DELAY sethello SIOCDEVPRIVATE, BRCTL_SET_HELLO_TIME setmaxage SIOCDEVPRIVATE, BRCTL_SET_MAX_AGE setpathcost SIOCDEVPRIVATE, BRCTL_SET_PATH_COST setportprio SIOCDEVPRIVATE, BRCTL_SET_PORT_PRIORITYa show SIOCDEVPRIVATE, BRCTL_GET_BRIDGE_INFO showmacs SIOCDEVPRIVATE, BRCTL_GET_FDB_ENTRIES showstp SIOCDEVPRIVATE, BRCTL_SET_BRIDGE_INFO stp SIOCDEVPRIVATE, BRCTL_SET_BRIDGE_STP_STATE a Version 1.0.6 of brctl uses BRCTL_SET_PATH_COST rather than BRCTL_SET_PORT_PRIORITY. This is likely to be a cut-and-paste error. Note that all brctl commands use the SIOCDEVPRIVATE command (even though its use is pretty much deprecated in Linux) and an argument that identifies the exact operation. The sysfs-based configuration simply identifies the right file in /sys and writes to it using the libsysfs library. The operations in Table 17-2 cannot be implemented via sysfs because there is no file in its hierarchy for them.