source: networking/netprogs/bridgeutils.xml@ 20a35ab

<?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 "&kernel-dl;/linux/utils/net/bridge-utils/bridge-utils-&bridgeutils-version;.tar.xz">
  <!ENTITY bridge-download-ftp  " ">
  <!ENTITY bridge-md5sum        "3e1fee4dc22cac5457c2f6ffb990a518">
  <!ENTITY bridge-size          "29 KB">
  <!ENTITY bridge-buildsize     "1.1 MB">
  <!ENTITY bridge-time          "less than 0.1 SBU">
]>

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

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

    &lfs110a_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 ---&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>autoconf                  &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" revision="sysv">
    <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
VIRTINT=yes
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>
<!-- There is a whole page about bridging for systemd in the "Connecting to
     a network" chapter
  <sect2 role="configuration" revision="systemd">
    <title>Configuring bridge-utils</title>

    <sect3 id='bridgeutils-init-systemd'>
      <title>Configuration Information</title>
      <para>
        TBA
      </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>