Branch HEAD

b=16581
i=he.huang
i=andrew.perepechko

added man pages for llverdev.8 llbackup.8 llapi_quotactl.3 llobdstat.8 llstat.8 plot-llstat.8 l_getgroups.8 lst.8 routerstat.8

lustre/doc/Makefile.am

@@ -47,7 +47,8 @@ TEXEXPAND = texexpand
 SUFFIXES = .lin .lyx .pdf .ps .sgml .html .txt .tex .fig .eps .dvi
 
 MANFILES = lustre.7 lfs.1 mount.lustre.8 mkfs.lustre.8 tunefs.lustre.8 lctl.8 \
-	llverdev.8 llbackup.8 llapi_quotactl.3
+	llverdev.8 llbackup.8 llapi_quotactl.3 llobdstat.8 llstat.8 plot-llstat.8 \
+	l_getgroups.8 lst.8 routerstat.8
 
 if UTILS
 man_MANS = $(MANFILES)

lustre/doc/l_getgroups.8

+.TH l_getgroups 1 "Jul 7, 2008" Lustre "utilities"
+.SH NAME
+l_getgroups \- Handle Lustre user/group cache upcall
+.SH SYNOPSIS
+.B "l_getgroups [-v] [-d | mdsname] uid"
+.br
+.B "l_getgroups [-v] -s"
+.SH DESCRIPTION
+The group upcall file contains the path to an executable that, when
+properly installed, is invoked to resolve a numeric UID to a group
+membership list. This utility should complete the mds_grp_downcall_data
+data structure (see Data structures) and write it to the
+/proc/fs/lustre/mds/mds-service/group_info pseudo-file.
+.LP
+.B l_getgroups
+is the reference implementation of the user/group cache upcall
+.SH FILES
+/proc/fs/lustre/mds/mds-service/group_upcall
+.SH SEE ALSO
+Lustre Programming Interfaces section of Lustre Operations Manual.

lustre/doc/llobdstat.8

+.TH llobdstat 1 "Jul 7, 2008" Lustre "utilities"
+.SH NAME
+llobdstat \- display OST statistics
+.SH SYNOPSIS
+.B "llobdstat ost_name [interval]"
+.br
+.SH DESCRIPTION
+.B llobdstat
+displays a line of OST statistics for the given
+.I ost_name
+every
+.I interval
+seconds.  It should be run directly on an OSS node.
+Type control-C to stop statistics printing.
+.SH EXAMPLE
+.nf
+# llobdstat liane-OST0002 1
+/usr/bin/llobdstat on /proc/fs/lustre/obdfilter/liane-OST0002/stats
+Processor counters run at 2800.189 MHz
+Read: 1.21431e+07, Write: 9.93363e+08, create/destroy: 24/1499, stat: 34, punch: 18
+[NOTE: cx: create, dx: destroy, st: statfs, pu: punch ]
+
+Timestamp   Read-delta  ReadRate  Write-delta  WriteRate
+--------------------------------------------------------
+1217026053    0.00MB    0.00MB/s     0.00MB    0.00MB/s
+1217026054    0.00MB    0.00MB/s     0.00MB    0.00MB/s
+1217026055    0.00MB    0.00MB/s     0.00MB    0.00MB/s
+1217026056    0.00MB    0.00MB/s     0.00MB    0.00MB/s
+1217026057    0.00MB    0.00MB/s     0.00MB    0.00MB/s
+1217026058    0.00MB    0.00MB/s     0.00MB    0.00MB/s
+1217026059    0.00MB    0.00MB/s     0.00MB    0.00MB/s st:1
+...
+.fi
+.SH FILES
+/proc/fs/lustre/obdfilter/<ostname>/stats.

lustre/doc/llstat.8

