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