2 .\" Copyright (c) 2003 Silicon Graphics International Corp.
3 .\" Copyright (c) 2015-2021 Alexander Motin <mav@FreeBSD.org>
4 .\" Copyright (c) 2018 Marcelo Araujo <araujo@FreeBSD.org>
5 .\" All rights reserved.
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions, and the following disclaimer,
12 .\" without modification.
13 .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
14 .\" substantially similar to the "NO WARRANTY" disclaimer below
15 .\" ("Disclaimer") and any redistribution must be conditioned upon
16 .\" including a substantially similar Disclaimer requirement for further
17 .\" binary redistribution.
20 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
21 .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
22 .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
23 .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
24 .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
28 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
29 .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
30 .\" POSSIBILITY OF SUCH DAMAGES.
32 .\" ctladm utility man page.
34 .\" Author: Ken Merry <ken@FreeBSD.org>
36 .\" $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
169 .Op Fl p Ar targ_port
170 .Op Fl r Ar targ_port
177 .Op Fl p Ar targ_port
183 .Aq Fl p Ar targ_port
196 .Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
199 .Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
205 utility is designed to provide a way to access and control the CAM Target
207 It provides a way to send
209 commands to the CTL layer, and also provides
210 some meta-commands that utilize
215 command is implemented using the
217 REPORT LUNS and INQUIRY commands.)
221 utility has a number of primary functions, many of which require a device
223 The device identifier takes the following form:
226 Specify the LUN number to operate on.
228 Many of the primary functions of the
230 utility take the following optional arguments:
233 Specify the number of times to retry a command in the event of failure.
235 Specify the device to open.
236 This allows opening a device other than the default device,
238 to be opened for sending commands.
240 Specify the initiator number to use.
243 will use 7 as the initiator number.
251 TEST UNIT READY command to the device and report whether or not it is
256 INQUIRY command to the device and display some of the returned inquiry
261 REQUEST SENSE command to the device and display the returned sense
266 REPORT LUNS command to the device and display supported LUNs.
270 READ command to the device, and write the requested data to a file or
274 Specify the starting Logical Block Address for the READ.
275 This can be specified in decimal, octal (starting with 0),
276 hexadecimal (starting with 0x) or any other base supported by
279 Specify the length, in 512 byte blocks, of the READ request.
281 Specify the destination for the data read by the READ command.
284 for stdout may be specified.
288 CDB (Command Data Block) size to be used for the READ request.
289 Allowable values are 6, 10, 12 and 16.
290 Depending upon the LBA and amount of data requested, a larger CDB
291 size may be used to satisfy the request. (e.g., for LBAs above 0xffffffff,
292 READ(16) must be used to satisfy the request.)
293 .It Fl b Ar blocksize
294 Specify the blocksize of the underlying
296 device, so the transfer length
297 can be calculated accurately.
298 The blocksize can be obtained via the
300 READ CAPACITY command.
304 from the kernel when doing a read, just execute the command without copying
306 This is to be used for performance testing.
309 Read data from a file or stdin, and write the data to the device using the
314 Specify the starting Logical Block Address for the WRITE.
315 This can be specified in decimal, octal (starting with 0), hexadecimal
316 (starting with 0x) or any other base supported by
319 Specify the length, in 512 byte blocks, of the WRITE request.
321 Specify the source for the data to be written by the WRITE command.
324 for stdin may be specified.
328 CDB (Command Data Block) size to be used for the READ request.
329 Allowable values are 6, 10, 12 and 16.
330 Depending upon the LBA and amount of data requested, a larger CDB size
331 may be used to satisfy the request. (e.g., for LBAs above 0xffffffff, READ(16)
332 must be used to satisfy the request.)
333 .It Fl b Ar blocksize
334 Specify the blocksize of the underlying
336 device, so the transfer length
337 can be calculated accurately.
338 The blocksize can be obtained via the
340 READ CAPACITY command.
344 to the kernel when doing a write, just execute the command without copying
346 This is to be used for performance testing.
351 READ CAPACITY command to the device and display the device size and device
353 By default, READ CAPACITY(10) is used.
354 If the device returns a maximum LBA of 0xffffffff, however,
356 will automatically issue a READ CAPACITY(16), which is implemented as a
357 service action of the SERVICE ACTION IN(16) opcode.
358 The user can specify the minimum CDB size with the
363 option are 10 and 16.
364 If a 10 byte CDB is specified, the request will be automatically reissued
365 with a 16 byte CDB if the maximum LBA returned is 0xffffffff.
369 MODE SENSE command to the device, and display the requested mode page(s) or
373 Specify the mode page to display.
376 option are mutually exclusive.
377 One of the two must be specified, though.
378 Mode page numbers may be specified in decimal or hexadecimal.
380 Request that the list of mode pages supported by the device be returned.
383 option are mutually exclusive.
384 One of the two must be specified, though.
386 Specify the mode page control value.
388 .Bl -tag -width 2n -compact
392 Changeable value bitmask.
399 Disable block descriptors when sending the mode sense request.
401 Specify the subpage used with the mode sense request.
403 Specify the CDB size used for the mode sense request.
404 Supported values are 6 and 10.
409 START STOP UNIT command to the specified LUN with the start
413 Set the immediate bit in the CDB.
414 Note that CTL does not support the immediate bit, so this is primarily
415 useful for making sure that CTL returns the proper error.
420 START STOP UNIT command to the specified LUN with the start
422 We use an ordered tag to stop the LUN, so we can guarantee that all pending
423 I/O executes before it is stopped.
424 (CTL guarantees this anyway, but
426 sends an ordered tag for completeness.)
429 Set the immediate bit in the CDB.
430 Note that CTL does not support the immediate bit, so this is primarily
431 useful for making sure that CTL returns the proper error.
436 SYNCHRONIZE CACHE command to the device.
437 By default, SYNCHRONIZE CACHE(10) is used.
438 If the specified starting LBA is greater than 0xffffffff or the length is
439 greater than 0xffff, though, SYNCHRONIZE CACHE(16) will be used.
440 The 16 byte command will also be used if the user specifies a 16 byte CDB with the
445 Specify the starting LBA of the cache region to synchronize.
446 This option is a no-op for CTL.
447 If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN.
448 .It Fl b Ar blockcount
449 Specify the length of the cache region to synchronize.
450 This option is a no-op for CTL.
451 If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN.
453 Specify relative addressing for the starting LBA.
454 CTL does not support relative addressing, since it only works for linked commands,
455 and CTL does not support linked commands.
457 Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE
458 command rather than waiting for the cache to finish syncing.
459 CTL does not support this bit.
461 Specify the minimum CDB size.
462 Valid values are 10 and 16 bytes.
465 List all LUNs registered with CTL.
466 Because this command uses the ioctl port, it will only work when the FETDs
467 (Front End Target Drivers) are enabled.
468 This command is the equivalent of doing a REPORT LUNS on one LUN and then
469 an INQUIRY on each LUN in the system.
471 Delay commands at the given location.
472 There are two places where commands may be delayed currently: before data is transferred
474 and just prior to sending status to the host
476 One of the two must be supplied as an argument to the
481 option must also be specified.
484 Delay command(s) at the specified location.
485 This can either be at the data movement stage (datamove) or prior to
486 command completion (done).
487 .It Fl t Ar delaytime
488 Delay command(s) for the specified number of seconds.
489 This must be specified.
490 If set to 0, it will clear out any previously set delay for this particular
491 location (datamove or done).
492 .It Fl T Ar delaytype
493 Specify the delay type.
496 option will delay the next command sent to the given LUN.
499 option, every command will be delayed by the specified period of time.
502 the next command sent to the given LUN will be delayed and all subsequent
503 commands will be completed normally.
507 Inject the specified type of error for the LUN specified, when a command
508 that matches the given pattern is seen.
509 The sense data returned is in either fixed or descriptor format, depending
510 upon the status of the D_SENSE bit in the control mode page (page 0xa) for
513 Errors are only injected for commands that have not already failed for
515 By default, only the first command matching the pattern specified is
516 returned with the supplied error.
520 flag is specified, all commands matching the pattern will be returned with
521 the specified error until the error injection command is deleted with
526 Specify the error to return:
529 Return the next matching command on the specified LUN with the sense key
530 ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
533 Return the next matching command on the specified LUN with the sense key
534 MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
535 reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
538 Return the next matching command on the specified LUN with the sense key
539 UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
540 DEVICE RESET OCCURRED").
542 Return the next matching command on the specified LUN with the supplied
546 argument must be specified.
549 Specify which commands should be returned with the given error.
552 The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
554 The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
557 The error should apply to both read and write type commands.
559 The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
561 The error should apply to TEST UNIT READY commands.
563 The error should apply to any command.
566 Specify the starting lba and length of the range of LBAs which should
568 This option is only applies when read and/or write patterns are specified.
569 If used with other command types, the error will never be triggered.
570 .It Fl s Ar len fmt Op Ar args
571 Specify the sense data that is to be returned for custom actions.
574 len bytes of sense data will be read from standard input and written to the
576 If len is longer than 252 bytes (the maximum allowable
578 sense data length), it will be truncated to that length.
579 The sense data format is described in
582 The error injection should be persistent, instead of happening once.
583 Persistent errors must be deleted with the
586 .It Fl d Ar delete_id
587 Delete the specified error injection serial number.
588 The serial number is returned when the error is injected.
591 Perform one of several CTL frontend port operations.
592 Either get a list of frontend ports
594 turn one or more frontends on
597 or set the World Wide Node Name
599 or World Wide Port Name
610 The WWNN and WWPN may both be specified at the same time, but cannot be
611 combined with enabling/disabling or listing ports.
614 Create new frontend port using free pp and vp=0.
616 Turn the specified CTL frontend ports on or off.
617 If no port number or port type is specified, all ports are turned on or
620 Specify generic options on the ioctl frontend port.
621 At present, only pp and vp port numbers can be set.
622 .It Fl p Ar targ_port
623 Specify the frontend port number.
624 The port numbers can be found in the frontend port list.
626 Remove port specified with
627 .Pq Fl p Ar targ_port .
629 Specify the frontend type.
630 Currently defined port types are
636 (CTL ioctl interface),
641 Set the World Wide Node Name for the given port.
644 argument must be specified, since this is only possible to implement on a
646 As a general rule, the WWNN should be the same across all ports on the
649 Set the World Wide Port Name for the given port.
652 argument must be specified, since this is only possible to implement on a
654 As a general rule, the WWPN must be different for every port in the system.
657 List CTL frontend ports.
660 Specify the frontend type.
662 Report target and connected initiators addresses.
665 .It Fl p Ar targ_port
666 Specify the frontend port number.
668 Omit the header in the port list output.
670 Enable verbose output (report all port options).
672 Output the port list in XML format.
675 Change LUN mapping for specified port.
680 are specified -- LUN will be mapped.
685 is not -- LUN will be unmapped.
690 are specified -- LUN mapping will be disabled, exposing all CTL LUNs.
692 .It Fl p Ar targ_port
693 Specify the frontend port number.
695 LUN number visible by specified port.
700 Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
702 Dump the CTL structures to the console.
705 The backend must be specified, and depending upon the backend requested,
706 some of the other options may be required.
707 If the LUN is created successfully, the LUN configuration will be
709 If LUN creation fails, a message will be displayed describing the failure.
715 This specifies the name backend to use when creating the LUN.
720 .It Fl B Ar blocksize
721 Specify the blocksize of the backend in bytes.
722 .It Fl d Ar device_id
723 Specify the LUN-associated string to use in the
725 INQUIRY VPD page 0x83 data.
727 Request that a particular LUN number be assigned.
728 If the requested LUN number is not available, the request will fail.
729 .It Fl o Ar name=value
730 Specify a backend-specific name/value pair.
733 arguments may be specified.
734 Refer to the backend documentation for arguments that may be used.
735 .It Fl s Ar size_bytes
736 Specify the size of the LUN in bytes.
737 Some backends may allow setting the size (e.g. the ramdisk backend) and for
738 others the size may be implicit (e.g. the block backend).
739 .It Fl S Ar serial_num
740 Specify the serial number to be used in the
742 INQUIRY VPD page 0x80 data.
743 .It Fl t Ar device_type
744 Specify the numeric SCSI device type to use when creating the LUN.
745 If this flag is not used, the type of LUN created is backend-specific.
746 Not all LUN types are supported.
747 Currently CTL supports Direct Access (type 0), Processor (type 3)
748 and CD/DVD (type 5) LUNs.
749 The backend requested may or may not support all of the LUN types that CTL
754 The backend must be specified, and the LUN number must also be specified.
755 Backend-specific options may also be specified with the
760 Specify the backend that owns the LUN to be removed.
766 Specify the LUN number to remove.
767 .It Fl o Ar name=value
768 Specify a backend-specific name/value pair.
771 arguments may be specified.
772 Refer to the backend documentation for arguments that may be used.
776 The backend, the LUN number, and the size must be specified.
779 Specify the backend that owns the LUN to be modified.
785 Specify the LUN number to modify.
786 .It Fl o Ar name=value
787 Specify a backend-specific name/value pair.
790 arguments may be specified.
791 Refer to the backend documentation for arguments that may be used.
792 .It Fl s Ar size_bytes
793 Specify the size of the LUN in bytes.
798 keyword may be passed instead; this will make CTL use the size of backing
802 Get a list of all configured LUNs.
803 This also includes the LUN size and blocksize, serial number and device ID.
807 This restricts the LUN list to the named backend.
814 This will also display any backend-specific LUN attributes in addition to
815 the standard per-LUN information.
818 The LUN list information from the kernel comes in XML format, and this
819 option allows the display of the raw XML data.
824 options are mutually exclusive.
827 the entire LUN database is displayed in XML format.
830 Get a list of currently running iSCSI sessions.
831 This includes initiator and target names and the unique connection IDs.
837 The sessions list information from the kernel comes in XML format, and this
838 option allows the display of the raw XML data.
841 Ask the initiator to log out iSCSI sessions matching criteria.
844 Log out all sessions.
846 Specify connection ID.
848 Specify initiator name.
850 Specify initiator portal (hostname or IP address).
853 Forcibly terminate iSCSI sessions matching criteria.
856 Terminate all sessions.
858 Specify connection ID.
860 Specify initiator name.
862 Specify initiator portal (hostname or IP address).
870 Number of additional configuration options may be specified for LUNs.
871 Some options are global, others are backend-specific.
876 Specifies LUN vendor string up to 8 chars.
878 Specifies LUN product string up to 16 chars.
880 Specifies LUN revision string up to 4 chars.
882 Specifies LUN SCSI name string.
884 Specifies LUN EUI-64 identifier.
886 Specifies LUN NAA identifier.
888 Specifies LUN locally assigned RFC 4122 UUID identifier.
889 EUI, NAA or UUID identifier should be set to UNIQUE value to allow
890 EXTENDED COPY command access the LUN.
891 Non-unique LUN identifiers may lead to data corruption.
892 Some initiators may not support later introduced UUID identifiers.
894 Specified LUN identification information (string or 0x + hex).
895 .It Va text_ident_info
896 Specified LUN text identification information (UTF-8 string).
898 Setting to "primary" or "secondary" overrides default role of the node
899 in HA cluster, set by kern.cam.ctl.ha_role sysctl.
901 Setting to "on" allows EXTENDED COPY command sent to this LUN access
902 other LUNs on this host, not accessible otherwise.
903 This allows to offload copying between different iSCSI targets residing
904 on the same host in trusted environments.
906 Set to "off", disables read caching for the LUN, if supported by the backend.
908 Set to "on", blocks all media write operations to the LUN, reporting it
911 Set to "on", makes LUN removable.
913 Set to "unrestricted", allows target to process commands with SIMPLE task
914 attribute in arbitrary order.
915 Any data integrity exposures related to command sequence order shall be
916 explicitly handled by the application client through the selection of
917 appropriate commands and task attributes.
918 The default value is "restricted".
919 It improves data integrity, but may introduce some additional delays.
921 Set to "on" to fully serialize consecutive reads/writes.
922 Set to "read" to fully serialize consecutive reads.
923 Set to "soft" to slightly serialize consecutive reads.
924 Set to "off" to allow them be issued in parallel.
925 Parallel issue of consecutive operations may confuse logic of the
926 backing file system, hurting performance; but it may improve performance
927 of backing stores without prefetch/write-back.
930 Specify physical block size and offset of the device.
933 Specify UNMAP block size and offset of the device.
935 Specifies medium rotation rate of the device: 0 -- not reported,
936 1 -- non-rotating (SSD), >1024 -- value in revolutions per minute.
938 Specifies nominal form factor of the device: 0 -- not reported, 1 -- 5.25",
939 2 -- 3.5", 3 -- 2.5", 4 -- 1.8", 5 -- less then 1.8".
941 .It Va reftemperature
942 Specify current and reference (maximum) temperatures of the device.
943 .It Va provisioning_type
944 When UNMAP support is enabled, this option specifies provisioning type:
945 "resource", "thin" or "unknown".
946 Default value is "thin".
947 Logical units without UNMAP support are reported as fully provisioned.
949 Setting to "on" or "off" controls UNMAP support for the logical unit.
950 Default value is "on" if supported by the backend.
952 .It Va unmap_max_descr
953 Specify maximum allowed number of LBAs and block descriptors per UNMAP
954 command to report in Block Limits VPD page.
955 .It Va write_same_max_lba
956 Specify maximum allowed number of LBAs per WRITE SAME command to report
957 in Block Limits VPD page.
958 .It Va avail-threshold
959 .It Va used-threshold
960 .It Va pool-avail-threshold
961 .It Va pool-used-threshold
962 Set per-LUN/-pool thin provisioning soft thresholds.
963 LUN will establish UNIT ATTENTION condition if its or pool available space
964 get below configured avail values, or its or pool used space get above
965 configured used values.
966 Pool thresholds are working only for ZVOL-backed LUNs.
968 Set to "off", disables write caching for the LUN, if supported by the backend.
971 Options specific for block backend:
974 Specifies file or device name to use for backing store.
976 Specifies number of backend threads to use for this LUN.
979 Options specific for ramdisk backend:
982 Specifies capacity of backing store (maximum RAM for data).
983 The default value is zero, that disables backing store completely,
984 making all writes go to nowhere, while all reads return zeroes.
990 TEST UNIT READY command to LUN 1.
994 Display the list of mode pages supported by LUN 1.
996 .Dl ctladm modesense 1 -l
998 Display the saved version of the Control mode page (page 10) on LUN 0.
999 Disable fetching block descriptors, and use a 10 byte MODE SENSE command
1000 instead of the default 6 byte command.
1002 .Dl ctladm modesense 0 -m 10 -P 3 -d -c 10
1004 Read the first 512 byte block from LUN 2 and dump it to the file
1006 .Dl ctladm read 2 -l 0 -d 1 -b 512 -f - > foo
1009 Read 10240 bytes from the file
1011 and write it to LUN 3.
1012 starting at LBA 0xff432140.
1015 .Dl ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
1018 Create a LUN with the
1020 ramdisk as a backing store.
1021 The LUN will claim to have a size of approximately 10 terabytes,
1022 while having no real data store (all written data are lost).
1024 .Dl ctladm create -b ramdisk -s 10485760000000000
1026 Create a thin provisioned LUN with a ramdisk as a backing store.
1027 The LUN will have maximal backing store capacity of 10 gigabytes,
1028 while reporting size of 10 terabytes,
1030 .Dl ctladm create -b ramdisk -s 10T -o capacity=10G
1032 Create a LUN using the block backend, specify the ZFS volume
1034 as the backing store, and specify the
1036 VPD page 0x80 and 0x83 serial number
1040 The size of the LUN will be derived from the size of the ZVOL.
1042 .Dl ctladm create -b block -o file=/dev/zvol/tank/example -S MYSERIAL321 -d MYDEVID123
1044 Use to specify generic options on ioctl frontend port, now it is
1045 only possible to set pp and/or vp port number.
1047 .Dl ctladm port -c -O pp=11 -O vp=12
1049 Remove specified targ_port.
1051 .Dl ctladm port -r -p 4
1054 Remove LUN 12, which is handled by the block backend, from the system.
1056 .Dl ctladm remove -b block -l 12
1058 List configured LUNs in the system, along with their backend and serial
1060 This works when the Front End Target Drivers are enabled or disabled.
1064 List all LUNs in the system, along with their inquiry data and device type.
1065 This only works when the FETDs are enabled, since the commands go through the
1070 Inject a medium error on LUN 6 for every read that covers the first 512
1073 .Dl ctladm inject 6 -i mediumerr -p read -r 0,512 -c
1075 Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
1076 This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
1077 0x04,0x02 ("Logical unit not ready, initializing command required").
1079 .Bd -literal -offset indent
1080 ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
1084 .Xr cam_cdbparse 3 ,
1094 utility was originally written during the Winter/Spring of 2003 as an
1097 .An Ken Merry Aq Mt ken@FreeBSD.org
projects / FreeBSD / FreeBSD.git / blob