Updated the lctl manpage and Lustre How-To.

diff --git a/lustre/doc/lctl.lyx b/lustre/doc/lctl.lyx
index d9f578f..0e7a732 100644 (file)
--- a/lustre/doc/lctl.lyx
+++ b/lustre/doc/lctl.lyx
@@ -29,7 +29,7 @@
 LCTL
 \layout Subsection
 
-NAME kfjlkjd
+NAME 
 \layout Standard
 
 lctl - low level Lustre file system configuration utility
@@ -69,7 +69,60 @@ The program can be invoked in interactive mode by issuing
 lctl.
 
 \series default 
- After than commands are issued as below.
+ After that commands are issued as below.
+ The most common commands in lctl are (in matching pairs) 
+\family typewriter 
+device
+\family default 
+, 
+\family typewriter 
+attach
+\family default 
+ and 
+\family typewriter 
+detach
+\family default 
+, 
+\family typewriter 
+setup
+\family default 
+ and 
+\family typewriter 
+cleanup
+\family default 
+, 
+\family typewriter 
+connect
+\family default 
+ and 
+\family typewriter 
+disconnect
+\family default 
+, 
+\family typewriter 
+help
+\family default 
+, and 
+\family typewriter 
+quit
+\family default 
+.
+  To get a complete listing of available commands, type 
+\family typewriter 
+help
+\family default 
+ at the lctl prompt.
+  To get basic help on the meaning and syntax of a command, type 
+\family typewriter 
+help command
+\family default 
+.
+  Command completion is activated with the 
+\family typewriter 
+TAB
+\family default 
+ key, and command history is available via the up- and down-arrow keys.
+ 
 \layout Standard
 
 For non-interactive single threaded use, one uses the second invocation
@@ -102,9 +155,10 @@ on a device name.
 devno 
 \emph default 
 is used as above.
-\layout Subsection
+\layout LyX-Code
+
+\layout LyX-Code
 
-SUBCOMMANDS
 \layout Description
 
 network\SpecialChar ~
@@ -114,7 +168,7 @@ config
 
 network\SpecialChar ~
 <tcp/elans/myrinet> Indicate what kind of network applies for the
- configuration commands that follow.
+ configuration commands that follow
 \layout Description
 
 connect\SpecialChar ~
@@ -122,40 +176,65 @@ connect\SpecialChar ~
 <port>]\SpecialChar ~
 |\SpecialChar ~
 <elan\SpecialChar ~
-id>] 
+id>] This will establish a connection to
+ a remote network network id given by the hostname/port combination or the
+ elan id 
 \layout Description
 
-disconnect 
+disconnect\SpecialChar ~
+<nid> Disconnect from a remote nid
 \layout Description
 
-mynid 
+mynid\SpecialChar ~
+[nid] Informs the socknal of the local nid.
+ It defaults to hostname for tcp networks and is automatically setup for
+ elan/myrinet networks 
 \layout Description
 
-add_uuid 
+add_uuid\SpecialChar ~
+<uuid>\SpecialChar ~
+<nid> Associate a given UUID with an 
+\emph on 
+nid
+\emph default 
+ 
 \layout Description
 
-close_uuid 
+close_uuid\SpecialChar ~
+<uuid> Disconnect a UUID 
 \layout Description
 
-del_uuid 
+del_uuid\SpecialChar ~
+<uuid> Delete a UUID association
 \layout Description
 
-add_route 
+add_route\SpecialChar ~
+<gateway>\SpecialChar ~
+<target>\SpecialChar ~
+[target] Add an entry to the routing table for
+ the given target 
 \layout Description
 
-del_route 
+del_route\SpecialChar ~
+<target> Delete an entry for the target from the routing table
 \layout Description
 
-route_list 
+route_list Print the complete routing table 
 \layout Description
 
-recv_mem 
+recv_mem\SpecialChar ~
+[size] Set the socket receive buffer size, if the size is omited
+ the default size for the buffer is printed
 \layout Description
 
-send_mem 
+send_mem\SpecialChar ~
+[size] Set send buffer size for the socket, if size is omited the
+ default size for the buffer is printed
 \layout Description
 
-nagle
+nagle\SpecialChar ~
+[on/off] Enable/disable nagle, omiting the arguement will cause the
+ default value to be printed
 \end_deeper 
 \layout Description
 
@@ -164,16 +243,19 @@ selection
 \begin_deeper 
 \layout Description
 
-newdev 
+newdev Create a new device
 \layout Description
 
-name2dev 
+name2dev This command can be used to determine a device number for the given
+ device name.
 \layout Description
 
-device 
+device This will select the specified OBD device.
+  All other commands depend on the device being set.
+ 
 \layout Description
 
-device_list
+device_list Show all the devices
 \end_deeper 
 \layout Description
 
@@ -182,19 +264,44 @@ config
 \begin_deeper 
 \layout Description
 
-attach 
-\layout Description
-
-setup 
+attach\SpecialChar ~
+type\SpecialChar ~
+[name\SpecialChar ~
+[uuid]] 
+\shape italic 
+Attach
+\shape default 
+ a type to the current device (which you need to set using the 
+\family typewriter 
+device
+\family default 
+ command) and give that device a name and UUID.
+  This allows us to identify the device for use later, and also tells us
+ what type of device we will have.
+\layout Description
+
+setup\SpecialChar ~
+<args...> Type specific device setup commands.
+ For obdfilter a setup command tells the driver which block device it should
+ use for storage and what type of filesystem is on that device.
+ 
 \layout Description
 
-cleanup 
+cleanup Cleanup a previously setup device
 \layout Description
 
-detach 
+detach Remove driver (and name and uuid) from the current device
 \layout Description
 
