lustre/doc/lst.8

   1 .TH lst 1 "Jul 7, 2008" Lustre "utilities"
   2 .SH NAME
   3 lst \- Start the Lustre LNET Self-test
   4 .SH SYNOPSIS
   5 .B "lst"
   6 .SH DESCRIPTION
   7 LNET self-test helps site administrators confirm that Lustre
   8 Networking (LNET) has been properly installed and configured.
   9 The self-test also confirms that LNET and the network software
  10 and hardware underlying it are performing according to expectations.
  11 .LP
  12 Every LNET self-test runs in the context of a session.  A node can be
  13 associated with only one session at a time to ensure the session has
  14 exclusive use of the nodes on which it is running. A session is created,
  15 controlled and monitored from a single node; this is referred to as the
  16 self-test console.
  17 .LP
  18 Any node may act as the self-test console.  Nodes are named and allocated
  19 to a self-test session in groups.  This allows all nodes in a group to
  20 be referenced by a single name.
  21 .LP
  22 Test configurations are built by describing and running test batches.
  23 A test batch is simply a named collection of tests, with each test
  24 composed of a number of individual point-to-point tests running in parallel.
  25 These individual point-to-point tests are instantiated according to the
  26 test type, source group, target group and distribution specified when the
  27 test is added to the test batch.
  28 .LP
  29 .SH MODULES
  30 To run LNET self-test, load these modules: libcfs, lnet, lnet_selftest
  31 and any one of the klnds (i.e, ksocklnd, ko2iblnd...).
  32 To load all necessary modules, run modprobe lnet_selftest, which
  33 recursively loads the modules that lnet_selftest depends on.
  34 .LP
  35 There are two types of nodes for LNET self-test: the console node and
  36 test nodes. Both node types require all previously-specified modules
  37 to be loaded. (The userspace test node does not require these modules.)
  38 .LP
  39 Test nodes can be in either kernel or userspace.  A console user can
  40 invite a kernel test node to join the test session by running
  41 .I "lst add_group NID",
  42 but the user cannot actively add a userspace test node to the
  43 test-session.  However, the console user can passively accept a test
  44 node to the test session while the test node runs lstclient to connect
  45 to the console.
  46 .SH UTILITIES
  47 LNET self-test has two user utilities, lst and lstclient.
  48 .LP
  49 .B lst
  50 is the user interface for the self-test console (run on console node).
  51 It provides a list of commands to control the entire test system,
  52 such as create session, create test groups, etc.
  53 .LP
  54 .B lstclient
  55 is the userspace self-test program, which is linked with userspace
  56 LNDs and LNET. A user can use lstclient to join a self-test session:
  57 .nf
  58 lstclient -sesid CONSOLE_NID group NAME
  59 .fi
  60 .SH EXAMPLE SCRIPT
  61 Below is a sample LNET self-test script which simulates the traffic
  62 pattern of a set of Lustre servers on a TCP network, accessed by Lustre
  63 clients on an IB network (connected via LNET routers), with half the
  64 clients reading and half the clients writing.
  65 .LP
  66 .nf
  67 #!/bin/bash
  68 export LST_SESSION=$$
  69 lst new_session read/write
  70 lst add_group servers 192.168.10.[8,10,12-16]@tcp
  71 lst add_group readers 192.168.1.[1-253/2]@o2ib
  72 lst add_group writers 192.168.1.[2-254/2]@o2ib
  73 lst add_batch bulk_rw
  74 lst add_test --batch bulk_rw --from readers --to servers \
  75     brw read check=simple size=1M
  76 lst add_test --batch bulk_rw --from writers --to servers \
  77     brw write check=full size=4K
  78 # start running
  79 lst run bulk_rw
  80 # display server stats for 30 seconds
  81 lst stat servers & sleep 30; kill $!
  82 # tear down
  83 lst end_session
  84 .fi
  85 .SH SEE ALSO
  86 This manual page was extracted from Introduction to LNET Self-Test,
  87 section 19.4.1 of the Lustre Operations Manual.  For more detailed
  88 information, please refer to that document.