2 .\" Copyright (c) 2003 Silicon Graphics International Corp.
3 .\" Copyright (c) 2015 Alexander Motin <mav@FreeBSD.org>
4 .\" All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions, and the following disclaimer,
11 .\" without modification.
12 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
13 .\" substantially similar to the "NO WARRANTY" disclaimer below
14 .\" ("Disclaimer") and any redistribution must be conditioned upon
15 .\" including a substantially similar Disclaimer requirement for further
16 .\" binary redistribution.
19 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
20 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
21 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
22 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
23 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
27 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
28 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
29 .\" POSSIBILITY OF SUCH DAMAGES.
31 .\" ctladm utility man page.
33 .\" Author: Ken Merry <ken@FreeBSD.org>
35 .\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $
43 .Nd CAM Target Layer control utility
73 .Aq Fl b Ar blocksize_bytes
83 .Aq Fl b Ar blocksize_bytes
94 .Aq Fl m Ar page | Fl l
116 .Op Fl b Ar blockcount
125 .Aq Fl l Ar datamove|done
127 .Op Fl T Ar oneshot|cont
133 .Op Fl s Ar len fmt Op Ar args
135 .Op Fl d Ar delete_id
139 .Op Fl B Ar blocksize
140 .Op Fl d Ar device_id
142 .Op Fl o Ar name=value
143 .Op Fl s Ar size_bytes
144 .Op Fl S Ar serial_num
145 .Op Fl t Ar device_type
150 .Op Fl o Ar name=value
155 .Op Fl o Ar name=value
156 .Aq Fl s Ar size_bytes
167 .Op Fl p Ar targ_port
174 .Op Fl p Ar targ_port
180 .Aq Fl p Ar targ_port
193 .Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
196 .Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
202 utility is designed to provide a way to access and control the CAM Target
204 It provides a way to send
206 commands to the CTL layer, and also provides
207 some meta-commands that utilize
212 command is implemented using the
214 REPORT LUNS and INQUIRY commands.)
218 utility has a number of primary functions, many of which require a device
220 The device identifier takes the following form:
223 Specify the LUN number to operate on.
225 Many of the primary functions of the
227 utility take the following optional arguments:
230 Specify the number of times to retry a command in the event of failure.
232 Specify the device to open. This allows opening a device other than the
235 to be opened for sending commands.
237 Specify the initiator number to use.
240 will use 7 as the initiator number.
248 TEST UNIT READY command to the device and report whether or not it is
253 INQUIRY command to the device and display some of the returned inquiry
258 REQUEST SENSE command to the device and display the returned sense
263 REPORT LUNS command to the device and display supported LUNs.
267 READ command to the device, and write the requested data to a file or
271 Specify the starting Logical Block Address for the READ. This can be
272 specified in decimal, octal (starting with 0), hexadecimal (starting with
273 0x) or any other base supported by
276 Specify the length, in 512 byte blocks, of the READ request.
278 Specify the destination for the data read by the READ command. Either a
281 for stdout may be specified.
285 CDB (Command Data Block) size to be used for the READ request. Allowable
286 values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
287 requested, a larger CDB size may be used to satisfy the request. (e.g.,
288 for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
289 .It Fl b Ar blocksize
290 Specify the blocksize of the underlying
292 device, so the transfer length
293 can be calculated accurately. The blocksize can be obtained via the
295 READ CAPACITY command.
299 from the kernel when doing a read, just execute the command without copying
301 This is to be used for performance testing.
304 Read data from a file or stdin, and write the data to the device using the
309 Specify the starting Logical Block Address for the WRITE. This can be
310 specified in decimal, octal (starting with 0), hexadecimal (starting with
311 0x) or any other base supported by
314 Specify the length, in 512 byte blocks, of the WRITE request.
316 Specify the source for the data to be written by the WRITE command. Either a
319 for stdin may be specified.
323 CDB (Command Data Block) size to be used for the READ request. Allowable
324 values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
325 requested, a larger CDB size may be used to satisfy the request. (e.g.,
326 for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
327 .It Fl b Ar blocksize
328 Specify the blocksize of the underlying
330 device, so the transfer length
331 can be calculated accurately. The blocksize can be obtained via the
333 READ CAPACITY command.
337 to the kernel when doing a write, just execute the command without copying
339 This is to be used for performance testing.
344 READ CAPACITY command to the device and display the device size and device
345 block size. By default, READ CAPACITY(10) is
346 used. If the device returns a maximum LBA of 0xffffffff, however,
348 will automatically issue a READ CAPACITY(16), which is implemented as a
349 service action of the SERVICE ACTION IN(16) opcode. The user can specify
350 the minimum CDB size with the
352 argument. Valid values for the
354 option are 10 and 16. If a 10 byte CDB is specified, the request will be
355 automatically reissued with a 16 byte CDB if the maximum LBA returned is
360 MODE SENSE command to the device, and display the requested mode page(s) or
364 Specify the mode page to display. This option and the
366 option are mutually exclusive. One of the two must be specified, though.
367 Mode page numbers may be specified in decimal or hexadecimal.
369 Request that the list of mode pages supported by the device be returned.
372 option are mutually exclusive. One of the two must be specified, though.
374 Specify the mode page control value. Possible values are:
375 .Bl -tag -width 2n -compact
379 Changeable value bitmask.
386 Disable block descriptors when sending the mode sense request.
388 Specify the subpage used with the mode sense request.
390 Specify the CDB size used for the mode sense request. Supported values are
396 START STOP UNIT command to the specified LUN with the start
400 Set the immediate bit in the CDB. Note that CTL does not support the
401 immediate bit, so this is primarily useful for making sure that CTL returns
407 START STOP UNIT command to the specified LUN with the start
408 bit cleared. We use an ordered tag to stop the LUN, so we can guarantee
409 that all pending I/O executes before it is stopped. (CTL guarantees this
412 sends an ordered tag for completeness.)
415 Set the immediate bit in the CDB. Note that CTL does not support the
416 immediate bit, so this is primarily useful for making sure that CTL returns
422 SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE
423 CACHE(10) is used. If the specified starting LBA is greater than
424 0xffffffff or the length is greater than 0xffff, though,
425 SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used
426 if the user specifies a 16 byte CDB with the
431 Specify the starting LBA of the cache region to synchronize. This option is a
432 no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the
433 cache for the entire LUN.
434 .It Fl b Ar blockcount
435 Specify the length of the cache region to synchronize. This option is a
436 no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the
437 cache for the entire LUN.
439 Specify relative addressing for the starting LBA. CTL does not support
440 relative addressing, since it only works for linked commands, and CTL
441 does not support linked commands.
443 Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE
444 command rather than waiting for the cache to finish syncing. CTL does not
447 Specify the minimum CDB size. Valid values are 10 and 16 bytes.
450 List all LUNs registered with CTL.
451 Because this command uses the ioctl port, it will only work when the FETDs
452 (Front End Target Drivers) are enabled.
453 This command is the equivalent of doing a REPORT LUNS on one LUN and then
454 an INQUIRY on each LUN in the system.
456 Delay commands at the given location. There are two places where commands
457 may be delayed currently: before data is transferred
459 and just prior to sending status to the host
461 One of the two must be supplied as an argument to the
465 option must also be specified.
468 Delay command(s) at the specified location.
469 This can either be at the data movement stage (datamove) or prior to
470 command completion (done).
471 .It Fl t Ar delaytime
472 Delay command(s) for the specified number of seconds. This must be
473 specified. If set to 0, it will clear out any previously set delay for
474 this particular location (datamove or done).
475 .It Fl T Ar delaytype
476 Specify the delay type.
479 option will delay the next command sent to the given LUN.
482 option, every command will be delayed by the specified period of time.
485 the next command sent to the given LUN will be delayed and all subsequent
486 commands will be completed normally.
490 Inject the specified type of error for the LUN specified, when a command
491 that matches the given pattern is seen.
492 The sense data returned is in either fixed or descriptor format, depending
493 upon the status of the D_SENSE bit in the control mode page (page 0xa) for
496 Errors are only injected for commands that have not already failed for
498 By default, only the first command matching the pattern specified is
499 returned with the supplied error.
503 flag is specified, all commands matching the pattern will be returned with
504 the specified error until the error injection command is deleted with
509 Specify the error to return:
512 Return the next matching command on the specified LUN with the sense key
513 ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
516 Return the next matching command on the specified LUN with the sense key
517 MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
518 reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
521 Return the next matching command on the specified LUN with the sense key
522 UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
523 DEVICE RESET OCCURRED").
525 Return the next matching command on the specified LUN with the supplied
529 argument must be specified.
532 Specify which commands should be returned with the given error.
535 The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
537 The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
540 The error should apply to both read and write type commands.
542 The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
544 The error should apply to TEST UNIT READY commands.
546 The error should apply to any command.
549 Specify the starting lba and length of the range of LBAs which should
551 This option is only applies when read and/or write patterns are specified.
552 If used with other command types, the error will never be triggered.
553 .It Fl s Ar len fmt Op Ar args
554 Specify the sense data that is to be returned for custom actions.
557 len bytes of sense data will be read from standard input and written to the
559 If len is longer than 252 bytes (the maximum allowable
561 sense data length), it will be truncated to that length.
562 The sense data format is described in
565 The error injection should be persistent, instead of happening once.
566 Persistent errors must be deleted with the
569 .It Fl d Ar delete_id
570 Delete the specified error injection serial number.
571 The serial number is returned when the error is injected.
574 Perform one of several CTL frontend port operations.
575 Either get a list of frontend ports
577 turn one or more frontends on
580 or set the World Wide Node Name
582 or World Wide Port Name
593 The WWNN and WWPN may both be specified at the same time, but cannot be
594 combined with enabling/disabling or listing ports.
597 Turn the specified CTL frontend ports off or on.
598 If no port number or port type is specified, all ports are turned on or
600 .It Fl p Ar targ_port
601 Specify the frontend port number.
602 The port numbers can be found in the frontend port list.
604 Specify the frontend type.
605 Currently defined port types are
611 (CTL ioctl interface),
616 Set the World Wide Node Name for the given port.
619 argument must be specified, since this is only possible to implement on a
621 As a general rule, the WWNN should be the same across all ports on the
624 Set the World Wide Port Name for the given port.
627 argument must be specified, since this is only possible to implement on a
629 As a general rule, the WWPN must be different for every port in the system.
632 List CTL frontend ports.
635 Specify the frontend type.
637 Report target and connected initiators addresses.
640 .It Fl p Ar targ_port
641 Specify the frontend port number.
643 Omit the header in the port list output.
645 Enable verbose output (report all port options).
647 Output the port list in XML format.
650 Change LUN mapping for specified port.
655 are specified -- LUN will be mapped.
660 is not -- LUN will be unmapped.
665 are specified -- LUN mapping will be disabled, exposing all CTL LUNs.
667 .It Fl p Ar targ_port
668 Specify the frontend port number.
670 LUN number visible by specified port.
675 Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
677 Dump the CTL structures to the console.
680 The backend must be specified, and depending upon the backend requested,
681 some of the other options may be required.
682 If the LUN is created successfully, the LUN configuration will be
684 If LUN creation fails, a message will be displayed describing the failure.
690 This specifies the name backend to use when creating the LUN.
695 .It Fl B Ar blocksize
696 Specify the blocksize of the backend in bytes.
697 .It Fl d Ar device_id
698 Specify the LUN-associated string to use in the
700 INQUIRY VPD page 0x83 data.
702 Request that a particular LUN number be assigned.
703 If the requested LUN number is not available, the request will fail.
704 .It Fl o Ar name=value
705 Specify a backend-specific name/value pair.
708 arguments may be specified.
709 Refer to the backend documentation for arguments that may be used.
710 .It Fl s Ar size_bytes
711 Specify the size of the LUN in bytes.
712 Some backends may allow setting the size (e.g. the ramdisk backend) and for
713 others the size may be implicit (e.g. the block backend).
714 .It Fl S Ar serial_num
715 Specify the serial number to be used in the
717 INQUIRY VPD page 0x80 data.
718 .It Fl t Ar device_type
719 Specify the numeric SCSI device type to use when creating the LUN.
720 If this flag is not used, the type of LUN created is backend-specific.
721 Not all LUN types are supported.
722 Currently CTL supports Direct Access (type 0), Processor (type 3)
723 and CD/DVD (type 5) LUNs.
724 The backend requested may or may not support all of the LUN types that CTL
729 The backend must be specified, and the LUN number must also be specified.
730 Backend-specific options may also be specified with the
735 Specify the backend that owns the LUN to be removed.
741 Specify the LUN number to remove.
742 .It Fl o Ar name=value
743 Specify a backend-specific name/value pair.
746 arguments may be specified.
747 Refer to the backend documentation for arguments that may be used.
751 The backend, the LUN number, and the size must be specified.
754 Specify the backend that owns the LUN to be removed.
760 Specify the LUN number to remove.
761 .It Fl o Ar name=value
762 Specify a backend-specific name/value pair.
765 arguments may be specified.
766 Refer to the backend documentation for arguments that may be used.
767 .It Fl s Ar size_bytes
768 Specify the size of the LUN in bytes.
773 keyword may be passed instead; this will make CTL use the size of backing
777 Get a list of all configured LUNs.
778 This also includes the LUN size and blocksize, serial number and device ID.
782 This restricts the LUN list to the named backend.
789 This will also display any backend-specific LUN attributes in addition to
790 the standard per-LUN information.
793 The LUN list information from the kernel comes in XML format, and this
794 option allows the display of the raw XML data.
799 options are mutually exclusive.
802 the entire LUN database is displayed in XML format.
805 Get a list of currently running iSCSI connections.
806 This includes initiator and target names and the unique connection IDs.
812 The connections list information from the kernel comes in XML format, and this
813 option allows the display of the raw XML data.
816 Ask the initiator to log out iSCSI connections matching criteria.
819 Log out all connections.
821 Specify connection ID.
823 Specify initiator name.
825 Specify initiator portal (hostname or IP address).
828 Forcibly terminate iSCSI connections matching criteria.
831 Terminate all connections.
833 Specify connection ID.
835 Specify initiator name.
837 Specify initiator portal (hostname or IP address).
845 Number of additional configuration options may be specified for LUNs.
846 Some options are global, others are backend-specific.
851 Specifies LUN vendor string up to 8 chars.
853 Specifies LUN product string up to 16 chars.
855 Specifies LUN revision string up to 4 chars.
857 Specifies LUN SCSI name string.
859 Specifies LUN EUI-64 identifier.
861 Specifies LUN NAA identifier.
863 Specifies LUN locally assigned RFC 4122 UUID identifier.
864 EUI, NAA or UUID identifier should be set to UNIQUE value to allow
865 EXTENDED COPY command access the LUN.
866 Non-unique LUN identifiers may lead to data corruption.
867 Some initiators may not support later introduced UUID identifiers.
869 Setting to "primary" or "secondary" overrides default role of the node
870 in HA cluster, set by kern.cam.ctl.ha_role sysctl.
872 Setting to "on" allows EXTENDED COPY command sent to this LUN access
873 other LUNs on this host, not accessible otherwise.
874 This allows to offload copying between different iSCSI targets residing
875 on the same host in trusted environments.
877 Set to "off", disables read caching for the LUN, if supported by the backend.
879 Set to "on", blocks all media write operations to the LUN, reporting it
882 Set to "on", makes LUN removable.
884 Set to "unrestricted", allows target to process commands with SIMPLE task
885 attribute in arbitrary order. Any data integrity exposures related to
886 command sequence order shall be explicitly handled by the application
887 client through the selection of appropriate commands and task attributes.
888 The default value is "restricted". It improves data integrity, but may
889 introduce some additional delays.
891 Set to "on" to serialize conseсutive reads/writes.
892 Set to "read" to serialize conseсutive reads.
893 Set to "off" to allow them be issued in parallel.
894 Parallel issue of consecutive operations may confuse logic of the
895 backing file system, hurting performance; but it may improve performance
896 of backing stores without prefetch/write-back.
899 Specify physical block size and offset of the device.
902 Specify UNMAP block size and offset of the device.
904 Specifies medium rotation rate of the device: 0 -- not reported,
905 1 -- non-rotating (SSD), >1024 -- value in revolutions per minute.
907 Specifies nominal form factor of the device: 0 -- not reported, 1 -- 5.25",
908 2 -- 3.5", 3 -- 2.5", 4 -- 1.8", 5 -- less then 1.8".
909 .It Va provisioning_type
910 When UNMAP support is enabled, this option specifies provisioning type:
911 "resource", "thin" or "unknown".
912 Default value is "thin".
913 Logical units without UNMAP support are reported as fully provisioned.
915 Setting to "on" or "off" controls UNMAP support for the logical unit.
916 Default value is "on" if supported by the backend.
918 .It Va unmap_max_descr
919 Specify maximum allowed number of LBAs and block descriptors per UNMAP
920 command to report in Block Limits VPD page.
921 .It Va write_same_max_lba
922 Specify maximum allowed number of LBAs per WRITE SAME command to report
923 in Block Limits VPD page.
924 .It Va avail-threshold
925 .It Va used-threshold
926 .It Va pool-avail-threshold
927 .It Va pool-used-threshold
928 Set per-LUN/-pool thin provisioning soft thresholds.
929 LUN will establish UNIT ATTENTION condition if its or pool available space
930 get below configured avail values, or its or pool used space get above
931 configured used values.
932 Pool thresholds are working only for ZVOL-backed LUNs.
934 Set to "off", disables write caching for the LUN, if supported by the backend.
937 Options specific for block backend:
940 Specifies file or device name to use for backing store.
942 Specifies number of backend threads to use for this LUN.
945 Options specific for ramdisk backend:
948 Specifies capacity of backing store (maximum RAM for data).
949 The default value is zero, that disables backing store completely,
950 making all writes go to nowhere, while all reads return zeroes.
957 TEST UNIT READY command to LUN 1.
959 .Dl ctladm modesense 1 -l
961 Display the list of mode pages supported by LUN 1.
963 .Dl ctladm modesense 0 -m 10 -P 3 -d -c 10
965 Display the saved version of the Control mode page (page 10) on LUN 0.
966 Disable fetching block descriptors, and use a 10 byte MODE SENSE command
967 instead of the default 6 byte command.
969 ctladm read 2 -l 0 -d 1 -b 512 -f - > foo
972 Read the first 512 byte block from LUN 2 and dump it to the file
975 ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
978 Read 10240 bytes from the file
980 and write it to LUN 3.
981 starting at LBA 0xff432140.
983 .Dl ctladm create -b ramdisk -s 10485760000000000
985 Create a LUN with the
987 ramdisk as a backing store.
988 The LUN will claim to have a size of approximately 10 terabytes,
989 while having no real data store (all written data are lost).
991 .Dl ctladm create -b ramdisk -s 10T -o capacity=10G
993 Create a thin provisioned LUN with a ramdisk as a backing store.
994 The LUN will have maximal backing store capacity of 10 gigabytes,
995 while reporting size of 10 terabytes,
997 .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8
999 Create a LUN using the block backend, and specify the file
1000 .Pa src/usr.sbin/ctladm/ctladm.8
1001 as the backing store.
1002 The size of the LUN will be derived from the size of the file.
1004 .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123
1006 Create a LUN using the block backend, specify the file
1007 .Pa src/usr.sbin/ctladm/ctladm.8
1008 as the backing store, and specify the
1010 VPD page 0x80 and 0x83 serial number
1015 .Dl ctladm remove -b block -l 12
1017 Remove LUN 12, which is handled by the block backend, from the system.
1021 List configured LUNs in the system, along with their backend and serial
1023 This works when the Front End Target Drivers are enabled or disabled.
1027 List all LUNs in the system, along with their inquiry data and device type.
1028 This only works when the FETDs are enabled, since the commands go through the
1031 .Dl ctladm inject 6 -i mediumerr -p read -r 0,512 -c
1033 Inject a medium error on LUN 6 for every read that covers the first 512
1035 .Bd -literal -offset indent
1036 ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
1039 Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
1040 This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
1041 0x04,0x02 ("Logical unit not ready, initializing command required").
1044 .Xr cam_cdbparse 3 ,
1054 utility was originally written during the Winter/Spring of 2003 as an
1057 .An Ken Merry Aq ken@FreeBSD.org
projects / FreeBSD / stable / 10.git / blob