lustre/doc/lctl.8

   1 .TH lctl 1 "2003 Oct 8" Lustre "configuration utilities"
   2 .SH NAME
   3 lctl \- Low level Lustre filesystem configuration utility
   4 .SH SYNOPSIS
   5 .br
   6 .B lctl
   7 .br
   8 .B lctl --device <devno> <command [args]>
   9 .br
  10 .B lctl --threads <numthreads> <verbose> <devno> <command [args]>
  11 .br
  12 .SH DESCRIPTION
  13 .B lctl
  14 can be invoked in interactive mode by issuing lctl command. After that, commands are issued as below. The most common commands in lctl are (in matching pairs)
  15 .B device
  16 and
  17 .B attach
  18 ,
  19 .B detach
  20 and
  21 .B setup
  22 ,
  23 .B cleanup
  24 and
  25 .B connect
  26 ,
  27 .B disconnect
  28 and
  29 .B help
  30 , and
  31 .B quit.
  32
  33 To get a complete listing of available commands, type help at the lctl prompt.  To get basic help on the meaning and syntax of a command, type help command.  Command completion is activated with the TAB key, and command history is available via the up- and down-arrow keys.
  34
  35 For non-interactive single-threaded use, one uses the second invocation, which runs command after connecting to the device.
  36
  37 .B Network Configuration
  38 .TP
  39 --net <tcp/elan/myrinet> <command>
  40 Indicate the network type to be used for the operation.
  41 .TP
  42 network <tcp/elans/myrinet>
  43 Indicate what kind of network applies for the configuration commands that follow.
  44 .TP
  45 interface_list
  46 Print the interface entries.
  47 .TP
  48 add_interface <ip> [netmask]
  49 Add an interface entry.
  50 .TP
  51 del_interface [ip]
  52 Delete an interface entry.
  53 .TP
  54 peer_list
  55 Print the peer entries.
  56 .TP
  57 add_peer <nid> <host> <port>
  58 Add a peer entry.
  59 .TP
  60 del_peer [<nid>] [<host>] [ks]
  61 Remove a peer entry.
  62 .TP
  63 conn_list
  64 Print all the connected remote nid.
  65 .TP
  66 connect [[<hostname> <port>] | <elan id>]
  67 This will establish a connection to a remote network network id given by the hostname/port combination, or the elan id.
  68 .TP
  69 disconnect <nid>
  70 Disconnect from a remote nid.
  71 .TP
  72 active_tx
  73 This command should print active transmits, and it is only used for elan network type.
  74 .TP
  75 mynid [nid]
  76 Informs the socknal of the local nid. It defaults to hostname for tcp networks and is automatically setup for elan/myrinet networks.
  77 .TP
  78 shownid
  79 Print the local NID.
  80 .TP
  81 add_uuid <uuid> <nid>
  82 Associate a given UUID with an nid.
  83 .TP
  84 close_uuid <uuid>
  85 Disconnect a UUID.
  86 .TP
  87 del_uuid <uuid>
  88 Delete a UUID association.
  89 .TP
  90 add_route <gateway> <target> [target]
  91 Add an entry to the routing table for the given target.
  92 .TP
  93 del_route <target>
  94 Delete an entry for the target from the routing table.
  95 .TP
  96 set_route <gateway> <up/down> [<time>]
  97 Enable/disable routes via the given gateway in the protals routing table. <time> is used to tell when a gateway comes back online.
  98 .TP
  99 route_list
 100 Print the complete routing table.
 101 .TP
 102 fail nid|_all_ [count]
 103 Fail/restore communications. Omitting the count implies fail indefinitely, count of zero indicates that communication should be restored. A non-zero count indicates the number of portals messages to be dropped after which the communication is restored. The argument "nid" is used to specify the gateway, which is one peer of the communication.
 104 .PP
 105 .B Device Selection
 106 .TP
 107 newdev
 108 Create a new device.
 109 .TP
 110 device
 111 This will select the specified OBD device.  All other commands depend on the device being set.
 112 .TP
 113 cfg_device <$name>
 114 Set current device being configured to <$name>.
 115 .TP
 116 device_list
 117 Show all the devices.
 118 .TP
 119 lustre_build_version
 120 Print the Lustre build version.
 121 .PP
 122 .B Device Configuration
 123 .TP
 124 attach type [name [uuid]]
 125 Attach a type to the current device (which you need to set using the device 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.
 126 .TP
 127 setup <args...>
 128 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.
 129 .TP
 130 cleanup
 131 Cleanup a previously setup device.
 132 .TP
 133 detach
 134 Remove driver (and name and UUID) from the current device.
 135 .TP
 136 lov_setconfig lov-uuid stripe-count default-stripe-size offset pattern UUID1 [UUID2...]
 137 Write LOV configuration to an MDS device.
 138 .TP
 139 lov_getconfig lov-uuid
 140 Read LOV configuration from an MDS device. Returns default-stripe-count, default-stripe-size, offset, pattern, and a list of OST UUID's.
 141 .TP
 142 record cfg-uuid-name
 143 Record commands that follow in log.
 144 .TP
 145 endrecord
 146 Stop recording.
 147 .TP
 148 parse config-uuid-name
 149 Parse the log of recorded commands for this config.
 150 .TP
 151 dump_log config-uuid-name
 152 Print log of recorded commands for this config to kernel debug log.
 153 .TP
 154 clear_log config-name
 155 Delete current config log of recorded commands.
 156 .PP
 157 .B Device Operations
 158 .TP
 159 probe [timeout]
 160 Build a connection handle to a device. This command is used to suspend configuration until the lctl command has ensured that the MDS and OSC services are available. This is to avoid mount failures in a rebooting cluster.
 161 .TP
 162 close
 163 Close the connection handle
 164 .TP
 165 getattr <objid>
 166 Get attributes for an OST object <objid> .
 167 .TP
 168 setattr <objid> <mode>
 169 Set mode attribute for OST object <objid>.
 170 .TP
 171 create [num [mode [verbose]]]
 172 Create the specified number <num> of OST objects with the given <mode>.
 173 .TP
 174 destroy <num>
 175 Starting at <objid>, destroy <num> number of objects starting from the object with object id <objid>.
 176 .TP
 177 test_getattr <num> [verbose [[t]objid]]
 178 Do <num> getattrs on OST object <objid> (objectid+1 on each thread).
 179 .TP
 180 test_brw [t]<num> [write [verbose [npages [[t]objid]]]]
 181 Do <num> bulk read/writes on OST object <objid> (<npages> per I/O).
 182 .TP
 183 test_ldlm
 184 Perform lock manager test.
 185 .TP
 186 ldlm_regress_start %s [numthreads [refheld [numres [numext]]]]
 187 Start lock manager stress test.
 188 .TP
 189 ldlm_regress_stop
 190 Stop lock manager stress test.
 191 .TP
 192 dump_ldlm
 193 Dump all lock manager state, this is very useful for debugging
 194 .TP
 195 activate
 196 Activate an import
 197 .TP
 198 deacttivate
 199 De-activate an import
 200 .TP
 201 recover <connection UUID>
 202 .TP
 203 lookup <directory> <file>
 204 .TP
 205 notransno
 206 Disable sending of committed transnumber updates
 207 .TP
 208 readonly
 209 Disable writes to the underlying device
 210 .TP
 211 abort_recovery
 212 Abort recovery on MDS device
 213 .TP
 214 mount_option
 215 Dump mount options to a file
 216 .TP
 217 get_stripe
 218 Show stripe info for an echo client object.
 219 .TP
 220 set_stripe <objid>[ width!count[@offset] [:id:id....]
 221 Set stripe info for an echo client
 222 .TP
 223 unset_stripe <objid>
 224 Unset stripe info for an echo client object.
 225 .TP
 226 del_mount_option profile
 227 Delete a specified profile.
 228 .TP
 229 set_timeout <secs>
 230 Set the timeout(obd_timeout) for server to wait before failing recovery.
 231 .TP
 232 set_lustre_upcall </full/path/to/upcall>
 233 Set the lustre upcall(obd_lustre_upcall) via the lustre.upcall sysctl.
 234 .TP
 235 llog_catlist
 236 List all catalog logs on current device.
 237 .TP
 238 llog_info <$logname|#oid#ogr#ogen>
 239 Print log header information.
 240 .TP
 241 llog_print <$logname|#oid#ogr#ogen> [from] [to]
 242 Print log content information. It will print all records from index 1 by default.
 243 .TP
 244 llog_check <$logname|#oid#ogr#ogen> [from] [to]
 245 Check log content information. It will check all records from index 1 by default.
 246 .TP
 247 llog_cancel <catalog id|catalog name> <log id> <index>
 248 Cancel one record in log.
 249 .TP
 250 llog_remove <catalog id|catalog name> <log id>
 251 Remove one log from catalog, erase it from disk.
 252 .PP
 253 .B Debug
 254 .TP
 255 debug_daemon
 256 Debug daemon control and dump to a file
 257 .TP
 258 debug_kernel [file] [raw]
 259 Get debug buffer and dump to a fileusage.
 260 .TP
 261 debug_file <input> [output]
 262 Convert kernel-dumped debug log from binary to plain text format.
 263 .TP
 264 clear
 265 Clear kernel debug buffer.
 266 .TP
 267 mark <text>
 268 Insert marker text in kernel debug buffer.
 269 .TP
 270 filter <subsystem id/debug mask>
 271 Filter message type from the kernel debug buffer.
 272 .TP
 273 show <subsystem id/debug mask>
 274 Show specific type of messages.
 275 .TP
 276 debug_list <subs/types>
 277 List all the subsystem and debug types.
 278 .TP
 279 modules <path>
 280 Provide gdb-friendly module information.
 281 .TP
 282 panic
 283 Force the kernel to panic.
 284 .TP
 285 lwt start/stop [file]
 286 Light-weight tracing.
 287 .TP
 288 memhog <page count> [<gfp flags>]
 289 Memory pressure testing.
 290 .PP
 291 .B Control
 292 .TP
 293 help
 294 Show a complete list of commands; help <command name> can be used to get help on specific command.
 295 .TP
 296 exit
 297 Close the lctl session.
 298 .TP
 299 quit
 300 Close the lctl session.
 301
 302 .SH OPTIONS
 303 The following options can be used to invoke lctl.
 304 .TP
 305 .B --device
 306 The device number to be used for the operation. The value of devno is an integer, normally found by calling lctl name2dev on a device name.
 307 .TP
 308 .B --threads
 309 How many threads should be forked doing the command specified. The numthreads variable is a strictly positive integer indicating how many threads should be started. The devno option is used as above.
 310 .TP
 311 .B --ignore_errors | ignore_errors
 312 Ignore errors during script processing
 313 .TP
 314 .B dump
 315 Save ioctls to a file
 316 .SH EXAMPLES
 317 .B attach
 318
 319 # lctl
 320 .br
 321 lctl > newdev
 322 .br
 323 lctl > attach obdfilter OBDDEV OBDUUID
 324
 325 .B connect
 326
 327 lctl > name2dev OSCDEV 2
 328 .br
 329 lctl > device 2
 330 .br
 331 lctl > connect
 332
 333 .B getattr
 334
 335 lctl > getattr 12
 336 .br
 337 id: 12
 338 .br
 339 grp: 0
 340 .br
 341 atime: 1002663714
 342 .br
 343 mtime: 1002663535
 344 .br
 345 ctime: 1002663535
 346 .br
 347 size: 10
 348 .br
 349 blocks: 8
 350 .br
 351 blksize: 4096
 352 .br
 353 mode: 100644
 354 .br
 355 uid: 0
 356 .br
 357 gid: 0
 358 .br
 359 flags: 0
 360 .br
 361 obdflags: 0
 362 .br
 363 nlink: 1
 364 .br
 365 valid: ffffffff
 366 .br
 367 inline:
 368 .br
 369 obdmd:
 370 .br
 371 lctl > disconnect
 372 .br
 373 Finished (success)
 374
 375 .B setup
 376
 377 lctl > setup /dev/loop0 extN
 378 .br
 379 lctl > quit
 380
 381 .SH BUGS
 382 None are known.