ConfiguringLNET.xml

   1 <?xml version='1.0' encoding='UTF-8'?>
   2 <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
   5     sections:</para>
   6   <itemizedlist>
   7     <listitem>
   8       <para><xref linkend="dbdoclet.50438216_33148"/>
   9           </para>
  10     </listitem>
  11     <listitem>
  12       <para><xref linkend="dbdoclet.50438216_46279"/>
  13           </para>
  14     </listitem>
  15     <listitem>
  16       <para><xref linkend="dbdoclet.50438216_31414"/>
  17           </para>
  18     </listitem>
  19     <listitem>
  20       <para><xref linkend="dbdoclet.50438216_71227"/>
  21           </para>
  22     </listitem>
  23     <listitem>
  24       <para><xref linkend="dbdoclet.50438216_10523"/>
  25           </para>
  26     </listitem>
  27     <listitem>
  28       <para><xref linkend="dbdoclet.50438216_15200"/>
  29           </para>
  30     </listitem>
  31   </itemizedlist>
  32   <note>
  33     <para>LNET will, by default, use the first TCP/IP interface it discovers on a system. If the
  34       default is sufficient, further configuration is not required.</para>
  35   </note>
  36   <section xml:id="dbdoclet.50438216_33148">
  37       <title><indexterm><primary>LNet</primary></indexterm>
  38           Overview of <literal>lnet</literal> Module Parameters</title>
  39     <para>The LNET kernel module parameters specify how LNET is to be configured to work with a
  40       Lustre file system, including details on which NICs are to be configured and how routing among
  41       LNET routers will take place.</para>
  42     <para>Parameters for LNET can be specified in the <literal>/etc/modprobe.d/lustre.conf</literal>
  43       file. The file need not be named <literal>lustre.conf</literal>. However, this convention will
  44       be used in this manual. For distributions previous to Red Hat Enterprise Edition 5 and SUSE
  45       Linux Enterprise Server 10, LNET parameters may have been stored in
  46         <literal>/etc/modprobe.conf</literal>, but this method of specifying LNET parameters is now
  47       deprecated. Storing LNET parameters in a separate
  48         <literal>/etc/modprobe.d/lustre.conf</literal> file simplifies administration and
  49       distribution of the Lustre networking configuration. This file contains one or more entries
  50       with the syntax:</para>
  51     <screen>options lnet <replaceable>parameter</replaceable>=<replaceable>value</replaceable></screen>
  52     <para>To specify the network interfaces that are to be used for the Lustre file system, set
  53       either the <literal>networks</literal> parameter or the <literal>ip2nets</literal> parameter
  54       (only one of these parameters can be used at a time):</para>
  55     <itemizedlist>
  56       <listitem>
  57         <para><literal>networks</literal> - Specifies the LNET network interfaces to be used.</para>
  58       </listitem>
  59       <listitem>
  60         <para><literal>ip2nets</literal> - Lists globally-available networks, each with a range of
  61           IP addresses. LNET then identifies locally-available networks through address
  62           list-matching lookup.</para>
  63       </listitem>
  64     </itemizedlist>
  65     <para>See <xref linkend="dbdoclet.50438216_46279"/> and <xref linkend="dbdoclet.50438216_31414"/> for more details.</para>
  66     <para>To set up routing between networks, use the <literal>routes</literal> parameter to
  67       identify the LNET subnets and the NID(s) of the routers that forward to them. See <xref
  68         linkend="dbdoclet.50438216_71227"/> for more details.</para>
  69     </section>
  70   <section xml:id="dbdoclet.50438216_46279">
  71     <title><indexterm><primary>LNet</primary><secondary>module parameters</secondary></indexterm><literal>networks</literal> Parameter</title>
  72     <para>The <literal>networks</literal> parameter maps a network interface to an LNET subnet. You
  73       can do this by including an entry or a comma separated list in the
  74         <literal>lustre.conf</literal> file.</para>
  75     <screen>options lnet networks=<replaceable>LNET(interface),LNET(interface),...</replaceable></screen>
  76     <para>For example:</para>
  77     <para>To map the LNET <literal>tcp0</literal> to the Ethernet interface
  78       <literal>eth1</literal>:</para>
  79     <screen>options lnet networks=tcp0(eth1)</screen>
  80     <para>To map the LNET <literal>o2ib</literal> to the InfiniBand interface
  81       <literal>ib0</literal>:</para>
  82     <screen>options lnet networks=o2ib(ib0)</screen>
  83     <para>Omitting a network number in an LNET specification results in a network number of
  84       0.</para>
  85     <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>
  86     <screen>options lnet networks=tcp0(eth2),tcp1(eth3)</screen>
  87     <para>When more than one interface is available during the network setup, the Lustre software
  88       chooses the best route based on the hopcount. Once the network connection is established, the
  89       Lustre software expects the network to stay connected. In a Lustre network, connections do not
  90       fail over to another interface, even if multiple interfaces are available on the same
  91       node.</para>
  92     <para condition="l25">Since Lustre software release 2.5, the route priority is also used to
  93       decide which interface to use. The priority has precendence over hopcount so the route with
  94       the lower priority number will be selected regardless of  the hopcount.</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>multi-homed</secondary></indexterm>Multi-homed Server Example</title>
 100       <para>If a server with multiple IP addresses (multi-homed server) is connected to a Lustre network, certain configuration settings are required. An example illustrating these setting consists of a network with the following nodes:</para>
 101       <itemizedlist>
 102         <listitem>
 103           <para> Server <literal>svr1</literal> with three Ethernet NIC s (<literal>eth0</literal>,
 104               <literal>eth1</literal>, and <literal>eth2</literal>) and an InfiniBand NIC.</para>
 105         </listitem>
 106         <listitem>
 107           <para> Server <literal>svr2</literal> with three Ethernet NICs (<literal>eth0</literal>,
 108               <literal>eth1</literal>, and <literal>eth2</literal>) and an InfiniBand NIC. The
 109             interface <literal>eth2</literal> will not be used for Lustre networking.</para>
 110         </listitem>
 111         <listitem>
 112           <para> TCP clients, each with a single Ethernet interface.</para>
 113         </listitem>
 114         <listitem>
 115           <para> InfiniBand clients, each with a single InfiniBand interface and an Ethernet
 116             interface for administration.</para>
 117         </listitem>
 118       </itemizedlist>
 119       <para>To set the <literal>networks</literal> option for this example:</para>
 120       <itemizedlist>
 121         <listitem>
 122           <para> On each server, <literal>svr1</literal> and <literal>svr2</literal>, include the following line in the <literal>lustre.conf</literal> file:</para>
 123         </listitem>
 124       </itemizedlist>
 125       <screen>options lnet networks=tcp0(eth0),tcp1(eth1),o2ib(ib0)</screen>
 126       <itemizedlist>
 127         <listitem>
 128           <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>
 129         </listitem>
 130         <listitem>
 131           <para> On the InfiniBand clients, include the following line in the <literal>lustre.conf</literal> file:</para>
 132         </listitem>
 133       </itemizedlist>
 134       <screen>options lnet networks=o2ib(ib0)</screen>
 135       <para>If a node has only one InfiniBand interface, then the interface name need not be
 136         specified. <literal>- ib0</literal> will be assumed.</para>
 137       </section>
 138   </section>
 139   <section xml:id="dbdoclet.50438216_31414">
 140     <title><indexterm><primary>LNet</primary><secondary>ip2nets</secondary></indexterm><literal>ip2nets</literal> 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
 143         <emphasis>only</emphasis> used to identify the networks that an individual node should
 144       instantiate. They are <emphasis>not</emphasis> used by LNET for any other communications
 145       purpose.</para>
 146     <para>For the example below, the nodes in the network have these IP addresses:</para>
 147     <itemizedlist>
 148       <listitem>
 149         <para> Server svr1: <literal>eth0</literal> IP address <literal>192.168.0.2</literal>, IP
 150           over InfiniBand (<literal>o2ib</literal>) address <literal>132.6.1.2</literal>.</para>
 151       </listitem>
 152       <listitem>
 153         <para> Server svr2: <literal>eth0</literal> IP address <literal>192.168.0.4</literal>, IP
 154           over InfiniBand (<literal>o2ib</literal>) address <literal>132.6.1.4</literal>.</para>
 155       </listitem>
 156       <listitem>
 157         <para> TCP clients have IP addresses <literal>192.168.0.5-255.</literal></para>
 158       </listitem>
 159       <listitem>
 160         <para> InfiniBand clients have IP over InfiniBand (<literal>o2ib</literal>) addresses
 161             <literal>132.6.[2-3].2, .4, .6, .8</literal>.</para>
 162       </listitem>
 163     </itemizedlist>
 164     <para>The following entry is placed in the <literal>lustre.conf</literal> file on each server and client:</para>
 165     <screen>options lnet &apos;ip2nets=&quot;tcp0(eth0) 192.168.0.[2,4]; \
 166 tcp0 192.168.0.*; o2ib0 132.6.[1-3].[2-8/2]&quot;&apos;</screen>
 167     <para>Each entry in <literal>ip2nets</literal> is referred to as a &apos;rule&apos;.</para>
 168     <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>
 169     <para>Because <literal>svr1</literal> and <literal>svr2</literal> match the first rule, LNET
 170       uses <literal>eth0</literal> for <literal>tcp0</literal> on those machines. (Although
 171         <literal>svr1</literal> and <literal>svr2</literal> also match the second rule, the first
 172       matching rule for a particular network is used).</para>
 173     <para>The <literal>[2-8/2]</literal> format indicates a range of 2-8 stepped by 2; that is
 174       2,4,6,8. Thus, the clients at <literal>132.6.3.5</literal> will not find a matching
 175         <literal>o2ib</literal> network.</para>
 176   </section>
 177   <section xml:id="dbdoclet.50438216_71227">
 178     <title><indexterm>
 179         <primary>LNet</primary>
 180         <secondary>routes</secondary>
 181       </indexterm>Using the <literal>routes</literal> Parameter</title>
 182     <para>Before discussing the <literal>routes</literal> parameter, it is important to look at what
 183       LNET routing achieves and why it is needed.</para>
 184     <para>The role of an LNET router is essentially that of a gateway that forwards Lustre traffic
 185       from one LNET network to one (or more) other LNET networks. This implies that at the LNET
 186       layer, an LNET router is the next hop between two nodes on different LNET networks. Note that
 187       this is orthogonal to whether or not the nodes in question are in the same IP subnet or are
 188       separated by one or more IP routers. Therefore, LNET routing is not required when clients and
 189       servers are all in the same LNET network.</para>
 190     <para>However, an LNET router is more than just a regular gateway; it is an LNET intelligent
 191       gateway. It is important to remember that Lustre routing is static routing, where the LNET
 192       network topology is statically configured and parsed when the system initializes. Routers can
 193       die and also come back online during operation. These topics will be discussed in greater
 194       detail in the following sections.</para>
 195     <section remap="h3"><title><indexterm><primary>LNet></primary><secondary>Routes Parameter</secondary></indexterm><literal>routes</literal> Parameter</title>
 196         <para>The <literal>routes</literal> parameter is used to tell a node which route to use when
 197         forwarding traffic by identifying LNET routers in a Lustre configuration. The routes
 198         parameter needs to be set in the <literal>lustre.conf</literal> file to specify the next hop
 199         router.</para>
 200         <para>The <literal>routes</literal> parameter specifies a semi-colon separated list of router definitions.</para>
 201         <screen>routes=<replaceable>dest_lnet [hop] [priority] router_NID@src_lnet; \
 202                                            dest_lnet [hop] [priority] router_NID@src_lnet</replaceable></screen>
 203         <para>An alternative syntax consists of a colon separated list of router definitions:</para>
 204         <screen>routes=<replaceable>dest_lnet: [hop] [priority] router_NID@src_lnet \
 205                                                [hop] [priority] router_NID@src_lnet</replaceable></screen>
 206       <para>When there are two or more LNET routers, it is possible to give weighted priorities to
 207         each router using the <literal>priority</literal> parameter. Some reasons for doing this are
 208         that one of the routers is more capable than the other, or one is a primary router and the
 209         other is a back up, or one is for one section of clients and the other is for another
 210         section, or each router is moving traffic to a different physical location.The
 211           <literal>priority</literal> parameter is optional and need not be specified if no priority
 212         exists.</para>
 213       <para>The <literal>hop</literal> parameter specifies the number of hops to the destination.
 214         When a node forwards traffic, the route with the least hops is used. If multiple routes to
 215         the same destination network have the same number of hops, the traffic is distributed
 216         between these routes in a round-robin fashion. To reach/transmit to the LNET
 217           <literal>dest_lnet</literal>, the next hop for a given node is the LNET router with the
 218         NID <literal>router_NID</literal>  in the LNET <literal>src_lnet</literal>. </para>
 219         <para>Given a sufficiently well-architected system, it is possible to map the flow to and from
 220         every single client or server. This type of routing has also been called
 221           <emphasis>fine-grained</emphasis> routing.</para>
 222     </section>
 223     <section remap="h3"><title><indexterm><primary>LNet></primary><secondary>Router configurations</secondary></indexterm>Router Configurations</title>
 224         <para>To get a router setup started and running, execute the following commands:</para>
 225         <screen>modprobe lnet
 226 lctl network configure</screen>
 227         <para> OR</para>
 228         <screen>lctl network up</screen>
 229       <para>For a router to forward traffic, the configuration parameter
 230           <literal>forwarding</literal> must be set to <literal>enabled</literal> (it is set to
 231           <literal>disabled</literal> by default). If  forwarding is not enabled, traffic destined
 232         for the node is dropped.</para>
 233         <para>
 234         <note>
 235           <para>Any changes to the <literal>lustre.conf</literal> modprobe file require unloading
 236             the <literal>lnet</literal> kernel module and repeating the above given commands. Thus
 237             any major changes, especially on the servers, should be made with due
 238             consideration.</para>
 239         </note>
 240       </para>
 241         <para>Here are a few examples starting from a basic setup and increasing in complexity to
 242         better illustrate LNET routing:</para>
 243
 244         <itemizedlist>
 245         <listitem>
 246         <para><emphasis role="italic">A simple setup involving one TCP client, one router and
 247               servers(MGS,MDS,OSS) in an InfiniBand fabric.</emphasis></para>
 248         <para>The LNET router has two NIDs, 192.168.1.2@tcp0 and 10.13.24.90@o2ib0.</para>
 249         <para>The <literal>lustre.conf</literal> file for the client includes:</para>
 250         <screen>options lnet networks=&quot;tcp0(eth0)&quot; routes=&quot;o2ib0 192.168.1.2@tcp0&quot;</screen>
 251         <para>On the router nodes:</para>
 252         <screen>options lnet networks=&quot;o2ib0(ib0),tcp0(eth0)&quot; forwarding=enabled</screen>
 253         <para>On the server nodes:</para>
 254         <screen>options lnet networks=&quot;o2ib0(ib0)&quot; routes=&quot;tcp0 10.13.24.90@o2ib0&quot;</screen>
 255         </listitem>
 256
 257         <listitem>
 258         <para><emphasis role="italic">Adding more routers to above described case.</emphasis></para>
 259         <para>When two or more routers are specified in the file, they are considered equivalent and are
 260             not configured as primary or secondary. The load is directed to the routers based on the
 261               <literal>route</literal> parameter settings for <literal>priority</literal> and
 262               <literal>hop</literal> (see <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 263               linkend="dbdoclet.50438216_71227"/>). The syntax on the client nodes is:</para>
 264         <screen>options lnet networks=&quot;tcp0(eth0)&quot; routes=&quot;o2ib0 192.168.1.2@tcp0;
 265         o2ib0 192.168.1.3@tcp0&quot;</screen>
 266         <para>The servers can be configured likewise. 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. The nodes are capable of recovering if one or more routers fail, provided, there is still at least one router left running. The nodes are also capable of recognizing when an offline routers comes online.</para>
 267         </listitem>
 268
 269         <listitem>
 270         <para><emphasis role="italic">Assigning priorities to routers.</emphasis></para>
 271         <screen>options lnet networks=&quot;tcp0(eth0)&quot; routes=&quot;o2ib0 1 192.168.1.2@tcp0;
 272         o2ib0 2 192.168.1.3@tcp0&quot;</screen>
 273         <para>The above example specifies two routers with priorities 1 and 2. In this case, the node will always first send traffic via 192.168.1.2 and if and only if that router is down, will it send traffic via 192.168.1.3.</para>
 274         <para>It is important to note that the weights are pre-configured and do not or cannot be
 275             changed dynamically. This method gives more control to an administrator on deciding
 276             which is a better route than just the route with least number of hops.</para>
 277         </listitem>
 278
 279         <listitem>
 280         <para><emphasis role="italic">Assigning equal priorities to routers.</emphasis></para>
 281         <screen>options lnet networks=&quot;tcp0(eth0)&quot; routes=&quot;o2ib0 1 192.168.1.2@tcp0;
 282         o2ib0 1 192.168.1.3@tcp0&quot;</screen>
 283         <para>The above example has two routers of the same priority. This is treated the same as
 284             specifying no priority at all.</para>
 285         </listitem>
 286
 287         <listitem>
 288         <para><emphasis role="italic">Creating classes of routers.</emphasis></para>
 289         <screen>options lnet networks=&quot;tcp0(eth0)&quot; routes=&quot;o2ib0 1 192.168.1.2@tcp0;
 290         o2ib0 1 192.168.1.3@tcp0;o2ib0 2 192.168.1.4@tcp0;
 291         o2ib0 2 192.168.1.5@tcp0&quot;</screen>
 292         <para>This example creates two classes of routers load balanced between themselves. In this case, the node will only use the routers with priority 2 only if both the routers with priority 1 are not running.</para>
 293         </listitem>
 294         </itemizedlist>
 295     </section>
 296     <section remap="h3">
 297       <title><indexterm>
 298           <primary>LNet></primary>
 299           <secondary>Kernel Parameters</secondary>
 300         </indexterm>Kernel Configuration Parameters</title>
 301       <para>In a Lustre configuration in which different types of LNET networks are connected by
 302         routers, several kernel module parameters can be set to monitor and improve routing
 303         performance. </para>
 304       <para>The routing related parameters are:</para>
 305       <itemizedlist>
 306         <listitem>
 307           <para><literal>auto_down</literal> - Enables/disables (1/0) the automatic marking of
 308             router state as up or down. The default value is 1. To disable router marking,
 309             enter:</para>
 310           <screen>options lnet auto_down=0</screen>
 311         </listitem>
 312         <listitem>
 313           <para><literal>avoid_asym_router_failure</literal> - Specifies that if even one interface
 314             of a router is down for some reason, the entire router is marked as down. This is
 315             important because if nodes are not aware that the interface on one side is down, they
 316             will still keep pushing data to the other side presuming that the router is healthy,
 317             when it really is not. To turn it on, enter:</para>
 318           <screen>options lnet avoid_asym_router_failure=1</screen>
 319         </listitem>
 320         <listitem>
 321           <para><literal>live_router_check_interval</literal> - Specifies a time interval in seconds
 322             after which the router checker will ping the live routers. The default value is 60. To
 323             set the value to 50, enter:</para>
 324           <screen>options lnet live_router_check_interval=50</screen>
 325         </listitem>
 326         <listitem>
 327           <para><literal>dead_router_check_interval</literal> - Specifies a time interval in seconds
 328             after which the router checker will check the dead routers. The default value is 60. To
 329             set the value to 50, enter:</para>
 330           <screen>options lnet dead_router_check_interval=50</screen>
 331           <note>
 332             <para>A kernel process called <literal>router_checker</literal> is started when either
 333               of the two options above are set (thus, the <literal>router_checker</literal> is
 334               enabled by default). It otians a list of next-hops from the routes entered and checks
 335               whether next-hops are alive. In a multi-hop router configuration, these parameters can
 336               be set on the routers as well, or on other node types. If no routes are entered, no
 337               checking is done.</para>
 338           </note>
 339         </listitem>
 340         <listitem>
 341           <para><literal>router_ping_timeout</literal> - Specifies a timeout for the router checker
 342             when it checks live or dead routers. The router checker sends a ping message to each
 343             dead or live router once every <literal>dead_router_check_interval</literal> or
 344               <literal>live_router_check_interval</literal> respectively. The default value is 50.
 345             To set the value to 60, enter:</para>
 346           <screen>options lnet router_ping_timeout=60</screen>
 347           <note>
 348             <para>The <literal>router_ping_timeout</literal> is consistent with the default LND
 349               timeouts. You may have to increase it on very large clusters if the LND timeout is
 350               also increased. For larger clusters, we suggest increasing the check interval.</para>
 351           </note>
 352         </listitem>
 353         <listitem>
 354           <para><literal>check_routers_before_use</literal> - Specifies that routers are to be
 355             checked before use. Set to off by default. If this parameter is set to on, the
 356               <literal>dead_router_check_interval</literal> parameter must be given a positive
 357             integer value.</para>
 358           <screen>options lnet check_routers_before_use=on</screen>
 359         </listitem>
 360       </itemizedlist>
 361       <para>The <literal>router_checker</literal> obtains the following information from each
 362         router:</para>
 363       <itemizedlist>
 364         <listitem>
 365           <para> Time the router was disabled</para>
 366         </listitem>
 367         <listitem>
 368           <para> Elapsed disable time</para>
 369         </listitem>
 370       </itemizedlist>
 371       <para>If the <literal>router_checker</literal> does not get a reply message from the router
 372         within <literal>router_ping_timeout</literal> seconds, it considers the router to be
 373         down.</para>
 374       <para>When a router in a priority class goes down, the traffic stops intermittently until LNET
 375         safely marks the router which is down as 'down' and then proceeds on again, depending either
 376         on other routers of the same or a different priority class. The time it takes for LNET to
 377         recover is roughly based on the values for the <literal>live/dead_router_checker</literal>
 378         parameters provided.</para>
 379       <para>If a router that is marked 'up' responds to a ping, the timeout is reset. If 100 packets
 380         have been sent successfully through a router, the sent-packets counter for that router will
 381         have a value of 100. The ping response also provides the status of the NIDs of the node
 382         being pinged. In this way, the pinging node knows whether to keep using this node as a
 383         next-hop or not. If one of the NIDs of the router is down and the
 384           <literal>avoid_asym_router_failure = 1</literal> is set, then that router is no longer
 385         used.</para>
 386     </section>
 387   </section>
 388   <section xml:id="dbdoclet.50438216_10523">
 389     <title><indexterm><primary>LNET</primary><secondary>testing</secondary></indexterm>Testing the LNET Configuration</title>
 390     <para>After configuring Lustre networking, it is highly recommended that you test your LNET
 391       configuration using the LNET Self-Test provided with the Lustre software. For more information
 392       about using LNET Self-Test, see <xref linkend="lnetselftest"/>.</para>
 393   </section>
 394   <section xml:id="dbdoclet.50438216_15200">
 395     <title><indexterm>
 396         <primary>LNet</primary>
 397         <secondary>best practice</secondary>
 398       </indexterm>Best Practices for LNET Options</title>
 399     <para>For the <literal>networks</literal>, <literal>ip2nets</literal>, and <literal>routes</literal> options, follow these best practices to avoid configuration errors.</para>
 400     <section remap="h5">
 401       <title><indexterm>
 402           <primary>LNET</primary>
 403           <secondary>escaping commas with quotes</secondary>
 404         </indexterm>Escaping commas with quotes</title>
 405       <para>It is recommended that you use network addresses rather than host names to make it easier to read debug logs and debug configurations with multiple interfaces.</para>
 406       <para>If the server has multiple interfaces on the same subnet, the Linux kernel will send all
 407         traffic using the first configured interface. This is a limitation in the Linux
 408         distribution, not the Lustre software. In this case, network interface bonding should be
 409         used. For more information about network interface bonding, see <xref
 410           linkend="settingupbonding"/>.</para>
 411       <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>
 412       <para><screen>options lnet&apos;networks=&quot;tcp0,elan0&quot;&apos; &apos;routes=&quot;tcp [2,10]@elan0&quot;&apos;</screen></para>
 413       <para>Added quotes may confuse some distributions. Messages such as the following may indicate an issue related to added quotes:</para>
 414       <para><screen>lnet: Unknown parameter &apos;networks&apos;</screen></para>
 415       <para>A <literal>&apos;Refusing connection - no matching NID&apos;</literal> message generally
 416         points to an error in the LNET module configuration.</para>
 417     </section>
 418     <section remap="h5">
 419       <title><indexterm><primary>LNet</primary><secondary>comments</secondary></indexterm>Including comments</title>
 420       <para><emphasis>Place the semicolon terminating a comment immediately after the
 421           comment.</emphasis> LNET silently ignores everything between the <literal>#</literal>
 422         character at the beginning of the comment and the next semicolon.</para>
 423       <para>In this <emphasis>incorrect</emphasis> example, LNET silently ignores <literal>pt11
 424           192.168.0.[92,96]</literal>, resulting in these nodes not being properly initialized. No
 425         error message is generated.</para>
 426       <screen>options lnet ip2nets=&quot;pt10 192.168.0.[89,93]; # comment with semicolon \
 427       BEFORE comment pt11 192.168.0.[92,96];</screen>
 428       <para>This <emphasis role="italic">correct</emphasis> example shows the required syntax:
 429 </para>
 430       <para><screen>options lnet ip2nets=&quot;pt10 192.168.0.[89,93] \
 431 # comment with semicolon AFTER comment; \
 432 pt11 192.168.0.[92,96] # comment</screen></para>
 433       <para><emphasis role="italic">Do not add an excessive number of comments.</emphasis> The Linux kernel limits the length of
 434 character strings used in module options (usually to 1KB, but this may differ
 435 between vendor kernels). If you exceed this limit, errors result and the specified
 436 configuration may not be processed correctly.</para>
 437     </section>
 438   </section>
 439 </chapter>