source: networking/netprogs/bridgeutils.xml@ d28198d3

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY bridge-download-http "&sourceforge-repo2;/projects/bridge/files/bridge/bridge-utils-&bridgeutils-version;.tar.gz">
  <!ENTITY bridge-download-ftp  " ">
  <!ENTITY bridge-md5sum        "ec7b381160b340648dede58c31bb2238">
  <!ENTITY bridge-size          "36 KB">
  <!ENTITY bridge-buildsize     "1 MB">
  <!ENTITY bridge-time          "less than 0.1 SBU">
]>

<sect1 id="bridgeutils" xreflabel="bridge-utils-&bridgeutils-version;">
  <?dbhtml filename="bridge-utils.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>bridge-utils-&bridgeutils-version;</title>

  <indexterm zone="bridgeutils">
    <primary sortas="a-bridgeutils">bridge-utils</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to bridge-utils</title>

    <para>The <application>bridge-utils</application> package contains a utility
    needed to create and manage bridge devices.  This is useful in setting up
    networks for a hosted virtual machine (VM).</para>

    &lfs70_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>Download (HTTP): <ulink url="&bridge-download-http;"/></para>
      </listitem>
      <listitem>
        <para>Download (FTP): <ulink url="&bridge-download-ftp;"/></para>
      </listitem>
      <listitem>
        <para>Download MD5 sum: &bridge-md5sum;</para>
      </listitem>
      <listitem>
        <para>Download size: &bridge-size;</para>
      </listitem>
      <listitem>
        <para>Estimated disk space required: &bridge-buildsize;</para>
      </listitem>
      <listitem>
        <para>Estimated build time: &bridge-time;</para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">bridge-utils Dependencies</bridgehead>

    <bridgehead renderas="sect4">Optional (to run tests)</bridgehead>
    <para role="optional">
      <xref linkend="net-tools"/> 
    </para>

    <para condition="html" role="usernotes">User Notes:
    <ulink url="&blfs-wiki;/bridge"/></para>

  </sect2>

  <sect2 role="kernel" id='bridgeutils-kernel'>
    <title>Kernel Configuration</title>

    <para>Enable the following options in the kernel configuration
    and recompile the kernel if necessary:</para>

<screen><literal>Networking support: Y
  Networking options: 
    802.1d Ethernet Bridging: M or Y</literal></screen>

    <indexterm zone="bridgeutils bridgeutils-kernel">
      <primary sortas="d-bridgeutils">Bridge Utilities</primary>
    </indexterm>

  </sect2>

  <sect2 role="installation">
    <title>Installation of bridge-utils</title>

    <para>Install <application>bridge-utils</application> by running the following
    commands:</para>

<screen><userinput>autoreconf                &amp;&amp;
./configure --prefix=/usr &amp;&amp;
make</userinput></screen>

    <para>Testing the results requires running the six shell scripts in
    the <filename class='directory'>tools/</filename> directory.  
    Two of the tests require two ehternet ports.  Some tests
    will not preserve the current network configuration.  See
    <filename>tests/README</filename> for details.</para>

    <para>Now, as the <systemitem class="username">root</systemitem> user:</para>

<screen role="root"><userinput>make install</userinput></screen>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring bridge-utils</title>

    <sect3 id='bridgeutils-init'>
      <title>Configuration Information</title>

      <para>To automate bridge creation and configuration, 
      install the <filename>/lib/services/etc/bridge</filename>
      service script included in the <xref linkend="bootscripts"/>
      package.</para>

      <indexterm zone="bridgeutils bridgeutils-init">
        <primary sortas="f-bridgeutils">bridge-utils</primary>
      </indexterm>

<screen role="root"><userinput>make install-bridge</userinput></screen>

      <note><para>The <filename>bridge</filename> script depends
      on the comamnds <command>/sbin/ifup</command> and 
      <command>/sbin/ifdown</command> and the service script
      <emphasis>ipv4-static</emphasis> from the <emphasis>LFS</emphasis>
      bootscripts dated January 27, 2012 or later.</para></note>

      <para>The following configuration file will create a bridge device
      at boot time and attach the eth0 device to it.  If more than one
      device is desired, use a space separated list of INTERFACES.  This
      configuration is useful when planning to run a virtual machine
      such as kvm/qemu.</para>

      <para>Other SERVICE combinations are possible, for example, 
      SERVICES="bridge dhcp".  In that case, the address parameters
      are not needed, but do not interfere if present. The 
      bridge service may also be used alone, but will require
      additional subsequent configuration.</para>

      <caution><para>Do not run a parallel configuration for a device
      in the INTERFACES list.  For instance, in the example below,
      do not configure <filename>/etc/sysconfig/ifconfig.eth0</filename>
      to run at boot time.  The command <command>ifdown br0</command>
      followed by  command <command>ifup eth0</command> will work, but
      don't try to have both up at the same time.</para></caution>
      
<screen role="root"><userinput>cat &gt; /etc/sysconfig/ifconfig.br0 &lt;&lt; "EOF"
<literal>ONBOOT=yes
IFACE=br0
SERVICE="bridge ipv4-static"  # Space separated
IP=192.168.1.32
GATEWAY=192.168.1.1
PREFIX=24
BROADCAST=192.168.1.255
CHECK_LINK=no                 # Don't check before bridge is created
STP=no                        # Spanning tree protocol, default no
INTERFACES="eth0"             # Add to IFACE, space separated devices 
IP_FORWARD=true</literal>
EOF</userinput></screen>

      <para>All addresses should be changed to meet your circumstance.</para>

    </sect3>

  </sect2>


  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Program</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>brctl</seg>
        <seg>None</seg>
        <seg>None</seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="brctl">
        <term><command>brctl</command></term>
        <listitem>
          <para>is a program  used to set up, maintain, and inspect the
          ethernet bridge configuration in the linux kernel.  </para>
          <indexterm zone="bridgeutils brctl">
            <primary sortas="b-brctl">brctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>