ConfiguringLNET.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <!-- This document was created with Syntext Serna Free. --><chapter xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US" xml:id="configuringlnet">
   3   <title xml:id="configuringlnet.title">Configuring Lustre Networking (LNET)</title>
   4   <para>This chapter describes how to configure Lustre Networking (LNET). It includes the following sections:</para>
   5   <itemizedlist>
   6     <listitem>
   7       <para><xref linkend="dbdoclet.50438216_33148"/>
   8           </para>
   9     </listitem>
  10     <listitem>
  11       <para><xref linkend="dbdoclet.50438216_46279"/>
  12           </para>
  13     </listitem>
  14     <listitem>
  15       <para><xref linkend="dbdoclet.50438216_31414"/>
  16           </para>
  17     </listitem>
  18     <listitem>
  19       <para><xref linkend="dbdoclet.50438216_71227"/>
  20           </para>
  21     </listitem>
  22     <listitem>
  23       <para><xref linkend="dbdoclet.50438216_10523"/>
  24           </para>
  25     </listitem>
  26     <listitem>
  27       <para><xref linkend="dbdoclet.50438216_35668"/>
  28           </para>
  29     </listitem>
  30     <listitem>
  31       <para><xref linkend="dbdoclet.50438216_15200"/>
  32           </para>
  33     </listitem>
  34   </itemizedlist>
  35   <note>
  36     <para>Configuring LNET is optional.</para>
  37     <para>LNET will, by default, use the first TCP/IP interface it discovers on a system (<literal>eth0</literal>). If this network configuration is sufficient, you do not need to configure LNET. LNET configuration is required if you are using Infiniband or multiple Ethernet interfaces.</para>
  38   </note>
  39   <section xml:id="dbdoclet.50438216_33148">
  40       <title><indexterm><primary>LNET</primary></indexterm>
  41
  42           Overview of LNET Module Parameters</title>
  43     <para>LNET kernel module (lnet) parameters specify how LNET is to be configured to work with Lustre, including which NICs will be configured to work with Lustre and the routing to be used with Lustre.</para>
  44     <para>Parameters for LNET can be specified in the <literal>/etc/modprobe.d/lustre.conf</literal> file.  In some cases the parameters may have been stored in <literal>/etc/modprobe.conf</literal>, but this has been deprecated since before RHEL5 and SLES10, and having a separate <literal>/etc/modprobe.d/lustre.conf</literal> file simplifies administration and distribution of the Lustre networking configuration.  This file contains one or more entries with the syntax:</para>
  45     <screen>options lnet <replaceable>parameter</replaceable>=<replaceable>value</replaceable></screen>
  46     <para>To specify the network interfaces that are to be used for Lustre, set either the <literal>networks</literal> parameter or the <literal>ip2nets</literal> parameter (only one of these parameters can be used at a time):</para>
  47     <itemizedlist>
  48       <listitem>
  49         <para><literal>networks</literal>  - Specifies the networks to be used.</para>
  50       </listitem>
  51       <listitem>
  52         <para><literal>ip2nets</literal>  - Lists globally-available networks, each with a range of IP addresses. LNET then identifies locally-available networks through address list-matching lookup.</para>
  53       </listitem>
  54     </itemizedlist>
  55     <para>See <xref linkend="dbdoclet.50438216_46279"/> and <xref linkend="dbdoclet.50438216_31414"/> for more details.</para>
  56     <para>To set up routing between networks, use:</para>
  57     <itemizedlist>
  58       <listitem>
  59         <para><literal>routes</literal>  - Lists networks and the NIDs of routers that forward to them.</para>
  60       </listitem>
  61     </itemizedlist>
  62     <para>See <xref linkend="dbdoclet.50438216_71227"/> for more details.</para>
  63     <para>A <literal>router</literal> checker can be configured to enable Lustre nodes to detect router health status, avoid routers that appear dead, and reuse those that restore service after failures. See <xref linkend="dbdoclet.50438216_35668"/> for more details.</para>
  64     <para>For a complete reference to the LNET module parameters, see <emphasis><xref linkend="configurationfilesmoduleparameters"/>LNET Options</emphasis>.</para>
  65     <note>
  66       <para>We recommend that you use &apos;dotted-quad&apos; notation for IP addresses rather than host names to make it easier to read debug logs and debug configurations with multiple interfaces.</para>
  67     </note>
  68     <section remap="h3">
  69       <title><indexterm><primary>LNET</primary><secondary>using NID</secondary></indexterm>Using a Lustre Network Identifier (NID) to Identify a Node</title>
  70       <para>A Lustre network identifier (NID) is used to uniquely identify a Lustre network endpoint by node ID and network type. The format of the NID is:</para>
  71       <screen><replaceable>network_id</replaceable>@<replaceable>network_type</replaceable></screen>
  72       <para>Examples are:</para>
  73       <screen>10.67.73.200@tcp0
  74 10.67.75.100@o2ib</screen>
  75       <para>The first entry above identifies a TCP/IP node, while the second entry identifies an InfiniBand node.</para>
  76       <para>When a mount command is run on a client, the client uses the NID of the MDS to retrieve configuration information. If an MDS has more than one NID, the client should use the appropriate NID for its local network.</para>
  77       <para>To determine the appropriate NID to specify in the mount command, use the <literal>lctl</literal> command. To display MDS NIDs, run on the MDS :</para>
  78       <screen>lctl list_nids</screen>
  79       <para>To determine if a client can reach the MDS using a particular NID, run on the client:</para>
  80       <screen>lctl which_nid <replaceable>MDS_NID</replaceable></screen>
  81     </section>
  82   </section>
  83   <section xml:id="dbdoclet.50438216_46279">
  84     <title><indexterm><primary>LNET</primary><secondary>module parameters</secondary></indexterm>Setting the LNET Module networks Parameter</title>
  85     <para>If a node has more than one network interface, you&apos;ll typically want to dedicate a specific interface to Lustre. You can do this by including an entry in the <literal>lustre.conf</literal> file on the node that sets the LNET module <literal>networks</literal> parameter:</para>
  86     <screen>options lnet networks=<replaceable>comma-separated list of networks</replaceable></screen>
  87     <para>This example specifies that a Lustre node will use a TCP/IP interface and an InfiniBand interface:</para>
  88     <screen>options lnet networks=tcp0(eth0),o2ib(ib0)</screen>
  89     <para>This example specifies that the Lustre node will use the TCP/IP interface <literal>eth1</literal>:</para>
  90     <screen>options lnet networks=tcp0(eth1)</screen>
  91     <para>Depending on the network design, it may be necessary to specify explicit interfaces. To explicitly specify that interface <literal>eth2</literal> be used for network <literal>tcp0</literal> and <literal>eth3</literal> be used for <literal>tcp1</literal> , use this entry:</para>
  92     <screen>options lnet networks=tcp0(eth2),tcp1(eth3)</screen>
  93     <para>When more than one interface is available during the network setup, Lustre chooses the best route based on the hopcount. Once the network connection is established, Lustre expects the network to stay connected. In a Lustre network, connections do not fail over to another interface, even if multiple interfaces are available on the same node.</para>
  94     <para condition='l25'>Since version 2.5 of the Lustre software, the route priority is also used to decide which interface to use. The priority has precendence over hopcount so the route with the lower priority number will be selected regardless of what the hopcounts are.</para>
  95     <note>
  96       <para>LNET lines in <literal>lustre.conf</literal> are only used by the local node to determine what to call its interfaces. They are not used for routing decisions.</para>
  97     </note>
  98     <section remap="h3">
  99       <title><indexterm><primary>configuring</primary><secondary>multihome</secondary></indexterm>Multihome Server Example</title>
 100       <para>If a server with multiple IP addresses (multihome server) is connected to a Lustre network, certain configuration setting are required. An example illustrating these setting consists of a network with the following nodes:</para>
 101       <itemizedlist>
 102         <listitem>
 103           <para> Server svr1 with three TCP NICs (<literal>eth0</literal>, <literal>eth1</literal>, and <literal>eth2</literal>) and an InfiniBand NIC.</para>
 104         </listitem>
 105         <listitem>
 106           <para> Server svr2 with three TCP NICs (<literal>eth0</literal>, <literal>eth1</literal>, and <literal>eth2</literal>) and an InfiniBand NIC. Interface eth2 will not be used for Lustre networking.</para>
 107         </listitem>
 108         <listitem>
 109           <para> TCP clients, each with a single TCP interface.</para>
 110         </listitem>
 111         <listitem>
 112           <para> InfiniBand clients, each with a single Infiniband interface and a TCP/IP interface for administration.</para>
 113         </listitem>
 114       </itemizedlist>
 115       <para>To set the <literal>networks</literal> option for this example:</para>
 116       <itemizedlist>
 117         <listitem>
 118           <para> On each server, <literal>svr1</literal> and <literal>svr2</literal>, include the following line in the <literal>lustre.conf</literal> file:</para>
 119         </listitem>
 120       </itemizedlist>
 121       <screen>options lnet networks=tcp0(eth0),tcp1(eth1),o2ib</screen>
 122       <itemizedlist>
 123         <listitem>
 124           <para> For TCP-only clients, the first available non-loopback IP interface is used for <literal>tcp0</literal>. Thus, TCP clients with only one interface do not need to have options defined in the <literal>lustre.conf</literal> file.</para>
 125         </listitem>
 126         <listitem>
 127           <para> On the InfiniBand clients, include the following line in the <literal>lustre.conf</literal> file:</para>
 128         </listitem>
 129       </itemizedlist>
 130       <screen>options lnet networks=o2ib</screen>
 131       <note>
 132         <para>By default, Lustre ignores the loopback (<literal>lo0</literal>) interface. Lustre does not ignore IP addresses aliased to the loopback. If you alias IP addresses to the loopback interface, you must specify all Lustre networks using the LNET networks parameter.</para>
 133       </note>
 134       <note>
 135         <para>If the server has multiple interfaces on the same subnet, the Linux kernel will send all traffic using the first configured interface. This is a limitation of Linux, not Lustre. In this case, network interface bonding should be used. For more information about network interface bonding, see <xref linkend="settingupbonding"/>.</para>
 136       </note>
 137     </section>
 138   </section>
 139   <section xml:id="dbdoclet.50438216_31414">
 140     <title><indexterm><primary>LNET</primary><secondary>ip2nets</secondary></indexterm>Setting the LNET Module ip2nets Parameter</title>
 141     <para>The <literal>ip2nets</literal> option is typically used when a single, universal <literal>lustre.conf</literal> file is run on all servers and clients. Each node identifies the locally available networks based on the listed IP address patterns that match the node&apos;s local IP addresses.</para>
 142     <para>Note that the IP address patterns listed in the <literal>ip2nets</literal> option are <emphasis>only</emphasis> used to identify the networks that an individual node should instantiate. They are <emphasis>not</emphasis> used by LNET for any other communications purpose.</para>
 143     <para>For the example below, the nodes in the network have these IP addresses:</para>
 144     <itemizedlist>
 145       <listitem>
 146         <para> Server svr1: <literal>eth0</literal> IP address <literal>192.168.0.2</literal>, IP over Infiniband (<literal>o2ib</literal>) address <literal>132.6.1.2</literal>.</para>
 147       </listitem>
 148       <listitem>
 149         <para> Server svr2: <literal>eth0</literal> IP address <literal>192.168.0.4</literal>, IP over Infiniband (<literal>o2ib</literal>) address <literal>132.6.1.4</literal>.</para>
 150       </listitem>
 151       <listitem>
 152         <para> TCP clients have IP addresses <literal>192.168.0.5-255.</literal></para>
 153       </listitem>
 154       <listitem>
 155         <para> Infiniband clients have IP over Infiniband (<literal>o2ib</literal>) addresses <literal>132.6.[2-3].2, .4, .6, .8</literal>.</para>
 156       </listitem>
 157     </itemizedlist>
 158     <para>The following entry is placed in the <literal>lustre.conf</literal> file on each server and client:</para>
 159     <screen>options lnet &apos;ip2nets=&quot;tcp0(eth0) 192.168.0.[2,4]; \
 160 tcp0 192.168.0.*; o2ib0 132.6.[1-3].[2-8/2]&quot;&apos;</screen>
 161     <para>Each entry in <literal>ip2nets</literal> is referred to as a &apos;rule&apos;.</para>
 162     <para>The order of LNET entries is important when configuring servers. If a server node can be reached using more than one network, the first network specified in <literal>lustre.conf</literal> will be used.</para>
 163     <para>Because <literal>svr1</literal> and <literal>svr2</literal> match the first rule, LNET uses <literal>eth0</literal> for <literal>tcp0</literal> on those machines. (Although <literal>svr1</literal> and <literal>svr2</literal> also match the second rule, the first matching rule for a particular network is used).</para>
 164     <para>The <literal>[2-8/2]</literal> format indicates a range of 2-8 stepped by 2; that is 2,4,6,8. Thus, the clients at <literal>132.6.3.5</literal> will not find a matching o2ib network.</para>
 165   </section>
 166   <section xml:id="dbdoclet.50438216_71227">
 167     <title><indexterm><primary>LNET</primary><secondary>routes</secondary></indexterm>Setting the LNET Module routes Parameter</title>
 168     <para>The LNET module routes parameter is used to identify routers in a Lustre configuration. These parameters are set in <literal>modprobe.conf</literal> on each Lustre node.</para>
 169     <para>The LNET routes parameter specifies a colon-separated list of router definitions. Each route is defined as a network number, followed by a list of routers:</para>
 170     <screen>routes=<replaceable>net_type router_NID(s)</replaceable></screen>
 171     <para>This example specifies bi-directional routing in which TCP clients can reach Lustre resources on the IB networks and IB servers can access the TCP networks:</para>
 172     <screen>options lnet &apos;ip2nets=&quot;tcp0 192.168.0.*; \
 173   o2ib0(ib0) 132.6.1.[1-128]&quot;&apos; &apos;routes=&quot;tcp0   132.6.1.[1-8]@o2ib0; \
 174   o2ib0 192.16.8.0.[1-8]@tcp0&quot;&apos;</screen>
 175     <para>All LNET routers that bridge two networks are equivalent. They are not configured as primary or secondary, and the load is balanced across all available routers.</para>
 176     <para>The number of LNET routers is not limited. Enough routers should be used to handle the required file serving bandwidth plus a 25 percent margin for headroom.</para>
 177     <section remap="h3">
 178       <title><indexterm><primary>LNET</primary><secondary>routing example</secondary></indexterm>Routing Example</title>
 179       <para>On the clients, place the following entry in the <literal>lustre.conf</literal> file</para>
 180       <screen>lnet networks=&quot;tcp&quot; routes=&quot;o2ib0 192.168.0.[1-8]@tcp0&quot;</screen>
 181       <para>On the router nodes, use:</para>
 182       <screen>lnet networks=&quot;tcp o2ib&quot; forwarding=enabled </screen>
 183       <para>On the MDS, use the reverse as shown below:</para>
 184       <screen>lnet networks=&quot;o2ib0&quot; routes=&quot;tcp0 132.6.1.[1-8]@o2ib0&quot; </screen>
 185       <para>To start the routers, run:</para>
 186       <screen>modprobe lnet
 187 lctl network configure</screen>
 188     </section>
 189   </section>
 190   <section xml:id="dbdoclet.50438216_10523">
 191     <title><indexterm><primary>LNET</primary><secondary>testing</secondary></indexterm>Testing the LNET Configuration</title>
 192     <para>After configuring Lustre Networking, it is highly recommended that you test your LNET configuration using the LNET Self-Test provided with the Lustre software. For more information about using LNET Self-Test, see <xref linkend="lnetselftest"/>.</para>
 193   </section>
 194   <section xml:id="dbdoclet.50438216_35668">
 195     <title><indexterm><primary>LNET</primary><secondary>route checker</secondary></indexterm>Configuring the Router Checker</title>
 196     <para>In a Lustre configuration in which different types of networks, such as a TCP/IP network and an Infiniband network, are connected by routers, a router checker can be run on the clients and servers in the routed configuration to monitor the status of the routers. In a multi-hop routing configuration, router checkers can be configured on routers to monitor the health of their next-hop routers.</para>
 197     <para>A router checker is configured by setting lnet parameters in <literal>lustre.conf</literal> by including an entry in this form:</para>
 198     <screen>options lnet <replaceable>router_checker_parameter</replaceable>=<replaceable>value</replaceable></screen>
 199     <para>The router checker parameters are:</para>
 200     <itemizedlist>
 201       <listitem>
 202         <para><literal>live_router_check_interval</literal>  - Specifies a time interval in seconds after which the router checker will ping the live routers. The default value is 0, meaning no checking is done. To set the value to 60, enter:</para>
 203     <screen>options lnet live_router_check_interval=60</screen>
 204       </listitem>
 205       <listitem>
 206         <para><literal>dead_router_check_interval</literal>  - Specifies a time interval in seconds after which the router checker will check for dead routers. The default value is 0, meaning no checking is done. To set the value to 60, enter:</para>
 207     <screen>options lnet dead_router_check_interval=60</screen>
 208       </listitem>
 209       <listitem>
 210         <para>auto_down  - Enables/disables (1/0) the automatic marking of router state as up or down. The default value is 1. To disable router marking, enter:</para>
 211     <screen>options lnet auto_down=0</screen>
 212       </listitem>
 213       <listitem>
 214         <para><literal>router_ping_timeout</literal>  - Specifies a timeout for the router checker when it checks live or dead routers. The router checker sends a ping message to each dead or live router once every dead_router_check_interval or live_router_check_interval respectively. The default value is 50. To set the value to 60, enter:</para>
 215     <screen>options lnet router_ping_timeout=60</screen>
 216     <note>
 217         <para>The <literal>router_ping_timeout</literal> is consistent with the default LND timeouts. You may have to increase it on very large clusters if the LND timeout is also increased. For larger clusters, we suggest increasing the check interval.</para>
 218     </note>
 219       </listitem>
 220       <listitem>
 221           <para><literal>check_routers_before_use</literal>  - Specifies that routers are to be checked before use. Set to off by default. If this parameter is set to on, the dead_router_check_interval parameter must be given a positive integer value.</para>
 222     <screen>options lnet check_routers_before_use=on</screen>
 223       </listitem>
 224     </itemizedlist>
 225     <para>The router checker obtains the following information from each router:</para>
 226     <itemizedlist>
 227       <listitem>
 228         <para> Time the router was disabled</para>
 229       </listitem>
 230       <listitem>
 231         <para> Elapsed disable time</para>
 232       </listitem>
 233     </itemizedlist>
 234     <para>If the router checker does not get a reply message from the router within router_ping_timeout seconds, it considers the router to be down.</para>
 235     <para>If a router is marked &apos;up&apos; and responds to a ping, the timeout is reset.</para>
 236     <para>If 100 packets have been sent successfully through a router, the sent-packets counter for that router will have a value of 100.</para>
 237   </section>
 238   <section xml:id="dbdoclet.50438216_15200">
 239     <title><indexterm><primary>LNET</primary><secondary>best practice</secondary></indexterm>Best Practices for LNET Options</title>
 240     <para>For the <literal>networks</literal>, <literal>ip2nets</literal>, and <literal>routes</literal> options, follow these best practices to avoid configuration errors.</para>
 241     <section remap="h5">
 242       <title><indexterm><primary>LNET</primary><secondary>escaping commas with quotes</secondary></indexterm>Escaping commas with quotes</title>
 243       <para>Depending on the Linux distribution, commas may need to be escaped using single or double quotes. In the extreme case, the <literal>options</literal> entry would look like this:</para>
 244       <para><screen>options lnet&apos;networks=&quot;tcp0,elan0&quot;&apos; &apos;routes=&quot;tcp [2,10]@elan0&quot;&apos;</screen></para>
 245       <para>Added quotes may confuse some distributions. Messages such as the following may indicate an issue related to added quotes:</para>
 246       <para><screen>lnet: Unknown parameter &apos;networks&apos;</screen></para>
 247       <para>A <literal>&apos;Refusing connection - no matching NID&apos;</literal> message generally points to an error in the LNET module configuration.</para>
 248     </section>
 249     <section remap="h5">
 250       <title><indexterm><primary>LNET</primary><secondary>comments</secondary></indexterm>Including comments</title>
 251       <para><emphasis>Place the semicolon terminating a comment immediately after the comment.</emphasis> LNET silently ignores everything between the <literal>#</literal> character at the beginning of the comment and the next semicolon.</para>
 252       <para>In this <emphasis>incorrect</emphasis> example, LNET silently ignores <literal>pt11 192.168.0.[92,96]</literal>, resulting in these nodes not being properly initialized. No error message is generated.</para>
 253       <screen>options lnet ip2nets=&quot;pt10 192.168.0.[89,93]; # comment with semicolon BEFORE comment \
 254 pt11 192.168.0.[92,96];</screen>
 255       <para>This <emphasis role="italic">correct</emphasis> example shows the required syntax:
 256 </para>
 257       <para><screen>options lnet ip2nets=&quot;pt10 192.168.0.[89,93] \
 258 # comment with semicolon AFTER comment; \
 259 pt11 192.168.0.[92,96] # comment</screen></para>
 260       <para><emphasis role="italic">Do not add an excessive number of comments.</emphasis> The Linux kernel limits the length of
 261 character strings used in module options (usually to 1KB, but this may differ
 262 between vendor kernels). If you exceed this limit, errors result and the specified
 263 configuration may not be processed correctly.</para>
 264     </section>
 265   </section>
 266 </chapter>