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 autoconn_list
  64 Print autoconnect entries.
  65 .TP
  66 add_autoconn nid ipaddr port [ise]
  67 Add an autoconnect entry.
  68 .TP
  69 del_autoconn [<nid>] [<host>] [ks]
  70 Remove an autoconnect entry.
  71 .TP
  72 conn_list
  73 Print all the connected remote nid.
  74 .TP
  75 connect [[<hostname> <port>] | <elan id>]
  76 This will establish a connection to a remote network network id given by the hostname/port combination, or the elan id.
  77 .TP
  78 disconnect <nid>
  79 Disconnect from a remote nid.
  80 .TP
  81 active_tx
  82 This command should print active transmits, and it is only used for elan network type.
  83 .TP
  84 mynid [nid]
  85 Informs the socknal of the local nid. It defaults to hostname for tcp networks and is automatically setup for elan/myrinet networks.
  86 .TP
  87 shownid
  88 Print the local NID.
  89 .TP
  90 add_uuid <uuid> <nid>
  91 Associate a given UUID with an nid.
  92 .TP
  93 close_uuid <uuid>
  94 Disconnect a UUID.
  95 .TP
  96 del_uuid <uuid>
  97 Delete a UUID association.
  98 .TP
  99 add_route <gateway> <target> [target]
 100 Add an entry to the routing table for the given target.
 101 .TP
 102 del_route <target>
 103 Delete an entry for the target from the routing table.
 104 .TP
 105 set_route <gateway> <up/down> [<time>]
 106 Enable/disable routes via the given gateway in the protals routing table. <time> is used to tell when a gateway comes back online.
 107 .TP
 108 route_list
 109 Print the complete routing table.
 110 .TP
 111 fail nid|_all_ [count]
 112 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.
 113 .PP
 114 .B Device Selection
 115 .TP
 116 newdev
 117 Create a new device.
 118 .TP
 119 device
 120 This will select the specified OBD device.  All other commands depend on the device being set.
 121 .TP
 122 cfg_device <$name>
 123 Set current device being configured to <$name>.
 124 .TP
 125 device_list
 126 Show all the devices.
 127 .TP
 128 lustre_build_version
 129 Print the Lustre build version.
 130 .PP
 131 .B Device Configuration
 132 .TP
 133 attach type [name [uuid]]
 134 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.
 135 .TP
 136 setup <args...>
 137 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.
 138 .TP
 139 cleanup
 140 Cleanup a previously setup device.
 141 .TP
 142 detach
 143 Remove driver (and name and UUID) from the current device.
 144 .TP
 145 lov_setconfig lov-uuid stripe-count default-stripe-size offset pattern UUID1 [UUID2...]
 146 Write LOV configuration to an MDS device.
 147 .TP
 148 lov_getconfig lov-uuid
 149 Read LOV configuration from an MDS device. Returns default-stripe-count, default-stripe-size, offset, pattern, and a list of OST UUID's.
 150 .TP
 151 record cfg-uuid-name
 152 Record commands that follow in log.
 153 .TP
 154 endrecord
 155 Stop recording.
 156 .TP
 157 parse config-uuid-name
 158 Parse the log of recorded commands for this config.
 159 .TP
 160 dump_log config-uuid-name
 161 Print log of recorded commands for this config to kernel debug log.
 162 .TP
 163 clear_log config-name
 164 Delete current config log of recorded commands.
 165 .PP
 166 .B Device Operations
 167 .TP
 168 probe [timeout]
 169 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.
 170 .TP
 171 close
 172 Close the connection handle
 173 .TP
 174 getattr <objid>
 175 Get attributes for an OST object <objid> .
 176 .TP
 177 setattr <objid> <mode>
 178 Set mode attribute for OST object <objid>.
 179 .TP
 180 create [num [mode [verbose]]]
 181 Create the specified number <num> of OST objects with the given <mode>.
 182 .TP
 183 destroy <num>
 184 Starting at <objid>, destroy <num> number of objects starting from the object with object id <objid>.
 185 .TP
 186 test_getattr <num> [verbose [[t]objid]]
 187 Do <num> getattrs on OST object <objid> (objectid+1 on each thread).
 188 .TP
 189 test_brw [t]<num> [write [verbose [npages [[t]objid]]]]
 190 Do <num> bulk read/writes on OST object <objid> (<npages> per I/O).
 191 .TP
 192 test_ldlm
 193 Perform lock manager test.
 194 .TP
 195 ldlm_regress_start %s [numthreads [refheld [numres [numext]]]]
 196 Start lock manager stress test.
 197 .TP
 198 ldlm_regress_stop
 199 Stop lock manager stress test.
 200 .TP
 201 dump_ldlm
 202 Dump all lock manager state, this is very useful for debugging
 203 .TP
 204 activate
 205 Activate an import
 206 .TP
 207 deacttivate
 208 De-activate an import
 209 .TP
 210 recover <connection UUID>
 211 .TP
 212 lookup <directory> <file>
 213 .TP
 214 notransno
 215 Disable sending of committed transnumber updates
 216 .TP
 217 readonly
 218 Disable writes to the underlying device
 219 .TP
 220 abort_recovery
 221 Abort recovery on MDS device
 222 .TP
 223 mount_option
 224 Dump mount options to a file
 225 .TP
 226 get_stripe
 227 Show stripe info for an echo client object.
 228 .TP
 229 set_stripe <objid>[ width!count[@offset] [:id:id....]
 230 Set stripe info for an echo client
 231 .TP
 232 unset_stripe <objid>
 233 Unset stripe info for an echo client object.
 234 .TP
 235 del_mount_option profile
 236 Delete a specified profile.
 237 .TP
 238 set_timeout <secs>
 239 Set the timeout(obd_timeout) for server to wait before failing recovery.
 240 .TP
 241 set_lustre_upcall </full/path/to/upcall>
 242 Set the lustre upcall(obd_lustre_upcall) via the lustre.upcall sysctl.
 243 .TP
 244 llog_catlist
 245 List all catalog logs on current device.
 246 .TP
 247 llog_info <$logname|#oid#ogr#ogen>
 248 Print log header information.
 249 .TP
 250 llog_print <$logname|#oid#ogr#ogen> [from] [to]
 251 Print log content information. It will print all records from index 1 by default.
 252 .TP
 253 llog_check <$logname|#oid#ogr#ogen> [from] [to]
 254 Check log content information. It will check all records from index 1 by default.
 255 .TP
 256 llog_cancel <catalog id|catalog name> <log id> <index>
 257 Cancel one record in log.
 258 .TP
 259 llog_remove <catalog id|catalog name> <log id>
 260 Remove one log from catalog, erase it from disk.
 261 .PP
 262 .B Debug
 263 .TP
 264 debug_daemon
 265 Debug daemon control and dump to a file
 266 .TP
 267 debug_kernel [file] [raw]
 268 Get debug buffer and dump to a fileusage.
 269 .TP
 270 debug_file <input> [output] [raw]
 271 Read debug buffer from input and dump to outputusage.
 272 .TP
 273 clear
 274 Clear kernel debug buffer.
 275 .TP
 276 mark <text>
 277 Insert marker text in kernel debug buffer.
 278 .TP
 279 filter <subsystem id/debug mask>
 280 Filter message type from the kernel debug buffer.
 281 .TP
 282 show <subsystem id/debug mask>
 283 Show specific type of messages.
 284 .TP
 285 debug_list <subs/types>
 286 List all the subsystem and debug types.
 287 .TP
 288 modules <path>
 289 Provide gdb-friendly module information.
 290 .TP
 291 panic
 292 Force the kernel to panic.
 293 .TP
 294 lwt start/stop [file]
 295 Light-weight tracing.
 296 .TP
 297 memhog <page count> [<gfp flags>]
 298 Memory pressure testing.
 299 .PP
 300 .B Control
 301 .TP
 302 help
 303 Show a complete list of commands; help <command name> can be used to get help on specific command.
 304 .TP
 305 exit
 306 Close the lctl session.
 307 .TP
 308 quit
 309 Close the lctl session.
 310
 311 .SH OPTIONS
 312 The following options can be used to invoke lctl.
 313 .TP
 314 .B --device
 315 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.
 316 .TP
 317 .B --threads
 318 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.
 319 .TP
 320 .B --ignore_errors | ignore_errors
 321 Ignore errors during script processing
 322 .TP
 323 .B dump
 324 Save ioctls to a file
 325 .SH EXAMPLES
 326 .B attach
 327
 328 # lctl
 329 .br
 330 lctl > newdev
 331 .br
 332 lctl > attach obdfilter OBDDEV OBDUUID
 333
 334 .B connect
 335
 336 lctl > name2dev OSCDEV 2
 337 .br
 338 lctl > device 2
 339 .br
 340 lctl > connect
 341
 342 .B getattr
 343
 344 lctl > getattr 12
 345 .br
 346 id: 12
 347 .br
 348 grp: 0
 349 .br
 350 atime: 1002663714
 351 .br
 352 mtime: 1002663535
 353 .br
 354 ctime: 1002663535
 355 .br
 356 size: 10
 357 .br
 358 blocks: 8
 359 .br
 360 blksize: 4096
 361 .br
 362 mode: 100644
 363 .br
 364 uid: 0
 365 .br
 366 gid: 0
 367 .br
 368 flags: 0
 369 .br
 370 obdflags: 0
 371 .br
 372 nlink: 1
 373 .br
 374 valid: ffffffff
 375 .br
 376 inline:
 377 .br
 378 obdmd:
 379 .br
 380 lctl > disconnect
 381 .br
 382 Finished (success)
 383
 384 .B setup
 385
 386 lctl > setup /dev/loop0 extN
 387 .br
 388 lctl > quit
 389
 390 .SH BUGS
 391 None are known.