+.TH llstat 1 "Jul 7, 2008" Lustre "utilities"
+.SH NAME
+llstat \- print Lustre statistics
+.SH SYNOPSIS
+.B "llstat [-c] [-g] [-i interval] stats_file"
+.br
+.SH DESCRIPTION
+.B llstat
+can display statistics from any of several lustre stats files that
+share a common format, updated every \fIinterval\fR seconds.
+Use control-C to stop statistics printing.
+.TP
+.I "\-c"
+Clear the stats file first.
+.TP
+.I "\-i interval"
+Polling period in seconds.
+.TP
+.I "\-g"
+Graphable output format.
+.TP
+.I "\-h"
+Display help information.
+.TP
+.I "stats_file"
+Either the full path to a stats file, or the shorthand:
+\fImds\fR or \fIost\fR.
+.SH EXAMPLE
+To monitor /proc/fs/lustre/ost/OSS/ost/stats every second:
+.IP
+llstat -i 1 ost
+.SH FILES
+.nf
+/proc/fs/lustre/mdt/MDS/*/stats
+/proc/fs/lustre/mds/*/exports/*/stats
+/proc/fs/lustre/mdc/*/stats
+/proc/fs/lustre/ldlm/services/*/stats
+/proc/fs/lustre/ldlm/namespaces/*/pool/stats
+/proc/fs/lustre/mgs/MGS/exports/*/stats
+/proc/fs/lustre/ost/OSS/*/stats
+/proc/fs/lustre/osc/*/stats
+/proc/fs/lustre/obdfilter/*/exports/*/stats
+/proc/fs/lustre/obdfilter/*/stats
+/proc/fs/lustre/llite/*/stats
+.fi

lustre/doc/lst.8

+.TH lst 1 "Jul 7, 2008" Lustre "utilities"
+.SH NAME
+lst \- Start the Lustre LNET Self-test
+.SH SYNOPSIS
+.B "lst"
+.SH DESCRIPTION
+LNET self-test helps site administrators confirm that Lustre
+Networking (LNET) has been properly installed and configured.
+The self-test also confirms that LNET and the network software
+and hardware underlying it are performing according to expectations.
+.LP
+Every LNET self-test runs in the context of a session.  A node can be
+associated with only one session at a time to ensure the session has
+exclusive use of the nodes on which it is running. A session is created,
+controlled and monitored from a single node; this is referred to as the
+self-test console.
+.LP
+Any node may act as the self-test console.  Nodes are named and allocated
+to a self-test session in groups.  This allows all nodes in a group to
+be referenced by a single name.
+.LP
+Test configurations are built by describing and running test batches.
+A test batch is simply a named collection of tests, with each test
+composed of a number of individual point-to-point tests running in parallel.
+These individual point-to-point tests are instantiated according to the
+test type, source group, target group and distribution specified when the
+test is added to the test batch.
+.LP
+.SH MODULES
+To run LNET self-test, load these modules: libcfs, lnet, lnet_selftest
+and any one of the klnds (i.e, ksocklnd, ko2iblnd...).
+To load all necessary modules, run modprobe lnet_selftest, which
+recursively loads the modules that lnet_selftest depends on.
+.LP
+There are two types of nodes for LNET self-test: the console node and
+test nodes. Both node types require all previously-specified modules
+to be loaded. (The userspace test node does not require these modules.)
+.LP
+Test nodes can be in either kernel or userspace.  A console user can
+invite a kernel test node to join the test session by running
+.I "lst add_group NID",
+but the user cannot actively add a userspace test node to the
+test-session.  However, the console user can passively accept a test
+node to the test session while the test node runs lstclient to connect
+to the console.
+.SH UTILITIES
+LNET self-test has two user utilities, lst and lstclient.
+.LP
+.B lst
+is the user interface for the self-test console (run on console node).
+It provides a list of commands to control the entire test system,
+such as create session, create test groups, etc.
+.LP
+.B lstclient
+is the userspace self-test program, which is linked with userspace
+LNDs and LNET. A user can use lstclient to join a self-test session:
+.nf
+lstclient -sesid CONSOLE_NID group NAME
+.fi
+.SH EXAMPLE SCRIPT
+Below is a sample LNET self-test script which simulates the traffic
+pattern of a set of Lustre servers on a TCP network, accessed by Lustre
+clients on an IB network (connected via LNET routers), with half the
+clients reading and half the clients writing.
+.LP
+.nf
+#!/bin/bash
+export LST_SESSION=$$
+lst new_session read/write
+lst add_group servers 192.168.10.[8,10,12-16]@tcp
+lst add_group readers 192.168.1.[1-253/2]@o2ib
+lst add_group writers 192.168.1.[2-254/2]@o2ib
+lst add_batch bulk_rw
+lst add_test --batch bulk_rw --from readers --to servers \
+    brw read check=simple size=1M
+lst add_test --batch bulk_rw --from writers --to servers \
+    brw write check=full size=4K
+# start running
+lst run bulk_rw
+# display server stats for 30 seconds
+lst stat servers & sleep 30; kill $?
+# tear down
+lst end_session
+.fi
+.SH SEE ALSO
+This manual page was extracted from Introduction to LNET Self-Test,
+section 19.4.1 of the Lustre Operations Manual.  For more detailed
+information, please refer to that document.

lustre/doc/plot-llstat.8

+.TH plot0llstat 1 "Jul 7, 2008" Lustre "utilities"
+.SH NAME
+plot-llstat \- plot Lustre statistics
+.SH SYNOPSIS
+.B "plot-llstat results_filename [parameter_index]"
+.br
+.SH DESCRIPTION
+The
+.B plot-llstat
+script is used to generate csv file and instructions files for gnuplot
+from the output of
+.B llstat.
+Since
+.B llstat
+is generic in nature,
+.B plot-llstat
+is also a generic script.
+.LP
+.I parameter_index
+can be 1 for count per interval, 2 for count per second (default),
+or 3 for total count.
+.LP
+plot-llstat script creates dat(csv) file using number of operations
+specified by the user. Number of operations equals to number of columns in csv
+file. And values in those columns are equals to the corresponding value of
+the
+.I "parameter_index"
+parameter from the output file.
+.LP
+.B plot-llstat
+also creates .scr file that contains instructions for gnuplot to plot
+the graph. After generating .dat and .scr files
+.B plot-llstat
+invokes
+.B gnuplot
+to display graph.
+.SH EXAMPLE
+.nf
+llstat -i2 -g -c lustre-OST0000 > log
+plot-llstat log 3
+.fi
+.SH SEE ALSO
+llstat(8)

lustre/doc/routerstat.8

+.TH routerstat 1 "Jul 7, 2008" Lustre "utilities"
+.SH NAME
+routerstat \- print Lustre router statistics
+.SH SYNOPSIS
+.B "routerstat [interval]
+.br
+.SH DESCRIPTION
+.B routerstat
+watches LNET router statistics.  If no
+.I interval
+is specified, stats are sampled and printed only once;
+otherwise, stats are sampled and printed every
+.I interval
+seconds.
+.LP
+Output includes the following fields:
+.LP
+.nf
+M - msgs_alloc(msgs_max)
+E - errors
+S - send_count/send_length
+R - recv_count/recv_length
+F - route_count/route_length
+D - drop_count/drop_length
+.fi
+.SH FILES
+/proc/sys/lnet/stats