2 .\" Copyright (c) 2003 Silicon Graphics International Corp.
3 .\" Copyright (c) 2015-2020 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 $
44 .Nd CAM Target Layer control utility
74 .Aq Fl b Ar blocksize_bytes
84 .Aq Fl b Ar blocksize_bytes
95 .Aq Fl m Ar page | Fl l
117 .Op Fl b Ar blockcount
126 .Aq Fl l Ar datamove|done
128 .Op Fl T Ar oneshot|cont
134 .Op Fl s Ar len fmt Op Ar args
136 .Op Fl d Ar delete_id
140 .Op Fl B Ar blocksize
141 .Op Fl d Ar device_id
143 .Op Fl o Ar name=value
144 .Op Fl s Ar size_bytes
145 .Op Fl S Ar serial_num
146 .Op Fl t Ar device_type
151 .Op Fl o Ar name=value
156 .Op Fl o Ar name=value
157 .Aq Fl s Ar size_bytes
170 .Op Fl p Ar targ_port
171 .Op Fl r Ar targ_port
178 .Op Fl p Ar targ_port
184 .Aq Fl p Ar targ_port
197 .Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
200 .Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
206 utility is designed to provide a way to access and control the CAM Target
208 It provides a way to send
210 commands to the CTL layer, and also provides
211 some meta-commands that utilize
216 command is implemented using the
218 REPORT LUNS and INQUIRY commands.)
222 utility has a number of primary functions, many of which require a device
224 The device identifier takes the following form:
227 Specify the LUN number to operate on.
229 Many of the primary functions of the
231 utility take the following optional arguments:
234 Specify the number of times to retry a command in the event of failure.
236 Specify the device to open.
237 This allows opening a device other than the default device,
239 to be opened for sending commands.
241 Specify the initiator number to use.
244 will use 7 as the initiator number.
252 TEST UNIT READY command to the device and report whether or not it is
257 INQUIRY command to the device and display some of the returned inquiry
262 REQUEST SENSE command to the device and display the returned sense
267 REPORT LUNS command to the device and display supported LUNs.
271 READ command to the device, and write the requested data to a file or
275 Specify the starting Logical Block Address for the READ.
276 This can be specified in decimal, octal (starting with 0),
277 hexadecimal (starting with 0x) or any other base supported by
280 Specify the length, in 512 byte blocks, of the READ request.
282 Specify the destination for the data read by the READ command.
285 for stdout may be specified.
289 CDB (Command Data Block) size to be used for the READ request.
290 Allowable values are 6, 10, 12 and 16.
291 Depending upon the LBA and amount of data requested, a larger CDB
292 size may be used to satisfy the request. (e.g., for LBAs above 0xffffffff,
293 READ(16) must be used to satisfy the request.)
294 .It Fl b Ar blocksize
295 Specify the blocksize of the underlying
297 device, so the transfer length
298 can be calculated accurately.
299 The blocksize can be obtained via the
301 READ CAPACITY command.
305 from the kernel when doing a read, just execute the command without copying
307 This is to be used for performance testing.
310 Read data from a file or stdin, and write the data to the device using the
315 Specify the starting Logical Block Address for the WRITE.
316 This can be specified in decimal, octal (starting with 0), hexadecimal
317 (starting with 0x) or any other base supported by
320 Specify the length, in 512 byte blocks, of the WRITE request.
322 Specify the source for the data to be written by the WRITE command.
325 for stdin may be specified.
329 CDB (Command Data Block) size to be used for the READ request.
330 Allowable values are 6, 10, 12 and 16.
331 Depending upon the LBA and amount of data requested, a larger CDB size
332 may be used to satisfy the request. (e.g., for LBAs above 0xffffffff, READ(16)
333 must be used to satisfy the request.)
334 .It Fl b Ar blocksize
335 Specify the blocksize of the underlying
337 device, so the transfer length
338 can be calculated accurately.
339 The blocksize can be obtained via the
341 READ CAPACITY command.
345 to the kernel when doing a write, just execute the command without copying
347 This is to be used for performance testing.
352 READ CAPACITY command to the device and display the device size and device
354 By default, READ CAPACITY(10) is used.
355 If the device returns a maximum LBA of 0xffffffff, however,
357 will automatically issue a READ CAPACITY(16), which is implemented as a
358 service action of the SERVICE ACTION IN(16) opcode.
359 The user can specify the minimum CDB size with the
364 option are 10 and 16.
365 If a 10 byte CDB is specified, the request will be automatically reissued
366 with a 16 byte CDB if the maximum LBA returned is 0xffffffff.
370 MODE SENSE command to the device, and display the requested mode page(s) or
374 Specify the mode page to display.
377 option are mutually exclusive.
378 One of the two must be specified, though.
379 Mode page numbers may be specified in decimal or hexadecimal.
381 Request that the list of mode pages supported by the device be returned.
384 option are mutually exclusive.
385 One of the two must be specified, though.
387 Specify the mode page control value.
389 .Bl -tag -width 2n -compact
393 Changeable value bitmask.
400 Disable block descriptors when sending the mode sense request.
402 Specify the subpage used with the mode sense request.
404 Specify the CDB size used for the mode sense request.
405 Supported values are 6 and 10.
410 START STOP UNIT command to the specified LUN with the start
414 Set the immediate bit in the CDB.
415 Note that CTL does not support the immediate bit, so this is primarily
416 useful for making sure that CTL returns the proper error.
421 START STOP UNIT command to the specified LUN with the start
423 We use an ordered tag to stop the LUN, so we can guarantee that all pending
424 I/O executes before it is stopped.
425 (CTL guarantees this anyway, but
427 sends an ordered tag for completeness.)
430 Set the immediate bit in the CDB.
431 Note that CTL does not support the immediate bit, so this is primarily
432 useful for making sure that CTL returns the proper error.
437 SYNCHRONIZE CACHE command to the device.
438 By default, SYNCHRONIZE CACHE(10) is used.
439 If the specified starting LBA is greater than 0xffffffff or the length is
440 greater than 0xffff, though, SYNCHRONIZE CACHE(16) will be used.
441 The 16 byte command will also be used if the user specifies a 16 byte CDB with the
446 Specify the starting LBA of the cache region to synchronize.
447 This option is a no-op for CTL.
448 If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN.
449 .It Fl b Ar blockcount
450 Specify the length of the cache region to synchronize.
451 This option is a no-op for CTL.
452 If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN.
454 Specify relative addressing for the starting LBA.
455 CTL does not support relative addressing, since it only works for linked commands,
456 and CTL does not support linked commands.
458 Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE
459 command rather than waiting for the cache to finish syncing.
460 CTL does not support this bit.
462 Specify the minimum CDB size.
463 Valid values are 10 and 16 bytes.
466 List all LUNs registered with CTL.
467 Because this command uses the ioctl port, it will only work when the FETDs
468 (Front End Target Drivers) are enabled.
469 This command is the equivalent of doing a REPORT LUNS on one LUN and then
470 an INQUIRY on each LUN in the system.
472 Delay commands at the given location.
473 There are two places where commands may be delayed currently: before data is transferred
475 and just prior to sending status to the host
477 One of the two must be supplied as an argument to the
482 option must also be specified.
485 Delay command(s) at the specified location.
486 This can either be at the data movement stage (datamove) or prior to
487 command completion (done).
488 .It Fl t Ar delaytime
489 Delay command(s) for the specified number of seconds.
490 This must be specified.
491 If set to 0, it will clear out any previously set delay for this particular
492 location (datamove or done).
493 .It Fl T Ar delaytype
494 Specify the delay type.
497 option will delay the next command sent to the given LUN.
500 option, every command will be delayed by the specified period of time.
503 the next command sent to the given LUN will be delayed and all subsequent
504 commands will be completed normally.
508 Inject the specified type of error for the LUN specified, when a command
509 that matches the given pattern is seen.
510 The sense data returned is in either fixed or descriptor format, depending
511 upon the status of the D_SENSE bit in the control mode page (page 0xa) for
514 Errors are only injected for commands that have not already failed for
516 By default, only the first command matching the pattern specified is
517 returned with the supplied error.
521 flag is specified, all commands matching the pattern will be returned with
522 the specified error until the error injection command is deleted with
527 Specify the error to return:
530 Return the next matching command on the specified LUN with the sense key
531 ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
534 Return the next matching command on the specified LUN with the sense key
535 MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
536 reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
539 Return the next matching command on the specified LUN with the sense key
540 UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
541 DEVICE RESET OCCURRED").
543 Return the next matching command on the specified LUN with the supplied
547 argument must be specified.
550 Specify which commands should be returned with the given error.
553 The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
555 The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
558 The error should apply to both read and write type commands.
560 The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
562 The error should apply to TEST UNIT READY commands.
564 The error should apply to any command.
567 Specify the starting lba and length of the range of LBAs which should
569 This option is only applies when read and/or write patterns are specified.
570 If used with other command types, the error will never be triggered.
571 .It Fl s Ar len fmt Op Ar args
572 Specify the sense data that is to be returned for custom actions.
575 len bytes of sense data will be read from standard input and written to the
577 If len is longer than 252 bytes (the maximum allowable
579 sense data length), it will be truncated to that length.
580 The sense data format is described in
583 The error injection should be persistent, instead of happening once.
584 Persistent errors must be deleted with the
587 .It Fl d Ar delete_id
588 Delete the specified error injection serial number.
589 The serial number is returned when the error is injected.
592 Perform one of several CTL frontend port operations.
593 Either get a list of frontend ports
595 turn one or more frontends on
598 or set the World Wide Node Name
600 or World Wide Port Name
611 The WWNN and WWPN may both be specified at the same time, but cannot be
612 combined with enabling/disabling or listing ports.
615 Create new frontend port using free pp and vp=0.
617 Turn the specified CTL frontend ports on or off.
618 If no port number or port type is specified, all ports are turned on or
621 Specify generic options on the ioctl frontend port.
622 At present, only pp and vp port numbers can be set.
623 .It Fl p Ar targ_port
624 Specify the frontend port number.
625 The port numbers can be found in the frontend port list.
627 Remove port specified with
628 .Pq Fl p Ar targ_port .
630 Specify the frontend type.
631 Currently defined port types are
637 (CTL ioctl interface),
642 Set the World Wide Node Name for the given port.
645 argument must be specified, since this is only possible to implement on a
647 As a general rule, the WWNN should be the same across all ports on the
650 Set the World Wide Port Name for the given port.
653 argument must be specified, since this is only possible to implement on a
655 As a general rule, the WWPN must be different for every port in the system.
658 List CTL frontend ports.
661 Specify the frontend type.
663 Report target and connected initiators addresses.
666 .It Fl p Ar targ_port
667 Specify the frontend port number.
669 Omit the header in the port list output.
671 Enable verbose output (report all port options).
673 Output the port list in XML format.
676 Change LUN mapping for specified port.
681 are specified -- LUN will be mapped.
686 is not -- LUN will be unmapped.
691 are specified -- LUN mapping will be disabled, exposing all CTL LUNs.
693 .It Fl p Ar targ_port
694 Specify the frontend port number.
696 LUN number visible by specified port.
701 Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
703 Dump the CTL structures to the console.
706 The backend must be specified, and depending upon the backend requested,
707 some of the other options may be required.
708 If the LUN is created successfully, the LUN configuration will be
710 If LUN creation fails, a message will be displayed describing the failure.
716 This specifies the name backend to use when creating the LUN.
721 .It Fl B Ar blocksize
722 Specify the blocksize of the backend in bytes.
723 .It Fl d Ar device_id
724 Specify the LUN-associated string to use in the
726 INQUIRY VPD page 0x83 data.
728 Request that a particular LUN number be assigned.
729 If the requested LUN number is not available, the request will fail.
730 .It Fl o Ar name=value
731 Specify a backend-specific name/value pair.
734 arguments may be specified.
735 Refer to the backend documentation for arguments that may be used.
736 .It Fl s Ar size_bytes
737 Specify the size of the LUN in bytes.
738 Some backends may allow setting the size (e.g. the ramdisk backend) and for
739 others the size may be implicit (e.g. the block backend).
740 .It Fl S Ar serial_num
741 Specify the serial number to be used in the
743 INQUIRY VPD page 0x80 data.
744 .It Fl t Ar device_type
745 Specify the numeric SCSI device type to use when creating the LUN.
746 If this flag is not used, the type of LUN created is backend-specific.
747 Not all LUN types are supported.
748 Currently CTL supports Direct Access (type 0), Processor (type 3)
749 and CD/DVD (type 5) LUNs.
750 The backend requested may or may not support all of the LUN types that CTL
755 The backend must be specified, and the LUN number must also be specified.
756 Backend-specific options may also be specified with the
761 Specify the backend that owns the LUN to be removed.
767 Specify the LUN number to remove.
768 .It Fl o Ar name=value
769 Specify a backend-specific name/value pair.
772 arguments may be specified.
773 Refer to the backend documentation for arguments that may be used.
777 The backend, the LUN number, and the size must be specified.
780 Specify the backend that owns the LUN to be modified.
786 Specify the LUN number to modify.
787 .It Fl o Ar name=value
788 Specify a backend-specific name/value pair.
791 arguments may be specified.
792 Refer to the backend documentation for arguments that may be used.
793 .It Fl s Ar size_bytes
794 Specify the size of the LUN in bytes.
799 keyword may be passed instead; this will make CTL use the size of backing
803 Get a list of all configured LUNs.
804 This also includes the LUN size and blocksize, serial number and device ID.
808 This restricts the LUN list to the named backend.
815 This will also display any backend-specific LUN attributes in addition to
816 the standard per-LUN information.
819 The LUN list information from the kernel comes in XML format, and this
820 option allows the display of the raw XML data.
825 options are mutually exclusive.
828 the entire LUN database is displayed in XML format.
831 Get a list of currently running iSCSI sessions.
832 This includes initiator and target names and the unique connection IDs.
838 The sessions list information from the kernel comes in XML format, and this
839 option allows the display of the raw XML data.
842 Ask the initiator to log out iSCSI sessions matching criteria.
845 Log out all sessions.
847 Specify connection ID.
849 Specify initiator name.
851 Specify initiator portal (hostname or IP address).
854 Forcibly terminate iSCSI sessions matching criteria.
857 Terminate all sessions.
859 Specify connection ID.
861 Specify initiator name.
863 Specify initiator portal (hostname or IP address).
871 Number of additional configuration options may be specified for LUNs.
872 Some options are global, others are backend-specific.
877 Specifies LUN vendor string up to 8 chars.
879 Specifies LUN product string up to 16 chars.
881 Specifies LUN revision string up to 4 chars.
883 Specifies LUN SCSI name string.
885 Specifies LUN EUI-64 identifier.
887 Specifies LUN NAA identifier.
889 Specifies LUN locally assigned RFC 4122 UUID identifier.
890 EUI, NAA or UUID identifier should be set to UNIQUE value to allow
891 EXTENDED COPY command access the LUN.
892 Non-unique LUN identifiers may lead to data corruption.
893 Some initiators may not support later introduced UUID identifiers.
895 Specified LUN identification information (string or 0x + hex).
896 .It Va text_ident_info
897 Specified LUN text identification information (UTF-8 string).
899 Setting to "primary" or "secondary" overrides default role of the node
900 in HA cluster, set by kern.cam.ctl.ha_role sysctl.
902 Setting to "on" allows EXTENDED COPY command sent to this LUN access
903 other LUNs on this host, not accessible otherwise.
904 This allows to offload copying between different iSCSI targets residing
905 on the same host in trusted environments.
907 Set to "off", disables read caching for the LUN, if supported by the backend.
909 Set to "on", blocks all media write operations to the LUN, reporting it
912 Set to "on", makes LUN removable.
914 Set to "unrestricted", allows target to process commands with SIMPLE task
915 attribute in arbitrary order.
916 Any data integrity exposures related to command sequence order shall be
917 explicitly handled by the application client through the selection of
918 appropriate commands and task attributes.
919 The default value is "restricted".
920 It improves data integrity, but may introduce some additional delays.
922 Set to "on" to serialize consecutive reads/writes.
923 Set to "read" to 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