[networking-guide] master: Updates to Team (c774b3f)
stephenw at fedoraproject.org
stephenw at fedoraproject.org
Tue Jan 6 21:37:18 UTC 2015
Repository : http://git.fedorahosted.org/cgit/docs/networking-guide.git
On branch : master
>---------------------------------------------------------------
commit c774b3f26e6477228ed4fd8928bb7713333e2059
Author: Stephen Wadeley <swadeley at redhat.com>
Date: Tue Jan 6 22:36:38 2015 +0100
Updates to Team
improvements after review
>---------------------------------------------------------------
en-US/Configure_Network_Teaming.xml | 136 ++++++++++++++++++++++++++---------
1 files changed, 101 insertions(+), 35 deletions(-)
diff --git a/en-US/Configure_Network_Teaming.xml b/en-US/Configure_Network_Teaming.xml
index c0ae320..b8cb715 100644
--- a/en-US/Configure_Network_Teaming.xml
+++ b/en-US/Configure_Network_Teaming.xml
@@ -15,7 +15,7 @@
Network Teaming, or Team, is designed to implement the concept in a different way by providing a small kernel driver to implement the fast handling of packet flows, and various user-space applications to do everything else in user space. The driver has an <firstterm>Application Programming Interface</firstterm> (<acronym>API</acronym>), referred to as <quote>Team Netlink API</quote>, which implements Netlink communications. User-space applications can use this API to communicate with the driver. A library, referred to as <quote>lib</quote>, has been provided to do user space wrapping of Team Netlink communications and RT Netlink messages. An application daemon, <systemitem class="daemon">teamd</systemitem>, which uses Libteam lib is also provided. One instance of <systemitem class="daemon">teamd</systemitem> can control one instance of the Team driver. The daemon implements the load-balancing and active-backup logic, such as round-robin, by using additional code referre
d to as <quote>runners</quote>. By separating the code in this way, the Network Teaming implementation presents an easily extensible and scalable solution for load-balancing and redundancy requirements. For example, custom runners can be relatively easily written to implement new logic via <systemitem class="daemon">teamd</systemitem>, and even <systemitem class="daemon">teamd</systemitem> is optional, users can write their own application to use <application>libteam</application>.
</para>
<para>
- A tool to control a running instance of <systemitem class="daemon">teamd</systemitem> using D-bus is provided by <application>teamdctl</application>. It provides a D-Bus wrapper around the <systemitem class="daemon">teamd</systemitem> D-Bus API. By default, <systemitem class="daemon">teamd</systemitem> listens and communicates using Unix Domain Sockets but still monitors D-Bus. This is to insure that <systemitem class="daemon">teamd</systemitem> can be used in environments where D-Bus is not present or not yet loaded. For example, when booting over <systemitem class="daemon">teamd</systemitem> links D-Bus would not yet be loaded. The <application>teamdctl</application> tool can be used during run time to read the configuration, the state of link-watchers, check and change the state of ports, add and remove ports, and to change ports between active and backup states.
+ A tool to control a running instance of <systemitem class="daemon">teamd</systemitem> using D-bus is provided by <application>teamdctl</application>. It provides a D-Bus wrapper around the <systemitem class="daemon">teamd</systemitem> D-Bus API. By default, <systemitem class="daemon">teamd</systemitem> listens and communicates using Unix Domain Sockets but still monitors D-Bus. This is to ensure that <systemitem class="daemon">teamd</systemitem> can be used in environments where D-Bus is not present or not yet loaded. For example, when booting over <systemitem class="daemon">teamd</systemitem> links D-Bus would not yet be loaded. The <application>teamdctl</application> tool can be used during run time to read the configuration, the state of link-watchers, check and change the state of ports, add and remove ports, and to change ports between active and backup states.
</para>
<para>
Team Netlink API communicates with user-space applications using Netlink messages. The user-space library <application>libteam</application> does not directly interact with the API, but uses <application>libnl</application> or <application>teamnl</application> to interact with the driver API.
@@ -117,6 +117,12 @@ When controlling teamed port interfaces using the <systemitem class="daemon">Net
</listitem>
</orderedlist>
</para>
+
+<warning>
+ <para>
+ The use of direct cable connections without network switches is not supported for teaming. The failover mechanisms described here will not work as expected without the presence of network switches.
+</para>
+</warning>
</section>
<section id="sec-Understanding_the_Network_Teaming_Daemon_and_the_Runners">
@@ -193,8 +199,43 @@ The Team daemon, <systemitem class="daemon">teamd</systemitem>, uses <applicatio
<para>
To see some examples of the command format, issue the following command:
<screen>~]$ <command>bond2team --examples</command></screen>
- New files will be created in a directory whose name starts with <filename class="directory">/tmp/bond2team.XXXXXX/</filename>, where XXXXXX is a random string. After creating the new configuration files, move the old bonding files to a backup folder and then move the new files to the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory. See the <filename>bond2team(1)</filename> man page for further details.
+ New files will be created in a directory whose name starts with <filename class="directory">/tmp/bond2team.XXXXXX/</filename>, where XXXXXX is a random string. After creating the new configuration files, move the old bonding files to a backup folder and then move the new files to the <filename class="directory">/etc/sysconfig/network-scripts/</filename> directory.
+ </para>
+
+<example id="ex-Convert_a_Bond_to_a_Team">
+ <title>Convert a Bond to a Team</title>
+ <para>
+ To convert a current <literal>bond0</literal> configuration to team <literal>ifcfg</literal>, issue a command as <systemitem class="username">root</systemitem>:
+<screen>~]# <command>/usr/bin/bond2team --master bond0</command></screen>
+Note that this will retain the name <literal>bond0</literal>. To use a new name to save the configuration, use the <option>--rename</option> as follows:
+<screen>~]# <command>/usr/bin/bond2team --master bond0 --rename team0</command></screen>
+add the <option>--json</option> option to output JSON format files instead of <literal>ifcfg</literal> files. See the <filename>teamd.conf(5)</filename> man page for examples of JSON format.
</para>
+</example>
+
+<example id="ex_Convert_a_Bond_to_a_Team_and_Specify_the_File_Path">
+<title>Convert a Bond to a Team and Specify the File Path</title>
+ <para>
+ To convert a current <literal>bond0</literal> configuration to team <literal>ifcfg</literal>, and to manually specify the path to the <literal>ifcfg</literal> file, issue a command as <systemitem class="username">root</systemitem>:
+<screen>~]# <command>/usr/bin/bond2team --master bond0 --configdir <replaceable>/path/to/ifcfg-file</replaceable></command></screen>
+add the <option>--json</option> option to output JSON format files instead of <literal>ifcfg</literal> files.
+ </para>
+</example>
+
+<example id="ex_Create_a_Team_Configuration_Using_Bond2team">
+<title>Create a Team Configuration Using Bond2team</title>
+ <para>
+ It is also possible to create a team configuration by supplying the <application>bond2team</application> tool with a list of bonding parameters. For example:
+ <screen>~]# <command>/usr/bin/bond2team --bonding_opts "mode=1 miimon=500"</command></screen>
+ Ports can also be supplied on the command line as follows:
+<screen>~]# <command>/usr/bin/bond2team --bonding_opts "mode=1 miimon=500 primary=eth1 \</command>
+ <command>primary_reselect-0" --port eth1 --port eth2 --port eth3 --port eth4</command></screen>
+ </para>
+ </example>
+
+<para>
+ See the <filename>bond2team(1)</filename> man page for further details. For an explanation of bonding parameters, see <xref linkend="sec-Using_Channel_Bonding" />
+</para>
</section>
<section id="sec-Selecting_Interfaces_to_Use_as_Port_for_a_Network_Team">
@@ -291,7 +332,7 @@ From the available interfaces, determine which are suitable for adding to your n
</step>
<step>
- <para>Select the connection you wish to edit and click the <guilabel>Options</guilabel> button.</para>
+ <para>Select the connection you want to edit and click the <guilabel>Options</guilabel> button.</para>
</step>
<step>
<para>Select the <guilabel>General</guilabel> tab.</para>
@@ -336,7 +377,7 @@ From the available interfaces, determine which are suitable for adding to your n
<bridgehead
id="bh-Saving_Your_New_or_Modified_Connection_and_Making_Further_Configurations-team">Saving Your New (or Modified) Connection and Making Further Configurations</bridgehead>
- <para>Once you have finished editing your team connection, click the <guibutton>Save</guibutton> button to save your customized configuration. To make <application>NetworkManager</application> apply the changes, power cycle the interface. See <xref
+ <para>Once you have finished editing your team connection, click the <guibutton>Save</guibutton> button to save your customized configuration. If the profile was in use while being edited, power cycle the connection to make <application>NetworkManager</application> apply the changes. If the profile is OFF, set it to ON. See <xref
linkend="sec-Connecting_to_a_Network_Using_a_GUI"/> for information on using your new or altered connection.</para>
<para>You can further configure an existing connection by selecting it in the <guilabel>Network</guilabel> window and clicking <guilabel>Options</guilabel> to return to the <guilabel>Editing</guilabel> dialog.</para>
<para>Then, to configure:</para>
@@ -1092,61 +1133,86 @@ This mechanism of overriding runner selection logic in order to bind traffic to
</section>
</section>
- <section id="sec-Configure_Network_Teaming_Using_nmcli">
+<section id="sec-Configure_Network_Teaming_Using_nmcli">
<title>Configure Network Teaming Using nmcli</title>
+ <para>
+ To view the devices available on the system, issue the following command:
+ <screen>~]$ <command>nmcli connection show</command>
+NAME UUID TYPE DEVICE
+eth1 0e8185a1-f0fd-4802-99fb-bedbb31c689b 802-3-ethernet --
+eth0 dfe1f57b-419d-4d1c-aaf5-245deab82487 802-3-ethernet --</screen>
+ </para>
+<para>
+ To create a new team interface, with name <replaceable>team-ServerA</replaceable>, issue a command as follows:
+ <screen>~]$ <command>nmcli connection add type team ifname <replaceable>team-ServerA</replaceable></command>
+Connection 'team-ServerA' (b954c62f-5fdd-4339-97b0-40efac734c50) successfully added.</screen>
+<application>NetworkManager</application> will set its internal parameter <option>connection.autoconnect</option> to <literal>yes</literal> and as no <systemitem class="protocol">IP</systemitem> address was given <option>ipv4.method</option> will be set to <literal>auto</literal>. <application>NetworkManager</application> will also write a configuration file to <filename>/etc/sysconfig/network-scripts/ifcfg-team-ServerA</filename> where the corresponding ONBOOT will be set to <literal>yes</literal> and BOOTPROTO will be set to <literal>dhcp</literal>.</para>
<para>
- To create a new team interface, with name <interface>team-ServerA</interface>, issue a command as follows:
- <screen>~]$ <command>nmcli connection add type team ifname ServerA</command>
-Connection 'team-ServerA' (981eb129-1707-4a2e-a6ea-413330d96c10) successfully added.</screen>
-As no JSON configuration file was specified the default configuration is used.
+Note that manual changes to the ifcfg file will not be noticed by <application>NetworkManger</application> until the interface is next brought up. See <xref linkend="sec-Network_Configuration_Using_sysconfig_Files" /> for more information on using configuration files.
+</para>
+<para>
+To view the other values assigned, issue a command as follows:
+<screen>~]$ <command>nmcli con show <replaceable>team-ServerA</replaceable></command>
+connection.id: team-ServerA
+connection.uuid: b954c62f-5fdd-4339-97b0-40efac734c50
+connection.interface-name: ServerA
+connection.type: team
+connection.autoconnect: yes
+<lineannotation>…</lineannotation>
+ipv4.method: auto
+<lineannotation>[output truncated]</lineannotation></screen>
+As no JSON configuration file was specified the default values apply. See the <filename>teamd.conf(5)</filename> man page for more information on the team JSON parameters and their default values.
Notice that the name was derived from the interface name by prepending the type.
-Alternatively, specify a name with <option>con-name</option> as follows:
- <screen>~]$ <command>nmcli connection add type team con-name Team0 ifname ServerB</command>
-Connection 'Team0' (fcafb3f0-4c95-48df-9e28-7ac7213f38ba) successfully added.</screen>
+Alternatively, specify a name with the <option>con-name</option> option as follows:
+ <screen>~]$ <command>nmcli connection add type team con-name <replaceable>Team0</replaceable> ifname <replaceable>ServerB</replaceable></command>
+Connection 'Team0' (5f7160a1-09f6-4204-8ff0-6d96a91218a7) successfully added.</screen>
</para>
<para>
To view the team interfaces just configured, issue a command as follows:
- <screen>~]$ <command>nmcli connection show</command>
-NAME UUID TYPE TIMESTAMP-REAL
-Team0 fcafb3f0-4c95-48df-9e28-7ac7213f38ba team never
-team-ServerA 981eb129-1707-4a2e-a6ea-413330d96c10 team never</screen>
+ <screen>~]$ <command>nmcli con show</command>
+NAME UUID TYPE DEVICE
+team-ServerA b954c62f-5fdd-4339-97b0-40efac734c50 team ServerA
+eth1 0e8185a1-f0fd-4802-99fb-bedbb31c689b 802-3-ethernet --
+eth0 dfe1f57b-419d-4d1c-aaf5-245deab82487 802-3-ethernet --
+Team0 5f7160a1-09f6-4204-8ff0-6d96a91218a7 team ServerB</screen>
</para>
<para>
- To load a team configuration file for a team that already exists, issue a command as follows:
- <screen>~]$ <command>nmcli connection modify team-ServerA team.config <replaceable>JSON-config</replaceable></command></screen>
- You can specify the team configuration either as JSON string or provide a file name containing the configuration. The file name can include the path. In both cases, what is stored in the <parameter>team.config</parameter> property is the JSON string. In the case of a JSON string, use single quotes around the string and paste the entire string to the command line.
+ To change the name assigned to a team, issue a command in the following format:
+<synopsis><command>nmcli con mod <replaceable>old-team-name</replaceable> connection.id <replaceable>new-team-name</replaceable></command></synopsis>
</para>
<para>
- To review the <parameter>team.config</parameter> property, enter a command as follows:
- <screen>~]$ <command>nmcli conn show team-ServerA | grep team.config</command></screen>
+ To load a team configuration file for a team that already exists, issue a command in the following format:
+ <synopsis><command>nmcli connection modify <replaceable>team-name</replaceable> team.config <replaceable>JSON-config</replaceable></command></synopsis>
+ You can specify the team configuration either as a JSON string or provide a file name containing the configuration. The file name can include the path. In both cases, what is stored in the <parameter>team.config</parameter> property is the JSON string. In the case of a JSON string, use single quotes around the string and paste the entire string to the command line.
</para>
<para>
- To add an interface to the team, with name <interface>team-slave-ens3</interface>, issue a command as follows:
- <screen>~]$ <command>nmcli connection add type team-slave ifname ens3 master Team0</command>
-Connection 'team-slave-ens3' (a33d5d32-87d7-4dc4-8a27-5a44aabfa440) successfully added.</screen>
-Notice that the name was derived from the interface name by prepending the type.
-Alternatively, specify a name with <option>con-name</option> as follows:
- <screen>~]$ <command>nmcli con add type team-slave con-name Team0-port1 ifname ens3 master Team0</command>
-Connection 'Team0-port1' (adbf21f2-51b6-492f-8fc8-48b831383ac9) successfully added.
-~]$ <command>nmcli con add type team-slave con-name Team0-port2 ifname ens7 master Team0</command>
-Connection 'Team0-port2' (e5317075-c0c1-472f-b25d-0433b0297ea3) successfully added.</screen>
+ To review the <literal>team.config</literal> property, enter a command in the following format:
+ <synopsis><command>nmcli con show <replaceable>team-name</replaceable> | grep team.config</command></synopsis>
+</para>
+<para>
+ To add an interface <replaceable>eth0</replaceable> to <literal>Team0</literal>, with the name <replaceable>Team0-port1</replaceable>, issue a command as follows:
+ <screen>~]$ <command>nmcli con add type team-slave con-name <replaceable>Team0-port1</replaceable> ifname <replaceable>eth0</replaceable> master <replaceable>Team0</replaceable></command>
+Connection 'Team0-port1' (ccd87704-c866-459e-8fe7-01b06cf1cffc) successfully added.</screen>
+Similarly, to add another interface, <replaceable>eth1</replaceable>, with the name <replaceable>Team0-port2</replaceable>, issue a command as follows:
+<screen>~]$ <command>nmcli con add type team-slave con-name <replaceable>Team0-port2</replaceable> ifname <replaceable>eth1</replaceable> master <replaceable>Team0</replaceable></command>
+Connection 'Team0-port2' (a89ccff8-8202-411e-8ca6-2953b7db52dd) successfully added.</screen>
At time of writing, <application>nmcli</application> only supports Ethernet ports.
</para>
<para>
In order to bring up a team, the ports must be brought up first as follows:
- <screen>~]$ <command>nmcli connection up Team0-port1</command>
+ <screen>~]$ <command>nmcli connection up <replaceable>Team0-port1</replaceable></command>
Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/2)</screen>
-<screen>~]$ <command>nmcli connection up Team0-port2</command>
+<screen>~]$ <command>nmcli connection up <replaceable>Team0-port2</replaceable></command>
Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/3)</screen>
</para>
<para>
-You can verify the team interface was brought up by the activation of the ports, as follows:
+You can verify that the team interface was brought up by the activation of the ports, as follows:
<screen>~]$ <command>ip link</command>
3: Team0: <BROADCAST,MULTICAST,UP,LOWER_UP> mtu 1500 qdisc noqueue state UP mode DEFAULT
link/ether 52:54:00:76:6f:f0 brd ff:ff:ff:ff:ff:f</screen>
Alternatively, issue a command to bring up the team as follows:
-<screen>~]$ <command>nmcli connection up Team0</command>
+<screen>~]$ <command>nmcli connection up <replaceable>Team0</replaceable></command>
Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkManager/ActiveConnection/4)</screen>
</para>
@@ -1201,7 +1267,7 @@ Connection successfully activated (D-Bus active path: /org/freedesktop/NetworkMa
<listitem>
<para>
<filename
- class="directory">/usr/share/doc/kernel-doc-<replaceable><kernel_version></replaceable>/Documentation/</filename> — This directory, which is provided by the <package>kernel-doc</package> package, contains information on bonding which is also relevant to teaming. Before accessing the kernel documentation, you must run the following command as <systemitem class="username">root</systemitem>:</para>
+ class="directory">/usr/share/doc/kernel-doc-<replaceable>kernel_version</replaceable>/Documentation/</filename> — This directory, which is provided by the <package>kernel-doc</package> package, contains information on bonding which is also relevant to teaming. Before accessing the kernel documentation, you must run the following command as <systemitem class="username">root</systemitem>:</para>
<screen>~]# <command>yum install kernel-doc</command></screen>
<para>
<filename>/usr/share/doc/kernel-doc/Documentation/networking/multiqueue.txt</filename> — Describes kernel support for multiqueue devices.
More information about the docs-commits
mailing list