2 .\" Copyright (c) 2003 Silicon Graphics International Corp.
3 .\" Copyright (c) 2015 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. This allows opening a device other than the
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. This can be
276 specified in decimal, octal (starting with 0), hexadecimal (starting with
277 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. Either a
285 for stdout may be specified.
289 CDB (Command Data Block) size to be used for the READ request. Allowable
290 values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
291 requested, a larger CDB size may be used to satisfy the request. (e.g.,
292 for LBAs above 0xffffffff, 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. The blocksize can be obtained via the
299 READ CAPACITY command.
303 from the kernel when doing a read, just execute the command without copying
305 This is to be used for performance testing.
308 Read data from a file or stdin, and write the data to the device using the
313 Specify the starting Logical Block Address for the WRITE. This can be
314 specified in decimal, octal (starting with 0), hexadecimal (starting with
315 0x) or any other base supported by
318 Specify the length, in 512 byte blocks, of the WRITE request.
320 Specify the source for the data to be written by the WRITE command. Either a
323 for stdin may be specified.
327 CDB (Command Data Block) size to be used for the READ request. Allowable
328 values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
329 requested, a larger CDB size may be used to satisfy the request. (e.g.,
330 for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
331 .It Fl b Ar blocksize
332 Specify the blocksize of the underlying
334 device, so the transfer length
335 can be calculated accurately. The blocksize can be obtained via the
337 READ CAPACITY command.
341 to the kernel when doing a write, just execute the command without copying
343 This is to be used for performance testing.
348 READ CAPACITY command to the device and display the device size and device
349 block size. By default, READ CAPACITY(10) is
350 used. If the device returns a maximum LBA of 0xffffffff, however,
352 will automatically issue a READ CAPACITY(16), which is implemented as a
353 service action of the SERVICE ACTION IN(16) opcode. The user can specify
354 the minimum CDB size with the
356 argument. Valid values for the
358 option are 10 and 16. If a 10 byte CDB is specified, the request will be
359 automatically reissued with a 16 byte CDB if the maximum LBA returned is
364 MODE SENSE command to the device, and display the requested mode page(s) or
368 Specify the mode page to display. This option and the
370 option are mutually exclusive. One of the two must be specified, though.
371 Mode page numbers may be specified in decimal or hexadecimal.
373 Request that the list of mode pages supported by the device be returned.
376 option are mutually exclusive. One of the two must be specified, though.
378 Specify the mode page control value. Possible values are:
379 .Bl -tag -width 2n -compact
383 Changeable value bitmask.
390 Disable block descriptors when sending the mode sense request.
392 Specify the subpage used with the mode sense request.
394 Specify the CDB size used for the mode sense request. Supported values are
400 START STOP UNIT command to the specified LUN with the start
404 Set the immediate bit in the CDB. Note that CTL does not support the
405 immediate bit, so this is primarily useful for making sure that CTL returns
411 START STOP UNIT command to the specified LUN with the start
412 bit cleared. We use an ordered tag to stop the LUN, so we can guarantee
413 that all pending I/O executes before it is stopped. (CTL guarantees this
416 sends an ordered tag for completeness.)
419 Set the immediate bit in the CDB. Note that CTL does not support the
420 immediate bit, so this is primarily useful for making sure that CTL returns
426 SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE
427 CACHE(10) is used. If the specified starting LBA is greater than
428 0xffffffff or the length is greater than 0xffff, though,
429 SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used
430 if the user specifies a 16 byte CDB with the
435 Specify the starting LBA 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.
438 .It Fl b Ar blockcount
439 Specify the length of the cache region to synchronize. This option is a
440 no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the
441 cache for the entire LUN.
443 Specify relative addressing for the starting LBA. CTL does not support
444 relative addressing, since it only works for linked commands, and CTL
445 does not support linked commands.
447 Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE
448 command rather than waiting for the cache to finish syncing. CTL does not
451 Specify the minimum CDB size. Valid values are 10 and 16 bytes.
454 List all LUNs registered with CTL.
455 Because this command uses the ioctl port, it will only work when the FETDs
456 (Front End Target Drivers) are enabled.
457 This command is the equivalent of doing a REPORT LUNS on one LUN and then
458 an INQUIRY on each LUN in the system.
460 Delay commands at the given location. There are two places where commands
461 may be delayed currently: before data is transferred
463 and just prior to sending status to the host
465 One of the two must be supplied as an argument to the
469 option must also be specified.
472 Delay command(s) at the specified location.
473 This can either be at the data movement stage (datamove) or prior to
474 command completion (done).
475 .It Fl t Ar delaytime
476 Delay command(s) for the specified number of seconds. This must be
477 specified. If set to 0, it will clear out any previously set delay for
478 this particular location (datamove or done).
479 .It Fl T Ar delaytype
480 Specify the delay type.
483 option will delay the next command sent to the given LUN.
486 option, every command will be delayed by the specified period of time.
489 the next command sent to the given LUN will be delayed and all subsequent
490 commands will be completed normally.
494 Inject the specified type of error for the LUN specified, when a command
495 that matches the given pattern is seen.
496 The sense data returned is in either fixed or descriptor format, depending
497 upon the status of the D_SENSE bit in the control mode page (page 0xa) for
500 Errors are only injected for commands that have not already failed for
502 By default, only the first command matching the pattern specified is
503 returned with the supplied error.
507 flag is specified, all commands matching the pattern will be returned with
508 the specified error until the error injection command is deleted with
513 Specify the error to return:
516 Return the next matching command on the specified LUN with the sense key
517 ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
520 Return the next matching command on the specified LUN with the sense key
521 MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
522 reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
525 Return the next matching command on the specified LUN with the sense key
526 UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
527 DEVICE RESET OCCURRED").
529 Return the next matching command on the specified LUN with the supplied
533 argument must be specified.
536 Specify which commands should be returned with the given error.
539 The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
541 The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
544 The error should apply to both read and write type commands.
546 The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
548 The error should apply to TEST UNIT READY commands.
550 The error should apply to any command.
553 Specify the starting lba and length of the range of LBAs which should
555 This option is only applies when read and/or write patterns are specified.
556 If used with other command types, the error will never be triggered.
557 .It Fl s Ar len fmt Op Ar args
558 Specify the sense data that is to be returned for custom actions.
561 len bytes of sense data will be read from standard input and written to the
563 If len is longer than 252 bytes (the maximum allowable
565 sense data length), it will be truncated to that length.
566 The sense data format is described in
569 The error injection should be persistent, instead of happening once.
570 Persistent errors must be deleted with the
573 .It Fl d Ar delete_id
574 Delete the specified error injection serial number.
575 The serial number is returned when the error is injected.
578 Perform one of several CTL frontend port operations.
579 Either get a list of frontend ports
581 turn one or more frontends on
584 or set the World Wide Node Name
586 or World Wide Port Name
597 The WWNN and WWPN may both be specified at the same time, but cannot be
598 combined with enabling/disabling or listing ports.
601 Create new frontend port using free pp and vp=0.
603 Turn the specified CTL frontend ports on or off.
604 If no port number or port type is specified, all ports are turned on or
607 Specify generic options on the ioctl frontend port.
608 At present, only pp and vp port numbers can be set.
609 .It Fl p Ar targ_port
610 Specify the frontend port number.
611 The port numbers can be found in the frontend port list.
613 Remove port specified with
614 .Pq Fl p Ar targ_port .
616 Specify the frontend type.
617 Currently defined port types are
623 (CTL ioctl interface),
628 Set the World Wide Node Name for the given port.
631 argument must be specified, since this is only possible to implement on a
633 As a general rule, the WWNN should be the same across all ports on the
636 Set the World Wide Port Name for the given port.
639 argument must be specified, since this is only possible to implement on a
641 As a general rule, the WWPN must be different for every port in the system.
644 List CTL frontend ports.
647 Specify the frontend type.
649 Report target and connected initiators addresses.
652 .It Fl p Ar targ_port
653 Specify the frontend port number.
655 Omit the header in the port list output.
657 Enable verbose output (report all port options).
659 Output the port list in XML format.
662 Change LUN mapping for specified port.
667 are specified -- LUN will be mapped.
672 is not -- LUN will be unmapped.
677 are specified -- LUN mapping will be disabled, exposing all CTL LUNs.
679 .It Fl p Ar targ_port
680 Specify the frontend port number.
682 LUN number visible by specified port.
687 Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
689 Dump the CTL structures to the console.
692 The backend must be specified, and depending upon the backend requested,
693 some of the other options may be required.
694 If the LUN is created successfully, the LUN configuration will be
696 If LUN creation fails, a message will be displayed describing the failure.
702 This specifies the name backend to use when creating the LUN.
707 .It Fl B Ar blocksize
708 Specify the blocksize of the backend in bytes.
709 .It Fl d Ar device_id
710 Specify the LUN-associated string to use in the
712 INQUIRY VPD page 0x83 data.
714 Request that a particular LUN number be assigned.
715 If the requested LUN number is not available, the request will fail.
716 .It Fl o Ar name=value
717 Specify a backend-specific name/value pair.
720 arguments may be specified.
721 Refer to the backend documentation for arguments that may be used.
722 .It Fl s Ar size_bytes
723 Specify the size of the LUN in bytes.
724 Some backends may allow setting the size (e.g. the ramdisk backend) and for
725 others the size may be implicit (e.g. the block backend).
726 .It Fl S Ar serial_num
727 Specify the serial number to be used in the
729 INQUIRY VPD page 0x80 data.
730 .It Fl t Ar device_type
731 Specify the numeric SCSI device type to use when creating the LUN.
732 If this flag is not used, the type of LUN created is backend-specific.
733 Not all LUN types are supported.
734 Currently CTL supports Direct Access (type 0), Processor (type 3)
735 and CD/DVD (type 5) LUNs.
736 The backend requested may or may not support all of the LUN types that CTL
741 The backend must be specified, and the LUN number must also be specified.
742 Backend-specific options may also be specified with the
747 Specify the backend that owns the LUN to be removed.
753 Specify the LUN number to remove.
754 .It Fl o Ar name=value
755 Specify a backend-specific name/value pair.
758 arguments may be specified.
759 Refer to the backend documentation for arguments that may be used.
763 The backend, the LUN number, and the size must be specified.
766 Specify the backend that owns the LUN to be modified.
772 Specify the LUN number to modify.
773 .It Fl o Ar name=value
774 Specify a backend-specific name/value pair.
777 arguments may be specified.
778 Refer to the backend documentation for arguments that may be used.
779 .It Fl s Ar size_bytes
780 Specify the size of the LUN in bytes.
785 keyword may be passed instead; this will make CTL use the size of backing
789 Get a list of all configured LUNs.
790 This also includes the LUN size and blocksize, serial number and device ID.
794 This restricts the LUN list to the named backend.
801 This will also display any backend-specific LUN attributes in addition to
802 the standard per-LUN information.
805 The LUN list information from the kernel comes in XML format, and this
806 option allows the display of the raw XML data.
811 options are mutually exclusive.
814 the entire LUN database is displayed in XML format.
817 Get a list of currently running iSCSI sessions.
818 This includes initiator and target names and the unique connection IDs.
824 The sessions list information from the kernel comes in XML format, and this
825 option allows the display of the raw XML data.
828 Ask the initiator to log out iSCSI sessions matching criteria.
831 Log out all sessions.
833 Specify connection ID.
835 Specify initiator name.
837 Specify initiator portal (hostname or IP address).
840 Forcibly terminate iSCSI sessions matching criteria.
843 Terminate all sessions.
845 Specify connection ID.
847 Specify initiator name.
849 Specify initiator portal (hostname or IP address).
857 Number of additional configuration options may be specified for LUNs.
858 Some options are global, others are backend-specific.
863 Specifies LUN vendor string up to 8 chars.
865 Specifies LUN product string up to 16 chars.
867 Specifies LUN revision string up to 4 chars.
869 Specifies LUN SCSI name string.
871 Specifies LUN EUI-64 identifier.
873 Specifies LUN NAA identifier.
875 Specifies LUN locally assigned RFC 4122 UUID identifier.
876 EUI, NAA or UUID identifier should be set to UNIQUE value to allow
877 EXTENDED COPY command access the LUN.
878 Non-unique LUN identifiers may lead to data corruption.
879 Some initiators may not support later introduced UUID identifiers.
881 Setting to "primary" or "secondary" overrides default role of the node
882 in HA cluster, set by kern.cam.ctl.ha_role sysctl.
884 Setting to "on" allows EXTENDED COPY command sent to this LUN access
885 other LUNs on this host, not accessible otherwise.
886 This allows to offload copying between different iSCSI targets residing
887 on the same host in trusted environments.
889 Set to "off", disables read caching for the LUN, if supported by the backend.
891 Set to "on", blocks all media write operations to the LUN, reporting it
894 Set to "on", makes LUN removable.
896 Set to "unrestricted", allows target to process commands with SIMPLE task
897 attribute in arbitrary order. Any data integrity exposures related to
898 command sequence order shall be explicitly handled by the application
899 client through the selection of appropriate commands and task attributes.
900 The default value is "restricted". It improves data integrity, but may
901 introduce some additional delays.
903 Set to "on" to serialize consecutive reads/writes.
904 Set to "read" to serialize consecutive reads.
905 Set to "off" to allow them be issued in parallel.
906 Parallel issue of consecutive operations may confuse logic of the
907 backing file system, hurting performance; but it may improve performance
908 of backing stores without prefetch/write-back.
911 Specify physical block size and offset of the device.
914 Specify UNMAP block size and offset of the device.
916 Specifies medium rotation rate of the device: 0 -- not reported,
917 1 -- non-rotating (SSD), >1024 -- value in revolutions per minute.
919 Specifies nominal form factor of the device: 0 -- not reported, 1 -- 5.25",
920 2 -- 3.5", 3 -- 2.5", 4 -- 1.8", 5 -- less then 1.8".
922 .It Va reftemperature
923 Specify current and reference (maximum) temperatures of the device.
924 .It Va provisioning_type
925 When UNMAP support is enabled, this option specifies provisioning type:
926 "resource", "thin" or "unknown".
927 Default value is "thin".
928 Logical units without UNMAP support are reported as fully provisioned.
930 Setting to "on" or "off" controls UNMAP support for the logical unit.
931 Default value is "on" if supported by the backend.
933 .It Va unmap_max_descr
934 Specify maximum allowed number of LBAs and block descriptors per UNMAP
935 command to report in Block Limits VPD page.
936 .It Va write_same_max_lba
937 Specify maximum allowed number of LBAs per WRITE SAME command to report
938 in Block Limits VPD page.
939 .It Va avail-threshold
940 .It Va used-threshold
941 .It Va pool-avail-threshold
942 .It Va pool-used-threshold
943 Set per-LUN/-pool thin provisioning soft thresholds.
944 LUN will establish UNIT ATTENTION condition if its or pool available space
945 get below configured avail values, or its or pool used space get above
946 configured used values.
947 Pool thresholds are working only for ZVOL-backed LUNs.
949 Set to "off", disables write caching for the LUN, if supported by the backend.
952 Options specific for block backend:
955 Specifies file or device name to use for backing store.
957 Specifies number of backend threads to use for this LUN.
960 Options specific for ramdisk backend:
963 Specifies capacity of backing store (maximum RAM for data).
964 The default value is zero, that disables backing store completely,
965 making all writes go to nowhere, while all reads return zeroes.
971 TEST UNIT READY command to LUN 1.
975 Display the list of mode pages supported by LUN 1.
977 .Dl ctladm modesense 1 -l
979 Display the saved version of the Control mode page (page 10) on LUN 0.
980 Disable fetching block descriptors, and use a 10 byte MODE SENSE command
981 instead of the default 6 byte command.
983 .Dl ctladm modesense 0 -m 10 -P 3 -d -c 10
985 Read the first 512 byte block from LUN 2 and dump it to the file
987 .Dl ctladm read 2 -l 0 -d 1 -b 512 -f - > foo
990 Read 10240 bytes from the file
992 and write it to LUN 3.
993 starting at LBA 0xff432140.
996 .Dl ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
999 Create a LUN with the
1001 ramdisk as a backing store.
1002 The LUN will claim to have a size of approximately 10 terabytes,
1003 while having no real data store (all written data are lost).
1005 .Dl ctladm create -b ramdisk -s 10485760000000000
1007 Create a thin provisioned LUN with a ramdisk as a backing store.
1008 The LUN will have maximal backing store capacity of 10 gigabytes,
1009 while reporting size of 10 terabytes,
1011 .Dl ctladm create -b ramdisk -s 10T -o capacity=10G
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
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 create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123
1031 Use to specify generic options on ioctl frontend port, now it is
1032 only possible to set pp and/or vp port number.
1034 .Dl ctladm port -c -O pp=11 -O vp=12
1036 Remove specified targ_port.
1038 .Dl ctladm port -r -p 4
1041 Remove LUN 12, which is handled by the block backend, from the system.
1043 .Dl ctladm remove -b block -l 12
1045 List configured LUNs in the system, along with their backend and serial
1047 This works when the Front End Target Drivers are enabled or disabled.
1051 List all LUNs in the system, along with their inquiry data and device type.
1052 This only works when the FETDs are enabled, since the commands go through the
1057 Inject a medium error on LUN 6 for every read that covers the first 512
1060 .Dl ctladm inject 6 -i mediumerr -p read -r 0,512 -c
1062 Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
1063 This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
1064 0x04,0x02 ("Logical unit not ready, initializing command required").
1066 .Bd -literal -offset indent
1067 ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
1071 .Xr cam_cdbparse 3 ,
1081 utility was originally written during the Winter/Spring of 2003 as an
1084 .An Ken Merry Aq Mt ken@FreeBSD.org
projects / FreeBSD / FreeBSD.git / blob