-lovconfig 
+lovconfig\SpecialChar ~
+lov-uuid\SpecialChar ~
+stripe-count\SpecialChar ~
+stripe-size\SpecialChar ~
+offset\SpecialChar ~
+pattern\SpecialChar ~
+UUID1\SpecialChar ~
+[UUID2...] Write
+ LOV configuration to an MDS device
 \end_deeper 
 \layout Description
 
@@ -203,43 +310,73 @@ operations
 \begin_deeper 
 \layout Description
 
-probe
+probe\SpecialChar ~
+[timeout] Build a connection handle to a device.
+ This command is used to suspend configuration till the lctl command has
+ ensured that the mds and osc services are available.
+ This is to avoid mount failures in a reebooting cluster
 \layout Description
 
 close 
 \layout Description
 
-getattr 
+getattr\SpecialChar ~
+<objid> Get attributes for an OST object <objid> 
 \layout Description
 
-setattr
+setattr\SpecialChar ~
+<objid>\SpecialChar ~
+<mode> Set mode attribute for OST object <objid>
 \layout Description
 
-create 
+create\SpecialChar ~
+[num\SpecialChar ~
+[mode\SpecialChar ~
+[verbose]]] Create the specified number <num> of OST objects
+ with the given <mode>
 \layout Description
 
-destroy
+destroy\SpecialChar ~
+<objid> Destroy an OST object
 \layout Description
 
-test_getattr
+test_getattr\SpecialChar ~
+<num>\SpecialChar ~
+[verbose\SpecialChar ~
+[[t]objid]] Do <num> getattrs on OST object <objid>
+ (objectid+1 on each thread)
 \layout Description
 
-test_brw
+test_brw\SpecialChar ~
+[t]<num>\SpecialChar ~
+[write\SpecialChar ~
+[verbose\SpecialChar ~
+[npages\SpecialChar ~
+[[t]objid]]]] Do <num> bulk read/writes
+ on OST object <objid> (<npages> per I/O)
 \layout Description
 
-test_ldlm
+test_ldlm Perform lock manager test
 \layout Description
 
-ldlm_regress_start
+ldlm_regress_start\SpecialChar ~
+%s\SpecialChar ~
+[numthreads\SpecialChar ~
+[refheld\SpecialChar ~
+[numres\SpecialChar ~
+[numext]]]] Start lock manager
+ stress test
 \layout Description
 
-ldlm_regress_stop
+ldlm_regress_stop Stop lock manager stress test
 \layout Description
 
-dump_ldlm 
+dump_ldlm Dump all lock manager state, this is very useful for debugging
 \layout Description
 
-newconn 
+newconn\SpecialChar ~
+<olduuid>\SpecialChar ~
+[newuuid]
 \end_deeper 
 \layout Description
 
@@ -247,29 +384,43 @@ debug
 \begin_deeper 
 \layout Description
 
-debug_kernel 
+debug_kernel\SpecialChar ~
+[file]\SpecialChar ~
+[raw] Get debug buffer and dump to a fileusage
 \layout Description
 
-debug_file 
+debug_file\SpecialChar ~
+<input>\SpecialChar ~
+[output]\SpecialChar ~
+[raw] Read debug buffer from input and dump to
+ outputusage
 \layout Description
 
-clear 
+clear Clear kernel debug buffer 
 \layout Description
 
-mark 
+mark\SpecialChar ~
+<text> Insert marker text in kernel debug buffer 
 \layout Description
 
-filter 
+filter\SpecialChar ~
+<subsystem\SpecialChar ~
+id/debug\SpecialChar ~
+mask> Filter message type from the kernel debug
+ buffer
 \layout Description
 
-show 
+show\SpecialChar ~
+<subsystem\SpecialChar ~
+id/debug\SpecialChar ~
+mask> Show specific type of messages 
 \layout Description
 
 debug_list\SpecialChar ~
-modules 
+<subs/types> List all the subsystem and debug types
 \layout Description
 
-panic
+panic Force the kernel to panic
 \end_deeper 
 \layout Description
 
@@ -277,17 +428,96 @@ control
 \begin_deeper 
 \layout Description
 
-help 
+help Show a complete list of commands, help <command name> can be used to
+ get help on specific command
 \layout Description
 
-exit 
+exit Close the lctl session
 \layout Description
 
-quit 
+quit Close the lctl session
 \end_deeper 
 \layout Subsection
 
 EXAMPLES
+\layout Description
+
+attach
+\layout LyX-Code
+
+# lctl
+\newline 
+lctl > newdev
+\newline 
+lctl > attach obdfilter OBDDEV OBDUUID 
+\layout Description
+
+connect
+\layout LyX-Code
+
+lctl > name2dev OSCDEV
+\newline 
+2 
+\newline 
+lctl > device 2
+\newline 
+lctl > connect
+\newline 
+
+\layout Description
+
+getattr
+\layout LyX-Code
+
+lctl > getattr 12
+\newline 
+id: 12
+\newline 
+grp: 0
+\newline 
+atime: 1002663714
+\newline 
+mtime: 1002663535
+\newline 
+ctime: 1002663535
+\newline 
+size: 10
+\newline 
+blocks: 8
+\newline 
+blksize: 4096
+\newline 
+mode: 100644
+\newline 
+uid: 0
+\newline 
+gid: 0
+\newline 
+flags: 0
+\newline 
+obdflags: 0
+\newline 
+nlink: 1
+\newline 
+valid: ffffffff
+\newline 
+inline:
+\newline 
+obdmd:
+\newline 
+lctl > disconnect 
+\newline 
+Finished (success)
+\layout Description
+
+setup 
+\layout LyX-Code
+
+lctl > setup /dev/loop0 extN
+\newline 
+lctl > quit 
+\layout LyX-Code
+
 \layout Subsection
 
 BUGS