usr.sbin/ctladm/ctladm.8

   1 .\"
   2 .\" Copyright (c) 2003 Silicon Graphics International Corp.
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions, and the following disclaimer,
  10 .\"    without modification.
  11 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
  12 .\"    substantially similar to the "NO WARRANTY" disclaimer below
  13 .\"    ("Disclaimer") and any redistribution must be conditioned upon
  14 .\"    including a substantially similar Disclaimer requirement for further
  15 .\"    binary redistribution.
  16 .\"
  17 .\" NO WARRANTY
  18 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  19 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  20 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
  21 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  22 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  26 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
  27 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGES.
  29 .\"
  30 .\" ctladm utility man page.
  31 .\"
  32 .\" Author: Ken Merry <ken@FreeBSD.org>
  33 .\"
  34 .\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $
  35 .\" $FreeBSD$
  36 .\"
  37 .Dd April 2, 2013
  38 .Dt CTLADM 8
  39 .Os
  40 .Sh NAME
  41 .Nm ctladm
  42 .Nd CAM Target Layer control utility
  43 .Sh SYNOPSIS
  44 .Nm
  45 .Aq Ar command
  46 .Op target:lun
  47 .Op generic args
  48 .Op command args
  49 .Nm
  50 .Ic tur
  51 .Aq target:lun
  52 .Op general options
  53 .Nm
  54 .Ic inquiry
  55 .Aq target:lun
  56 .Op general options
  57 .Nm
  58 .Ic reqsense
  59 .Aq target:lun
  60 .Op general options
  61 .Nm
  62 .Ic reportluns
  63 .Aq target:lun
  64 .Op general options
  65 .Nm
  66 .Ic read
  67 .Aq target:lun
  68 .Op general options
  69 .Aq Fl l Ar lba
  70 .Aq Fl d Ar datalen
  71 .Aq Fl f Ar file|-
  72 .Aq Fl b Ar blocksize_bytes
  73 .Op Fl c Ar cdbsize
  74 .Op Fl N
  75 .Nm
  76 .Ic write
  77 .Aq target:lun
  78 .Op general options
  79 .Aq Fl l Ar lba
  80 .Aq Fl d Ar datalen
  81 .Aq Fl f Ar file|-
  82 .Aq Fl b Ar blocksize_bytes
  83 .Op Fl c Ar cdbsize
  84 .Op Fl N
  85 .Nm
  86 .Ic bbrread
  87 .Aq target:lun
  88 .Op general options
  89 .Aq Fl -l Ar lba
  90 .Aq Fl -d Ar datalen
  91 .Nm
  92 .Ic readcap
  93 .Aq target:lun
  94 .Op general options
  95 .Op Fl c Ar cdbsize
  96 .Nm
  97 .Ic modesense
  98 .Aq target:lun
  99 .Aq Fl m Ar page | Fl l
 100 .Op Fl P Ar pc
 101 .Op Fl d
 102 .Op Fl S Ar subpage
 103 .Op Fl c Ar size
 104 .Nm
 105 .Ic start
 106 .Aq target:lun
 107 .Op general options
 108 .Op Fl i
 109 .Op Fl o
 110 .Nm
 111 .Ic stop
 112 .Aq target:lun
 113 .Op general options
 114 .Op Fl i
 115 .Op Fl o
 116 .Nm
 117 .Ic synccache
 118 .Aq target:lun
 119 .Op general options
 120 .Op Fl l Ar lba
 121 .Op Fl b Ar blockcount
 122 .Op Fl r
 123 .Op Fl i
 124 .Op Fl c Ar cdbsize
 125 .Nm
 126 .Ic shutdown
 127 .Op general options
 128 .Nm
 129 .Ic startup
 130 .Op general options
 131 .Nm
 132 .Ic hardstop
 133 .Nm
 134 .Ic hardstart
 135 .Nm
 136 .Ic lunlist
 137 .Nm
 138 .Ic delay
 139 .Aq target:lun
 140 .Aq Fl l Ar datamove|done
 141 .Aq Fl t Ar secs
 142 .Op Fl T Ar oneshot|cont
 143 .Nm
 144 .Ic realsync Aq on|off|query
 145 .Nm
 146 .Ic setsync interval
 147 .Aq target:lun
 148 .Aq Fl i Ar interval
 149 .Nm
 150 .Ic getsync
 151 .Aq target:lun
 152 .Nm
 153 .Ic inject
 154 .Aq Fl i Ar action
 155 .Aq Fl p Ar pattern
 156 .Op Fl r Ar lba,len
 157 .Op Fl s Ar len fmt Op Ar args
 158 .Op Fl c
 159 .Op Fl d Ar delete_id
 160 .Nm
 161 .Ic create
 162 .Aq Fl b Ar backend
 163 .Op Fl B Ar blocksize
 164 .Op Fl d Ar device_id
 165 .Op Fl l Ar lun_id
 166 .Op Fl o Ar name=value
 167 .Op Fl s Ar size_bytes
 168 .Op Fl S Ar serial_num
 169 .Op Fl t Ar device_type
 170 .Nm
 171 .Ic remove
 172 .Aq Fl b Ar backend
 173 .Aq Fl l Ar lun_id
 174 .Op Fl o Ar name=value
 175 .Nm
 176 .Ic modify
 177 .Aq Fl b Ar backend
 178 .Aq Fl l Ar lun_id
 179 .Aq Fl s Ar size_bytes
 180 .Nm
 181 .Ic devlist
 182 .Op Fl b Ar backend
 183 .Op Fl v
 184 .Op Fl x
 185 .Nm
 186 .Ic port
 187 .Op Fl l
 188 .Op Fl o Ar on|off
 189 .Op Fl w Ar wwpn
 190 .Op Fl W Ar wwnn
 191 .Op Fl p Ar targ_port
 192 .Op Fl t Ar fe_type
 193 .Op Fl q
 194 .Op Fl x
 195 .Nm
 196 .Ic dumpooa
 197 .Nm
 198 .Ic dumpstructs
 199 .Nm
 200 .Ic help
 201 .Sh DESCRIPTION
 202 The
 203 .Nm
 204 utility is designed to provide a way to access and control the CAM Target
 205 Layer (CTL).
 206 It provides a way to send
 207 .Tn SCSI
 208 commands to the CTL layer, and also provides
 209 some meta-commands that utilize
 210 .Tn SCSI
 211 commands.
 212 (For instance, the
 213 .Ic lunlist
 214 command is implemented using the
 215 .Tn SCSI
 216 REPORT LUNS and INQUIRY commands.)
 217 .Pp
 218 The
 219 .Nm
 220 utility has a number of primary functions, many of which require a device
 221 identifier.
 222 The device identifier takes the following form:
 223 .Bl -tag -width 14n
 224 .It target:lun
 225 Specify the target (almost always 0) and LUN number to operate on.
 226 .El
 227 Many of the primary functions of the
 228 .Nm
 229 utility take the following optional arguments:
 230 .Pp
 231 .Bl -tag -width 10n
 232 .It Fl C Ar retries
 233 Specify the number of times to retry a command in the event of failure.
 234 .It Fl D Ar device
 235 Specify the device to open.  This allows opening a device other than the
 236 default device,
 237 .Pa /dev/cam/ctl ,
 238 to be opened for sending commands.
 239 .It Fl I Ar id
 240 Specify the initiator number to use.
 241 By default,
 242 .Nm
 243 will use 7 as the initiator number.
 244 .El
 245 .Pp
 246 Primary commands:
 247 .Bl -tag -width 11n
 248 .It Ic tur
 249 Send the
 250 .Tn SCSI
 251 TEST UNIT READY command to the device and report whether or not it is
 252 ready.
 253 .It Ic inquiry
 254 Send the
 255 .Tn SCSI
 256 INQUIRY command to the device and display some of the returned inquiry
 257 data.
 258 .It Ic reqsense
 259 Send the
 260 .Tn SCSI
 261 REQUEST SENSE command to the device and display the returned sense
 262 information.
 263 .It Ic reportluns
 264 Send the
 265 .Tn SCSI
 266 REPORT LUNS command to the device and display supported LUNs.
 267 .It Ic read
 268 Send a
 269 .Tn SCSI
 270 READ command to the device, and write the requested data to a file or
 271 stdout.
 272 .Bl -tag -width 12n
 273 .It Fl l Ar lba
 274 Specify the starting Logical Block Address for the READ.  This can be
 275 specified in decimal, octal (starting with 0), hexadecimal (starting with
 276 0x) or any other base supported by
 277 .Xr strtoull 3 .
 278 .It Fl d Ar datalen
 279 Specify the length, in 512 byte blocks, of the READ request.
 280 .It Fl f Ar file
 281 Specify the destination for the data read by the READ command.  Either a
 282 filename or
 283 .Sq -
 284 for stdout may be specified.
 285 .It Fl c Ar cdbsize
 286 Specify the minimum
 287 .Tn SCSI
 288 CDB (Command Data Block) size to be used for the READ request.  Allowable
 289 values are 6, 10, 12 and 16.  Depending upon the LBA and amount of data
 290 requested, a larger CDB size may be used to satisfy the request.  (e.g.,
 291 for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
 292 .It Fl b Ar blocksize
 293 Specify the blocksize of the underlying
 294 .Tn SCSI
 295 device, so the transfer length
 296 can be calculated accurately.  The blocksize can be obtained via the
 297 .Tn SCSI
 298 READ CAPACITY command.
 299 .It Fl N
 300 Do not copy data to
 301 .Nm
 302 from the kernel when doing a read, just execute the command without copying
 303 data.
 304 This is to be used for performance testing.
 305 .El
 306 .It Ic write
 307 Read data from a file or stdin, and write the data to the device using the
 308 .Tn SCSI
 309 WRITE command.
 310 .Bl -tag -width 12n
 311 .It Fl l Ar lba
 312 Specify the starting Logical Block Address for the WRITE.  This can be
 313 specified in decimal, octal (starting with 0), hexadecimal (starting with
 314 0x) or any other base supported by
 315 .Xr strtoull 3 .
 316 .It Fl d Ar atalen
 317 Specify the length, in 512 byte blocks, of the WRITE request.
 318 .It Fl f Ar file
 319 Specify the source for the data to be written by the WRITE command.  Either a
 320 filename or
 321 .Sq -
 322 for stdin may be specified.
 323 .It Fl c Ar cdbsize
 324 Specify the minimum
 325 .Tn SCSI
 326 CDB (Command Data Block) size to be used for the READ request.  Allowable
 327 values are 6, 10, 12 and 16.  Depending upon the LBA and amount of data
 328 requested, a larger CDB size may be used to satisfy the request.  (e.g.,
 329 for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
 330 .It Fl b Ar blocksize
 331 Specify the blocksize of the underlying
 332 .Tn SCSI
 333 device, so the transfer length
 334 can be calculated accurately.  The blocksize can be obtained via the
 335 .Tn SCSI
 336 READ CAPACITY command.
 337 .It Fl N
 338 Do not copy data to
 339 .Nm
 340 to the kernel when doing a write, just execute the command without copying
 341 data.
 342 This is to be used for performance testing.
 343 .El
 344 .It Ic bbrread
 345 Issue a SCSI READ command to the logical device to potentially force a bad
 346 block on a disk in the RAID set to be reconstructed from the other disks in
 347 the array.  This command should only be used on an array that is in the
 348 normal state.  If used on a critical array, it could cause the array to go
 349 offline if the bad block to be remapped is on one of the disks that is
 350 still active in the array.
 351 .Pp
 352 The data for this particular command will be discarded, and not returned to
 353 the user.
 354 .Pp
 355 In order to determine which LUN to read from, the user should first
 356 determine which LUN the disk with a bad block belongs to.  Then he should
 357 map the bad disk block back to the logical block address for the array in
 358 order to determine which LBA to pass in to the
 359 .Ic bbrread
 360 command.
 361 .Pp
 362 This command is primarily intended for testing.  In practice, bad block
 363 remapping will generally be triggered by the in-kernel Disk Aerobics and
 364 Disk Scrubbing code.
 365 .Bl -tag -width 10n
 366 .It Fl l Ar lba
 367 Specify the starting Logical Block Address.
 368 .It Fl d Ar datalen
 369 Specify the amount of data in bytes to read from the LUN.  This must be a
 370 multiple of the LUN blocksize.
 371 .El
 372 .It Ic readcap
 373 Send the
 374 .Tn SCSI
 375 READ CAPACITY command to the device and display the device size and device
 376 block size.  By default, READ CAPACITY(10) is
 377 used.  If the device returns a maximum LBA of 0xffffffff, however,
 378 .Nm
 379 will automatically issue a READ CAPACITY(16), which is implemented as a
 380 service action of the SERVICE ACTION IN(16) opcode.  The user can specify
 381 the minimum CDB size with the
 382 .Fl c
 383 argument.  Valid values for the
 384 .Fl c
 385 option are 10 and 16.  If a 10 byte CDB is specified, the request will be
 386 automatically reissued with a 16 byte CDB if the maximum LBA returned is
 387 0xffffffff.
 388 .It Ic modesense
 389 Send a
 390 .Tn SCSI
 391 MODE SENSE command to the device, and display the requested mode page(s) or
 392 page list.
 393 .Bl -tag -width 10n
 394 .It Fl m Ar page
 395 Specify the mode page to display.  This option and the
 396 .Fl l
 397 option are mutually exclusive.  One of the two must be specified, though.
 398 Mode page numbers may be specified in decimal or hexadecimal.
 399 .It Fl l
 400 Request that the list of mode pages supported by the device be returned.
 401 This option and the
 402 .Fl m
 403 option are mutually exclusive.  One of the two must be specified, though.
 404 .It Fl P Ar pc
 405 Specify the mode page page control value.  Possible values are:
 406 .Bl -tag -width 2n -compact
 407 .It 0
 408 Current values.
 409 .It 1
 410 Changeable value bitmask.
 411 .It 2
 412 Default values.
 413 .It 3
 414 Saved values.
 415 .El
 416 .It Fl d
 417 Disable block descriptors when sending the mode sense request.
 418 .It Fl S Ar subpage
 419 Specify the subpage used with the mode sense request.
 420 .It Fl c Ar cdbsize
 421 Specify the CDB size used for the mode sense request.  Supported values are
 422 6 and 10.
 423 .El
 424 .It Ic start
 425 Send the
 426 .Tn SCSI
 427 START STOP UNIT command to the specified LUN with the start
 428 bit set.
 429 .Bl -tag -width 4n
 430 .It Fl i
 431 Set the immediate bit in the CDB.  Note that CTL does not support the
 432 immediate bit, so this is primarily useful for making sure that CTL returns
 433 the proper error.
 434 .It Fl o
 435 Set the Copan proprietary on/offline bit in the CDB.  When this flag is
 436 used, the LUN will be marked online again (see the description of the
 437 .Ic shutdown
 438 and
 439 .Ic startup
 440 commands).  When this flag is used with a
 441 start command, the LUN will NOT be spun up.  You need to use a start
 442 command without the
 443 .Fl o
 444 flag to spin up the disks in the LUN.
 445 .El
 446 .It Ic stop
 447 Send the
 448 .Tn SCSI
 449 START STOP UNIT command to the specified LUN with the start
 450 bit cleared.  We use an ordered tag to stop the LUN, so we can guarantee
 451 that all pending I/O executes before it is stopped.  (CTL guarantees this
 452 anyway, but
 453 .Nm
 454 sends an ordered tag for completeness.)
 455 .Bl -tag -width 4n
 456 .It Fl i
 457 Set the immediate bit in the CDB.  Note that CTL does not support the
 458 immediate bit, so this is primarily useful for making sure that CTL returns
 459 the proper error.
 460 .It Fl o
 461 Set the Copan proprietary on/offline bit in the CDB.  When this flag is
 462 used, the LUN will be spun down and taken offline ("Logical unit not ready,
 463 manual intervention required").  See the description of the
 464 .Ic shutdown
 465 and
 466 .Ic startup
 467 options.
 468 .El
 469 .It Ic synccache
 470 Send the
 471 .Tn SCSI
 472 SYNCHRONIZE CACHE command to the device.  By default, SYNCHRONIZE
 473 CACHE(10) is used.  If the specified starting LBA is greater than
 474 0xffffffff or the length is greater than 0xffff, though,
 475 SYNCHRONIZE CACHE(16) will be used.  The 16 byte command will also be used
 476 if the user specifies a 16 byte CDB with the
 477 .Fl c
 478 argument.
 479 .Bl -tag -width 14n
 480 .It Fl l Ar lba
 481 Specify the starting LBA of the cache region to synchronize.  This option is a
 482 no-op for CTL.  If you send a SYNCHRONIZE CACHE command, it will sync the
 483 cache for the entire LUN.
 484 .It Fl b Ar blockcount
 485 Specify the length of the cache region to synchronize.  This option is a
 486 no-op for CTL.  If you send a SYNCHRONIZE CACHE command, it will sync the
 487 cache for the entire LUN.
 488 .It Fl r
 489 Specify relative addressing for the starting LBA.  CTL does not support
 490 relative addressing, since it only works for linked commands, and CTL
 491 doesn't support linked commands.
 492 .It Fl i
 493 Tell the target to return status immediately after issuing the SYHCHRONIZE CACHE
 494 command rather than waiting for the cache to finish syncing.  CTL does not
 495 support this bit.
 496 .It Fl c Ar cdbsize
 497 Specify the minimum CDB size.  Valid values are 10 and 16 bytes.
 498 .El
 499 .It Ic shutdown
 500 Issue a
 501 .Tn SCSI
 502 START STOP UNIT command with the start bit cleared and the on/offline bit
 503 set to all direct access LUNs.  This will spin down all direct access LUNs,
 504 and mark them offline ("Logical unit not ready, manual intervention
 505 required").  Once marked offline, the state can only be cleared by sending
 506 a START STOP UNIT command with the start bit set and the on/offline bit
 507 set.  The
 508 .Nm
 509 commands
 510 .Ic startup
 511 and
 512 .Ic start
 513 will accomplish this.  Note that the
 514 on/offline bit is a non-standard Copan extension to the
 515 .Tn SCSI
 516 START STOP UNIT command, so merely sending a normal start command from an
 517 initiator will not clear the condition.  (This is by design.)
 518 .It Ic startup
 519 Issue a
 520 .Tn SCSI
 521 START STOP UNIT command with the start bit set and the on/offline bit set
 522 to all direct access LUNs.  This will mark all direct access LUNs "online"
 523 again.  It will not cause any LUNs to start up.  A separate start command
 524 without the on/offline bit set is necessary for that.
 525 .It Ic hardstop
 526 Use the kernel facility for stopping all direct access LUNs and setting the
 527 offline bit.  Unlike the
 528 .Ic shutdown
 529 command above, this command allows shutting down LUNs with I/O active.  It
 530 will also issue a LUN reset to any reserved LUNs to break the reservation
 531 so that the LUN can be stopped.
 532 .Ic shutdown
 533 command instead.
 534 .It Ic hardstart
 535 This command is functionally identical to the
 536 .Ic startup
 537 command described above.  The primary difference is that the LUNs are
 538 enumerated and commands sent by the in-kernel Front End Target Driver
 539 instead of by
 540 .Nm .
 541 .It Ic lunlist
 542 List all LUNs registered with CTL.
 543 Because this command uses the ioctl port, it will only work when the FETDs
 544 (Front End Target Drivers) are enabled.
 545 This command is the equivalent of doing a REPORT LUNS on one LUN and then
 546 an INQUIRY on each LUN in the system.
 547 .It Ic delay
 548 Delay commands at the given location.  There are two places where commands
 549 may be delayed currently: before data is transferred
 550 .Pq Dq datamove
 551 and just prior to sending status to the host
 552 .Pq Dq done .
 553 One of the two must be supplied as an argument to the
 554 .Fl l
 555 option.  The
 556 .Fl t
 557 option must also be specified.
 558 .Bl -tag -width 12n
 559 .It Fl l Ar delayloc
 560 Delay command(s) at the specified location.
 561 This can either be at the data movement stage (datamove) or prior to
 562 command completion (done).
 563 .It Fl t Ar delaytime
 564 Delay command(s) for the specified number of seconds.  This must be
 565 specified.  If set to 0, it will clear out any previously set delay for
 566 this particular location (datamove or done).
 567 .It Fl T Ar delaytype
 568 Specify the delay type.
 569 By default, the
 570 .Ic delay
 571 option will delay the next command sent to the given LUN.
 572 With the
 573 .Fl T Ar cont
 574 option, every command will be delayed by the specified period of time.
 575 With the
 576 .Fl T Ar oneshot
 577 the next command sent to the given LUN will be delayed and all subsequent
 578 commands will be completed normally.
 579 This is the default.
 580 .El
 581 .It Ic realsync
 582 Query and control CTL's SYNCHRONIZE CACHE behavior.  The
 583 .Sq query
 584 argument
 585 will show whether SYNCHRONIZE CACHE commands are being sent to the backend
 586 or not.
 587 The default is to send SYNCHRONIZE CACHE commands to the backend.
 588 The
 589 .Sq on
 590 argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be
 591 sent to the backend.
 592 The
 593 .Sq off
 594 argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be
 595 immediately returned to the initiator with successful status.
 596 .It Ic setsync
 597 For a given lun, only actually service every Nth SYNCHRONIZE CACHE command
 598 that is sent.  This can be used for debugging the optimal time period for
 599 sending SYNCHRONIZE cache commands.  An interval of 0 means that the cache
 600 will be flushed for this LUN every time a SYNCHRONIZE CACHE command is
 601 received.
 602 .Pp
 603 You must specify the target and LUN you want to modify.
 604 .It Ic getsync
 605 Get the interval at which we actually service the SYNCHRONIZE CACHE
 606 command, as set by the
 607 .Ic setsync
 608 command above.
 609 The reported number means that we will actually flush the cache on every
 610 Nth SYNCHRONIZE CACHE command.  A value of 0 means that we will flush the
 611 cache every time.
 612 .Pp
 613 You must specify the target and LUN you want to query.
 614 .It Ic inject
 615 Inject the specified type of error for the LUN specified, when a command
 616 that matches the given pattern is seen.
 617 The sense data returned is in either fixed or descriptor format, depending
 618 upon the status of the D_SENSE bit in the control mode page (page 0xa) for
 619 the LUN.
 620 .Pp
 621 Errors are only injected for commands that have not already failed for
 622 other reasons.
 623 By default, only the first command matching the pattern specified is
 624 returned with the supplied error.
 625 .Pp
 626 If the
 627 .Fl c
 628 flag is specified, all commands matching the pattern will be returned with
 629 the specified error until the error injection command is deleted with
 630 .Fl d
 631 flag.
 632 .Bl -tag -width 17n
 633 .It Fl i Ar action
 634 Specify the error to return:
 635 .Bl -tag -width 10n
 636 .It aborted
 637 Return the next matching command on the specified LUN with the sense key
 638 ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
 639 failure").
 640 .It mediumerr
 641 Return the next matching command on the specified LUN with the sense key
 642 MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
 643 reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
 644 for write errors.
 645 .It ua
 646 Return the next matching command on the specified LUN with the sense key
 647 UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
 648 DEVICE RESET OCCURRED").
 649 .It custom
 650 Return the next matching command on the specified LUN with the supplied
 651 sense data.
 652 The
 653 .Fl s
 654 argument must be specified.
 655 .El
 656 .It Fl p Ar pattern
 657 Specify which commands should be returned with the given error.
 658 .Bl -tag -width 10n
 659 .It read
 660 The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
 661 .It write
 662 The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
 663 AND VERIFY(10), etc.
 664 .It rw
 665 The error should apply to both read and write type commands.
 666 .It readcap
 667 The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
 668 .It tur
 669 The error should apply to TEST UNIT READY commands.
 670 .It any
 671 The error should apply to any command.
 672 .El
 673 .It Fl r Ar lba,len
 674 Specify the starting lba and length of the range of LBAs which should
 675 trigger an error.
 676 This option is only applies when read and/or write patterns are specified.
 677 If used with other command types, the error will never be triggered.
 678 .It Fl s Ar len fmt Op Ar args
 679 Specify the sense data that is to be returned for custom actions.
 680 If the format is
 681 .Sq - ,
 682 len bytes of sense data will be read from standard input and written to the
 683 sense buffer.
 684 If len is longer than 252 bytes (the maximum allowable
 685 .Tn SCSI
 686 sense data length), it will be truncated to that length.
 687 The sense data format is described in
 688 .Xr cam_cdparse 3 .
 689 .It Fl c
 690 The error injection should be persistent, instead of happening once.
 691 Persistent errors must be deleted with the
 692 .Fl d
 693 argument.
 694 .It Fl d Ar delete_id
 695 Delete the specified error injection serial number.
 696 The serial number is returned when the error is injected.
 697 .El
 698 .It Ic port
 699 Perform one of several CTL frontend port operations.
 700 Either get a list of frontend ports
 701 .Pq Fl l ,
 702 turn one or more frontends on
 703 or off
 704 .Pq Fl o Ar on|off ,
 705 or set the World Wide Node Name
 706 .Pq Fl w Ar wwnn
 707 or World Wide Port Name
 708 .Pq Fl W Ar wwpn
 709 for a given port.
 710 One of
 711 .Fl l ,
 712 .Fl o ,
 713 or
 714 .Fl w
 715 or
 716 .Fl W
 717 must be specified.
 718 The WWNN and WWPN may both be specified at the same time, but cannot be
 719 combined with enabling/disabling or listing ports.
 720 .Bl -tag -width 12n
 721 .It Fl l
 722 List all CTL frontend ports or a specific port type or number.
 723 .It Fl o Ar on|off
 724 Turn the specified CTL frontend ports off or on.
 725 If no port number or port type is specified, all ports are turned on or
 726 off.
 727 .It Fl p Ar targ_port
 728 Specify the frontend port number.
 729 The port numbers can be found in the frontend port list.
 730 .It Fl q
 731 Omit the header in the port list output.
 732 .It Fl t Ar fe_type
 733 Specify the frontend type.
 734 Currently defined port types are
 735 .Dq fc
 736 (Fibre Channel),
 737 .Dq scsi
 738 (Parallel SCSI),
 739 .Dq ioctl
 740 (CTL ioctl interface),
 741 and
 742 .Dq internal
 743 (CTL CAM SIM).
 744 .It Fl w Ar wwnn
 745 Set the World Wide Node Name for the given port.
 746 The
 747 .Fl n
 748 argument must be specified, since this is only possible to implement on a
 749 single port.
 750 As a general rule, the WWNN should be the same across all ports on the
 751 system.
 752 .It Fl W Ar wwpn
 753 Set the World Wide Port Name for the given port.
 754 The
 755 .Fl n
 756 argument must be specified, since this is only possible to implement on a
 757 single port.
 758 As a general rule, the WWPN must be different for every port in the system.
 759 .It Fl x
 760 Output the port list in XML format.
 761 .El
 762 .It Ic dumpooa
 763 Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
 764 .It Ic dumpstructs
 765 Dump the CTL structures to the console.
 766 .It Ic create
 767 Create a new LUN.
 768 The backend must be specified, and depending upon the backend requested,
 769 some of the other options may be required.
 770 If the LUN is created successfully, the LUN configuration will be
 771 displayed.
 772 If LUN creation fails, a message will be displayed describing the failure.
 773 .Bl -tag -width 14n
 774 .It Fl b Ar backend
 775 The
 776 .Fl b
 777 flag is required.
 778 This specifies the name backend to use when creating the LUN.
 779 Examples are
 780 .Dq ramdisk
 781 and
 782 .Dq block .
 783 .It Fl B Ar blocksize
 784 Specify the blocksize of the backend in bytes.
 785 .It Fl d Ar device_id
 786 Specify the LUN-associated string to use in the
 787 .Tn SCSI
 788 INQUIRY VPD page 0x83 data.
 789 .It Fl l Ar lun_id
 790 Request that a particular LUN number be assigned.
 791 If the requested LUN number is not available, the request will fail.
 792 .It Fl o Ar name=value
 793 Specify a backend-specific name/value pair.
 794 Multiple
 795 .Fl o
 796 arguments may be specified.
 797 Refer to the backend documentation for arguments that may be used.
 798 .It Fl s Ar size_bytes
 799 Specify the size of the LUN in bytes.
 800 Some backends may allow setting the size (e.g. the ramdisk backend) and for
 801 others the size may be implicit (e.g. the block backend).
 802 .It Fl S Ar serial_num
 803 Specify the serial number to be used in the
 804 .Tn SCSI
 805 INQUIRY VPD page 0x80 data.
 806 .It Fl t Ar device_type
 807 Specify the numeric SCSI device type to use when creating the LUN.
 808 For example, the Direct Access type is 0.
 809 If this flag is not used, the type of LUN created is backend-specific.
 810 Not all LUN types are supported.
 811 Currently CTL only supports Direct Access (type 0) and Processor (type 3)
 812 LUNs.
 813 The backend requested may or may not support all of the LUN types that CTL
 814 supports.
 815 .El
 816 .It Ic remove
 817 Remove a LUN.
 818 The backend must be specified, and the LUN number must also be specified.
 819 Backend-specific options may also be specified with the
 820 .Fl o
 821 flag.
 822 .Bl -tag -width 14n
 823 .It Fl b Ar backend
 824 Specify the backend that owns the LUN to be removed.
 825 Examples are
 826 .Dq ramdisk
 827 and
 828 .Dq block .
 829 .It Fl l Ar lun_id
 830 Specify the LUN number to remove.
 831 .It Fl o Ar name=value
 832 Specify a backend-specific name/value pair.
 833 Multiple
 834 .Fl o
 835 arguments may be specified.
 836 Refer to the backend documentation for arguments that may be used.
 837 .El
 838 .It Ic modify
 839 Modify a LUN size.
 840 The backend, the LUN number, and the size must be specified.
 841 .Bl -tag -width 14n
 842 .It Fl b Ar backend
 843 Specify the backend that owns the LUN to be removed.
 844 Examples are
 845 .Dq ramdisk
 846 and
 847 .Dq block .
 848 .It Fl l Ar lun_id
 849 Specify the LUN number to remove.
 850 .It Fl s Ar size_bytes
 851 Specify the size of the LUN in bytes.
 852 For the
 853 .Dq block
 854 backend, an
 855 .Dq auto
 856 keyword may be passed instead; this will make CTL use the size of backing
 857 file or device.
 858 .El
 859 .It Ic devlist
 860 Get a list of all configured LUNs.
 861 This also includes the LUN size and blocksize, serial number and device ID.
 862 .Bl -tag -width 11n
 863 .It Fl b Ar backend
 864 Specify the backend.
 865 This restricts the LUN list to the named backend.
 866 Examples are
 867 .Dq ramdisk
 868 and
 869 .Dq block .
 870 .It Fl v
 871 Be verbose.
 872 This will also display any backend-specific LUN attributes in addition to
 873 the standard per-LUN information.
 874 .It Fl x
 875 Dump the raw XML.
 876 The LUN list information from the kernel comes in XML format, and this
 877 option allows the display of the raw XML data.
 878 This option and the
 879 .Fl v
 880 and
 881 .Fl b
 882 options are mutually exclusive.
 883 If you specify
 884 .Fl x ,
 885 the entire LUN database is displayed in XML format.
 886 .El
 887 .It Ic help
 888 Display
 889 .Nm
 890 usage information.
 891 .El
 892 .Sh EXAMPLES
 893 .Dl ctladm tur 0:1
 894 .Pp
 895 Send a
 896 .Tn SCSI
 897 TEST UNIT READY command to LUN 1.
 898 .Pp
 899 .Dl ctladm modesense 0:1 -l
 900 .Pp
 901 Display the list of mode pages supported by LUN 1.
 902 .Pp
 903 .Dl ctladm modesense 0:0 -m 10 -P 3 -d -c 10
 904 .Pp
 905 Display the saved version of the Control mode page (page 10) on LUN 0.
 906 Disable fetching block descriptors, and use a 10 byte MODE SENSE command
 907 instead of the default 6 byte command.
 908 .Pp
 909 .Bd -literal
 910 ctladm read 0:2 -l 0 -d 1 -b 512 -f - > foo
 911 .Ed
 912 .Pp
 913 Read the first 512 byte block from LUN 2 and dump it to the file
 914 .Pa foo .
 915 .Bd -literal
 916 ctladm write 0:3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
 917 .Ed
 918 .Pp
 919 Read 10240 bytes from the file
 920 .Pa /tmp/bar
 921 and write it to target 0, LUN 3.
 922 starting at LBA 0xff432140.
 923 .Pp
 924 .Dl ctladm create -b ramdisk -s 10485760000000000
 925 .Pp
 926 Create a LUN with the
 927 .Dq fake
 928 ramdisk as a backing store.
 929 The LUN will claim to have a size of approximately 10 terabytes.
 930 .Pp
 931 .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8
 932 .Pp
 933 Create a LUN using the block backend, and specify the file
 934 .Pa src/usr.sbin/ctladm/ctladm.8
 935 as the backing store.
 936 The size of the LUN will be derived from the size of the file.
 937 .Pp
 938 .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123
 939 .Pp
 940 Create a LUN using the block backend, specify the file
 941 .Pa src/usr.sbin/ctladm/ctladm.8
 942 as the backing store, and specify the
 943 .Tn SCSI
 944 VPD page 0x80 and 0x83 serial number
 945 .Fl ( S )
 946 and device ID
 947 .Fl ( d ) .
 948 .Pp
 949 .Dl ctladm remove -b block -l 12
 950 .Pp
 951 Remove LUN 12, which is handled by the block backend, from the system.
 952 .Pp
 953 .Dl ctladm devlist
 954 .Pp
 955 List configured LUNs in the system, along with their backend and serial
 956 number.
 957 This works when the Front End Target Drivers are enabled or disabled.
 958 .Pp
 959 .Dl ctladm lunlist
 960 .Pp
 961 List all LUNs in the system, along with their inquiry data and device type.
 962 This only works when the FETDs are enabled, since the commands go through the
 963 ioctl port.
 964 .Pp
 965 .Dl ctladm inject 0:6 -i mediumerr -p read -r 0,512 -c
 966 .Pp
 967 Inject a medium error on LUN 6 for every read that covers the first 512
 968 blocks of the LUN.
 969 .Pp
 970 .Bd -literal -offset indent
 971 ctladm inject 0:6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
 972 .Ed
 973 .Pp
 974 Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
 975 This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
 976 0x04,0x02 ("Logical unit not ready, initializing command required").
 977 .Sh SEE ALSO
 978 .Xr cam 3 ,
 979 .Xr cam_cdbparse 3 ,
 980 .Xr cam 4 ,
 981 .Xr ctl 4 ,
 982 .Xr xpt 4 ,
 983 .Xr camcontrol 8
 984 .Sh HISTORY
 985 The
 986 .Nm
 987 utility was originally written during the Winter/Spring of 2003 as an
 988 interface to CTL.
 989 .Sh AUTHORS
 990 .An Ken Merry Aq ken@FreeBSD.org