source: networking/netprogs/bridgeutils.xml@ 95d46499

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

    &lfs76_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">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/bridge-utils-&bridgeutils-version;-linux_3.8_fix-1.patch"/>
        </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 ---&gt;            [CONFIG_NET]
      Networking options ---&gt;
        &lt;*/M&gt; 802.1d Ethernet Bridging [CONFIG_BRIDGE]</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>patch -Np1 -i ../bridge-utils-&bridgeutils-version;-linux_3.8_fix-1.patch &amp;&amp;
autoconf -o configure configure.in                      &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 ethernet 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-service-bridge</userinput></screen>

      <note><para>The <filename>bridge</filename> script depends
      on the commands <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 INTERFACE_COMPONENTS.  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
      INTERFACE_COMPONENTS 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
INTERFACE_COMPONENTS="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>