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