ManagingLNet.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <chapter xmlns="http://docbook.org/ns/docbook"
   3  xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en-US"
   4  xml:id="managinglnet">
   5   <title xml:id="managinglnet.title">Managing Lustre Networking (LNet)</title>
   6   <para>This chapter describes some tools for managing Lustre networking (LNet) and includes the
   7     following sections:</para>
   8   <itemizedlist>
   9     <listitem>
  10       <para><xref linkend="updating_health_status_of_router"/></para>
  11     </listitem>
  12     <listitem>
  13       <para><xref linkend="starting_stoping_lnet"/></para>
  14     </listitem>
  15     <listitem>
  16       <para><xref linkend="multi_rail_configuration_lnet"/></para>
  17     </listitem>
  18     <listitem>
  19       <para><xref linkend="load_balancing_ib_network"/></para>
  20     </listitem>
  21     <listitem>
  22       <para><xref linkend="managinglnet.configuringroutes"/></para>
  23     </listitem>
  24   </itemizedlist>
  25   <section xml:id="updating_health_status_of_router">
  26       <title><indexterm><primary>LNet</primary><secondary>management</secondary></indexterm>
  27           Updating the Health Status of a Peer or Router</title>
  28     <para>There are two mechanisms to update the health status of a peer or a router:</para>
  29     <itemizedlist>
  30       <listitem>
  31         <para>LNet can actively check health status of all routers and mark them as dead or alive automatically. By default, this is off. To enable it set <literal>auto_down</literal> and if desired <literal>check_routers_before_use</literal>. This initial check may cause a pause equal to <literal>router_ping_timeout</literal> at system startup, if there are dead routers in the system.</para>
  32       </listitem>
  33       <listitem>
  34         <para>When there is a communication error, all LNDs notify LNet that the peer (not necessarily a router) is down. This mechanism is always on, and there is no parameter to turn it off. However, if you set the LNet module parameter <literal>auto_down</literal> to <literal>0</literal>, LNet ignores all such peer-down notifications.</para>
  35       </listitem>
  36     </itemizedlist>
  37     <para>Several key differences in both mechanisms:</para>
  38     <itemizedlist>
  39       <listitem>
  40         <para>The router pinger only checks routers for their health, while LNDs notices all dead peers, regardless of whether they are a router or not.</para>
  41       </listitem>
  42       <listitem>
  43         <para>The router pinger actively checks the router health by sending pings, but LNDs only notice a dead peer when there is network traffic going on.</para>
  44       </listitem>
  45       <listitem>
  46         <para>The router pinger can bring a router from alive to dead or vice versa, but LNDs can only bring a peer down.</para>
  47       </listitem>
  48     </itemizedlist>
  49   </section>
  50   <section xml:id="starting_stoping_lnet">
  51       <title><indexterm><primary>LNet</primary><secondary>starting/stopping</secondary></indexterm>Starting and Stopping LNet</title>
  52     <para>The Lustre software automatically starts and stops LNet, but it can also be manually
  53       started in a standalone manner. This is particularly useful to verify that your networking
  54       setup is working correctly before you attempt to start the Lustre file system.</para>
  55     <section remap="h3">
  56       <title>Starting LNet</title>
  57       <para>To start LNet, run:</para>
  58       <screen>$ modprobe lnet
  59 $ lctl network up</screen>
  60       <para>To see the list of local NIDs, run:</para>
  61       <screen>$ lctl list_nids</screen>
  62       <para>This command tells you the network(s) configured to work with the Lustre file
  63         system.</para>
  64       <para>If the networks are not correctly setup, see the <literal>modules.conf</literal> &quot;<literal>networks=</literal>&quot; line and make sure the network layer modules are correctly installed and configured.</para>
  65       <para>To get the best remote NID, run:</para>
  66       <screen>$ lctl which_nid <replaceable>NIDs</replaceable></screen>
  67       <para>where <literal><replaceable>NIDs</replaceable></literal> is the list of available NIDs.</para>
  68       <para>This command takes the &quot;best&quot; NID from a list of the NIDs of a remote host. The &quot;best&quot; NID is the one that the local node uses when trying to communicate with the remote node.</para>
  69       <section remap="h4">
  70         <title>Starting Clients</title>
  71         <para>To start a TCP client, run:</para>
  72         <screen>mount -t lustre mdsnode:/mdsA/client /mnt/lustre/</screen>
  73         <para>To start an Elan client, run:</para>
  74         <screen>mount -t lustre 2@elan0:/mdsA/client /mnt/lustre</screen>
  75       </section>
  76     </section>
  77     <section remap="h3">
  78       <title>Stopping LNet</title>
  79       <para>Before the LNet modules can be removed, LNet references must be removed. In general,
  80         these references are removed automatically when the Lustre file system is shut down, but for
  81         standalone routers, an explicit step is needed to stop LNet. Run:</para>
  82       <screen>lctl network unconfigure</screen>
  83       <note>
  84         <para>Attempting to remove Lustre modules prior to stopping the network may result in a
  85           crash or an LNet hang. If this occurs, the node must be rebooted (in most cases). Make
  86           sure that the Lustre network and Lustre file system are stopped prior to unloading the
  87           modules. Be extremely careful using <literal>rmmod -f</literal>.</para>
  88       </note>
  89       <para>To unconfigure the LNet network, run:</para>
  90       <screen>modprobe -r <replaceable>lnd_and_lnet_modules</replaceable></screen>
  91       <note>
  92         <para>
  93 To remove all Lustre modules, run:</para>
  94         <para><literal>$ lustre_rmmod</literal></para>
  95       </note>
  96     </section>
  97   </section>
  98   <section xml:id="multi_rail_configuration_lnet">
  99     <title><indexterm><primary>LNet</primary><secondary>hardware multi-rail
 100     configuration</secondary></indexterm>Hardware Based Multi-Rail
 101     Configurations with LNet</title>
 102     <para>To aggregate bandwidth across both rails of a dual-rail IB cluster
 103         (o2iblnd) <footnote>
 104         <para>Hardware multi-rail configurations are only supported by o2iblnd;
 105         other IB LNDs do not support multiple interfaces.</para>
 106       </footnote> using LNet, consider these points:</para>
 107     <itemizedlist>
 108       <listitem>
 109         <para>LNet can work with multiple rails, however, it does not load
 110         balance across them. The actual rail used for any communication is
 111         determined by the peer NID.</para>
 112       </listitem>
 113       <listitem>
 114         <para>Hardware multi-rail LNet configurations do not provide an
 115         additional level of network fault tolerance. The configurations
 116         described below are for bandwidth aggregation only.</para>
 117       </listitem>
 118       <listitem>
 119         <para>A Lustre node always uses the same local NID to communicate with a
 120         given peer NID. The criteria used to determine the local NID are:</para>
 121         <itemizedlist>
 122               <listitem>
 123                 <para condition='l25'>Lowest route priority number (lower number,
 124             higher priority).</para>
 125               </listitem>
 126           <listitem>
 127             <para>Fewest hops (to minimize routing), and</para>
 128           </listitem>
 129           <listitem>
 130             <para>Appears first in the &quot;<literal>networks</literal>&quot;
 131             or &quot;<literal>ip2nets</literal>&quot; LNet configuration strings
 132             </para>
 133           </listitem>
 134         </itemizedlist>
 135       </listitem>
 136     </itemizedlist>
 137   </section>
 138   <section xml:id="load_balancing_ib_network">
 139     <title><indexterm>
 140         <primary>LNet</primary>
 141         <secondary>InfiniBand load balancing</secondary>
 142       </indexterm>Load Balancing with an InfiniBand<superscript>*</superscript> Network</title>
 143     <para>A Lustre file system contains OSSs with two InfiniBand HCAs. Lustre clients have only one
 144       InfiniBand HCA using OFED-based Infiniband &apos;&apos;o2ib&apos;&apos; drivers. Load
 145       balancing between the HCAs on the OSS is accomplished through LNet.</para>
 146     <section remap="h3">
 147       <title><indexterm><primary>LNet</primary><secondary>lustre.conf</secondary></indexterm>Setting Up <literal>lustre.conf</literal> for Load Balancing</title>
 148       <para>To configure LNet for load balancing on clients and servers:</para>
 149       <orderedlist>
 150         <listitem>
 151           <para>Set the <literal>lustre.conf</literal> options.</para>
 152           <para>Depending on your configuration, set <literal>lustre.conf</literal> options as follows:</para>
 153           <itemizedlist>
 154             <listitem>
 155               <para>Dual HCA OSS server</para>
 156             </listitem>
 157           </itemizedlist>
 158           <screen>options lnet networks="o2ib0(ib0),o2ib1(ib1)"</screen>
 159           <itemizedlist>
 160             <listitem>
 161               <para>Client with the odd IP address</para>
 162             </listitem>
 163           </itemizedlist>
 164           <screen>options lnet ip2nets="o2ib0(ib0) 192.168.10.[103-253/2]"</screen>
 165           <itemizedlist>
 166             <listitem>
 167               <para>Client with the even IP address</para>
 168             </listitem>
 169           </itemizedlist>
 170           <screen>options lnet ip2nets="o2ib1(ib0) 192.168.10.[102-254/2]"</screen>
 171         </listitem>
 172         <listitem>
 173           <para>Run the modprobe lnet command and create a combined MGS/MDT file system.</para>
 174           <para>The following commands create an MGS/MDT or OST file system and mount the targets on the servers.</para>
 175           <screen>modprobe lnet
 176 # mkfs.lustre --fsname lustre --mgs --mdt <replaceable>/dev/mdt_device</replaceable>
 177 # mkdir -p <replaceable>/mount_point</replaceable>
 178 # mount -t lustre /dev/<replaceable>mdt_device</replaceable> <replaceable>/mount_point</replaceable></screen>
 179           <para>For example:</para>
 180           <screen>modprobe lnet
 181 mds# mkfs.lustre --fsname lustre --mdt --mgs /dev/sda
 182 mds# mkdir -p /mnt/test/mdt
 183 mds# mount -t lustre /dev/sda /mnt/test/mdt
 184 mds# mount -t lustre mgs@o2ib0:/lustre /mnt/mdt
 185 oss# mkfs.lustre --fsname lustre --mgsnode=mds@o2ib0 --ost --index=0 /dev/sda
 186 oss# mkdir -p /mnt/test/mdt
 187 oss# mount -t lustre /dev/sda /mnt/test/ost
 188 oss# mount -t lustre mgs@o2ib0:/lustre /mnt/ost0</screen>
 189         </listitem>
 190         <listitem>
 191           <para>Mount the clients.</para>
 192           <screen>client# mount -t lustre <replaceable>mgs_node</replaceable>:/<replaceable>fsname</replaceable> <replaceable>/mount_point</replaceable></screen>
 193           <para>This example shows an IB client being mounted.</para>
 194           <screen>client# mount -t lustre
 195 192.168.10.101@o2ib0,192.168.10.102@o2ib1:/mds/client /mnt/lustre</screen>
 196         </listitem>
 197       </orderedlist>
 198       <para>As an example, consider a two-rail IB cluster running the OFED stack with these IPoIB
 199         address assignments.</para>
 200       <screen>             ib0                             ib1
 201 Servers            192.168.0.*                     192.168.1.*
 202 Clients            192.168.[2-127].*               192.168.[128-253].*</screen>
 203       <para>You could create these configurations:</para>
 204       <itemizedlist>
 205         <listitem>
 206           <para>A cluster with more clients than servers. The fact that an individual client cannot get two rails of bandwidth is unimportant because the servers are typically the actual bottleneck.</para>
 207         </listitem>
 208       </itemizedlist>
 209       <screen>ip2nets=&quot;o2ib0(ib0),    o2ib1(ib1)      192.168.[0-1].*                     \
 210                                             #all servers;\
 211                    o2ib0(ib0)      192.168.[2-253].[0-252/2]       #even cl\
 212 ients;\
 213                    o2ib1(ib1)      192.168.[2-253].[1-253/2]       #odd cli\
 214 ents&quot;</screen>
 215       <para>This configuration gives every server two NIDs, one on each network, and statically load-balances clients between the rails.</para>
 216       <itemizedlist>
 217         <listitem>
 218           <para>A single client that must get two rails of bandwidth, and it does not matter if the maximum aggregate bandwidth is only (# servers) * (1 rail).</para>
 219         </listitem>
 220       </itemizedlist>
 221       <screen>ip2nets=&quot;       o2ib0(ib0)                      192.168.[0-1].[0-252/2]     \
 222                                             #even servers;\
 223            o2ib1(ib1)                      192.168.[0-1].[1-253/2]         \
 224                                         #odd servers;\
 225            o2ib0(ib0),o2ib1(ib1)           192.168.[2-253].*               \
 226                                         #clients&quot;</screen>
 227       <para>This configuration gives every server a single NID on one rail or the other. Clients have a NID on both rails.</para>
 228       <itemizedlist>
 229         <listitem>
 230           <para>All clients and all servers must get two rails of bandwidth.</para>
 231         </listitem>
 232       </itemizedlist>
 233       <screen>ip2nets=â€   o2ib0(ib0),o2ib2(ib1)           192.168.[0-1].[0-252/2]       \
 234   #even servers;\
 235            o2ib1(ib0),o2ib3(ib1)           192.168.[0-1].[1-253/2]         \
 236 #odd servers;\
 237            o2ib0(ib0),o2ib3(ib1)           192.168.[2-253].[0-252/2)       \
 238 #even clients;\
 239            o2ib1(ib0),o2ib2(ib1)           192.168.[2-253].[1-253/2)       \
 240 #odd clients&quot;</screen>
 241       <para>This configuration includes two additional proxy o2ib networks to work around the
 242         simplistic NID selection algorithm in the Lustre software. It connects &quot;even&quot;
 243         clients to &quot;even&quot; servers with <literal>o2ib0</literal> on
 244           <literal>rail0</literal>, and &quot;odd&quot; servers with <literal>o2ib3</literal> on
 245           <literal>rail1</literal>. Similarly, it connects &quot;odd&quot; clients to
 246         &quot;odd&quot; servers with <literal>o2ib1</literal> on <literal>rail0</literal>, and
 247         &quot;even&quot; servers with <literal>o2ib2</literal> on <literal>rail1</literal>.</para>
 248     </section>
 249   </section>
 250   <section xml:id="managinglnet.configuringroutes">
 251     <title><indexterm><primary>LNet</primary></indexterm>Dynamically Configuring
 252     LNet Routes</title>
 253     <para>Two scripts are provided:
 254     <literal>lustre/scripts/lustre_routes_config</literal> and
 255     <literal>lustre/scripts/lustre_routes_conversion</literal>.</para>
 256     <para><literal>lustre_routes_config</literal> sets or cleans up LNet routes
 257     from the specified config file.  The
 258     <literal>/etc/sysconfig/lnet_routes.conf</literal> file can be used to
 259     automatically configure routes on LNet startup. </para>
 260     <para><literal>lustre_routes_conversion</literal> converts a legacy routes
 261     configuration file to the new syntax, which is parsed by
 262     <literal>lustre_routes_config</literal>.</para>
 263     <section remap="h3">
 264       <title><indexterm><primary>LNet</primary></indexterm>
 265       <literal>lustre_routes_config</literal></title>
 266       <para><literal>lustre_routes_config</literal> usage is as follows</para>
 267       <screen><literal>lustre_routes_config [--setup|--cleanup|--dry-run|--verbose] <replaceable>config_file</replaceable></literal>
 268          --setup: configure routes listed in config_file
 269          --cleanup: unconfigure routes listed in config_file
 270          --dry-run: echo commands to be run, but do not execute them
 271          --verbose: echo commands before they are executed </screen>
 272       <para> The format of the file which is passed into the script is as
 273       follows: </para>
 274       <para><literal><replaceable>network</replaceable>: { gateway: <replaceable>gateway</replaceable>@<replaceable>exit_network</replaceable> [hop: <replaceable>hop</replaceable>] [priority: <replaceable>priority</replaceable>] }</literal></para>
 275       <para> An LNet router is identified when its local NID appears within the
 276       list of routes.  However, this can not be achieved by the use of this
 277       script, since the script only adds extra routes after the router is
 278       identified.  To ensure that a router is identified correctly, make sure to
 279       add its local NID in the routes parameter in the modprobe lustre
 280       configuration file.
 281       See <xref linkend='tuning_lnet_mod_params'/>.</para>
 282     </section>
 283     <section remap="h3">
 284       <title><indexterm><primary>LNet</primary></indexterm><literal>lustre_routes_conversion</literal></title>
 285       <para><literal>lustre_routes_conversion</literal> usage is as follows:</para>
 286       <screen><literal>lustre_routes_conversion <replaceable>legacy_file</replaceable> <replaceable>new_file</replaceable></literal></screen>
 287       <para><literal>lustre_routes_conversion</literal> takes as a first parameter a file with routes configured as follows:</para>
 288       <para><literal><replaceable>network</replaceable> [<replaceable>hop</replaceable>] <replaceable>gateway</replaceable>@<replaceable>exit network</replaceable>[:<replaceable>priority</replaceable>];</literal></para>
 289       <para>The script then converts each routes entry in the provided file to:</para>
 290       <para><literal><replaceable>network</replaceable>: { gateway: <replaceable>gateway</replaceable>@<replaceable>exit network</replaceable> [hop: <replaceable>hop</replaceable>] [priority: <replaceable>priority</replaceable>] }</literal></para>
 291       <para>and appends each converted entry to the output file passed in as the second parameter to the script.</para>
 292     </section>
 293     <section remap="h3">
 294       <title><indexterm><primary>LNet</primary></indexterm><literal>Route Configuration Examples</literal></title>
 295       <para>Below is an example of a legacy LNet route configuration.  A legacy configuration file can have multiple entries.</para>
 296       <screen><literal>tcp1 10.1.1.2@tcp0:1;
 297 tcp2 10.1.1.3@tcp0:2;
 298 tcp3 10.1.1.4@tcp0;</literal></screen>
 299       <para>Below is an example of the converted LNet route configuration.  The following would be the result of the <literal>lustre_routes_conversion</literal> script, when run on the above legacy entries.</para>
 300       <screen><literal>tcp1: { gateway: 10.1.1.2@tcp0 priority: 1 }
 301 tcp2: { gateway: 10.1.1.2@tcp0 priority: 2 }
 302 tcp1: { gateway: 10.1.1.4@tcp0 }</literal></screen>
 303     </section>
 304   </section>
 305 </chapter>
 306 <!--vim:expandtab:shiftwidth=2:tabstop=8:-->