2 .\" Copyright (c) 2003 Silicon Graphics International Corp.
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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.
30 .\" ctladm utility man page.
32 .\" Author: Ken Merry <ken@FreeBSD.org>
34 .\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $
42 .Nd CAM Target Layer control utility
72 .Aq Fl b Ar blocksize_bytes
82 .Aq Fl b Ar blocksize_bytes
99 .Aq Fl m Ar page | Fl l
121 .Op Fl b Ar blockcount
140 .Aq Fl l Ar datamove|done
142 .Op Fl T Ar oneshot|cont
144 .Ic realsync Aq on|off|query
157 .Op Fl s Ar len fmt Op Ar args
159 .Op Fl d Ar delete_id
163 .Op Fl B Ar blocksize
164 .Op Fl d Ar device_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
174 .Op Fl o Ar name=value
179 .Aq Fl s Ar size_bytes
191 .Op Fl p Ar targ_port
205 .Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
208 .Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
214 utility is designed to provide a way to access and control the CAM Target
216 It provides a way to send
218 commands to the CTL layer, and also provides
219 some meta-commands that utilize
224 command is implemented using the
226 REPORT LUNS and INQUIRY commands.)
230 utility has a number of primary functions, many of which require a device
232 The device identifier takes the following form:
235 Specify the target (almost always 0) and LUN number to operate on.
237 Many of the primary functions of the
239 utility take the following optional arguments:
242 Specify the number of times to retry a command in the event of failure.
244 Specify the device to open. This allows opening a device other than the
247 to be opened for sending commands.
249 Specify the initiator number to use.
252 will use 7 as the initiator number.
260 TEST UNIT READY command to the device and report whether or not it is
265 INQUIRY command to the device and display some of the returned inquiry
270 REQUEST SENSE command to the device and display the returned sense
275 REPORT LUNS command to the device and display supported LUNs.
279 READ command to the device, and write the requested data to a file or
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
288 Specify the length, in 512 byte blocks, of the READ request.
290 Specify the destination for the data read by the READ command. Either a
293 for stdout may be specified.
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
304 device, so the transfer length
305 can be calculated accurately. The blocksize can be obtained via the
307 READ CAPACITY command.
311 from the kernel when doing a read, just execute the command without copying
313 This is to be used for performance testing.
316 Read data from a file or stdin, and write the data to the device using the
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
326 Specify the length, in 512 byte blocks, of the WRITE request.
328 Specify the source for the data to be written by the WRITE command. Either a
331 for stdin may be specified.
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
342 device, so the transfer length
343 can be calculated accurately. The blocksize can be obtained via the
345 READ CAPACITY command.
349 to the kernel when doing a write, just execute the command without copying
351 This is to be used for performance testing.
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.
361 The data for this particular command will be discarded, and not returned to
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
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
376 Specify the starting Logical Block Address.
378 Specify the amount of data in bytes to read from the LUN. This must be a
379 multiple of the LUN blocksize.
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,
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
392 argument. Valid values for the
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
400 MODE SENSE command to the device, and display the requested mode page(s) or
404 Specify the mode page to display. This option and the
406 option are mutually exclusive. One of the two must be specified, though.
407 Mode page numbers may be specified in decimal or hexadecimal.
409 Request that the list of mode pages supported by the device be returned.
412 option are mutually exclusive. One of the two must be specified, though.
414 Specify the mode page control value. Possible values are:
415 .Bl -tag -width 2n -compact
419 Changeable value bitmask.
426 Disable block descriptors when sending the mode sense request.
428 Specify the subpage used with the mode sense request.
430 Specify the CDB size used for the mode sense request. Supported values are
436 START STOP UNIT command to the specified LUN with the start
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
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
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
453 flag to spin up the disks in the LUN.
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
463 sends an ordered tag for completeness.)
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
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
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
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.
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.
502 Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE
503 command rather than waiting for the cache to finish syncing. CTL does not
506 Specify the minimum CDB size. Valid values are 10 and 16 bytes.
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
522 will accomplish this. Note that the
523 on/offline bit is a non-standard Copan extension to the
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.)
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.
535 Use the kernel facility for stopping all direct access LUNs and setting the
536 offline bit. Unlike the
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.
544 This command is functionally identical to the
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
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.
557 Delay commands at the given location. There are two places where commands
558 may be delayed currently: before data is transferred
560 and just prior to sending status to the host
562 One of the two must be supplied as an argument to the
566 option must also be specified.
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.
580 option will delay the next command sent to the given LUN.
583 option, every command will be delayed by the specified period of time.
586 the next command sent to the given LUN will be delayed and all subsequent
587 commands will be completed normally.
591 Query and control CTL's SYNCHRONIZE CACHE behavior. The
594 will show whether SYNCHRONIZE CACHE commands are being sent to the backend
596 The default is to send SYNCHRONIZE CACHE commands to the backend.
599 argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be
603 argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be
604 immediately returned to the initiator with successful status.
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
612 You must specify the target and LUN you want to modify.
614 Get the interval at which we actually service the SYNCHRONIZE CACHE
615 command, as set by the
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
622 You must specify the target and LUN you want to query.
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
630 Errors are only injected for commands that have not already failed for
632 By default, only the first command matching the pattern specified is
633 returned with the supplied error.
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
643 Specify the error to return:
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
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")
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").
659 Return the next matching command on the specified LUN with the supplied
663 argument must be specified.
666 Specify which commands should be returned with the given error.
669 The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
671 The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
674 The error should apply to both read and write type commands.
676 The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
678 The error should apply to TEST UNIT READY commands.
680 The error should apply to any command.
683 Specify the starting lba and length of the range of LBAs which should
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.
691 len bytes of sense data will be read from standard input and written to the
693 If len is longer than 252 bytes (the maximum allowable
695 sense data length), it will be truncated to that length.
696 The sense data format is described in
699 The error injection should be persistent, instead of happening once.
700 Persistent errors must be deleted with the
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.
708 Perform one of several CTL frontend port operations.
709 Either get a list of frontend ports
711 turn one or more frontends on
714 or set the World Wide Node Name
716 or World Wide Port Name
727 The WWNN and WWPN may both be specified at the same time, but cannot be
728 combined with enabling/disabling or listing ports.
731 List all CTL frontend ports or a specific port type or number.
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
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.
740 Omit the header in the port list output.
742 Specify the frontend type.
743 Currently defined port types are
749 (CTL ioctl interface),
754 Set the World Wide Node Name for the given port.
757 argument must be specified, since this is only possible to implement on a
759 As a general rule, the WWNN should be the same across all ports on the
762 Set the World Wide Port Name for the given port.
765 argument must be specified, since this is only possible to implement on a
767 As a general rule, the WWPN must be different for every port in the system.
769 Output the port list in XML format.
772 Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
774 Dump the CTL structures to the console.
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
781 If LUN creation fails, a message will be displayed describing the failure.
787 This specifies the name backend to use when creating the LUN.
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
797 INQUIRY VPD page 0x83 data.
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.
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
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)
822 The backend requested may or may not support all of the LUN types that CTL
827 The backend must be specified, and the LUN number must also be specified.
828 Backend-specific options may also be specified with the
833 Specify the backend that owns the LUN to be removed.
839 Specify the LUN number to remove.
840 .It Fl o Ar name=value
841 Specify a backend-specific name/value pair.
844 arguments may be specified.
845 Refer to the backend documentation for arguments that may be used.
849 The backend, the LUN number, and the size must be specified.
852 Specify the backend that owns the LUN to be removed.
858 Specify the LUN number to remove.
859 .It Fl s Ar size_bytes
860 Specify the size of the LUN in bytes.
865 keyword may be passed instead; this will make CTL use the size of backing
869 Get a list of all configured LUNs.
870 This also includes the LUN size and blocksize, serial number and device ID.
874 This restricts the LUN list to the named backend.
881 This will also display any backend-specific LUN attributes in addition to
882 the standard per-LUN information.
885 The LUN list information from the kernel comes in XML format, and this
886 option allows the display of the raw XML data.
891 options are mutually exclusive.
894 the entire LUN database is displayed in XML format.
897 Get a list of currently running iSCSI connections.
898 This includes initiator and target names and the unique connection IDs.
904 The connections list information from the kernel comes in XML format, and this
905 option allows the display of the raw XML data.
908 Ask the initiator to log out iSCSI connections matching criteria.
911 Log out all connections.
913 Specify connection ID.
915 Specify initiator name.
917 Specify initiator portal (hostname or IP address).
920 Forcibly terminate iSCSI connections matching criteria.
923 Terminate all connections.
925 Specify connection ID.
927 Specify initiator name.
929 Specify initiator portal (hostname or IP address).
937 Number of additional configuration options may be specified for LUNs.
938 Some options are global, others are backend-specific.
943 Specifies LUN vendor string up to 8 chars.
945 Specifies LUN product string up to 16 chars.
947 Specifies LUN revision string up to 4 chars.
949 Specifies LUN SCSI name string.
951 Specifies LUN EUI-64 identifier.
953 Specifies LUN NAA identifier.
954 Either EUI or NAA identifier should be set to UNIQUE value to allow
955 EXTENDED COPY command access the LUN.
956 Non-unique LUN identifiers may lead to data corruption.
958 Setting to "on" allows EXTENDED COPY command sent to this LUN access
959 other LUNs on this host, not accessible otherwise.
960 This allows to offload copying between different iSCSI targets residing
961 on the same host in trusted environments.
963 Set to "on", enables UNMAP support for the LUN.
966 Options specific for block backend:
969 Specifies file or device name to use for backing store.
971 Specifies number of backend threads to use for this LUN.
978 TEST UNIT READY command to LUN 1.
980 .Dl ctladm modesense 0:1 -l
982 Display the list of mode pages supported by LUN 1.
984 .Dl ctladm modesense 0:0 -m 10 -P 3 -d -c 10
986 Display the saved version of the Control mode page (page 10) on LUN 0.
987 Disable fetching block descriptors, and use a 10 byte MODE SENSE command
988 instead of the default 6 byte command.
990 ctladm read 0:2 -l 0 -d 1 -b 512 -f - > foo
993 Read the first 512 byte block from LUN 2 and dump it to the file
996 ctladm write 0:3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
999 Read 10240 bytes from the file
1001 and write it to target 0, LUN 3.
1002 starting at LBA 0xff432140.
1004 .Dl ctladm create -b ramdisk -s 10485760000000000
1006 Create a LUN with the
1008 ramdisk as a backing store.
1009 The LUN will claim to have a size of approximately 10 terabytes.
1011 .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8
1013 Create a LUN using the block backend, and specify the file
1014 .Pa src/usr.sbin/ctladm/ctladm.8
1015 as the backing store.
1016 The size of the LUN will be derived from the size of the file.
1018 .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123
1020 Create a LUN using the block backend, specify the file
1021 .Pa src/usr.sbin/ctladm/ctladm.8
1022 as the backing store, and specify the
1024 VPD page 0x80 and 0x83 serial number
1029 .Dl ctladm remove -b block -l 12
1031 Remove LUN 12, which is handled by the block backend, from the system.
1035 List configured LUNs in the system, along with their backend and serial
1037 This works when the Front End Target Drivers are enabled or disabled.
1041 List all LUNs in the system, along with their inquiry data and device type.
1042 This only works when the FETDs are enabled, since the commands go through the
1045 .Dl ctladm inject 0:6 -i mediumerr -p read -r 0,512 -c
1047 Inject a medium error on LUN 6 for every read that covers the first 512
1049 .Bd -literal -offset indent
1050 ctladm inject 0:6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
1053 Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
1054 This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
1055 0x04,0x02 ("Logical unit not ready, initializing command required").
1058 .Xr cam_cdbparse 3 ,
1067 utility was originally written during the Winter/Spring of 2003 as an
1070 .An Ken Merry Aq ken@FreeBSD.org