1.\"
2.\" Copyright (c) 2003 Silicon Graphics International Corp.
3.\" Copyright (c) 2015 Alexander Motin <mav@FreeBSD.org>
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
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.
17.\"
18.\" NO WARRANTY
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.
30.\"
31.\" ctladm utility man page.
32.\"
33.\" Author: Ken Merry <ken@FreeBSD.org>
34.\"
35.\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $
| 1.\"
2.\" Copyright (c) 2003 Silicon Graphics International Corp.
3.\" Copyright (c) 2015 Alexander Motin <mav@FreeBSD.org>
4.\" All rights reserved.
5.\"
6.\" Redistribution and use in source and binary forms, with or without
7.\" modification, are permitted provided that the following conditions
8.\" are met:
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.
17.\"
18.\" NO WARRANTY
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.
30.\"
31.\" ctladm utility man page.
32.\"
33.\" Author: Ken Merry <ken@FreeBSD.org>
34.\"
35.\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $
|
37.\"
38.Dd September 26, 2015
39.Dt CTLADM 8
40.Os
41.Sh NAME
42.Nm ctladm
43.Nd CAM Target Layer control utility
44.Sh SYNOPSIS
45.Nm
46.Aq Ar command
47.Op lun
48.Op generic args
49.Op command args
50.Nm
51.Ic tur
52.Aq lun
53.Op general options
54.Nm
55.Ic inquiry
56.Aq lun
57.Op general options
58.Nm
59.Ic reqsense
60.Aq lun
61.Op general options
62.Nm
63.Ic reportluns
64.Aq lun
65.Op general options
66.Nm
67.Ic read
68.Aq lun
69.Op general options
70.Aq Fl l Ar lba
71.Aq Fl d Ar datalen
72.Aq Fl f Ar file|-
73.Aq Fl b Ar blocksize_bytes
74.Op Fl c Ar cdbsize
75.Op Fl N
76.Nm
77.Ic write
78.Aq lun
79.Op general options
80.Aq Fl l Ar lba
81.Aq Fl d Ar datalen
82.Aq Fl f Ar file|-
83.Aq Fl b Ar blocksize_bytes
84.Op Fl c Ar cdbsize
85.Op Fl N
86.Nm
87.Ic readcap
88.Aq lun
89.Op general options
90.Op Fl c Ar cdbsize
91.Nm
92.Ic modesense
93.Aq lun
94.Aq Fl m Ar page | Fl l
95.Op Fl P Ar pc
96.Op Fl d
97.Op Fl S Ar subpage
98.Op Fl c Ar size
99.Nm
100.Ic start
101.Aq lun
102.Op general options
103.Op Fl i
104.Op Fl o
105.Nm
106.Ic stop
107.Aq lun
108.Op general options
109.Op Fl i
110.Op Fl o
111.Nm
112.Ic synccache
113.Aq lun
114.Op general options
115.Op Fl l Ar lba
116.Op Fl b Ar blockcount
117.Op Fl r
118.Op Fl i
119.Op Fl c Ar cdbsize
120.Nm
121.Ic lunlist
122.Nm
123.Ic delay
124.Aq lun
125.Aq Fl l Ar datamove|done
126.Aq Fl t Ar secs
127.Op Fl T Ar oneshot|cont
128.Nm
129.Ic inject
130.Aq Fl i Ar action
131.Aq Fl p Ar pattern
132.Op Fl r Ar lba,len
133.Op Fl s Ar len fmt Op Ar args
134.Op Fl c
135.Op Fl d Ar delete_id
136.Nm
137.Ic create
138.Aq Fl b Ar backend
139.Op Fl B Ar blocksize
140.Op Fl d Ar device_id
141.Op Fl l Ar lun_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
146.Nm
147.Ic remove
148.Aq Fl b Ar backend
149.Aq Fl l Ar lun_id
150.Op Fl o Ar name=value
151.Nm
152.Ic modify
153.Aq Fl b Ar backend
154.Aq Fl l Ar lun_id
155.Op Fl o Ar name=value
156.Aq Fl s Ar size_bytes
157.Nm
158.Ic devlist
159.Op Fl b Ar backend
160.Op Fl v
161.Op Fl x
162.Nm
163.Ic port
164.Op Fl o Ar on|off
165.Op Fl w Ar wwpn
166.Op Fl W Ar wwnn
167.Op Fl p Ar targ_port
168.Op Fl t Ar fe_type
169.Nm
170.Ic portlist
171.Op Fl f Ar frontend
172.Op Fl i
173.Op Fl l
174.Op Fl p Ar targ_port
175.Op Fl q
176.Op Fl v
177.Op Fl x
178.Nm
179.Ic lunmap
180.Aq Fl p Ar targ_port
181.Op Fl l Ar pLUN
182.Op Fl L Ar cLUN
183.Nm
184.Ic dumpooa
185.Nm
186.Ic dumpstructs
187.Nm
188.Ic islist
189.Op Fl v
190.Op Fl x
191.Nm
192.Ic islogout
193.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
194.Nm
195.Ic isterminate
196.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
197.Nm
198.Ic help
199.Sh DESCRIPTION
200The
201.Nm
202utility is designed to provide a way to access and control the CAM Target
203Layer (CTL).
204It provides a way to send
205.Tn SCSI
206commands to the CTL layer, and also provides
207some meta-commands that utilize
208.Tn SCSI
209commands.
210(For instance, the
211.Ic lunlist
212command is implemented using the
213.Tn SCSI
214REPORT LUNS and INQUIRY commands.)
215.Pp
216The
217.Nm
218utility has a number of primary functions, many of which require a device
219identifier.
220The device identifier takes the following form:
221.Bl -tag -width 14n
222.It lun
223Specify the LUN number to operate on.
224.El
225Many of the primary functions of the
226.Nm
227utility take the following optional arguments:
228.Bl -tag -width 10n
229.It Fl C Ar retries
230Specify the number of times to retry a command in the event of failure.
231.It Fl D Ar device
232Specify the device to open. This allows opening a device other than the
233default device,
234.Pa /dev/cam/ctl ,
235to be opened for sending commands.
236.It Fl I Ar id
237Specify the initiator number to use.
238By default,
239.Nm
240will use 7 as the initiator number.
241.El
242.Pp
243Primary commands:
244.Bl -tag -width 11n
245.It Ic tur
246Send the
247.Tn SCSI
248TEST UNIT READY command to the device and report whether or not it is
249ready.
250.It Ic inquiry
251Send the
252.Tn SCSI
253INQUIRY command to the device and display some of the returned inquiry
254data.
255.It Ic reqsense
256Send the
257.Tn SCSI
258REQUEST SENSE command to the device and display the returned sense
259information.
260.It Ic reportluns
261Send the
262.Tn SCSI
263REPORT LUNS command to the device and display supported LUNs.
264.It Ic read
265Send a
266.Tn SCSI
267READ command to the device, and write the requested data to a file or
268stdout.
269.Bl -tag -width 12n
270.It Fl l Ar lba
271Specify the starting Logical Block Address for the READ. This can be
272specified in decimal, octal (starting with 0), hexadecimal (starting with
2730x) or any other base supported by
274.Xr strtoull 3 .
275.It Fl d Ar datalen
276Specify the length, in 512 byte blocks, of the READ request.
277.It Fl f Ar file
278Specify the destination for the data read by the READ command. Either a
279filename or
280.Sq -
281for stdout may be specified.
282.It Fl c Ar cdbsize
283Specify the minimum
284.Tn SCSI
285CDB (Command Data Block) size to be used for the READ request. Allowable
286values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
287requested, a larger CDB size may be used to satisfy the request. (e.g.,
288for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
289.It Fl b Ar blocksize
290Specify the blocksize of the underlying
291.Tn SCSI
292device, so the transfer length
293can be calculated accurately. The blocksize can be obtained via the
294.Tn SCSI
295READ CAPACITY command.
296.It Fl N
297Do not copy data to
298.Nm
299from the kernel when doing a read, just execute the command without copying
300data.
301This is to be used for performance testing.
302.El
303.It Ic write
304Read data from a file or stdin, and write the data to the device using the
305.Tn SCSI
306WRITE command.
307.Bl -tag -width 12n
308.It Fl l Ar lba
309Specify the starting Logical Block Address for the WRITE. This can be
310specified in decimal, octal (starting with 0), hexadecimal (starting with
3110x) or any other base supported by
312.Xr strtoull 3 .
313.It Fl d Ar atalen
314Specify the length, in 512 byte blocks, of the WRITE request.
315.It Fl f Ar file
316Specify the source for the data to be written by the WRITE command. Either a
317filename or
318.Sq -
319for stdin may be specified.
320.It Fl c Ar cdbsize
321Specify the minimum
322.Tn SCSI
323CDB (Command Data Block) size to be used for the READ request. Allowable
324values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
325requested, a larger CDB size may be used to satisfy the request. (e.g.,
326for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
327.It Fl b Ar blocksize
328Specify the blocksize of the underlying
329.Tn SCSI
330device, so the transfer length
331can be calculated accurately. The blocksize can be obtained via the
332.Tn SCSI
333READ CAPACITY command.
334.It Fl N
335Do not copy data to
336.Nm
337to the kernel when doing a write, just execute the command without copying
338data.
339This is to be used for performance testing.
340.El
341.It Ic readcap
342Send the
343.Tn SCSI
344READ CAPACITY command to the device and display the device size and device
345block size. By default, READ CAPACITY(10) is
346used. If the device returns a maximum LBA of 0xffffffff, however,
347.Nm
348will automatically issue a READ CAPACITY(16), which is implemented as a
349service action of the SERVICE ACTION IN(16) opcode. The user can specify
350the minimum CDB size with the
351.Fl c
352argument. Valid values for the
353.Fl c
354option are 10 and 16. If a 10 byte CDB is specified, the request will be
355automatically reissued with a 16 byte CDB if the maximum LBA returned is
3560xffffffff.
357.It Ic modesense
358Send a
359.Tn SCSI
360MODE SENSE command to the device, and display the requested mode page(s) or
361page list.
362.Bl -tag -width 10n
363.It Fl m Ar page
364Specify the mode page to display. This option and the
365.Fl l
366option are mutually exclusive. One of the two must be specified, though.
367Mode page numbers may be specified in decimal or hexadecimal.
368.It Fl l
369Request that the list of mode pages supported by the device be returned.
370This option and the
371.Fl m
372option are mutually exclusive. One of the two must be specified, though.
373.It Fl P Ar pc
374Specify the mode page control value. Possible values are:
375.Bl -tag -width 2n -compact
376.It 0
377Current values.
378.It 1
379Changeable value bitmask.
380.It 2
381Default values.
382.It 3
383Saved values.
384.El
385.It Fl d
386Disable block descriptors when sending the mode sense request.
387.It Fl S Ar subpage
388Specify the subpage used with the mode sense request.
389.It Fl c Ar cdbsize
390Specify the CDB size used for the mode sense request. Supported values are
3916 and 10.
392.El
393.It Ic start
394Send the
395.Tn SCSI
396START STOP UNIT command to the specified LUN with the start
397bit set.
398.Bl -tag -width 4n
399.It Fl i
400Set the immediate bit in the CDB. Note that CTL does not support the
401immediate bit, so this is primarily useful for making sure that CTL returns
402the proper error.
403.El
404.It Ic stop
405Send the
406.Tn SCSI
407START STOP UNIT command to the specified LUN with the start
408bit cleared. We use an ordered tag to stop the LUN, so we can guarantee
409that all pending I/O executes before it is stopped. (CTL guarantees this
410anyway, but
411.Nm
412sends an ordered tag for completeness.)
413.Bl -tag -width 4n
414.It Fl i
415Set the immediate bit in the CDB. Note that CTL does not support the
416immediate bit, so this is primarily useful for making sure that CTL returns
417the proper error.
418.El
419.It Ic synccache
420Send the
421.Tn SCSI
422SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE
423CACHE(10) is used. If the specified starting LBA is greater than
4240xffffffff or the length is greater than 0xffff, though,
425SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used
426if the user specifies a 16 byte CDB with the
427.Fl c
428argument.
429.Bl -tag -width 14n
430.It Fl l Ar lba
431Specify the starting LBA of the cache region to synchronize. This option is a
432no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the
433cache for the entire LUN.
434.It Fl b Ar blockcount
435Specify the length of the cache region to synchronize. This option is a
436no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the
437cache for the entire LUN.
438.It Fl r
439Specify relative addressing for the starting LBA. CTL does not support
440relative addressing, since it only works for linked commands, and CTL
441does not support linked commands.
442.It Fl i
443Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE
444command rather than waiting for the cache to finish syncing. CTL does not
445support this bit.
446.It Fl c Ar cdbsize
447Specify the minimum CDB size. Valid values are 10 and 16 bytes.
448.El
449.It Ic lunlist
450List all LUNs registered with CTL.
451Because this command uses the ioctl port, it will only work when the FETDs
452(Front End Target Drivers) are enabled.
453This command is the equivalent of doing a REPORT LUNS on one LUN and then
454an INQUIRY on each LUN in the system.
455.It Ic delay
456Delay commands at the given location. There are two places where commands
457may be delayed currently: before data is transferred
458.Pq Dq datamove
459and just prior to sending status to the host
460.Pq Dq done .
461One of the two must be supplied as an argument to the
462.Fl l
463option. The
464.Fl t
465option must also be specified.
466.Bl -tag -width 12n
467.It Fl l Ar delayloc
468Delay command(s) at the specified location.
469This can either be at the data movement stage (datamove) or prior to
470command completion (done).
471.It Fl t Ar delaytime
472Delay command(s) for the specified number of seconds. This must be
473specified. If set to 0, it will clear out any previously set delay for
474this particular location (datamove or done).
475.It Fl T Ar delaytype
476Specify the delay type.
477By default, the
478.Ic delay
479option will delay the next command sent to the given LUN.
480With the
481.Fl T Ar cont
482option, every command will be delayed by the specified period of time.
483With the
484.Fl T Ar oneshot
485the next command sent to the given LUN will be delayed and all subsequent
486commands will be completed normally.
487This is the default.
488.El
489.It Ic inject
490Inject the specified type of error for the LUN specified, when a command
491that matches the given pattern is seen.
492The sense data returned is in either fixed or descriptor format, depending
493upon the status of the D_SENSE bit in the control mode page (page 0xa) for
494the LUN.
495.Pp
496Errors are only injected for commands that have not already failed for
497other reasons.
498By default, only the first command matching the pattern specified is
499returned with the supplied error.
500.Pp
501If the
502.Fl c
503flag is specified, all commands matching the pattern will be returned with
504the specified error until the error injection command is deleted with
505.Fl d
506flag.
507.Bl -tag -width 17n
508.It Fl i Ar action
509Specify the error to return:
510.Bl -tag -width 10n
511.It aborted
512Return the next matching command on the specified LUN with the sense key
513ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
514failure").
515.It mediumerr
516Return the next matching command on the specified LUN with the sense key
517MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
518reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
519for write errors.
520.It ua
521Return the next matching command on the specified LUN with the sense key
522UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
523DEVICE RESET OCCURRED").
524.It custom
525Return the next matching command on the specified LUN with the supplied
526sense data.
527The
528.Fl s
529argument must be specified.
530.El
531.It Fl p Ar pattern
532Specify which commands should be returned with the given error.
533.Bl -tag -width 10n
534.It read
535The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
536.It write
537The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
538AND VERIFY(10), etc.
539.It rw
540The error should apply to both read and write type commands.
541.It readcap
542The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
543.It tur
544The error should apply to TEST UNIT READY commands.
545.It any
546The error should apply to any command.
547.El
548.It Fl r Ar lba,len
549Specify the starting lba and length of the range of LBAs which should
550trigger an error.
551This option is only applies when read and/or write patterns are specified.
552If used with other command types, the error will never be triggered.
553.It Fl s Ar len fmt Op Ar args
554Specify the sense data that is to be returned for custom actions.
555If the format is
556.Sq - ,
557len bytes of sense data will be read from standard input and written to the
558sense buffer.
559If len is longer than 252 bytes (the maximum allowable
560.Tn SCSI
561sense data length), it will be truncated to that length.
562The sense data format is described in
563.Xr cam_cdparse 3 .
564.It Fl c
565The error injection should be persistent, instead of happening once.
566Persistent errors must be deleted with the
567.Fl d
568argument.
569.It Fl d Ar delete_id
570Delete the specified error injection serial number.
571The serial number is returned when the error is injected.
572.El
573.It Ic port
574Perform one of several CTL frontend port operations.
575Either get a list of frontend ports
576.Pq Fl l ,
577turn one or more frontends on
578or off
579.Pq Fl o Ar on|off ,
580or set the World Wide Node Name
581.Pq Fl w Ar wwnn
582or World Wide Port Name
583.Pq Fl W Ar wwpn
584for a given port.
585One of
586.Fl l ,
587.Fl o ,
588or
589.Fl w
590or
591.Fl W
592must be specified.
593The WWNN and WWPN may both be specified at the same time, but cannot be
594combined with enabling/disabling or listing ports.
595.Bl -tag -width 12n
596.It Fl o Ar on|off
597Turn the specified CTL frontend ports off or on.
598If no port number or port type is specified, all ports are turned on or
599off.
600.It Fl p Ar targ_port
601Specify the frontend port number.
602The port numbers can be found in the frontend port list.
603.It Fl t Ar fe_type
604Specify the frontend type.
605Currently defined port types are
606.Dq fc
607(Fibre Channel),
608.Dq scsi
609(Parallel SCSI),
610.Dq ioctl
611(CTL ioctl interface),
612and
613.Dq internal
614(CTL CAM SIM).
615.It Fl w Ar wwnn
616Set the World Wide Node Name for the given port.
617The
618.Fl n
619argument must be specified, since this is only possible to implement on a
620single port.
621As a general rule, the WWNN should be the same across all ports on the
622system.
623.It Fl W Ar wwpn
624Set the World Wide Port Name for the given port.
625The
626.Fl n
627argument must be specified, since this is only possible to implement on a
628single port.
629As a general rule, the WWPN must be different for every port in the system.
630.El
631.It Ic portlist
632List CTL frontend ports.
633.Bl -tag -width 12n
634.It Fl f Ar frontend
635Specify the frontend type.
636.It Fl i
637Report target and connected initiators addresses.
638.It Fl l
639Report LUN mapping.
640.It Fl p Ar targ_port
641Specify the frontend port number.
642.It Fl q
643Omit the header in the port list output.
644.It Fl v
645Enable verbose output (report all port options).
646.It Fl x
647Output the port list in XML format.
648.El
649.It Ic lunmap
650Change LUN mapping for specified port.
651If both
652.Ar pLUN
653and
654.Ar cLUN
655are specified -- LUN will be mapped.
656If
657.Ar pLUN
658is specified, but
659.Ar cLUN
660is not -- LUN will be unmapped.
661If neither
662.Ar pLUN
663nor
664.Ar cLUN
665are specified -- LUN mapping will be disabled, exposing all CTL LUNs.
666.Bl -tag -width 12n
667.It Fl p Ar targ_port
668Specify the frontend port number.
669.It Fl l Ar pLUN
670LUN number visible by specified port.
671.It Fl L Ar cLUN
672CTL LUN number.
673.El
674.It Ic dumpooa
675Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
676.It Ic dumpstructs
677Dump the CTL structures to the console.
678.It Ic create
679Create a new LUN.
680The backend must be specified, and depending upon the backend requested,
681some of the other options may be required.
682If the LUN is created successfully, the LUN configuration will be
683displayed.
684If LUN creation fails, a message will be displayed describing the failure.
685.Bl -tag -width 14n
686.It Fl b Ar backend
687The
688.Fl b
689flag is required.
690This specifies the name backend to use when creating the LUN.
691Examples are
692.Dq ramdisk
693and
694.Dq block .
695.It Fl B Ar blocksize
696Specify the blocksize of the backend in bytes.
697.It Fl d Ar device_id
698Specify the LUN-associated string to use in the
699.Tn SCSI
700INQUIRY VPD page 0x83 data.
701.It Fl l Ar lun_id
702Request that a particular LUN number be assigned.
703If the requested LUN number is not available, the request will fail.
704.It Fl o Ar name=value
705Specify a backend-specific name/value pair.
706Multiple
707.Fl o
708arguments may be specified.
709Refer to the backend documentation for arguments that may be used.
710.It Fl s Ar size_bytes
711Specify the size of the LUN in bytes.
712Some backends may allow setting the size (e.g. the ramdisk backend) and for
713others the size may be implicit (e.g. the block backend).
714.It Fl S Ar serial_num
715Specify the serial number to be used in the
716.Tn SCSI
717INQUIRY VPD page 0x80 data.
718.It Fl t Ar device_type
719Specify the numeric SCSI device type to use when creating the LUN.
| 37.\"
38.Dd September 26, 2015
39.Dt CTLADM 8
40.Os
41.Sh NAME
42.Nm ctladm
43.Nd CAM Target Layer control utility
44.Sh SYNOPSIS
45.Nm
46.Aq Ar command
47.Op lun
48.Op generic args
49.Op command args
50.Nm
51.Ic tur
52.Aq lun
53.Op general options
54.Nm
55.Ic inquiry
56.Aq lun
57.Op general options
58.Nm
59.Ic reqsense
60.Aq lun
61.Op general options
62.Nm
63.Ic reportluns
64.Aq lun
65.Op general options
66.Nm
67.Ic read
68.Aq lun
69.Op general options
70.Aq Fl l Ar lba
71.Aq Fl d Ar datalen
72.Aq Fl f Ar file|-
73.Aq Fl b Ar blocksize_bytes
74.Op Fl c Ar cdbsize
75.Op Fl N
76.Nm
77.Ic write
78.Aq lun
79.Op general options
80.Aq Fl l Ar lba
81.Aq Fl d Ar datalen
82.Aq Fl f Ar file|-
83.Aq Fl b Ar blocksize_bytes
84.Op Fl c Ar cdbsize
85.Op Fl N
86.Nm
87.Ic readcap
88.Aq lun
89.Op general options
90.Op Fl c Ar cdbsize
91.Nm
92.Ic modesense
93.Aq lun
94.Aq Fl m Ar page | Fl l
95.Op Fl P Ar pc
96.Op Fl d
97.Op Fl S Ar subpage
98.Op Fl c Ar size
99.Nm
100.Ic start
101.Aq lun
102.Op general options
103.Op Fl i
104.Op Fl o
105.Nm
106.Ic stop
107.Aq lun
108.Op general options
109.Op Fl i
110.Op Fl o
111.Nm
112.Ic synccache
113.Aq lun
114.Op general options
115.Op Fl l Ar lba
116.Op Fl b Ar blockcount
117.Op Fl r
118.Op Fl i
119.Op Fl c Ar cdbsize
120.Nm
121.Ic lunlist
122.Nm
123.Ic delay
124.Aq lun
125.Aq Fl l Ar datamove|done
126.Aq Fl t Ar secs
127.Op Fl T Ar oneshot|cont
128.Nm
129.Ic inject
130.Aq Fl i Ar action
131.Aq Fl p Ar pattern
132.Op Fl r Ar lba,len
133.Op Fl s Ar len fmt Op Ar args
134.Op Fl c
135.Op Fl d Ar delete_id
136.Nm
137.Ic create
138.Aq Fl b Ar backend
139.Op Fl B Ar blocksize
140.Op Fl d Ar device_id
141.Op Fl l Ar lun_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
146.Nm
147.Ic remove
148.Aq Fl b Ar backend
149.Aq Fl l Ar lun_id
150.Op Fl o Ar name=value
151.Nm
152.Ic modify
153.Aq Fl b Ar backend
154.Aq Fl l Ar lun_id
155.Op Fl o Ar name=value
156.Aq Fl s Ar size_bytes
157.Nm
158.Ic devlist
159.Op Fl b Ar backend
160.Op Fl v
161.Op Fl x
162.Nm
163.Ic port
164.Op Fl o Ar on|off
165.Op Fl w Ar wwpn
166.Op Fl W Ar wwnn
167.Op Fl p Ar targ_port
168.Op Fl t Ar fe_type
169.Nm
170.Ic portlist
171.Op Fl f Ar frontend
172.Op Fl i
173.Op Fl l
174.Op Fl p Ar targ_port
175.Op Fl q
176.Op Fl v
177.Op Fl x
178.Nm
179.Ic lunmap
180.Aq Fl p Ar targ_port
181.Op Fl l Ar pLUN
182.Op Fl L Ar cLUN
183.Nm
184.Ic dumpooa
185.Nm
186.Ic dumpstructs
187.Nm
188.Ic islist
189.Op Fl v
190.Op Fl x
191.Nm
192.Ic islogout
193.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
194.Nm
195.Ic isterminate
196.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
197.Nm
198.Ic help
199.Sh DESCRIPTION
200The
201.Nm
202utility is designed to provide a way to access and control the CAM Target
203Layer (CTL).
204It provides a way to send
205.Tn SCSI
206commands to the CTL layer, and also provides
207some meta-commands that utilize
208.Tn SCSI
209commands.
210(For instance, the
211.Ic lunlist
212command is implemented using the
213.Tn SCSI
214REPORT LUNS and INQUIRY commands.)
215.Pp
216The
217.Nm
218utility has a number of primary functions, many of which require a device
219identifier.
220The device identifier takes the following form:
221.Bl -tag -width 14n
222.It lun
223Specify the LUN number to operate on.
224.El
225Many of the primary functions of the
226.Nm
227utility take the following optional arguments:
228.Bl -tag -width 10n
229.It Fl C Ar retries
230Specify the number of times to retry a command in the event of failure.
231.It Fl D Ar device
232Specify the device to open. This allows opening a device other than the
233default device,
234.Pa /dev/cam/ctl ,
235to be opened for sending commands.
236.It Fl I Ar id
237Specify the initiator number to use.
238By default,
239.Nm
240will use 7 as the initiator number.
241.El
242.Pp
243Primary commands:
244.Bl -tag -width 11n
245.It Ic tur
246Send the
247.Tn SCSI
248TEST UNIT READY command to the device and report whether or not it is
249ready.
250.It Ic inquiry
251Send the
252.Tn SCSI
253INQUIRY command to the device and display some of the returned inquiry
254data.
255.It Ic reqsense
256Send the
257.Tn SCSI
258REQUEST SENSE command to the device and display the returned sense
259information.
260.It Ic reportluns
261Send the
262.Tn SCSI
263REPORT LUNS command to the device and display supported LUNs.
264.It Ic read
265Send a
266.Tn SCSI
267READ command to the device, and write the requested data to a file or
268stdout.
269.Bl -tag -width 12n
270.It Fl l Ar lba
271Specify the starting Logical Block Address for the READ. This can be
272specified in decimal, octal (starting with 0), hexadecimal (starting with
2730x) or any other base supported by
274.Xr strtoull 3 .
275.It Fl d Ar datalen
276Specify the length, in 512 byte blocks, of the READ request.
277.It Fl f Ar file
278Specify the destination for the data read by the READ command. Either a
279filename or
280.Sq -
281for stdout may be specified.
282.It Fl c Ar cdbsize
283Specify the minimum
284.Tn SCSI
285CDB (Command Data Block) size to be used for the READ request. Allowable
286values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
287requested, a larger CDB size may be used to satisfy the request. (e.g.,
288for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
289.It Fl b Ar blocksize
290Specify the blocksize of the underlying
291.Tn SCSI
292device, so the transfer length
293can be calculated accurately. The blocksize can be obtained via the
294.Tn SCSI
295READ CAPACITY command.
296.It Fl N
297Do not copy data to
298.Nm
299from the kernel when doing a read, just execute the command without copying
300data.
301This is to be used for performance testing.
302.El
303.It Ic write
304Read data from a file or stdin, and write the data to the device using the
305.Tn SCSI
306WRITE command.
307.Bl -tag -width 12n
308.It Fl l Ar lba
309Specify the starting Logical Block Address for the WRITE. This can be
310specified in decimal, octal (starting with 0), hexadecimal (starting with
3110x) or any other base supported by
312.Xr strtoull 3 .
313.It Fl d Ar atalen
314Specify the length, in 512 byte blocks, of the WRITE request.
315.It Fl f Ar file
316Specify the source for the data to be written by the WRITE command. Either a
317filename or
318.Sq -
319for stdin may be specified.
320.It Fl c Ar cdbsize
321Specify the minimum
322.Tn SCSI
323CDB (Command Data Block) size to be used for the READ request. Allowable
324values are 6, 10, 12 and 16. Depending upon the LBA and amount of data
325requested, a larger CDB size may be used to satisfy the request. (e.g.,
326for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
327.It Fl b Ar blocksize
328Specify the blocksize of the underlying
329.Tn SCSI
330device, so the transfer length
331can be calculated accurately. The blocksize can be obtained via the
332.Tn SCSI
333READ CAPACITY command.
334.It Fl N
335Do not copy data to
336.Nm
337to the kernel when doing a write, just execute the command without copying
338data.
339This is to be used for performance testing.
340.El
341.It Ic readcap
342Send the
343.Tn SCSI
344READ CAPACITY command to the device and display the device size and device
345block size. By default, READ CAPACITY(10) is
346used. If the device returns a maximum LBA of 0xffffffff, however,
347.Nm
348will automatically issue a READ CAPACITY(16), which is implemented as a
349service action of the SERVICE ACTION IN(16) opcode. The user can specify
350the minimum CDB size with the
351.Fl c
352argument. Valid values for the
353.Fl c
354option are 10 and 16. If a 10 byte CDB is specified, the request will be
355automatically reissued with a 16 byte CDB if the maximum LBA returned is
3560xffffffff.
357.It Ic modesense
358Send a
359.Tn SCSI
360MODE SENSE command to the device, and display the requested mode page(s) or
361page list.
362.Bl -tag -width 10n
363.It Fl m Ar page
364Specify the mode page to display. This option and the
365.Fl l
366option are mutually exclusive. One of the two must be specified, though.
367Mode page numbers may be specified in decimal or hexadecimal.
368.It Fl l
369Request that the list of mode pages supported by the device be returned.
370This option and the
371.Fl m
372option are mutually exclusive. One of the two must be specified, though.
373.It Fl P Ar pc
374Specify the mode page control value. Possible values are:
375.Bl -tag -width 2n -compact
376.It 0
377Current values.
378.It 1
379Changeable value bitmask.
380.It 2
381Default values.
382.It 3
383Saved values.
384.El
385.It Fl d
386Disable block descriptors when sending the mode sense request.
387.It Fl S Ar subpage
388Specify the subpage used with the mode sense request.
389.It Fl c Ar cdbsize
390Specify the CDB size used for the mode sense request. Supported values are
3916 and 10.
392.El
393.It Ic start
394Send the
395.Tn SCSI
396START STOP UNIT command to the specified LUN with the start
397bit set.
398.Bl -tag -width 4n
399.It Fl i
400Set the immediate bit in the CDB. Note that CTL does not support the
401immediate bit, so this is primarily useful for making sure that CTL returns
402the proper error.
403.El
404.It Ic stop
405Send the
406.Tn SCSI
407START STOP UNIT command to the specified LUN with the start
408bit cleared. We use an ordered tag to stop the LUN, so we can guarantee
409that all pending I/O executes before it is stopped. (CTL guarantees this
410anyway, but
411.Nm
412sends an ordered tag for completeness.)
413.Bl -tag -width 4n
414.It Fl i
415Set the immediate bit in the CDB. Note that CTL does not support the
416immediate bit, so this is primarily useful for making sure that CTL returns
417the proper error.
418.El
419.It Ic synccache
420Send the
421.Tn SCSI
422SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE
423CACHE(10) is used. If the specified starting LBA is greater than
4240xffffffff or the length is greater than 0xffff, though,
425SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used
426if the user specifies a 16 byte CDB with the
427.Fl c
428argument.
429.Bl -tag -width 14n
430.It Fl l Ar lba
431Specify the starting LBA of the cache region to synchronize. This option is a
432no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the
433cache for the entire LUN.
434.It Fl b Ar blockcount
435Specify the length of the cache region to synchronize. This option is a
436no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the
437cache for the entire LUN.
438.It Fl r
439Specify relative addressing for the starting LBA. CTL does not support
440relative addressing, since it only works for linked commands, and CTL
441does not support linked commands.
442.It Fl i
443Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE
444command rather than waiting for the cache to finish syncing. CTL does not
445support this bit.
446.It Fl c Ar cdbsize
447Specify the minimum CDB size. Valid values are 10 and 16 bytes.
448.El
449.It Ic lunlist
450List all LUNs registered with CTL.
451Because this command uses the ioctl port, it will only work when the FETDs
452(Front End Target Drivers) are enabled.
453This command is the equivalent of doing a REPORT LUNS on one LUN and then
454an INQUIRY on each LUN in the system.
455.It Ic delay
456Delay commands at the given location. There are two places where commands
457may be delayed currently: before data is transferred
458.Pq Dq datamove
459and just prior to sending status to the host
460.Pq Dq done .
461One of the two must be supplied as an argument to the
462.Fl l
463option. The
464.Fl t
465option must also be specified.
466.Bl -tag -width 12n
467.It Fl l Ar delayloc
468Delay command(s) at the specified location.
469This can either be at the data movement stage (datamove) or prior to
470command completion (done).
471.It Fl t Ar delaytime
472Delay command(s) for the specified number of seconds. This must be
473specified. If set to 0, it will clear out any previously set delay for
474this particular location (datamove or done).
475.It Fl T Ar delaytype
476Specify the delay type.
477By default, the
478.Ic delay
479option will delay the next command sent to the given LUN.
480With the
481.Fl T Ar cont
482option, every command will be delayed by the specified period of time.
483With the
484.Fl T Ar oneshot
485the next command sent to the given LUN will be delayed and all subsequent
486commands will be completed normally.
487This is the default.
488.El
489.It Ic inject
490Inject the specified type of error for the LUN specified, when a command
491that matches the given pattern is seen.
492The sense data returned is in either fixed or descriptor format, depending
493upon the status of the D_SENSE bit in the control mode page (page 0xa) for
494the LUN.
495.Pp
496Errors are only injected for commands that have not already failed for
497other reasons.
498By default, only the first command matching the pattern specified is
499returned with the supplied error.
500.Pp
501If the
502.Fl c
503flag is specified, all commands matching the pattern will be returned with
504the specified error until the error injection command is deleted with
505.Fl d
506flag.
507.Bl -tag -width 17n
508.It Fl i Ar action
509Specify the error to return:
510.Bl -tag -width 10n
511.It aborted
512Return the next matching command on the specified LUN with the sense key
513ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
514failure").
515.It mediumerr
516Return the next matching command on the specified LUN with the sense key
517MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
518reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
519for write errors.
520.It ua
521Return the next matching command on the specified LUN with the sense key
522UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
523DEVICE RESET OCCURRED").
524.It custom
525Return the next matching command on the specified LUN with the supplied
526sense data.
527The
528.Fl s
529argument must be specified.
530.El
531.It Fl p Ar pattern
532Specify which commands should be returned with the given error.
533.Bl -tag -width 10n
534.It read
535The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
536.It write
537The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
538AND VERIFY(10), etc.
539.It rw
540The error should apply to both read and write type commands.
541.It readcap
542The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
543.It tur
544The error should apply to TEST UNIT READY commands.
545.It any
546The error should apply to any command.
547.El
548.It Fl r Ar lba,len
549Specify the starting lba and length of the range of LBAs which should
550trigger an error.
551This option is only applies when read and/or write patterns are specified.
552If used with other command types, the error will never be triggered.
553.It Fl s Ar len fmt Op Ar args
554Specify the sense data that is to be returned for custom actions.
555If the format is
556.Sq - ,
557len bytes of sense data will be read from standard input and written to the
558sense buffer.
559If len is longer than 252 bytes (the maximum allowable
560.Tn SCSI
561sense data length), it will be truncated to that length.
562The sense data format is described in
563.Xr cam_cdparse 3 .
564.It Fl c
565The error injection should be persistent, instead of happening once.
566Persistent errors must be deleted with the
567.Fl d
568argument.
569.It Fl d Ar delete_id
570Delete the specified error injection serial number.
571The serial number is returned when the error is injected.
572.El
573.It Ic port
574Perform one of several CTL frontend port operations.
575Either get a list of frontend ports
576.Pq Fl l ,
577turn one or more frontends on
578or off
579.Pq Fl o Ar on|off ,
580or set the World Wide Node Name
581.Pq Fl w Ar wwnn
582or World Wide Port Name
583.Pq Fl W Ar wwpn
584for a given port.
585One of
586.Fl l ,
587.Fl o ,
588or
589.Fl w
590or
591.Fl W
592must be specified.
593The WWNN and WWPN may both be specified at the same time, but cannot be
594combined with enabling/disabling or listing ports.
595.Bl -tag -width 12n
596.It Fl o Ar on|off
597Turn the specified CTL frontend ports off or on.
598If no port number or port type is specified, all ports are turned on or
599off.
600.It Fl p Ar targ_port
601Specify the frontend port number.
602The port numbers can be found in the frontend port list.
603.It Fl t Ar fe_type
604Specify the frontend type.
605Currently defined port types are
606.Dq fc
607(Fibre Channel),
608.Dq scsi
609(Parallel SCSI),
610.Dq ioctl
611(CTL ioctl interface),
612and
613.Dq internal
614(CTL CAM SIM).
615.It Fl w Ar wwnn
616Set the World Wide Node Name for the given port.
617The
618.Fl n
619argument must be specified, since this is only possible to implement on a
620single port.
621As a general rule, the WWNN should be the same across all ports on the
622system.
623.It Fl W Ar wwpn
624Set the World Wide Port Name for the given port.
625The
626.Fl n
627argument must be specified, since this is only possible to implement on a
628single port.
629As a general rule, the WWPN must be different for every port in the system.
630.El
631.It Ic portlist
632List CTL frontend ports.
633.Bl -tag -width 12n
634.It Fl f Ar frontend
635Specify the frontend type.
636.It Fl i
637Report target and connected initiators addresses.
638.It Fl l
639Report LUN mapping.
640.It Fl p Ar targ_port
641Specify the frontend port number.
642.It Fl q
643Omit the header in the port list output.
644.It Fl v
645Enable verbose output (report all port options).
646.It Fl x
647Output the port list in XML format.
648.El
649.It Ic lunmap
650Change LUN mapping for specified port.
651If both
652.Ar pLUN
653and
654.Ar cLUN
655are specified -- LUN will be mapped.
656If
657.Ar pLUN
658is specified, but
659.Ar cLUN
660is not -- LUN will be unmapped.
661If neither
662.Ar pLUN
663nor
664.Ar cLUN
665are specified -- LUN mapping will be disabled, exposing all CTL LUNs.
666.Bl -tag -width 12n
667.It Fl p Ar targ_port
668Specify the frontend port number.
669.It Fl l Ar pLUN
670LUN number visible by specified port.
671.It Fl L Ar cLUN
672CTL LUN number.
673.El
674.It Ic dumpooa
675Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
676.It Ic dumpstructs
677Dump the CTL structures to the console.
678.It Ic create
679Create a new LUN.
680The backend must be specified, and depending upon the backend requested,
681some of the other options may be required.
682If the LUN is created successfully, the LUN configuration will be
683displayed.
684If LUN creation fails, a message will be displayed describing the failure.
685.Bl -tag -width 14n
686.It Fl b Ar backend
687The
688.Fl b
689flag is required.
690This specifies the name backend to use when creating the LUN.
691Examples are
692.Dq ramdisk
693and
694.Dq block .
695.It Fl B Ar blocksize
696Specify the blocksize of the backend in bytes.
697.It Fl d Ar device_id
698Specify the LUN-associated string to use in the
699.Tn SCSI
700INQUIRY VPD page 0x83 data.
701.It Fl l Ar lun_id
702Request that a particular LUN number be assigned.
703If the requested LUN number is not available, the request will fail.
704.It Fl o Ar name=value
705Specify a backend-specific name/value pair.
706Multiple
707.Fl o
708arguments may be specified.
709Refer to the backend documentation for arguments that may be used.
710.It Fl s Ar size_bytes
711Specify the size of the LUN in bytes.
712Some backends may allow setting the size (e.g. the ramdisk backend) and for
713others the size may be implicit (e.g. the block backend).
714.It Fl S Ar serial_num
715Specify the serial number to be used in the
716.Tn SCSI
717INQUIRY VPD page 0x80 data.
718.It Fl t Ar device_type
719Specify the numeric SCSI device type to use when creating the LUN.
|
879.It Va reordering
880Set to "unrestricted", allows target to process commands with SIMPLE task
881attribute in arbitrary order. Any data integrity exposures related to
882command sequence order shall be explicitly handled by the application
883client through the selection of appropriate commands and task attributes.
884The default value is "restricted". It improves data integrity, but may
885introduce some additional delays.
886.It Va serseq
887Set to "on" to serialize conse��utive reads/writes.
888Set to "read" to serialize conse��utive reads.
889Set to "off" to allow them be issued in parallel.
890Parallel issue of consecutive operations may confuse logic of the
891backing file system, hurting performance; but it may improve performance
892of backing stores without prefetch/write-back.
893.It Va pblocksize
894.It Va pblockoffset
895Specify physical block size and offset of the device.
896.It Va ublocksize
897.It Va ublockoffset
898Specify UNMAP block size and offset of the device.
899.It Va rpm
900Specifies medium rotation rate of the device: 0 -- not reported,
9011 -- non-rotating (SSD), >1024 -- value in revolutions per minute.
902.It Va formfactor
903Specifies nominal form factor of the device: 0 -- not reported, 1 -- 5.25",
9042 -- 3.5", 3 -- 2.5", 4 -- 1.8", 5 -- less then 1.8".
905.It Va unmap
906Set to "on", enables UNMAP support for the LUN, if supported by the backend.
907.It Va avail-threshold
908.It Va used-threshold
909.It Va pool-avail-threshold
910.It Va pool-used-threshold
911Set per-LUN/-pool thin provisioning soft thresholds.
912LUN will establish UNIT ATTENTION condition if its or pool available space
913get below configured avail values, or its or pool used space get above
914configured used values.
915Pool thresholds are working only for ZVOL-backed LUNs.
916.It Va writecache
917Set to "off", disables write caching for the LUN, if supported by the backend.
918.El
919.Pp
920Options specific for block backend:
921.Bl -tag -width 12n
922.It Va file
923Specifies file or device name to use for backing store.
924.It Va num_threads
925Specifies number of backend threads to use for this LUN.
926.El
927.Sh EXAMPLES
928.Dl ctladm tur 1
929.Pp
930Send a
931.Tn SCSI
932TEST UNIT READY command to LUN 1.
933.Pp
934.Dl ctladm modesense 1 -l
935.Pp
936Display the list of mode pages supported by LUN 1.
937.Pp
938.Dl ctladm modesense 0 -m 10 -P 3 -d -c 10
939.Pp
940Display the saved version of the Control mode page (page 10) on LUN 0.
941Disable fetching block descriptors, and use a 10 byte MODE SENSE command
942instead of the default 6 byte command.
943.Bd -literal
944ctladm read 2 -l 0 -d 1 -b 512 -f - > foo
945.Ed
946.Pp
947Read the first 512 byte block from LUN 2 and dump it to the file
948.Pa foo .
949.Bd -literal
950ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
951.Ed
952.Pp
953Read 10240 bytes from the file
954.Pa /tmp/bar
955and write it to LUN 3.
956starting at LBA 0xff432140.
957.Pp
958.Dl ctladm create -b ramdisk -s 10485760000000000
959.Pp
960Create a LUN with the
961.Dq fake
962ramdisk as a backing store.
963The LUN will claim to have a size of approximately 10 terabytes.
964.Pp
965.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8
966.Pp
967Create a LUN using the block backend, and specify the file
968.Pa src/usr.sbin/ctladm/ctladm.8
969as the backing store.
970The size of the LUN will be derived from the size of the file.
971.Pp
972.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123
973.Pp
974Create a LUN using the block backend, specify the file
975.Pa src/usr.sbin/ctladm/ctladm.8
976as the backing store, and specify the
977.Tn SCSI
978VPD page 0x80 and 0x83 serial number
979.Fl ( S )
980and device ID
981.Fl ( d ) .
982.Pp
983.Dl ctladm remove -b block -l 12
984.Pp
985Remove LUN 12, which is handled by the block backend, from the system.
986.Pp
987.Dl ctladm devlist
988.Pp
989List configured LUNs in the system, along with their backend and serial
990number.
991This works when the Front End Target Drivers are enabled or disabled.
992.Pp
993.Dl ctladm lunlist
994.Pp
995List all LUNs in the system, along with their inquiry data and device type.
996This only works when the FETDs are enabled, since the commands go through the
997ioctl port.
998.Pp
999.Dl ctladm inject 6 -i mediumerr -p read -r 0,512 -c
1000.Pp
1001Inject a medium error on LUN 6 for every read that covers the first 512
1002blocks of the LUN.
1003.Bd -literal -offset indent
1004ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
1005.Ed
1006.Pp
1007Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
1008This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
10090x04,0x02 ("Logical unit not ready, initializing command required").
1010.Sh SEE ALSO
1011.Xr cam 3 ,
1012.Xr cam_cdbparse 3 ,
1013.Xr cam 4 ,
1014.Xr ctl 4 ,
1015.Xr xpt 4 ,
1016.Xr camcontrol 8 ,
1017.Xr ctld 8 ,
1018.Xr ctlstat 8
1019.Sh HISTORY
1020The
1021.Nm
1022utility was originally written during the Winter/Spring of 2003 as an
1023interface to CTL.
1024.Sh AUTHORS
1025.An Ken Merry Aq Mt ken@FreeBSD.org
| 880.It Va reordering
881Set to "unrestricted", allows target to process commands with SIMPLE task
882attribute in arbitrary order. Any data integrity exposures related to
883command sequence order shall be explicitly handled by the application
884client through the selection of appropriate commands and task attributes.
885The default value is "restricted". It improves data integrity, but may
886introduce some additional delays.
887.It Va serseq
888Set to "on" to serialize conse��utive reads/writes.
889Set to "read" to serialize conse��utive reads.
890Set to "off" to allow them be issued in parallel.
891Parallel issue of consecutive operations may confuse logic of the
892backing file system, hurting performance; but it may improve performance
893of backing stores without prefetch/write-back.
894.It Va pblocksize
895.It Va pblockoffset
896Specify physical block size and offset of the device.
897.It Va ublocksize
898.It Va ublockoffset
899Specify UNMAP block size and offset of the device.
900.It Va rpm
901Specifies medium rotation rate of the device: 0 -- not reported,
9021 -- non-rotating (SSD), >1024 -- value in revolutions per minute.
903.It Va formfactor
904Specifies nominal form factor of the device: 0 -- not reported, 1 -- 5.25",
9052 -- 3.5", 3 -- 2.5", 4 -- 1.8", 5 -- less then 1.8".
906.It Va unmap
907Set to "on", enables UNMAP support for the LUN, if supported by the backend.
908.It Va avail-threshold
909.It Va used-threshold
910.It Va pool-avail-threshold
911.It Va pool-used-threshold
912Set per-LUN/-pool thin provisioning soft thresholds.
913LUN will establish UNIT ATTENTION condition if its or pool available space
914get below configured avail values, or its or pool used space get above
915configured used values.
916Pool thresholds are working only for ZVOL-backed LUNs.
917.It Va writecache
918Set to "off", disables write caching for the LUN, if supported by the backend.
919.El
920.Pp
921Options specific for block backend:
922.Bl -tag -width 12n
923.It Va file
924Specifies file or device name to use for backing store.
925.It Va num_threads
926Specifies number of backend threads to use for this LUN.
927.El
928.Sh EXAMPLES
929.Dl ctladm tur 1
930.Pp
931Send a
932.Tn SCSI
933TEST UNIT READY command to LUN 1.
934.Pp
935.Dl ctladm modesense 1 -l
936.Pp
937Display the list of mode pages supported by LUN 1.
938.Pp
939.Dl ctladm modesense 0 -m 10 -P 3 -d -c 10
940.Pp
941Display the saved version of the Control mode page (page 10) on LUN 0.
942Disable fetching block descriptors, and use a 10 byte MODE SENSE command
943instead of the default 6 byte command.
944.Bd -literal
945ctladm read 2 -l 0 -d 1 -b 512 -f - > foo
946.Ed
947.Pp
948Read the first 512 byte block from LUN 2 and dump it to the file
949.Pa foo .
950.Bd -literal
951ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
952.Ed
953.Pp
954Read 10240 bytes from the file
955.Pa /tmp/bar
956and write it to LUN 3.
957starting at LBA 0xff432140.
958.Pp
959.Dl ctladm create -b ramdisk -s 10485760000000000
960.Pp
961Create a LUN with the
962.Dq fake
963ramdisk as a backing store.
964The LUN will claim to have a size of approximately 10 terabytes.
965.Pp
966.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8
967.Pp
968Create a LUN using the block backend, and specify the file
969.Pa src/usr.sbin/ctladm/ctladm.8
970as the backing store.
971The size of the LUN will be derived from the size of the file.
972.Pp
973.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123
974.Pp
975Create a LUN using the block backend, specify the file
976.Pa src/usr.sbin/ctladm/ctladm.8
977as the backing store, and specify the
978.Tn SCSI
979VPD page 0x80 and 0x83 serial number
980.Fl ( S )
981and device ID
982.Fl ( d ) .
983.Pp
984.Dl ctladm remove -b block -l 12
985.Pp
986Remove LUN 12, which is handled by the block backend, from the system.
987.Pp
988.Dl ctladm devlist
989.Pp
990List configured LUNs in the system, along with their backend and serial
991number.
992This works when the Front End Target Drivers are enabled or disabled.
993.Pp
994.Dl ctladm lunlist
995.Pp
996List all LUNs in the system, along with their inquiry data and device type.
997This only works when the FETDs are enabled, since the commands go through the
998ioctl port.
999.Pp
1000.Dl ctladm inject 6 -i mediumerr -p read -r 0,512 -c
1001.Pp
1002Inject a medium error on LUN 6 for every read that covers the first 512
1003blocks of the LUN.
1004.Bd -literal -offset indent
1005ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
1006.Ed
1007.Pp
1008Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
1009This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
10100x04,0x02 ("Logical unit not ready, initializing command required").
1011.Sh SEE ALSO
1012.Xr cam 3 ,
1013.Xr cam_cdbparse 3 ,
1014.Xr cam 4 ,
1015.Xr ctl 4 ,
1016.Xr xpt 4 ,
1017.Xr camcontrol 8 ,
1018.Xr ctld 8 ,
1019.Xr ctlstat 8
1020.Sh HISTORY
1021The
1022.Nm
1023utility was originally written during the Winter/Spring of 2003 as an
1024interface to CTL.
1025.Sh AUTHORS
1026.An Ken Merry Aq Mt ken@FreeBSD.org
|