LustreTuning.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="lustretuning">
   5   <title xml:id="lustretuning.title">Tuning a Lustre File System</title>
   6   <para>This chapter contains information about tuning a Lustre file system for
   7   better performance.</para>
   8   <note>
   9     <para>Many options in the Lustre software are set by means of kernel module
  10     parameters. These parameters are contained in the
  11     <literal>/etc/modprobe.d/lustre.conf</literal> file.</para>
  12   </note>
  13   <section xml:id="dbdoclet.50438272_55226">
  14     <title>
  15     <indexterm>
  16       <primary>tuning</primary>
  17     </indexterm>
  18     <indexterm>
  19       <primary>tuning</primary>
  20       <secondary>service threads</secondary>
  21     </indexterm>Optimizing the Number of Service Threads</title>
  22     <para>An OSS can have a minimum of two service threads and a maximum of 512
  23     service threads. The number of service threads is a function of how much
  24     RAM and how many CPUs are on each OSS node (1 thread / 128MB * num_cpus).
  25     If the load on the OSS node is high, new service threads will be started in
  26     order to process more requests concurrently, up to 4x the initial number of
  27     threads (subject to the maximum of 512). For a 2GB 2-CPU system, the
  28     default thread count is 32 and the maximum thread count is 128.</para>
  29     <para>Increasing the size of the thread pool may help when:</para>
  30     <itemizedlist>
  31       <listitem>
  32         <para>Several OSTs are exported from a single OSS</para>
  33       </listitem>
  34       <listitem>
  35         <para>Back-end storage is running synchronously</para>
  36       </listitem>
  37       <listitem>
  38         <para>I/O completions take excessive time due to slow storage</para>
  39       </listitem>
  40     </itemizedlist>
  41     <para>Decreasing the size of the thread pool may help if:</para>
  42     <itemizedlist>
  43       <listitem>
  44         <para>Clients are overwhelming the storage capacity</para>
  45       </listitem>
  46       <listitem>
  47         <para>There are lots of "slow I/O" or similar messages</para>
  48       </listitem>
  49     </itemizedlist>
  50     <para>Increasing the number of I/O threads allows the kernel and storage to
  51     aggregate many writes together for more efficient disk I/O. The OSS thread
  52     pool is shared--each thread allocates approximately 1.5 MB (maximum RPC
  53     size + 0.5 MB) for internal I/O buffers.</para>
  54     <para>It is very important to consider memory consumption when increasing
  55     the thread pool size. Drives are only able to sustain a certain amount of
  56     parallel I/O activity before performance is degraded, due to the high
  57     number of seeks and the OST threads just waiting for I/O. In this
  58     situation, it may be advisable to decrease the load by decreasing the
  59     number of OST threads.</para>
  60     <para>Determining the optimum number of OSS threads is a process of trial
  61     and error, and varies for each particular configuration. Variables include
  62     the number of OSTs on each OSS, number and speed of disks, RAID
  63     configuration, and available RAM. You may want to start with a number of
  64     OST threads equal to the number of actual disk spindles on the node. If you
  65     use RAID, subtract any dead spindles not used for actual data (e.g., 1 of N
  66     of spindles for RAID5, 2 of N spindles for RAID6), and monitor the
  67     performance of clients during usual workloads. If performance is degraded,
  68     increase the thread count and see how that works until performance is
  69     degraded again or you reach satisfactory performance.</para>
  70     <note>
  71       <para>If there are too many threads, the latency for individual I/O
  72       requests can become very high and should be avoided. Set the desired
  73       maximum thread count permanently using the method described above.</para>
  74     </note>
  75     <section>
  76       <title>
  77       <indexterm>
  78         <primary>tuning</primary>
  79         <secondary>OSS threads</secondary>
  80       </indexterm>Specifying the OSS Service Thread Count</title>
  81       <para>The
  82       <literal>oss_num_threads</literal> parameter enables the number of OST
  83       service threads to be specified at module load time on the OSS
  84       nodes:</para>
  85       <screen>
  86 options ost oss_num_threads={N}
  87 </screen>
  88       <para>After startup, the minimum and maximum number of OSS thread counts
  89       can be set via the
  90       <literal>{service}.thread_{min,max,started}</literal> tunable. To change
  91       the tunable at runtime, run:</para>
  92       <para>
  93         <screen>
  94 lctl {get,set}_param {service}.thread_{min,max,started}
  95 </screen>
  96       </para>
  97       <para>
  98       This works in a similar fashion to
  99       binding of threads on MDS. MDS thread tuning is covered in
 100       <xref linkend="dbdoclet.mdsbinding" />.</para>
 101       <itemizedlist>
 102         <listitem>
 103           <para>
 104           <literal>oss_cpts=[EXPRESSION]</literal> binds the default OSS service
 105           on CPTs defined by
 106           <literal>[EXPRESSION]</literal>.</para>
 107         </listitem>
 108         <listitem>
 109           <para>
 110           <literal>oss_io_cpts=[EXPRESSION]</literal> binds the IO OSS service
 111           on CPTs defined by
 112           <literal>[EXPRESSION]</literal>.</para>
 113         </listitem>
 114       </itemizedlist>
 115       <para>For further details, see
 116       <xref linkend="dbdoclet.50438271_87260" />.</para>
 117     </section>
 118     <section xml:id="dbdoclet.mdstuning">
 119       <title>
 120       <indexterm>
 121         <primary>tuning</primary>
 122         <secondary>MDS threads</secondary>
 123       </indexterm>Specifying the MDS Service Thread Count</title>
 124       <para>The
 125       <literal>mds_num_threads</literal> parameter enables the number of MDS
 126       service threads to be specified at module load time on the MDS
 127       node:</para>
 128       <screen>options mds mds_num_threads={N}</screen>
 129       <para>After startup, the minimum and maximum number of MDS thread counts
 130       can be set via the
 131       <literal>{service}.thread_{min,max,started}</literal> tunable. To change
 132       the tunable at runtime, run:</para>
 133       <para>
 134         <screen>
 135 lctl {get,set}_param {service}.thread_{min,max,started}
 136 </screen>
 137       </para>
 138       <para>For details, see
 139       <xref linkend="dbdoclet.50438271_87260" />.</para>
 140       <para>The number of MDS service threads started depends on system size
 141       and the load on the server, and has a default maximum of 64. The
 142       maximum potential number of threads (<literal>MDS_MAX_THREADS</literal>)
 143       is 1024.</para>
 144       <note>
 145         <para>The OSS and MDS start two threads per service per CPT at mount
 146         time, and dynamically increase the number of running service threads in
 147         response to server load. Setting the <literal>*_num_threads</literal>
 148         module parameter starts the specified number of threads for that
 149         service immediately and disables automatic thread creation behavior.
 150         </para>
 151       </note>
 152       <para condition='l23'>Lustre software release 2.3 introduced new
 153       parameters to provide more control to administrators.</para>
 154       <itemizedlist>
 155         <listitem>
 156           <para>
 157           <literal>mds_rdpg_num_threads</literal> controls the number of threads
 158           in providing the read page service. The read page service handles
 159           file close and readdir operations.</para>
 160         </listitem>
 161         <listitem>
 162           <para>
 163           <literal>mds_attr_num_threads</literal> controls the number of threads
 164           in providing the setattr service to clients running Lustre software
 165           release 1.8.</para>
 166         </listitem>
 167       </itemizedlist>
 168     </section>
 169   </section>
 170   <section xml:id="dbdoclet.mdsbinding" condition='l23'>
 171     <title>
 172     <indexterm>
 173       <primary>tuning</primary>
 174       <secondary>MDS binding</secondary>
 175     </indexterm>Binding MDS Service Thread to CPU Partitions</title>
 176     <para>With the introduction of Node Affinity (
 177     <xref linkend="nodeaffdef" />) in Lustre software release 2.3, MDS threads
 178     can be bound to particular CPU partitions (CPTs) to improve CPU cache
 179     usage and memory locality.  Default values for CPT counts and CPU core
 180     bindings are selected automatically to provide good overall performance for
 181     a given CPU count. However, an administrator can deviate from these setting
 182     if they choose.  For details on specifying the mapping of CPU cores to
 183     CPTs see <xref linkend="dbdoclet.libcfstuning"/>.
 184     </para>
 185     <itemizedlist>
 186       <listitem>
 187         <para>
 188         <literal>mds_num_cpts=[EXPRESSION]</literal> binds the default MDS
 189         service threads to CPTs defined by
 190         <literal>EXPRESSION</literal>. For example
 191         <literal>mds_num_cpts=[0-3]</literal> will bind the MDS service threads
 192         to
 193         <literal>CPT[0,1,2,3]</literal>.</para>
 194       </listitem>
 195       <listitem>
 196         <para>
 197         <literal>mds_rdpg_num_cpts=[EXPRESSION]</literal> binds the read page
 198         service threads to CPTs defined by
 199         <literal>EXPRESSION</literal>. The read page service handles file close
 200         and readdir requests. For example
 201         <literal>mds_rdpg_num_cpts=[4]</literal> will bind the read page threads
 202         to
 203         <literal>CPT4</literal>.</para>
 204       </listitem>
 205       <listitem>
 206         <para>
 207         <literal>mds_attr_num_cpts=[EXPRESSION]</literal> binds the setattr
 208         service threads to CPTs defined by
 209         <literal>EXPRESSION</literal>.</para>
 210       </listitem>
 211     </itemizedlist>
 212         <para>Parameters must be set before module load in the file
 213     <literal>/etc/modprobe.d/lustre.conf</literal>. For example:
 214     <example><title>lustre.conf</title>
 215     <screen>options lnet networks=tcp0(eth0)
 216 options mdt mds_num_cpts=[0]</screen>
 217     </example>
 218     </para>
 219   </section>
 220   <section xml:id="dbdoclet.50438272_73839">
 221     <title>
 222     <indexterm>
 223       <primary>LNet</primary>
 224       <secondary>tuning</secondary>
 225     </indexterm>
 226     <indexterm>
 227       <primary>tuning</primary>
 228       <secondary>LNet</secondary>
 229     </indexterm>Tuning LNet Parameters</title>
 230     <para>This section describes LNet tunables, the use of which may be
 231     necessary on some systems to improve performance. To test the performance
 232     of your Lustre network, see
 233     <xref linkend='lnetselftest' />.</para>
 234     <section remap="h3">
 235       <title>Transmit and Receive Buffer Size</title>
 236       <para>The kernel allocates buffers for sending and receiving messages on
 237       a network.</para>
 238       <para>
 239       <literal>ksocklnd</literal> has separate parameters for the transmit and
 240       receive buffers.</para>
 241       <screen>
 242 options ksocklnd tx_buffer_size=0 rx_buffer_size=0
 243 </screen>
 244       <para>If these parameters are left at the default value (0), the system
 245       automatically tunes the transmit and receive buffer size. In almost every
 246       case, this default produces the best performance. Do not attempt to tune
 247       these parameters unless you are a network expert.</para>
 248     </section>
 249     <section remap="h3">
 250       <title>Hardware Interrupts (
 251       <literal>enable_irq_affinity</literal>)</title>
 252       <para>The hardware interrupts that are generated by network adapters may
 253       be handled by any CPU in the system. In some cases, we would like network
 254       traffic to remain local to a single CPU to help keep the processor cache
 255       warm and minimize the impact of context switches. This is helpful when an
 256       SMP system has more than one network interface and ideal when the number
 257       of interfaces equals the number of CPUs. To enable the
 258       <literal>enable_irq_affinity</literal> parameter, enter:</para>
 259       <screen>
 260 options ksocklnd enable_irq_affinity=1
 261 </screen>
 262       <para>In other cases, if you have an SMP platform with a single fast
 263       interface such as 10 Gb Ethernet and more than two CPUs, you may see
 264       performance improve by turning this parameter off.</para>
 265       <screen>
 266 options ksocklnd enable_irq_affinity=0
 267 </screen>
 268       <para>By default, this parameter is off. As always, you should test the
 269       performance to compare the impact of changing this parameter.</para>
 270     </section>
 271     <section condition='l23'>
 272       <title>
 273       <indexterm>
 274         <primary>tuning</primary>
 275         <secondary>Network interface binding</secondary>
 276       </indexterm>Binding Network Interface Against CPU Partitions</title>
 277       <para>Lustre software release 2.3 and beyond provide enhanced network
 278       interface control. The enhancement means that an administrator can bind
 279       an interface to one or more CPU partitions. Bindings are specified as
 280       options to the LNet modules. For more information on specifying module
 281       options, see
 282       <xref linkend="dbdoclet.50438293_15350" /></para>
 283       <para>For example,
 284       <literal>o2ib0(ib0)[0,1]</literal> will ensure that all messages for
 285       <literal>o2ib0</literal> will be handled by LND threads executing on
 286       <literal>CPT0</literal> and
 287       <literal>CPT1</literal>. An additional example might be:
 288       <literal>tcp1(eth0)[0]</literal>. Messages for
 289       <literal>tcp1</literal> are handled by threads on
 290       <literal>CPT0</literal>.</para>
 291     </section>
 292     <section>
 293       <title>
 294       <indexterm>
 295         <primary>tuning</primary>
 296         <secondary>Network interface credits</secondary>
 297       </indexterm>Network Interface Credits</title>
 298       <para>Network interface (NI) credits are shared across all CPU partitions
 299       (CPT). For example, if a machine has four CPTs and the number of NI
 300       credits is 512, then each partition has 128 credits. If a large number of
 301       CPTs exist on the system, LNet checks and validates the NI credits for
 302       each CPT to ensure each CPT has a workable number of credits. For
 303       example, if a machine has 16 CPTs and the number of NI credits is 256,
 304       then each partition only has 16 credits. 16 NI credits is low and could
 305       negatively impact performance. As a result, LNet automatically adjusts
 306       the credits to 8*
 307       <literal>peer_credits</literal>(
 308       <literal>peer_credits</literal> is 8 by default), so each partition has 64
 309       credits.</para>
 310       <para>Increasing the number of
 311       <literal>credits</literal>/
 312       <literal>peer_credits</literal> can improve the performance of high
 313       latency networks (at the cost of consuming more memory) by enabling LNet
 314       to send more inflight messages to a specific network/peer and keep the
 315       pipeline saturated.</para>
 316       <para>An administrator can modify the NI credit count using
 317       <literal>ksoclnd</literal> or
 318       <literal>ko2iblnd</literal>. In the example below, 256 credits are
 319       applied to TCP connections.</para>
 320       <screen>
 321 ksocklnd credits=256
 322 </screen>
 323       <para>Applying 256 credits to IB connections can be achieved with:</para>
 324       <screen>
 325 ko2iblnd credits=256
 326 </screen>
 327       <note condition="l23">
 328         <para>In Lustre software release 2.3 and beyond, LNet may revalidate
 329         the NI credits, so the administrator's request may not persist.</para>
 330       </note>
 331     </section>
 332     <section>
 333       <title>
 334       <indexterm>
 335         <primary>tuning</primary>
 336         <secondary>router buffers</secondary>
 337       </indexterm>Router Buffers</title>
 338       <para>When a node is set up as an LNet router, three pools of buffers are
 339       allocated: tiny, small and large. These pools are allocated per CPU
 340       partition and are used to buffer messages that arrive at the router to be
 341       forwarded to the next hop. The three different buffer sizes accommodate
 342       different size messages.</para>
 343       <para>If a message arrives that can fit in a tiny buffer then a tiny
 344       buffer is used, if a message doesn’t fit in a tiny buffer, but fits in a
 345       small buffer, then a small buffer is used. Finally if a message does not
 346       fit in either a tiny buffer or a small buffer, a large buffer is
 347       used.</para>
 348       <para>Router buffers are shared by all CPU partitions. For a machine with
 349       a large number of CPTs, the router buffer number may need to be specified
 350       manually for best performance. A low number of router buffers risks
 351       starving the CPU partitions of resources.</para>
 352       <itemizedlist>
 353         <listitem>
 354           <para>
 355           <literal>tiny_router_buffers</literal>: Zero payload buffers used for
 356           signals and acknowledgements.</para>
 357         </listitem>
 358         <listitem>
 359           <para>
 360           <literal>small_router_buffers</literal>: 4 KB payload buffers for
 361           small messages</para>
 362         </listitem>
 363         <listitem>
 364           <para>
 365           <literal>large_router_buffers</literal>: 1 MB maximum payload
 366           buffers, corresponding to the recommended RPC size of 1 MB.</para>
 367         </listitem>
 368       </itemizedlist>
 369       <para>The default setting for router buffers typically results in
 370       acceptable performance. LNet automatically sets a default value to reduce
 371       the likelihood of resource starvation. The size of a router buffer can be
 372       modified as shown in the example below. In this example, the size of the
 373       large buffer is modified using the
 374       <literal>large_router_buffers</literal> parameter.</para>
 375       <screen>
 376 lnet large_router_buffers=8192
 377 </screen>
 378       <note condition="l23">
 379         <para>In Lustre software release 2.3 and beyond, LNet may revalidate
 380         the router buffer setting, so the administrator's request may not
 381         persist.</para>
 382       </note>
 383     </section>
 384     <section>
 385       <title>
 386       <indexterm>
 387         <primary>tuning</primary>
 388         <secondary>portal round-robin</secondary>
 389       </indexterm>Portal Round-Robin</title>
 390       <para>Portal round-robin defines the policy LNet applies to deliver
 391       events and messages to the upper layers. The upper layers are PLRPC
 392       service or LNet selftest.</para>
 393       <para>If portal round-robin is disabled, LNet will deliver messages to
 394       CPTs based on a hash of the source NID. Hence, all messages from a
 395       specific peer will be handled by the same CPT. This can reduce data
 396       traffic between CPUs. However, for some workloads, this behavior may
 397       result in poorly balancing loads across the CPU.</para>
 398       <para>If portal round-robin is enabled, LNet will round-robin incoming
 399       events across all CPTs. This may balance load better across the CPU but
 400       can incur a cross CPU overhead.</para>
 401       <para>The current policy can be changed by an administrator with
 402       <literal>echo
 403       <replaceable>value</replaceable>&gt;
 404       /proc/sys/lnet/portal_rotor</literal>. There are four options for
 405       <literal>
 406         <replaceable>value</replaceable>
 407       </literal>:</para>
 408       <itemizedlist>
 409         <listitem>
 410           <para>
 411             <literal>OFF</literal>
 412           </para>
 413           <para>Disable portal round-robin on all incoming requests.</para>
 414         </listitem>
 415         <listitem>
 416           <para>
 417             <literal>ON</literal>
 418           </para>
 419           <para>Enable portal round-robin on all incoming requests.</para>
 420         </listitem>
 421         <listitem>
 422           <para>
 423             <literal>RR_RT</literal>
 424           </para>
 425           <para>Enable portal round-robin only for routed messages.</para>
 426         </listitem>
 427         <listitem>
 428           <para>
 429             <literal>HASH_RT</literal>
 430           </para>
 431           <para>Routed messages will be delivered to the upper layer by hash of
 432           source NID (instead of NID of router.) This is the default
 433           value.</para>
 434         </listitem>
 435       </itemizedlist>
 436     </section>
 437     <section>
 438       <title>LNet Peer Health</title>
 439       <para>Two options are available to help determine peer health:
 440       <itemizedlist>
 441         <listitem>
 442           <para>
 443           <literal>peer_timeout</literal>- The timeout (in seconds) before an
 444           aliveness query is sent to a peer. For example, if
 445           <literal>peer_timeout</literal> is set to
 446           <literal>180sec</literal>, an aliveness query is sent to the peer
 447           every 180 seconds. This feature only takes effect if the node is
 448           configured as an LNet router.</para>
 449           <para>In a routed environment, the
 450           <literal>peer_timeout</literal> feature should always be on (set to a
 451           value in seconds) on routers. If the router checker has been enabled,
 452           the feature should be turned off by setting it to 0 on clients and
 453           servers.</para>
 454           <para>For a non-routed scenario, enabling the
 455           <literal>peer_timeout</literal> option provides health information
 456           such as whether a peer is alive or not. For example, a client is able
 457           to determine if an MGS or OST is up when it sends it a message. If a
 458           response is received, the peer is alive; otherwise a timeout occurs
 459           when the request is made.</para>
 460           <para>In general,
 461           <literal>peer_timeout</literal> should be set to no less than the LND
 462           timeout setting. For more information about LND timeouts, see
 463           <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 464           linkend="section_c24_nt5_dl" />.</para>
 465           <para>When the
 466           <literal>o2iblnd</literal>(IB) driver is used,
 467           <literal>peer_timeout</literal> should be at least twice the value of
 468           the
 469           <literal>ko2iblnd</literal> keepalive option. for more information
 470           about keepalive options, see
 471           <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 472           linkend="section_ngq_qhy_zl" />.</para>
 473         </listitem>
 474         <listitem>
 475           <para>
 476           <literal>avoid_asym_router_failure</literal>– When set to 1, the
 477           router checker running on the client or a server periodically pings
 478           all the routers corresponding to the NIDs identified in the routes
 479           parameter setting on the node to determine the status of each router
 480           interface. The default setting is 1. (For more information about the
 481           LNet routes parameter, see
 482           <xref xmlns:xlink="http://www.w3.org/1999/xlink"
 483           linkend="dbdoclet.50438216_71227" /></para>
 484           <para>A router is considered down if any of its NIDs are down. For
 485           example, router X has three NIDs:
 486           <literal>Xnid1</literal>,
 487           <literal>Xnid2</literal>, and
 488           <literal>Xnid3</literal>. A client is connected to the router via
 489           <literal>Xnid1</literal>. The client has router checker enabled. The
 490           router checker periodically sends a ping to the router via
 491           <literal>Xnid1</literal>. The router responds to the ping with the
 492           status of each of its NIDs. In this case, it responds with
 493           <literal>Xnid1=up</literal>,
 494           <literal>Xnid2=up</literal>,
 495           <literal>Xnid3=down</literal>. If
 496           <literal>avoid_asym_router_failure==1</literal>, the router is
 497           considered down if any of its NIDs are down, so router X is
 498           considered down and will not be used for routing messages. If
 499           <literal>avoid_asym_router_failure==0</literal>, router X will
 500           continue to be used for routing messages.</para>
 501         </listitem>
 502       </itemizedlist></para>
 503       <para>The following router checker parameters must be set to the maximum
 504       value of the corresponding setting for this option on any client or
 505       server:
 506       <itemizedlist>
 507         <listitem>
 508           <para>
 509             <literal>dead_router_check_interval</literal>
 510           </para>
 511         </listitem>
 512         <listitem>
 513           <para>
 514             <literal>live_router_check_interval</literal>
 515           </para>
 516         </listitem>
 517         <listitem>
 518           <para>
 519             <literal>router_ping_timeout</literal>
 520           </para>
 521         </listitem>
 522       </itemizedlist></para>
 523       <para>For example, the
 524       <literal>dead_router_check_interval</literal> parameter on any router must
 525       be MAX.</para>
 526     </section>
 527   </section>
 528   <section xml:id="dbdoclet.libcfstuning" condition='l23'>
 529     <title>
 530     <indexterm>
 531       <primary>tuning</primary>
 532       <secondary>libcfs</secondary>
 533     </indexterm>libcfs Tuning</title>
 534     <para>Lustre software release 2.3 introduced binding service threads via
 535     CPU Partition Tables (CPTs). This allows the system administrator to
 536     fine-tune on which CPU cores the Lustre service threads are run, for both
 537     OSS and MDS services, as well as on the client.
 538     </para>
 539     <para>CPTs are useful to reserve some cores on the OSS or MDS nodes for
 540     system functions such as system monitoring, HA heartbeat, or similar
 541     tasks.  On the client it may be useful to restrict Lustre RPC service
 542     threads to a small subset of cores so that they do not interfere with
 543     computation, or because these cores are directly attached to the network
 544     interfaces.
 545     </para>
 546     <para>By default, the Lustre software will automatically generate CPU
 547     partitions (CPT) based on the number of CPUs in the system.
 548     The CPT count can be explicitly set on the libcfs module using
 549     <literal>cpu_npartitions=<replaceable>NUMBER</replaceable></literal>.
 550     The value of <literal>cpu_npartitions</literal> must be an integer between
 551     1 and the number of online CPUs.
 552     </para>
 553     <para condition='l29'>In Lustre 2.9 and later the default is to use
 554     one CPT per NUMA node.  In earlier versions of Lustre, by default there
 555     was a single CPT if the online CPU core count was four or fewer, and
 556     additional CPTs would be created depending on the number of CPU cores,
 557     typically with 4-8 cores per CPT.
 558     </para>
 559     <tip>
 560       <para>Setting <literal>cpu_npartitions=1</literal> will disable most
 561       of the SMP Node Affinity functionality.</para>
 562     </tip>
 563     <section>
 564       <title>CPU Partition String Patterns</title>
 565       <para>CPU partitions can be described using string pattern notation.
 566       If <literal>cpu_pattern=N</literal> is used, then there will be one
 567       CPT for each NUMA node in the system, with each CPT mapping all of
 568       the CPU cores for that NUMA node.
 569       </para>
 570       <para>It is also possible to explicitly specify the mapping between
 571       CPU cores and CPTs, for example:</para>
 572       <itemizedlist>
 573         <listitem>
 574           <para>
 575             <literal>cpu_pattern="0[2,4,6] 1[3,5,7]</literal>
 576           </para>
 577           <para>Create two CPTs, CPT0 contains cores 2, 4, and 6, while CPT1
 578           contains cores 3, 5, 7.  CPU cores 0 and 1 will not be used by Lustre
 579           service threads, and could be used for node services such as
 580           system monitoring, HA heartbeat threads, etc.  The binding of
 581           non-Lustre services to those CPU cores may be done in userspace
 582           using <literal>numactl(8)</literal> or other application-specific
 583           methods, but is beyond the scope of this document.</para>
 584         </listitem>
 585         <listitem>
 586           <para>
 587             <literal>cpu_pattern="N 0[0-3] 1[4-7]</literal>
 588           </para>
 589           <para>Create two CPTs, with CPT0 containing all CPUs in NUMA
 590           node[0-3], while CPT1 contains all CPUs in NUMA node [4-7].</para>
 591         </listitem>
 592       </itemizedlist>
 593       <para>The current configuration of the CPU partition can be read via
 594       <literal>lctl get_parm cpu_partition_table</literal>.  For example,
 595       a simple 4-core system has a single CPT with all four CPU cores:
 596       <screen>$ lctl get_param cpu_partition_table
 597 cpu_partition_table=0   : 0 1 2 3</screen>
 598       while a larger NUMA system with four 12-core CPUs may have four CPTs:
 599       <screen>$ lctl get_param cpu_partition_table
 600 cpu_partition_table=
 601 0       : 0 1 2 3 4 5 6 7 8 9 10 11
 602 1       : 12 13 14 15 16 17 18 19 20 21 22 23
 603 2       : 24 25 26 27 28 29 30 31 32 33 34 35
 604 3       : 36 37 38 39 40 41 42 43 44 45 46 47
 605 </screen>
 606       </para>
 607     </section>
 608   </section>
 609   <section xml:id="dbdoclet.lndtuning">
 610     <title>
 611     <indexterm>
 612       <primary>tuning</primary>
 613       <secondary>LND tuning</secondary>
 614     </indexterm>LND Tuning</title>
 615     <para>LND tuning allows the number of threads per CPU partition to be
 616     specified. An administrator can set the threads for both
 617     <literal>ko2iblnd</literal> and
 618     <literal>ksocklnd</literal> using the
 619     <literal>nscheds</literal> parameter. This adjusts the number of threads for
 620     each partition, not the overall number of threads on the LND.</para>
 621     <note>
 622       <para>Lustre software release 2.3 has greatly decreased the default
 623       number of threads for
 624       <literal>ko2iblnd</literal> and
 625       <literal>ksocklnd</literal> on high-core count machines. The current
 626       default values are automatically set and are chosen to work well across a
 627       number of typical scenarios.</para>
 628     </note>
 629     <section>
 630         <title>ko2iblnd Tuning</title>
 631         <para>The following table outlines the ko2iblnd module parameters to be used
 632     for tuning:</para>
 633         <informaltable frame="all">
 634           <tgroup cols="3">
 635             <colspec colname="c1" colwidth="50*" />
 636             <colspec colname="c2" colwidth="50*" />
 637             <colspec colname="c3" colwidth="50*" />
 638             <thead>
 639               <row>
 640                 <entry>
 641                   <para>
 642                     <emphasis role="bold">Module Parameter</emphasis>
 643                   </para>
 644                 </entry>
 645                 <entry>
 646                   <para>
 647                     <emphasis role="bold">Default Value</emphasis>
 648                   </para>
 649                 </entry>
 650                 <entry>
 651                   <para>
 652                     <emphasis role="bold">Description</emphasis>
 653                   </para>
 654                 </entry>
 655               </row>
 656             </thead>
 657             <tbody>
 658               <row>
 659                 <entry>
 660                   <para>
 661                     <literal>service</literal>
 662                   </para>
 663                 </entry>
 664                 <entry>
 665                   <para>
 666                     <literal>987</literal>
 667                   </para>
 668                 </entry>
 669                 <entry>
 670                   <para>Service number (within RDMA_PS_TCP).</para>
 671                 </entry>
 672               </row>
 673               <row>
 674                 <entry>
 675                   <para>
 676                     <literal>cksum</literal>
 677                   </para>
 678                 </entry>
 679                 <entry>
 680                   <para>
 681                     <literal>0</literal>
 682                   </para>
 683                 </entry>
 684                 <entry>
 685                   <para>Set non-zero to enable message (not RDMA) checksums.</para>
 686                 </entry>
 687               </row>
 688               <row>
 689                 <entry>
 690                   <para>
 691                     <literal>timeout</literal>
 692                   </para>
 693                 </entry>
 694                 <entry>
 695                 <para>
 696                   <literal>50</literal>
 697                 </para>
 698               </entry>
 699                 <entry>
 700                   <para>Timeout in seconds.</para>
 701                 </entry>
 702               </row>
 703               <row>
 704                 <entry>
 705                   <para>
 706                     <literal>nscheds</literal>
 707                   </para>
 708                 </entry>
 709                 <entry>
 710                   <para>
 711                     <literal>0</literal>
 712                   </para>
 713                 </entry>
 714                 <entry>
 715                   <para>Number of threads in each scheduler pool (per CPT).  Value of
 716           zero means we derive the number from the number of cores.</para>
 717                 </entry>
 718               </row>
 719               <row>
 720                 <entry>
 721                   <para>
 722                     <literal>conns_per_peer</literal>
 723                   </para>
 724                 </entry>
 725                 <entry>
 726                   <para>
 727                     <literal>4 (OmniPath), 1 (Everything else)</literal>
 728                   </para>
 729                 </entry>
 730                 <entry>
 731                   <para>Introduced in 2.10. Number of connections to each peer. Messages
 732           are sent round-robin over the connection pool.  Provides signifiant
 733           improvement with OmniPath.</para>
 734                 </entry>
 735               </row>
 736               <row>
 737                 <entry>
 738                   <para>
 739                     <literal>ntx</literal>
 740                   </para>
 741                 </entry>
 742                 <entry>
 743                   <para>
 744                     <literal>512</literal>
 745                   </para>
 746                 </entry>
 747                 <entry>
 748                   <para>Number of message descriptors allocated for each pool at
 749           startup. Grows at runtime. Shared by all CPTs.</para>
 750                 </entry>
 751               </row>
 752               <row>
 753                 <entry>
 754                   <para>
 755                     <literal>credits</literal>
 756                   </para>
 757                 </entry>
 758                 <entry>
 759                   <para>
 760                     <literal>256</literal>
 761                   </para>
 762                 </entry>
 763                 <entry>
 764                   <para>Number of concurrent sends on network.</para>
 765                 </entry>
 766               </row>
 767               <row>
 768                 <entry>
 769                   <para>
 770                     <literal>peer_credits</literal>
 771                   </para>
 772                 </entry>
 773                 <entry>
 774                   <para>
 775                     <literal>8</literal>
 776                   </para>
 777                 </entry>
 778                 <entry>
 779                   <para>Number of concurrent sends to 1 peer. Related/limited by IB
 780           queue size.</para>
 781                 </entry>
 782               </row>
 783               <row>
 784                 <entry>
 785                   <para>
 786                     <literal>peer_credits_hiw</literal>
 787                   </para>
 788                 </entry>
 789                 <entry>
 790                   <para>
 791                     <literal>0</literal>
 792                   </para>
 793                 </entry>
 794                 <entry>
 795                   <para>When eagerly to return credits.</para>
 796                 </entry>
 797               </row>
 798               <row>
 799                 <entry>
 800                   <para>
 801                     <literal>peer_buffer_credits</literal>
 802                   </para>
 803                 </entry>
 804                 <entry>
 805                   <para>
 806                     <literal>0</literal>
 807                   </para>
 808                 </entry>
 809                 <entry>
 810                   <para>Number per-peer router buffer credits.</para>
 811                 </entry>
 812               </row>
 813               <row>
 814                 <entry>
 815                   <para>
 816                     <literal>peer_timeout</literal>
 817                   </para>
 818                 </entry>
 819                 <entry>
 820                   <para>
 821                     <literal>180</literal>
 822                   </para>
 823                 </entry>
 824                 <entry>
 825                   <para>Seconds without aliveness news to declare peer dead (less than
 826           or equal to 0 to disable).</para>
 827                 </entry>
 828               </row>
 829               <row>
 830                 <entry>
 831                   <para>
 832                     <literal>ipif_name</literal>
 833                   </para>
 834                 </entry>
 835                 <entry>
 836                   <para>
 837                     <literal>ib0</literal>
 838                   </para>
 839                 </entry>
 840                 <entry>
 841                   <para>IPoIB interface name.</para>
 842                 </entry>
 843               </row>
 844               <row>
 845                 <entry>
 846                   <para>
 847                     <literal>retry_count</literal>
 848                   </para>
 849                 </entry>
 850                 <entry>
 851                   <para>
 852                     <literal>5</literal>
 853                   </para>
 854                 </entry>
 855                 <entry>
 856                   <para>Retransmissions when no ACK received.</para>
 857                 </entry>
 858               </row>
 859               <row>
 860                 <entry>
 861                   <para>
 862                     <literal>rnr_retry_count</literal>
 863                   </para>
 864                 </entry>
 865                 <entry>
 866                   <para>
 867                     <literal>6</literal>
 868                   </para>
 869                 </entry>
 870                 <entry>
 871                   <para>RNR retransmissions.</para>
 872                 </entry>
 873               </row>
 874               <row>
 875                 <entry>
 876                   <para>
 877                     <literal>keepalive</literal>
 878                   </para>
 879                 </entry>
 880                 <entry>
 881                   <para>
 882                     <literal>100</literal>
 883                   </para>
 884                 </entry>
 885                 <entry>
 886                   <para>Idle time in seconds before sending a keepalive.</para>
 887                 </entry>
 888               </row>
 889               <row>
 890                 <entry>
 891                   <para>
 892                     <literal>ib_mtu</literal>
 893                   </para>
 894                 </entry>
 895                 <entry>
 896                   <para>
 897                     <literal>0</literal>
 898                   </para>
 899                 </entry>
 900                 <entry>
 901                   <para>IB MTU 256/512/1024/2048/4096.</para>
 902                 </entry>
 903               </row>
 904               <row>
 905                 <entry>
 906                   <para>
 907                     <literal>concurrent_sends</literal>
 908                   </para>
 909                 </entry>
 910                 <entry>
 911                   <para>
 912                     <literal>0</literal>
 913                   </para>
 914                 </entry>
 915                 <entry>
 916                   <para>Send work-queue sizing. If zero, derived from
 917           <literal>map_on_demand</literal> and <literal>peer_credits</literal>.
 918           </para>
 919                 </entry>
 920               </row>
 921               <row>
 922                 <entry>
 923                   <para>
 924                     <literal>map_on_demand</literal>
 925                   </para>
 926                 </entry>
 927                 <entry>
 928                   <para>
 929             <literal>0 (pre-4.8 Linux) 1 (4.8 Linux onward) 32 (OmniPath)</literal>
 930                   </para>
 931                 </entry>
 932                 <entry>
 933                   <para>Number of fragments reserved for connection.  If zero, use
 934           global memory region (found to be security issue).  If non-zero, use
 935           FMR or FastReg for memory registration.  Value needs to agree between
 936           both peers of connection.</para>
 937                 </entry>
 938               </row>
 939               <row>
 940                 <entry>
 941                   <para>
 942                     <literal>fmr_pool_size</literal>
 943                   </para>
 944                 </entry>
 945                 <entry>
 946                   <para>
 947                     <literal>512</literal>
 948                   </para>
 949                 </entry>
 950                 <entry>
 951                   <para>Size of fmr pool on each CPT (>= ntx / 4).  Grows at runtime.
 952           </para>
 953                 </entry>
 954               </row>
 955               <row>
 956                 <entry>
 957                   <para>
 958                     <literal>fmr_flush_trigger</literal>
 959                   </para>
 960                 </entry>
 961                 <entry>
 962                   <para>
 963                     <literal>384</literal>
 964                   </para>
 965                 </entry>
 966                 <entry>
 967                   <para>Number dirty FMRs that triggers pool flush.</para>
 968                 </entry>
 969               </row>
 970               <row>
 971                 <entry>
 972                   <para>
 973                     <literal>fmr_cache</literal>
 974                   </para>
 975                 </entry>
 976                 <entry>
 977                   <para>
 978                     <literal>1</literal>
 979                   </para>
 980                 </entry>
 981                 <entry>
 982                   <para>Non-zero to enable FMR caching.</para>
 983                 </entry>
 984               </row>
 985               <row>
 986                 <entry>
 987                   <para>
 988                     <literal>dev_failover</literal>
 989                   </para>
 990                 </entry>
 991                 <entry>
 992                   <para>
 993                     <literal>0</literal>
 994                   </para>
 995                 </entry>
 996                 <entry>
 997                   <para>HCA failover for bonding (0 OFF, 1 ON, other values reserved).
 998           </para>
 999                 </entry>
1000               </row>
1001               <row>
1002                 <entry>
1003                   <para>
1004                     <literal>require_privileged_port</literal>
1005                   </para>
1006                 </entry>
1007                 <entry>
1008                   <para>
1009                     <literal>0</literal>
1010                   </para>
1011                 </entry>
1012                 <entry>
1013                   <para>Require privileged port when accepting connection.</para>
1014                 </entry>
1015               </row>
1016               <row>
1017                 <entry>
1018                   <para>
1019                     <literal>use_privileged_port</literal>
1020                   </para>
1021                 </entry>
1022                 <entry>
1023                   <para>
1024                     <literal>1</literal>
1025                   </para>
1026                 </entry>
1027                 <entry>
1028                   <para>Use privileged port when initiating connection.</para>
1029                 </entry>
1030               </row>
1031               <row>
1032                 <entry>
1033                   <para>
1034                     <literal>wrq_sge</literal>
1035                   </para>
1036                 </entry>
1037                 <entry>
1038                   <para>
1039                     <literal>2</literal>
1040                   </para>
1041                 </entry>
1042                 <entry>
1043                   <para>Introduced in 2.10. Number scatter/gather element groups per
1044           work request.  Used to deal with fragmentations which can consume
1045           double the number of work requests.</para>
1046                 </entry>
1047               </row>
1048             </tbody>
1049           </tgroup>
1050         </informaltable>
1051     </section>
1052   </section>
1053   <section xml:id="dbdoclet.nrstuning" condition='l24'>
1054     <title>
1055     <indexterm>
1056       <primary>tuning</primary>
1057       <secondary>Network Request Scheduler (NRS) Tuning</secondary>
1058     </indexterm>Network Request Scheduler (NRS) Tuning</title>
1059     <para>The Network Request Scheduler (NRS) allows the administrator to
1060     influence the order in which RPCs are handled at servers, on a per-PTLRPC
1061     service basis, by providing different policies that can be activated and
1062     tuned in order to influence the RPC ordering. The aim of this is to provide
1063     for better performance, and possibly discrete performance characteristics
1064     using future policies.</para>
1065     <para>The NRS policy state of a PTLRPC service can be read and set via the
1066     <literal>{service}.nrs_policies</literal> tunable. To read a PTLRPC
1067     service's NRS policy state, run:</para>
1068     <screen>
1069 lctl get_param {service}.nrs_policies
1070 </screen>
1071     <para>For example, to read the NRS policy state of the
1072     <literal>ost_io</literal> service, run:</para>
1073     <screen>
1074 $ lctl get_param ost.OSS.ost_io.nrs_policies
1075 ost.OSS.ost_io.nrs_policies=
1076
1077 regular_requests:
1078   - name: fifo
1079     state: started
1080     fallback: yes
1081     queued: 0
1082     active: 0
1083
1084   - name: crrn
1085     state: stopped
1086     fallback: no
1087     queued: 0
1088     active: 0
1089
1090   - name: orr
1091     state: stopped
1092     fallback: no
1093     queued: 0
1094     active: 0
1095
1096   - name: trr
1097     state: started
1098     fallback: no
1099     queued: 2420
1100     active: 268
1101
1102 high_priority_requests:
1103   - name: fifo
1104     state: started
1105     fallback: yes
1106     queued: 0
1107     active: 0
1108
1109   - name: crrn
1110     state: stopped
1111     fallback: no
1112     queued: 0
1113     active: 0
1114
1115   - name: orr
1116     state: stopped
1117     fallback: no
1118     queued: 0
1119     active: 0
1120
1121   - name: trr
1122     state: stopped
1123     fallback: no
1124     queued: 0
1125     active: 0
1126
1127 </screen>
1128     <para>NRS policy state is shown in either one or two sections, depending on
1129     the PTLRPC service being queried. The first section is named
1130     <literal>regular_requests</literal> and is available for all PTLRPC
1131     services, optionally followed by a second section which is named
1132     <literal>high_priority_requests</literal>. This is because some PTLRPC
1133     services are able to treat some types of RPCs as higher priority ones, such
1134     that they are handled by the server with higher priority compared to other,
1135     regular RPC traffic. For PTLRPC services that do not support high-priority
1136     RPCs, you will only see the
1137     <literal>regular_requests</literal> section.</para>
1138     <para>There is a separate instance of each NRS policy on each PTLRPC
1139     service for handling regular and high-priority RPCs (if the service
1140     supports high-priority RPCs). For each policy instance, the following
1141     fields are shown:</para>
1142     <informaltable frame="all">
1143       <tgroup cols="2">
1144         <colspec colname="c1" colwidth="50*" />
1145         <colspec colname="c2" colwidth="50*" />
1146         <thead>
1147           <row>
1148             <entry>
1149               <para>
1150                 <emphasis role="bold">Field</emphasis>
1151               </para>
1152             </entry>
1153             <entry>
1154               <para>
1155                 <emphasis role="bold">Description</emphasis>
1156               </para>
1157             </entry>
1158           </row>
1159         </thead>
1160         <tbody>
1161           <row>
1162             <entry>
1163               <para>
1164                 <literal>name</literal>
1165               </para>
1166             </entry>
1167             <entry>
1168               <para>The name of the policy.</para>
1169             </entry>
1170           </row>
1171           <row>
1172             <entry>
1173               <para>
1174                 <literal>state</literal>
1175               </para>
1176             </entry>
1177             <entry>
1178               <para>The state of the policy; this can be any of
1179               <literal>invalid, stopping, stopped, starting, started</literal>.
1180               A fully enabled policy is in the
1181               <literal>started</literal> state.</para>
1182             </entry>
1183           </row>
1184           <row>
1185             <entry>
1186               <para>
1187                 <literal>fallback</literal>
1188               </para>
1189             </entry>
1190             <entry>
1191               <para>Whether the policy is acting as a fallback policy or not. A
1192               fallback policy is used to handle RPCs that other enabled
1193               policies fail to handle, or do not support the handling of. The
1194               possible values are
1195               <literal>no, yes</literal>. Currently, only the FIFO policy can
1196               act as a fallback policy.</para>
1197             </entry>
1198           </row>
1199           <row>
1200             <entry>
1201               <para>
1202                 <literal>queued</literal>
1203               </para>
1204             </entry>
1205             <entry>
1206               <para>The number of RPCs that the policy has waiting to be
1207               serviced.</para>
1208             </entry>
1209           </row>
1210           <row>
1211             <entry>
1212               <para>
1213                 <literal>active</literal>
1214               </para>
1215             </entry>
1216             <entry>
1217               <para>The number of RPCs that the policy is currently
1218               handling.</para>
1219             </entry>
1220           </row>
1221         </tbody>
1222       </tgroup>
1223     </informaltable>
1224     <para>To enable an NRS policy on a PTLRPC service run:</para>
1225     <screen>
1226 lctl set_param {service}.nrs_policies=
1227 <replaceable>policy_name</replaceable>
1228 </screen>
1229     <para>This will enable the policy
1230     <replaceable>policy_name</replaceable>for both regular and high-priority
1231     RPCs (if the PLRPC service supports high-priority RPCs) on the given
1232     service. For example, to enable the CRR-N NRS policy for the ldlm_cbd
1233     service, run:</para>
1234     <screen>
1235 $ lctl set_param ldlm.services.ldlm_cbd.nrs_policies=crrn
1236 ldlm.services.ldlm_cbd.nrs_policies=crrn
1237
1238 </screen>
1239     <para>For PTLRPC services that support high-priority RPCs, you can also
1240     supply an optional
1241     <replaceable>reg|hp</replaceable>token, in order to enable an NRS policy
1242     for handling only regular or high-priority RPCs on a given PTLRPC service,
1243     by running:</para>
1244     <screen>
1245 lctl set_param {service}.nrs_policies="
1246 <replaceable>policy_name</replaceable>
1247 <replaceable>reg|hp</replaceable>"
1248 </screen>
1249     <para>For example, to enable the TRR policy for handling only regular, but
1250     not high-priority RPCs on the
1251     <literal>ost_io</literal> service, run:</para>
1252     <screen>
1253 $ lctl set_param ost.OSS.ost_io.nrs_policies="trr reg"
1254 ost.OSS.ost_io.nrs_policies="trr reg"
1255
1256 </screen>
1257     <note>
1258       <para>When enabling an NRS policy, the policy name must be given in
1259       lower-case characters, otherwise the operation will fail with an error
1260       message.</para>
1261     </note>
1262     <section>
1263       <title>
1264       <indexterm>
1265         <primary>tuning</primary>
1266         <secondary>Network Request Scheduler (NRS) Tuning</secondary>
1267         <tertiary>first in, first out (FIFO) policy</tertiary>
1268       </indexterm>First In, First Out (FIFO) policy</title>
1269       <para>The first in, first out (FIFO) policy handles RPCs in a service in
1270       the same order as they arrive from the LNet layer, so no special
1271       processing takes place to modify the RPC handling stream. FIFO is the
1272       default policy for all types of RPCs on all PTLRPC services, and is
1273       always enabled irrespective of the state of other policies, so that it
1274       can be used as a backup policy, in case a more elaborate policy that has
1275       been enabled fails to handle an RPC, or does not support handling a given
1276       type of RPC.</para>
1277       <para>The FIFO policy has no tunables that adjust its behaviour.</para>
1278     </section>
1279     <section>
1280       <title>
1281       <indexterm>
1282         <primary>tuning</primary>
1283         <secondary>Network Request Scheduler (NRS) Tuning</secondary>
1284         <tertiary>client round-robin over NIDs (CRR-N) policy</tertiary>
1285       </indexterm>Client Round-Robin over NIDs (CRR-N) policy</title>
1286       <para>The client round-robin over NIDs (CRR-N) policy performs batched
1287       round-robin scheduling of all types of RPCs, with each batch consisting
1288       of RPCs originating from the same client node, as identified by its NID.
1289       CRR-N aims to provide for better resource utilization across the cluster,
1290       and to help shorten completion times of jobs in some cases, by
1291       distributing available bandwidth more evenly across all clients.</para>
1292       <para>The CRR-N policy can be enabled on all types of PTLRPC services,
1293       and has the following tunable that can be used to adjust its
1294       behavior:</para>
1295       <itemizedlist>
1296         <listitem>
1297           <para>
1298             <literal>{service}.nrs_crrn_quantum</literal>
1299           </para>
1300           <para>The
1301           <literal>{service}.nrs_crrn_quantum</literal> tunable determines the
1302           maximum allowed size of each batch of RPCs; the unit of measure is in
1303           number of RPCs. To read the maximum allowed batch size of a CRR-N
1304           policy, run:</para>
1305           <screen>
1306 lctl get_param {service}.nrs_crrn_quantum
1307 </screen>
1308           <para>For example, to read the maximum allowed batch size of a CRR-N
1309           policy on the ost_io service, run:</para>
1310           <screen>
1311 $ lctl get_param ost.OSS.ost_io.nrs_crrn_quantum
1312 ost.OSS.ost_io.nrs_crrn_quantum=reg_quantum:16
1313 hp_quantum:8
1314
1315 </screen>
1316           <para>You can see that there is a separate maximum allowed batch size
1317           value for regular (
1318           <literal>reg_quantum</literal>) and high-priority (
1319           <literal>hp_quantum</literal>) RPCs (if the PTLRPC service supports
1320           high-priority RPCs).</para>
1321           <para>To set the maximum allowed batch size of a CRR-N policy on a
1322           given service, run:</para>
1323           <screen>
1324 lctl set_param {service}.nrs_crrn_quantum=
1325 <replaceable>1-65535</replaceable>
1326 </screen>
1327           <para>This will set the maximum allowed batch size on a given
1328           service, for both regular and high-priority RPCs (if the PLRPC
1329           service supports high-priority RPCs), to the indicated value.</para>
1330           <para>For example, to set the maximum allowed batch size on the
1331           ldlm_canceld service to 16 RPCs, run:</para>
1332           <screen>
1333 $ lctl set_param ldlm.services.ldlm_canceld.nrs_crrn_quantum=16
1334 ldlm.services.ldlm_canceld.nrs_crrn_quantum=16
1335
1336 </screen>
1337           <para>For PTLRPC services that support high-priority RPCs, you can
1338           also specify a different maximum allowed batch size for regular and
1339           high-priority RPCs, by running:</para>
1340           <screen>
1341 $ lctl set_param {service}.nrs_crrn_quantum=
1342 <replaceable>reg_quantum|hp_quantum</replaceable>:
1343 <replaceable>1-65535</replaceable>"
1344 </screen>
1345           <para>For example, to set the maximum allowed batch size on the
1346           ldlm_canceld service, for high-priority RPCs to 32, run:</para>
1347           <screen>
1348 $ lctl set_param ldlm.services.ldlm_canceld.nrs_crrn_quantum="hp_quantum:32"
1349 ldlm.services.ldlm_canceld.nrs_crrn_quantum=hp_quantum:32
1350
1351 </screen>
1352           <para>By using the last method, you can also set the maximum regular
1353           and high-priority RPC batch sizes to different values, in a single
1354           command invocation.</para>
1355         </listitem>
1356       </itemizedlist>
1357     </section>
1358     <section>
1359       <title>
1360       <indexterm>
1361         <primary>tuning</primary>
1362         <secondary>Network Request Scheduler (NRS) Tuning</secondary>
1363         <tertiary>object-based round-robin (ORR) policy</tertiary>
1364       </indexterm>Object-based Round-Robin (ORR) policy</title>
1365       <para>The object-based round-robin (ORR) policy performs batched
1366       round-robin scheduling of bulk read write (brw) RPCs, with each batch
1367       consisting of RPCs that pertain to the same backend-file system object,
1368       as identified by its OST FID.</para>
1369       <para>The ORR policy is only available for use on the ost_io service. The
1370       RPC batches it forms can potentially consist of mixed bulk read and bulk
1371       write RPCs. The RPCs in each batch are ordered in an ascending manner,
1372       based on either the file offsets, or the physical disk offsets of each
1373       RPC (only applicable to bulk read RPCs).</para>
1374       <para>The aim of the ORR policy is to provide for increased bulk read
1375       throughput in some cases, by ordering bulk read RPCs (and potentially
1376       bulk write RPCs), and thus minimizing costly disk seek operations.
1377       Performance may also benefit from any resulting improvement in resource
1378       utilization, or by taking advantage of better locality of reference
1379       between RPCs.</para>
1380       <para>The ORR policy has the following tunables that can be used to
1381       adjust its behaviour:</para>
1382       <itemizedlist>
1383         <listitem>
1384           <para>
1385             <literal>ost.OSS.ost_io.nrs_orr_quantum</literal>
1386           </para>
1387           <para>The
1388           <literal>ost.OSS.ost_io.nrs_orr_quantum</literal> tunable determines
1389           the maximum allowed size of each batch of RPCs; the unit of measure
1390           is in number of RPCs. To read the maximum allowed batch size of the
1391           ORR policy, run:</para>
1392           <screen>
1393 $ lctl get_param ost.OSS.ost_io.nrs_orr_quantum
1394 ost.OSS.ost_io.nrs_orr_quantum=reg_quantum:256
1395 hp_quantum:16
1396
1397 </screen>
1398           <para>You can see that there is a separate maximum allowed batch size
1399           value for regular (
1400           <literal>reg_quantum</literal>) and high-priority (
1401           <literal>hp_quantum</literal>) RPCs (if the PTLRPC service supports
1402           high-priority RPCs).</para>
1403           <para>To set the maximum allowed batch size for the ORR policy,
1404           run:</para>
1405           <screen>
1406 $ lctl set_param ost.OSS.ost_io.nrs_orr_quantum=
1407 <replaceable>1-65535</replaceable>
1408 </screen>
1409           <para>This will set the maximum allowed batch size for both regular
1410           and high-priority RPCs, to the indicated value.</para>
1411           <para>You can also specify a different maximum allowed batch size for
1412           regular and high-priority RPCs, by running:</para>
1413           <screen>
1414 $ lctl set_param ost.OSS.ost_io.nrs_orr_quantum=
1415 <replaceable>reg_quantum|hp_quantum</replaceable>:
1416 <replaceable>1-65535</replaceable>
1417 </screen>
1418           <para>For example, to set the maximum allowed batch size for regular
1419           RPCs to 128, run:</para>
1420           <screen>
1421 $ lctl set_param ost.OSS.ost_io.nrs_orr_quantum=reg_quantum:128
1422 ost.OSS.ost_io.nrs_orr_quantum=reg_quantum:128
1423
1424 </screen>
1425           <para>By using the last method, you can also set the maximum regular
1426           and high-priority RPC batch sizes to different values, in a single
1427           command invocation.</para>
1428         </listitem>
1429         <listitem>
1430           <para>
1431             <literal>ost.OSS.ost_io.nrs_orr_offset_type</literal>
1432           </para>
1433           <para>The
1434           <literal>ost.OSS.ost_io.nrs_orr_offset_type</literal> tunable
1435           determines whether the ORR policy orders RPCs within each batch based
1436           on logical file offsets or physical disk offsets. To read the offset
1437           type value for the ORR policy, run:</para>
1438           <screen>
1439 $ lctl get_param ost.OSS.ost_io.nrs_orr_offset_type
1440 ost.OSS.ost_io.nrs_orr_offset_type=reg_offset_type:physical
1441 hp_offset_type:logical
1442
1443 </screen>
1444           <para>You can see that there is a separate offset type value for
1445           regular (
1446           <literal>reg_offset_type</literal>) and high-priority (
1447           <literal>hp_offset_type</literal>) RPCs.</para>
1448           <para>To set the ordering type for the ORR policy, run:</para>
1449           <screen>
1450 $ lctl set_param ost.OSS.ost_io.nrs_orr_offset_type=
1451 <replaceable>physical|logical</replaceable>
1452 </screen>
1453           <para>This will set the offset type for both regular and
1454           high-priority RPCs, to the indicated value.</para>
1455           <para>You can also specify a different offset type for regular and
1456           high-priority RPCs, by running:</para>
1457           <screen>
1458 $ lctl set_param ost.OSS.ost_io.nrs_orr_offset_type=
1459 <replaceable>reg_offset_type|hp_offset_type</replaceable>:
1460 <replaceable>physical|logical</replaceable>
1461 </screen>
1462           <para>For example, to set the offset type for high-priority RPCs to
1463           physical disk offsets, run:</para>
1464           <screen>
1465 $ lctl set_param ost.OSS.ost_io.nrs_orr_offset_type=hp_offset_type:physical
1466 ost.OSS.ost_io.nrs_orr_offset_type=hp_offset_type:physical
1467 </screen>
1468           <para>By using the last method, you can also set offset type for
1469           regular and high-priority RPCs to different values, in a single
1470           command invocation.</para>
1471           <note>
1472             <para>Irrespective of the value of this tunable, only logical
1473             offsets can, and are used for ordering bulk write RPCs.</para>
1474           </note>
1475         </listitem>
1476         <listitem>
1477           <para>
1478             <literal>ost.OSS.ost_io.nrs_orr_supported</literal>
1479           </para>
1480           <para>The
1481           <literal>ost.OSS.ost_io.nrs_orr_supported</literal> tunable determines
1482           the type of RPCs that the ORR policy will handle. To read the types
1483           of supported RPCs by the ORR policy, run:</para>
1484           <screen>
1485 $ lctl get_param ost.OSS.ost_io.nrs_orr_supported
1486 ost.OSS.ost_io.nrs_orr_supported=reg_supported:reads
1487 hp_supported=reads_and_writes
1488
1489 </screen>
1490           <para>You can see that there is a separate supported 'RPC types'
1491           value for regular (
1492           <literal>reg_supported</literal>) and high-priority (
1493           <literal>hp_supported</literal>) RPCs.</para>
1494           <para>To set the supported RPC types for the ORR policy, run:</para>
1495           <screen>
1496 $ lctl set_param ost.OSS.ost_io.nrs_orr_supported=
1497 <replaceable>reads|writes|reads_and_writes</replaceable>
1498 </screen>
1499           <para>This will set the supported RPC types for both regular and
1500           high-priority RPCs, to the indicated value.</para>
1501           <para>You can also specify a different supported 'RPC types' value
1502           for regular and high-priority RPCs, by running:</para>
1503           <screen>
1504 $ lctl set_param ost.OSS.ost_io.nrs_orr_supported=
1505 <replaceable>reg_supported|hp_supported</replaceable>:
1506 <replaceable>reads|writes|reads_and_writes</replaceable>
1507 </screen>
1508           <para>For example, to set the supported RPC types to bulk read and
1509           bulk write RPCs for regular requests, run:</para>
1510           <screen>
1511 $ lctl set_param
1512 ost.OSS.ost_io.nrs_orr_supported=reg_supported:reads_and_writes
1513 ost.OSS.ost_io.nrs_orr_supported=reg_supported:reads_and_writes
1514
1515 </screen>
1516           <para>By using the last method, you can also set the supported RPC
1517           types for regular and high-priority RPC to different values, in a
1518           single command invocation.</para>
1519         </listitem>
1520       </itemizedlist>
1521     </section>
1522     <section>
1523       <title>
1524       <indexterm>
1525         <primary>tuning</primary>
1526         <secondary>Network Request Scheduler (NRS) Tuning</secondary>
1527         <tertiary>Target-based round-robin (TRR) policy</tertiary>
1528       </indexterm>Target-based Round-Robin (TRR) policy</title>
1529       <para>The target-based round-robin (TRR) policy performs batched
1530       round-robin scheduling of brw RPCs, with each batch consisting of RPCs
1531       that pertain to the same OST, as identified by its OST index.</para>
1532       <para>The TRR policy is identical to the object-based round-robin (ORR)
1533       policy, apart from using the brw RPC's target OST index instead of the
1534       backend-fs object's OST FID, for determining the RPC scheduling order.
1535       The goals of TRR are effectively the same as for ORR, and it uses the
1536       following tunables to adjust its behaviour:</para>
1537       <itemizedlist>
1538         <listitem>
1539           <para>
1540             <literal>ost.OSS.ost_io.nrs_trr_quantum</literal>
1541           </para>
1542           <para>The purpose of this tunable is exactly the same as for the
1543           <literal>ost.OSS.ost_io.nrs_orr_quantum</literal> tunable for the ORR
1544           policy, and you can use it in exactly the same way.</para>
1545         </listitem>
1546         <listitem>
1547           <para>
1548             <literal>ost.OSS.ost_io.nrs_trr_offset_type</literal>
1549           </para>
1550           <para>The purpose of this tunable is exactly the same as for the
1551           <literal>ost.OSS.ost_io.nrs_orr_offset_type</literal> tunable for the
1552           ORR policy, and you can use it in exactly the same way.</para>
1553         </listitem>
1554         <listitem>
1555           <para>
1556             <literal>ost.OSS.ost_io.nrs_trr_supported</literal>
1557           </para>
1558           <para>The purpose of this tunable is exactly the same as for the
1559           <literal>ost.OSS.ost_io.nrs_orr_supported</literal> tunable for the
1560           ORR policy, and you can use it in exactly the sme way.</para>
1561         </listitem>
1562       </itemizedlist>
1563     </section>
1564     <section xml:id="dbdoclet.tbftuning" condition='l26'>
1565       <title>
1566       <indexterm>
1567         <primary>tuning</primary>
1568         <secondary>Network Request Scheduler (NRS) Tuning</secondary>
1569         <tertiary>Token Bucket Filter (TBF) policy</tertiary>
1570       </indexterm>Token Bucket Filter (TBF) policy</title>
1571       <para>The TBF (Token Bucket Filter) is a Lustre NRS policy which enables
1572       Lustre services to enforce the RPC rate limit on clients/jobs for QoS
1573       (Quality of Service) purposes.</para>
1574       <figure>
1575         <title>The internal structure of TBF policy</title>
1576         <mediaobject>
1577           <imageobject>
1578             <imagedata scalefit="1" width="100%"
1579             fileref="figures/TBF_policy.svg" />
1580           </imageobject>
1581           <textobject>
1582             <phrase>The internal structure of TBF policy</phrase>
1583           </textobject>
1584         </mediaobject>
1585       </figure>
1586       <para>When a RPC request arrives, TBF policy puts it to a waiting queue
1587       according to its classification. The classification of RPC requests is
1588       based on either NID or JobID of the RPC according to the configure of
1589       TBF. TBF policy maintains multiple queues in the system, one queue for
1590       each category in the classification of RPC requests. The requests waits
1591       for tokens in the FIFO queue before they have been handled so as to keep
1592       the RPC rates under the limits.</para>
1593       <para>When Lustre services are too busy to handle all of the requests in
1594       time, all of the specified rates of the queues will not be satisfied.
1595       Nothing bad will happen except some of the RPC rates are slower than
1596       configured. In this case, the queue with higher rate will have an
1597       advantage over the queues with lower rates, but none of them will be
1598       starved.</para>
1599       <para>To manage the RPC rate of queues, we don't need to set the rate of
1600       each queue manually. Instead, we define rules which TBF policy matches to
1601       determine RPC rate limits. All of the defined rules are organized as an
1602       ordered list. Whenever a queue is newly created, it goes though the rule
1603       list and takes the first matched rule as its rule, so that the queue
1604       knows its RPC token rate. A rule can be added to or removed from the list
1605       at run time. Whenever the list of rules is changed, the queues will
1606       update their matched rules.</para>
1607       <itemizedlist>
1608         <listitem>
1609           <para>
1610             <literal>ost.OSS.ost_io.nrs_tbf_rule</literal>
1611           </para>
1612           <para>The format of the rule start command of TBF policy is as
1613           follows:</para>
1614           <screen>
1615 $ lctl set_param x.x.x.nrs_tbf_rule=
1616           "[reg|hp] start <replaceable>rule_name</replaceable> <replaceable>arguments</replaceable>..."
1617 </screen>
1618           <para>The '
1619           <replaceable>rule_name</replaceable>' argument is a string which
1620           identifies a rule. The format of the '
1621           <replaceable>arguments</replaceable>' is changing according to the
1622           type of the TBF policy. For the NID based TBF policy, its format is
1623           as follows:</para>
1624           <screen>
1625 $ lctl set_param x.x.x.nrs_tbf_rule=
1626           "[reg|hp] start <replaceable>rule_name</replaceable> {<replaceable>nidlist</replaceable>} <replaceable>rate</replaceable>"
1627 </screen>
1628           <para>The format of '
1629           <replaceable>nidlist</replaceable>' argument is the same as the
1630           format when configuring LNet route. The '
1631           <replaceable>rate</replaceable>' argument is the RPC rate of the
1632           rule, means the upper limit number of requests per second.</para>
1633           <para>Following commands are valid. Please note that a newly started
1634           rule is prior to old rules, so the order of starting rules is
1635           critical too.</para>
1636           <screen>
1637 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
1638           "start other_clients {192.168.*.*@tcp} 50"
1639 </screen>
1640           <screen>
1641 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
1642           "start loginnode {192.168.1.1@tcp} 100"
1643 </screen>
1644           <para>General rule can be replaced by two rules (reg and hp) as
1645           follows:</para>
1646           <screen>
1647 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
1648           "reg start loginnode {192.168.1.1@tcp} 100"
1649 </screen>
1650           <screen>
1651 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
1652           "hp start loginnode {192.168.1.1@tcp} 100"
1653 </screen>
1654           <screen>
1655 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
1656           "start computes {192.168.1.[2-128]@tcp} 500"
1657 </screen>
1658           <para>The above rules will put an upper limit for servers to process
1659           at most 5x as many RPCs from compute nodes as login nodes.</para>
1660           <para>For the JobID (please see
1661           <xref xmlns:xlink="http://www.w3.org/1999/xlink"
1662                 linkend="dbdoclet.jobstats" /> for more details) based TBF
1663           policy, its format is as follows:</para>
1664           <screen>
1665 $ lctl set_param x.x.x.nrs_tbf_rule=
1666           "[reg|hp] start <replaceable>name</replaceable> {<replaceable>jobid_list</replaceable>} <replaceable>rate</replaceable>"
1667 </screen>
1668           <para>Following commands are valid:</para>
1669           <screen>
1670 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
1671           "start user1 {iozone.500 dd.500} 100"
1672 </screen>
1673           <screen>
1674 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
1675           "start iozone_user1 {iozone.500} 100"
1676 </screen>
1677           <para>Same as nid, could use reg and hp rules separately:</para>
1678           <screen>
1679 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
1680           "hp start iozone_user1 {iozone.500} 100"
1681 </screen>
1682           <screen>
1683 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule=
1684           "reg start iozone_user1 {iozone.500} 100"
1685 </screen>
1686           <para>The format of the rule change command of TBF policy is as
1687           follows:</para>
1688           <screen>
1689 $ lctl set_param x.x.x.nrs_tbf_rule=
1690           "[reg|hp] change <replaceable>rule_name</replaceable> <replaceable>rate</replaceable>"
1691 </screen>
1692           <para>Following commands are valid:</para>
1693           <screen>
1694 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="change loginnode 200"
1695 </screen>
1696           <screen>
1697 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="reg change loginnode 200"
1698 </screen>
1699           <screen>
1700 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="hp change loginnode 200"
1701 </screen>
1702           <para>The format of the rule stop command of TBF policy is as
1703           follows:</para>
1704           <screen>
1705 $ lctl set_param x.x.x.nrs_tbf_rule="[reg|hp] stop
1706 <replaceable>rule_name</replaceable>"
1707 </screen>
1708           <para>Following commands are valid:</para>
1709           <screen>
1710 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="stop loginnode"
1711 </screen>
1712           <screen>
1713 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="reg stop loginnode"
1714 </screen>
1715           <screen>
1716 $ lctl set_param ost.OSS.ost_io.nrs_tbf_rule="hp stop loginnode"
1717 </screen>
1718         </listitem>
1719       </itemizedlist>
1720     </section>
1721   </section>
1722   <section xml:id="dbdoclet.50438272_25884">
1723     <title>
1724     <indexterm>
1725       <primary>tuning</primary>
1726       <secondary>lockless I/O</secondary>
1727     </indexterm>Lockless I/O Tunables</title>
1728     <para>The lockless I/O tunable feature allows servers to ask clients to do
1729     lockless I/O (the server does the locking on behalf of clients) for
1730     contended files to avoid lock ping-pong.</para>
1731     <para>The lockless I/O patch introduces these tunables:</para>
1732     <itemizedlist>
1733       <listitem>
1734         <para>
1735           <emphasis role="bold">OST-side:</emphasis>
1736         </para>
1737         <screen>
1738 ldlm.namespaces.filter-<replaceable>fsname</replaceable>-*.
1739 </screen>
1740         <para>
1741         <literal>contended_locks</literal>- If the number of lock conflicts in
1742         the scan of granted and waiting queues at contended_locks is exceeded,
1743         the resource is considered to be contended.</para>
1744         <para>
1745         <literal>contention_seconds</literal>- The resource keeps itself in a
1746         contended state as set in the parameter.</para>
1747         <para>
1748         <literal>max_nolock_bytes</literal>- Server-side locking set only for
1749         requests less than the blocks set in the
1750         <literal>max_nolock_bytes</literal> parameter. If this tunable is
1751         set to zero (0), it disables server-side locking for read/write
1752         requests.</para>
1753       </listitem>
1754       <listitem>
1755         <para>
1756           <emphasis role="bold">Client-side:</emphasis>
1757         </para>
1758         <screen>
1759 /proc/fs/lustre/llite/lustre-*
1760 </screen>
1761         <para>
1762         <literal>contention_seconds</literal>-
1763         <literal>llite</literal> inode remembers its contended state for the
1764         time specified in this parameter.</para>
1765       </listitem>
1766       <listitem>
1767         <para>
1768           <emphasis role="bold">Client-side statistics:</emphasis>
1769         </para>
1770         <para>The
1771         <literal>/proc/fs/lustre/llite/lustre-*/stats</literal> file has new
1772         rows for lockless I/O statistics.</para>
1773         <para>
1774         <literal>lockless_read_bytes</literal> and
1775         <literal>lockless_write_bytes</literal>- To count the total bytes read
1776         or written, the client makes its own decisions based on the request
1777         size. The client does not communicate with the server if the request
1778         size is smaller than the
1779         <literal>min_nolock_size</literal>, without acquiring locks by the
1780         client.</para>
1781       </listitem>
1782     </itemizedlist>
1783   </section>
1784   <section condition="l29">
1785       <title>
1786         <indexterm>
1787           <primary>tuning</primary>
1788           <secondary>with lfs ladvise</secondary>
1789         </indexterm>
1790         Server-Side Advice and Hinting
1791       </title>
1792       <section><title>Overview</title>
1793       <para>Use the <literal>lfs ladvise</literal> command give file access
1794       advices or hints to servers.</para>
1795       <screen>lfs ladvise [--advice|-a ADVICE ] [--background|-b]
1796 [--start|-s START[kMGT]]
1797 {[--end|-e END[kMGT]] | [--length|-l LENGTH[kMGT]]}
1798 <emphasis>file</emphasis> ...
1799       </screen>
1800       <para>
1801         <informaltable frame="all">
1802           <tgroup cols="2">
1803           <colspec colname="c1" colwidth="50*"/>
1804           <colspec colname="c2" colwidth="50*"/>
1805           <thead>
1806             <row>
1807               <entry>
1808                 <para><emphasis role="bold">Option</emphasis></para>
1809               </entry>
1810               <entry>
1811                 <para><emphasis role="bold">Description</emphasis></para>
1812               </entry>
1813             </row>
1814           </thead>
1815           <tbody>
1816             <row>
1817               <entry>
1818                 <para><literal>-a</literal>, <literal>--advice=</literal>
1819                 <literal>ADVICE</literal></para>
1820               </entry>
1821               <entry>
1822                 <para>Give advice or hint of type <literal>ADVICE</literal>.
1823                 Advice types are:</para>
1824                 <para><literal>willread</literal> to prefetch data into server
1825                 cache</para>
1826                 <para><literal>dontneed</literal> to cleanup data cache on
1827                 server</para>
1828               </entry>
1829             </row>
1830             <row>
1831               <entry>
1832                 <para><literal>-b</literal>, <literal>--background</literal>
1833                 </para>
1834               </entry>
1835               <entry>
1836                 <para>Enable the advices to be sent and handled asynchronously.
1837                 </para>
1838               </entry>
1839             </row>
1840             <row>
1841               <entry>
1842                 <para><literal>-s</literal>, <literal>--start=</literal>
1843                         <literal>START_OFFSET</literal></para>
1844               </entry>
1845               <entry>
1846                 <para>File range starts from <literal>START_OFFSET</literal>
1847                 </para>
1848                 </entry>
1849             </row>
1850             <row>
1851                 <entry>
1852                     <para><literal>-e</literal>, <literal>--end=</literal>
1853                         <literal>END_OFFSET</literal></para>
1854                 </entry>
1855                 <entry>
1856                     <para>File range ends at (not including)
1857                     <literal>END_OFFSET</literal>.  This option may not be
1858                     specified at the same time as the <literal>-l</literal>
1859                     option.</para>
1860                 </entry>
1861             </row>
1862             <row>
1863                 <entry>
1864                     <para><literal>-l</literal>, <literal>--length=</literal>
1865                         <literal>LENGTH</literal></para>
1866                 </entry>
1867                 <entry>
1868                   <para>File range has length of <literal>LENGTH</literal>.
1869                   This option may not be specified at the same time as the
1870                   <literal>-e</literal> option.</para>
1871                 </entry>
1872             </row>
1873           </tbody>
1874           </tgroup>
1875         </informaltable>
1876       </para>
1877       <para>Typically, <literal>lfs ladvise</literal> forwards the advice to
1878       Lustre servers without guaranteeing when and what servers will react to
1879       the advice. Actions may or may not triggered when the advices are
1880       recieved, depending on the type of the advice, as well as the real-time
1881       decision of the affected server-side components.</para>
1882       <para>A typical usage of ladvise is to enable applications and users with
1883       external knowledge to intervene in server-side cache management. For
1884       example, if a bunch of different clients are doing small random reads of a
1885       file, prefetching pages into OSS cache with big linear reads before the
1886       random IO is a net benefit. Fetching that data into each client cache with
1887       fadvise() may not be, due to much more data being sent to the client.
1888       </para>
1889       <para>The main difference between the Linux <literal>fadvise()</literal>
1890       system call and <literal>lfs ladvise</literal> is that
1891       <literal>fadvise()</literal> is only a client side mechanism that does
1892       not pass the advice to the filesystem, while <literal>ladvise</literal>
1893       can send advices or hints to the Lustre server side.</para>
1894       </section>
1895       <section><title>Examples</title>
1896         <para>The following example gives the OST(s) holding the first 1GB of
1897         <literal>/mnt/lustre/file1</literal>a hint that the first 1GB of the
1898         file will be read soon.</para>
1899         <screen>client1$ lfs ladvise -a willread -s 0 -e 1048576000 /mnt/lustre/file1
1900         </screen>
1901         <para>The following example gives the OST(s) holding the first 1GB of
1902         <literal>/mnt/lustre/file1</literal> a hint that the first 1GB of file
1903         will not be read in the near future, thus the OST(s) could clear the
1904         cache of the file in the memory.</para>
1905         <screen>client1$ lfs ladvise -a dontneed -s 0 -e 1048576000 /mnt/lustre/file1
1906         </screen>
1907       </section>
1908   </section>
1909   <section condition="l29">
1910       <title>
1911           <indexterm>
1912               <primary>tuning</primary>
1913               <secondary>Large Bulk IO</secondary>
1914           </indexterm>
1915           Large Bulk IO (16MB RPC)
1916       </title>
1917       <section><title>Overview</title>
1918           <para>Beginning with Lustre 2.9, Lustre is extended to support RPCs up
1919           to 16MB in size. By enabling a larger RPC size, fewer RPCs will be
1920           required to transfer the same amount of data between clients and
1921           servers.  With a larger RPC size, the OSS can submit more data to the
1922           underlying disks at once, therefore it can produce larger disk I/Os
1923           to fully utilize the increasing bandwidth of disks.</para>
1924           <para>At client connection time, clients will negotiate with
1925           servers what the maximum RPC size it is possible to use, but the
1926           client can always send RPCs smaller than this maximum.</para>
1927           <para>The parameter <literal>brw_size</literal> is used on the OST
1928           to tell the client the maximum (preferred) IO size.  All clients that
1929           talk to this target should never send an RPC greater than this size.
1930           Clients can individually set a smaller RPC size limit via the
1931           <literal>osc.*.max_pages_per_rpc</literal> tunable.
1932           </para>
1933           <note>
1934           <para>The smallest <literal>brw_size</literal> that can be set for
1935           ZFS OSTs is the <literal>recordsize</literal> of that dataset.  This
1936           ensures that the client can always write a full ZFS file block if it
1937           has enough dirty data, and does not otherwise force it to do read-
1938           modify-write operations for every RPC.
1939           </para>
1940           </note>
1941       </section>
1942       <section><title>Usage</title>
1943           <para>In order to enable a larger RPC size,
1944           <literal>brw_size</literal> must be changed to an IO size value up to
1945           16MB.  To temporarily change <literal>brw_size</literal>, the
1946           following command should be run on the OSS:</para>
1947           <screen>oss# lctl set_param obdfilter.<replaceable>fsname</replaceable>-OST*.brw_size=16</screen>
1948           <para>To persistently change <literal>brw_size</literal>, one of the following
1949           commands should be run on the OSS:</para>
1950           <screen>oss# lctl set_param -P obdfilter.<replaceable>fsname</replaceable>-OST*.brw_size=16</screen>
1951           <screen>oss# lctl conf_param <replaceable>fsname</replaceable>-OST*.obdfilter.brw_size=16</screen>
1952           <para>When a client connects to an OST target, it will fetch
1953           <literal>brw_size</literal> from the target and pick the maximum value
1954           of <literal>brw_size</literal> and its local setting for
1955           <literal>max_pages_per_rpc</literal> as the actual RPC size.
1956           Therefore, the <literal>max_pages_per_rpc</literal> on the client side
1957           would have to be set to 16M, or 4096 if the PAGESIZE is 4KB, to enable
1958           a 16MB RPC.  To temporarily make the change, the following command
1959           should be run on the client to set
1960           <literal>max_pages_per_rpc</literal>:</para>
1961           <screen>client$ lctl set_param osc.<replaceable>fsname</replaceable>-OST*.max_pages_per_rpc=16M</screen>
1962           <para>To persistently make this change, the following command should
1963           be run:</para>
1964           <screen>client$ lctl conf_param <replaceable>fsname</replaceable>-OST*.osc.max_pages_per_rpc=16M</screen>
1965           <caution><para>The <literal>brw_size</literal> of an OST can be
1966           changed on the fly.  However, clients have to be remounted to
1967           renegotiate the new maximum RPC size.</para></caution>
1968       </section>
1969   </section>
1970   <section xml:id="dbdoclet.50438272_80545">
1971     <title>
1972     <indexterm>
1973       <primary>tuning</primary>
1974       <secondary>for small files</secondary>
1975     </indexterm>Improving Lustre I/O Performance for Small Files</title>
1976     <para>An environment where an application writes small file chunks from
1977     many clients to a single file can result in poor I/O performance. To
1978     improve the performance of the Lustre file system with small files:</para>
1979     <itemizedlist>
1980       <listitem>
1981         <para>Have the application aggregate writes some amount before
1982         submitting them to the Lustre file system. By default, the Lustre
1983         software enforces POSIX coherency semantics, so it results in lock
1984         ping-pong between client nodes if they are all writing to the same
1985         file at one time.</para>
1986         <para>Using MPI-IO Collective Write functionality in
1987         the Lustre ADIO driver is one way to achieve this in a straight
1988         forward manner if the application is already using MPI-IO.</para>
1989       </listitem>
1990       <listitem>
1991         <para>Have the application do 4kB
1992         <literal>O_DIRECT</literal> sized I/O to the file and disable locking
1993         on the output file. This avoids partial-page IO submissions and, by
1994         disabling locking, you avoid contention between clients.</para>
1995       </listitem>
1996       <listitem>
1997         <para>Have the application write contiguous data.</para>
1998       </listitem>
1999       <listitem>
2000         <para>Add more disks or use SSD disks for the OSTs. This dramatically
2001         improves the IOPS rate. Consider creating larger OSTs rather than many
2002         smaller OSTs due to less overhead (journal, connections, etc).</para>
2003       </listitem>
2004       <listitem>
2005         <para>Use RAID-1+0 OSTs instead of RAID-5/6. There is RAID parity
2006         overhead for writing small chunks of data to disk.</para>
2007       </listitem>
2008     </itemizedlist>
2009   </section>
2010   <section xml:id="dbdoclet.50438272_45406">
2011     <title>
2012     <indexterm>
2013       <primary>tuning</primary>
2014       <secondary>write performance</secondary>
2015     </indexterm>Understanding Why Write Performance is Better Than Read
2016     Performance</title>
2017     <para>Typically, the performance of write operations on a Lustre cluster is
2018     better than read operations. When doing writes, all clients are sending
2019     write RPCs asynchronously. The RPCs are allocated, and written to disk in
2020     the order they arrive. In many cases, this allows the back-end storage to
2021     aggregate writes efficiently.</para>
2022     <para>In the case of read operations, the reads from clients may come in a
2023     different order and need a lot of seeking to get read from the disk. This
2024     noticeably hampers the read throughput.</para>
2025     <para>Currently, there is no readahead on the OSTs themselves, though the
2026     clients do readahead. If there are lots of clients doing reads it would not
2027     be possible to do any readahead in any case because of memory consumption
2028     (consider that even a single RPC (1 MB) readahead for 1000 clients would
2029     consume 1 GB of RAM).</para>
2030     <para>For file systems that use socklnd (TCP, Ethernet) as interconnect,
2031     there is also additional CPU overhead because the client cannot receive
2032     data without copying it from the network buffers. In the write case, the
2033     client CAN send data without the additional data copy. This means that the
2034     client is more likely to become CPU-bound during reads than writes.</para>
2035   </section>
2036 </chapter>