xref: /freebsd/usr.sbin/ctladm/ctladm.8 (revision 9768746b)
1.\"
2.\" Copyright (c) 2003 Silicon Graphics International Corp.
3.\" Copyright (c) 2015-2021 Alexander Motin <mav@FreeBSD.org>
4.\" Copyright (c) 2018 Marcelo Araujo <araujo@FreeBSD.org>
5.\" All rights reserved.
6.\"
7.\" Redistribution and use in source and binary forms, with or without
8.\" modification, are permitted provided that the following conditions
9.\" are met:
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.
18.\"
19.\" NO WARRANTY
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.
31.\"
32.\" ctladm utility man page.
33.\"
34.\" Author: Ken Merry <ken@FreeBSD.org>
35.\"
36.\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $
37.\" $FreeBSD$
38.\"
39.Dd March 9, 2021
40.Dt CTLADM 8
41.Os
42.Sh NAME
43.Nm ctladm
44.Nd CAM Target Layer control utility
45.Sh SYNOPSIS
46.Nm
47.Aq Ar command
48.Op lun
49.Op generic args
50.Op command args
51.Nm
52.Ic tur
53.Aq lun
54.Op general options
55.Nm
56.Ic inquiry
57.Aq lun
58.Op general options
59.Nm
60.Ic reqsense
61.Aq lun
62.Op general options
63.Nm
64.Ic reportluns
65.Aq lun
66.Op general options
67.Nm
68.Ic read
69.Aq lun
70.Op general options
71.Aq Fl l Ar lba
72.Aq Fl d Ar datalen
73.Aq Fl f Ar file|-
74.Aq Fl b Ar blocksize_bytes
75.Op Fl c Ar cdbsize
76.Op Fl N
77.Nm
78.Ic write
79.Aq lun
80.Op general options
81.Aq Fl l Ar lba
82.Aq Fl d Ar datalen
83.Aq Fl f Ar file|-
84.Aq Fl b Ar blocksize_bytes
85.Op Fl c Ar cdbsize
86.Op Fl N
87.Nm
88.Ic readcap
89.Aq lun
90.Op general options
91.Op Fl c Ar cdbsize
92.Nm
93.Ic modesense
94.Aq lun
95.Aq Fl m Ar page | Fl l
96.Op Fl P Ar pc
97.Op Fl d
98.Op Fl S Ar subpage
99.Op Fl c Ar size
100.Nm
101.Ic start
102.Aq lun
103.Op general options
104.Op Fl i
105.Op Fl o
106.Nm
107.Ic stop
108.Aq lun
109.Op general options
110.Op Fl i
111.Op Fl o
112.Nm
113.Ic synccache
114.Aq lun
115.Op general options
116.Op Fl l Ar lba
117.Op Fl b Ar blockcount
118.Op Fl r
119.Op Fl i
120.Op Fl c Ar cdbsize
121.Nm
122.Ic lunlist
123.Nm
124.Ic delay
125.Aq lun
126.Aq Fl l Ar datamove|done
127.Aq Fl t Ar secs
128.Op Fl T Ar oneshot|cont
129.Nm
130.Ic inject
131.Aq Fl i Ar action
132.Aq Fl p Ar pattern
133.Op Fl r Ar lba,len
134.Op Fl s Ar len fmt Op Ar args
135.Op Fl c
136.Op Fl d Ar delete_id
137.Nm
138.Ic create
139.Aq Fl b Ar backend
140.Op Fl B Ar blocksize
141.Op Fl d Ar device_id
142.Op Fl l Ar lun_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
147.Nm
148.Ic remove
149.Aq Fl b Ar backend
150.Aq Fl l Ar lun_id
151.Op Fl o Ar name=value
152.Nm
153.Ic modify
154.Aq Fl b Ar backend
155.Aq Fl l Ar lun_id
156.Op Fl o Ar name=value
157.Aq Fl s Ar size_bytes
158.Nm
159.Ic devlist
160.Op Fl b Ar backend
161.Op Fl v
162.Op Fl x
163.Nm
164.Ic port
165.Op Fl c
166.Op Fl o Ar on|off
167.Op Fl w Ar wwpn
168.Op Fl W Ar wwnn
169.Op Fl O Ar pp|vp
170.Op Fl p Ar targ_port
171.Op Fl r Ar targ_port
172.Op Fl t Ar fe_type
173.Nm
174.Ic portlist
175.Op Fl f Ar frontend
176.Op Fl i
177.Op Fl l
178.Op Fl p Ar targ_port
179.Op Fl q
180.Op Fl v
181.Op Fl x
182.Nm
183.Ic lunmap
184.Aq Fl p Ar targ_port
185.Op Fl l Ar pLUN
186.Op Fl L Ar cLUN
187.Nm
188.Ic dumpooa
189.Nm
190.Ic dumpstructs
191.Nm
192.Ic islist
193.Op Fl v
194.Op Fl x
195.Nm
196.Ic islogout
197.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
198.Nm
199.Ic isterminate
200.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
201.Nm
202.Ic help
203.Sh DESCRIPTION
204The
205.Nm
206utility is designed to provide a way to access and control the CAM Target
207Layer (CTL).
208It provides a way to send
209.Tn SCSI
210commands to the CTL layer, and also provides
211some meta-commands that utilize
212.Tn SCSI
213commands.
214(For instance, the
215.Ic lunlist
216command is implemented using the
217.Tn SCSI
218REPORT LUNS and INQUIRY commands.)
219.Pp
220The
221.Nm
222utility has a number of primary functions, many of which require a device
223identifier.
224The device identifier takes the following form:
225.Bl -tag -width 14n
226.It lun
227Specify the LUN number to operate on.
228.El
229Many of the primary functions of the
230.Nm
231utility take the following optional arguments:
232.Bl -tag -width 10n
233.It Fl C Ar retries
234Specify the number of times to retry a command in the event of failure.
235.It Fl D Ar device
236Specify the device to open.
237This allows opening a device other than the default device,
238.Pa /dev/cam/ctl ,
239to be opened for sending commands.
240.It Fl I Ar id
241Specify the initiator number to use.
242By default,
243.Nm
244will use 7 as the initiator number.
245.El
246.Pp
247Primary commands:
248.Bl -tag -width 11n
249.It Ic tur
250Send the
251.Tn SCSI
252TEST UNIT READY command to the device and report whether or not it is
253ready.
254.It Ic inquiry
255Send the
256.Tn SCSI
257INQUIRY command to the device and display some of the returned inquiry
258data.
259.It Ic reqsense
260Send the
261.Tn SCSI
262REQUEST SENSE command to the device and display the returned sense
263information.
264.It Ic reportluns
265Send the
266.Tn SCSI
267REPORT LUNS command to the device and display supported LUNs.
268.It Ic read
269Send a
270.Tn SCSI
271READ command to the device, and write the requested data to a file or
272stdout.
273.Bl -tag -width 12n
274.It Fl l Ar lba
275Specify the starting Logical Block Address for the READ.
276This can be specified in decimal, octal (starting with 0),
277hexadecimal (starting with 0x) or any other base supported by
278.Xr strtoull 3 .
279.It Fl d Ar datalen
280Specify the length, in 512 byte blocks, of the READ request.
281.It Fl f Ar file
282Specify the destination for the data read by the READ command.
283Either a filename or
284.Sq -
285for stdout may be specified.
286.It Fl c Ar cdbsize
287Specify the minimum
288.Tn SCSI
289CDB (Command Data Block) size to be used for the READ request.
290Allowable values are 6, 10, 12 and 16.
291Depending upon the LBA and amount of data requested, a larger CDB
292size may be used to satisfy the request.  (e.g., for LBAs above 0xffffffff,
293READ(16) must be used to satisfy the request.)
294.It Fl b Ar blocksize
295Specify the blocksize of the underlying
296.Tn SCSI
297device, so the transfer length
298can be calculated accurately.
299The blocksize can be obtained via the
300.Tn SCSI
301READ CAPACITY command.
302.It Fl N
303Do not copy data to
304.Nm
305from the kernel when doing a read, just execute the command without copying
306data.
307This is to be used for performance testing.
308.El
309.It Ic write
310Read data from a file or stdin, and write the data to the device using the
311.Tn SCSI
312WRITE command.
313.Bl -tag -width 12n
314.It Fl l Ar lba
315Specify the starting Logical Block Address for the WRITE.
316This can be specified in decimal, octal (starting with 0), hexadecimal
317(starting with 0x) or any other base supported by
318.Xr strtoull 3 .
319.It Fl d Ar atalen
320Specify the length, in 512 byte blocks, of the WRITE request.
321.It Fl f Ar file
322Specify the source for the data to be written by the WRITE command.
323Either a filename or
324.Sq -
325for stdin may be specified.
326.It Fl c Ar cdbsize
327Specify the minimum
328.Tn SCSI
329CDB (Command Data Block) size to be used for the READ request.
330Allowable values are 6, 10, 12 and 16.
331Depending upon the LBA and amount of data requested, a larger CDB size
332may be used to satisfy the request.  (e.g., for LBAs above 0xffffffff, READ(16)
333must be used to satisfy the request.)
334.It Fl b Ar blocksize
335Specify the blocksize of the underlying
336.Tn SCSI
337device, so the transfer length
338can be calculated accurately.
339The blocksize can be obtained via the
340.Tn SCSI
341READ CAPACITY command.
342.It Fl N
343Do not copy data to
344.Nm
345to the kernel when doing a write, just execute the command without copying
346data.
347This is to be used for performance testing.
348.El
349.It Ic readcap
350Send the
351.Tn SCSI
352READ CAPACITY command to the device and display the device size and device
353block size.
354By default, READ CAPACITY(10) is used.
355If the device returns a maximum LBA of 0xffffffff, however,
356.Nm
357will automatically issue a READ CAPACITY(16), which is implemented as a
358service action of the SERVICE ACTION IN(16) opcode.
359The user can specify the minimum CDB size with the
360.Fl c
361argument.
362Valid values for the
363.Fl c
364option are 10 and 16.
365If a 10 byte CDB is specified, the request will be automatically reissued
366with a 16 byte CDB if the maximum LBA returned is 0xffffffff.
367.It Ic modesense
368Send a
369.Tn SCSI
370MODE SENSE command to the device, and display the requested mode page(s) or
371page list.
372.Bl -tag -width 10n
373.It Fl m Ar page
374Specify the mode page to display.
375This option and the
376.Fl l
377option are mutually exclusive.
378One of the two must be specified, though.
379Mode page numbers may be specified in decimal or hexadecimal.
380.It Fl l
381Request that the list of mode pages supported by the device be returned.
382This option and the
383.Fl m
384option are mutually exclusive.
385One of the two must be specified, though.
386.It Fl P Ar pc
387Specify the mode page control value.
388Possible values are:
389.Bl -tag -width 2n -compact
390.It 0
391Current values.
392.It 1
393Changeable value bitmask.
394.It 2
395Default values.
396.It 3
397Saved values.
398.El
399.It Fl d
400Disable block descriptors when sending the mode sense request.
401.It Fl S Ar subpage
402Specify the subpage used with the mode sense request.
403.It Fl c Ar cdbsize
404Specify the CDB size used for the mode sense request.
405Supported values are 6 and 10.
406.El
407.It Ic start
408Send the
409.Tn SCSI
410START STOP UNIT command to the specified LUN with the start
411bit set.
412.Bl -tag -width 4n
413.It Fl i
414Set the immediate bit in the CDB.
415Note that CTL does not support the immediate bit, so this is primarily
416useful for making sure that CTL returns the proper error.
417.El
418.It Ic stop
419Send the
420.Tn SCSI
421START STOP UNIT command to the specified LUN with the start
422bit cleared.
423We use an ordered tag to stop the LUN, so we can guarantee that all pending
424I/O executes before it is stopped.
425(CTL guarantees this anyway, but
426.Nm
427sends an ordered tag for completeness.)
428.Bl -tag -width 4n
429.It Fl i
430Set the immediate bit in the CDB.
431Note that CTL does not support the immediate bit, so this is primarily
432useful for making sure that CTL returns the proper error.
433.El
434.It Ic synccache
435Send the
436.Tn SCSI
437SYNCHRONIZE CACHE command to the device.
438By default, SYNCHRONIZE CACHE(10) is used.
439If the specified starting LBA is greater than 0xffffffff or the length is
440greater than 0xffff, though, SYNCHRONIZE CACHE(16) will be used.
441The 16 byte command will also be used if the user specifies a 16 byte CDB with the
442.Fl c
443argument.
444.Bl -tag -width 14n
445.It Fl l Ar lba
446Specify the starting LBA of the cache region to synchronize.
447This option is a no-op for CTL.
448If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN.
449.It Fl b Ar blockcount
450Specify the length of the cache region to synchronize.
451This option is a no-op for CTL.
452If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN.
453.It Fl r
454Specify relative addressing for the starting LBA.
455CTL does not support relative addressing, since it only works for linked commands,
456and CTL does not support linked commands.
457.It Fl i
458Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE
459command rather than waiting for the cache to finish syncing.
460CTL does not support this bit.
461.It Fl c Ar cdbsize
462Specify the minimum CDB size.
463Valid values are 10 and 16 bytes.
464.El
465.It Ic lunlist
466List all LUNs registered with CTL.
467Because this command uses the ioctl port, it will only work when the FETDs
468(Front End Target Drivers) are enabled.
469This command is the equivalent of doing a REPORT LUNS on one LUN and then
470an INQUIRY on each LUN in the system.
471.It Ic delay
472Delay commands at the given location.
473There are two places where commands may be delayed currently: before data is transferred
474.Pq Dq datamove
475and just prior to sending status to the host
476.Pq Dq done .
477One of the two must be supplied as an argument to the
478.Fl l
479option.
480The
481.Fl t
482option must also be specified.
483.Bl -tag -width 12n
484.It Fl l Ar delayloc
485Delay command(s) at the specified location.
486This can either be at the data movement stage (datamove) or prior to
487command completion (done).
488.It Fl t Ar delaytime
489Delay command(s) for the specified number of seconds.
490This must be specified.
491If set to 0, it will clear out any previously set delay for this particular
492location (datamove or done).
493.It Fl T Ar delaytype
494Specify the delay type.
495By default, the
496.Ic delay
497option will delay the next command sent to the given LUN.
498With the
499.Fl T Ar cont
500option, every command will be delayed by the specified period of time.
501With the
502.Fl T Ar oneshot
503the next command sent to the given LUN will be delayed and all subsequent
504commands will be completed normally.
505This is the default.
506.El
507.It Ic inject
508Inject the specified type of error for the LUN specified, when a command
509that matches the given pattern is seen.
510The sense data returned is in either fixed or descriptor format, depending
511upon the status of the D_SENSE bit in the control mode page (page 0xa) for
512the LUN.
513.Pp
514Errors are only injected for commands that have not already failed for
515other reasons.
516By default, only the first command matching the pattern specified is
517returned with the supplied error.
518.Pp
519If the
520.Fl c
521flag is specified, all commands matching the pattern will be returned with
522the specified error until the error injection command is deleted with
523.Fl d
524flag.
525.Bl -tag -width 17n
526.It Fl i Ar action
527Specify the error to return:
528.Bl -tag -width 10n
529.It aborted
530Return the next matching command on the specified LUN with the sense key
531ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
532failure").
533.It mediumerr
534Return the next matching command on the specified LUN with the sense key
535MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
536reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
537for write errors.
538.It ua
539Return the next matching command on the specified LUN with the sense key
540UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
541DEVICE RESET OCCURRED").
542.It custom
543Return the next matching command on the specified LUN with the supplied
544sense data.
545The
546.Fl s
547argument must be specified.
548.El
549.It Fl p Ar pattern
550Specify which commands should be returned with the given error.
551.Bl -tag -width 10n
552.It read
553The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
554.It write
555The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
556AND VERIFY(10), etc.
557.It rw
558The error should apply to both read and write type commands.
559.It readcap
560The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
561.It tur
562The error should apply to TEST UNIT READY commands.
563.It any
564The error should apply to any command.
565.El
566.It Fl r Ar lba,len
567Specify the starting lba and length of the range of LBAs which should
568trigger an error.
569This option is only applies when read and/or write patterns are specified.
570If used with other command types, the error will never be triggered.
571.It Fl s Ar len fmt Op Ar args
572Specify the sense data that is to be returned for custom actions.
573If the format is
574.Sq - ,
575len bytes of sense data will be read from standard input and written to the
576sense buffer.
577If len is longer than 252 bytes (the maximum allowable
578.Tn SCSI
579sense data length), it will be truncated to that length.
580The sense data format is described in
581.Xr cam_cdbparse 3 .
582.It Fl c
583The error injection should be persistent, instead of happening once.
584Persistent errors must be deleted with the
585.Fl d
586argument.
587.It Fl d Ar delete_id
588Delete the specified error injection serial number.
589The serial number is returned when the error is injected.
590.El
591.It Ic port
592Perform one of several CTL frontend port operations.
593Either get a list of frontend ports
594.Pq Fl l ,
595turn one or more frontends on
596or off
597.Pq Fl o Ar on|off ,
598or set the World Wide Node Name
599.Pq Fl w Ar wwnn
600or World Wide Port Name
601.Pq Fl W Ar wwpn
602for a given port.
603One of
604.Fl l ,
605.Fl o ,
606or
607.Fl w
608or
609.Fl W
610must be specified.
611The WWNN and WWPN may both be specified at the same time, but cannot be
612combined with enabling/disabling or listing ports.
613.Bl -tag -width 12n
614.It Fl c
615Create new frontend port using free pp and vp=0.
616.It Fl o Ar on|off
617Turn the specified CTL frontend ports on or off.
618If no port number or port type is specified, all ports are turned on or
619off.
620.It Fl O Ar pp|vp
621Specify generic options on the ioctl frontend port.
622At present, only pp and vp port numbers can be set.
623.It Fl p Ar targ_port
624Specify the frontend port number.
625The port numbers can be found in the frontend port list.
626.It Fl r
627Remove port specified with
628.Pq Fl p Ar targ_port .
629.It Fl t Ar fe_type
630Specify the frontend type.
631Currently defined port types are
632.Dq fc
633(Fibre Channel),
634.Dq scsi
635(Parallel SCSI),
636.Dq ioctl
637(CTL ioctl interface),
638and
639.Dq internal
640(CTL CAM SIM).
641.It Fl w Ar wwnn
642Set the World Wide Node Name for the given port.
643The
644.Fl n
645argument must be specified, since this is only possible to implement on a
646single port.
647As a general rule, the WWNN should be the same across all ports on the
648system.
649.It Fl W Ar wwpn
650Set the World Wide Port Name for the given port.
651The
652.Fl n
653argument must be specified, since this is only possible to implement on a
654single port.
655As a general rule, the WWPN must be different for every port in the system.
656.El
657.It Ic portlist
658List CTL frontend ports.
659.Bl -tag -width 12n
660.It Fl f Ar frontend
661Specify the frontend type.
662.It Fl i
663Report target and connected initiators addresses.
664.It Fl l
665Report LUN mapping.
666.It Fl p Ar targ_port
667Specify the frontend port number.
668.It Fl q
669Omit the header in the port list output.
670.It Fl v
671Enable verbose output (report all port options).
672.It Fl x
673Output the port list in XML format.
674.El
675.It Ic lunmap
676Change LUN mapping for specified port.
677If both
678.Ar pLUN
679and
680.Ar cLUN
681are specified -- LUN will be mapped.
682If
683.Ar pLUN
684is specified, but
685.Ar cLUN
686is not -- LUN will be unmapped.
687If neither
688.Ar pLUN
689nor
690.Ar cLUN
691are specified -- LUN mapping will be disabled, exposing all CTL LUNs.
692.Bl -tag -width 12n
693.It Fl p Ar targ_port
694Specify the frontend port number.
695.It Fl l Ar pLUN
696LUN number visible by specified port.
697.It Fl L Ar cLUN
698CTL LUN number.
699.El
700.It Ic dumpooa
701Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
702.It Ic dumpstructs
703Dump the CTL structures to the console.
704.It Ic create
705Create a new LUN.
706The backend must be specified, and depending upon the backend requested,
707some of the other options may be required.
708If the LUN is created successfully, the LUN configuration will be
709displayed.
710If LUN creation fails, a message will be displayed describing the failure.
711.Bl -tag -width 14n
712.It Fl b Ar backend
713The
714.Fl b
715flag is required.
716This specifies the name backend to use when creating the LUN.
717Examples are
718.Dq ramdisk
719and
720.Dq block .
721.It Fl B Ar blocksize
722Specify the blocksize of the backend in bytes.
723.It Fl d Ar device_id
724Specify the LUN-associated string to use in the
725.Tn SCSI
726INQUIRY VPD page 0x83 data.
727.It Fl l Ar lun_id
728Request that a particular LUN number be assigned.
729If the requested LUN number is not available, the request will fail.
730.It Fl o Ar name=value
731Specify a backend-specific name/value pair.
732Multiple
733.Fl o
734arguments may be specified.
735Refer to the backend documentation for arguments that may be used.
736.It Fl s Ar size_bytes
737Specify the size of the LUN in bytes.
738Some backends may allow setting the size (e.g. the ramdisk backend) and for
739others the size may be implicit (e.g. the block backend).
740.It Fl S Ar serial_num
741Specify the serial number to be used in the
742.Tn SCSI
743INQUIRY VPD page 0x80 data.
744.It Fl t Ar device_type
745Specify the numeric SCSI device type to use when creating the LUN.
746If this flag is not used, the type of LUN created is backend-specific.
747Not all LUN types are supported.
748Currently CTL supports Direct Access (type 0), Processor (type 3)
749and CD/DVD (type 5) LUNs.
750The backend requested may or may not support all of the LUN types that CTL
751supports.
752.El
753.It Ic remove
754Remove a LUN.
755The backend must be specified, and the LUN number must also be specified.
756Backend-specific options may also be specified with the
757.Fl o
758flag.
759.Bl -tag -width 14n
760.It Fl b Ar backend
761Specify the backend that owns the LUN to be removed.
762Examples are
763.Dq ramdisk
764and
765.Dq block .
766.It Fl l Ar lun_id
767Specify the LUN number to remove.
768.It Fl o Ar name=value
769Specify a backend-specific name/value pair.
770Multiple
771.Fl o
772arguments may be specified.
773Refer to the backend documentation for arguments that may be used.
774.El
775.It Ic modify
776Modify a LUN size.
777The backend, the LUN number, and the size must be specified.
778.Bl -tag -width 14n
779.It Fl b Ar backend
780Specify the backend that owns the LUN to be modified.
781Examples are
782.Dq ramdisk
783and
784.Dq block .
785.It Fl l Ar lun_id
786Specify the LUN number to modify.
787.It Fl o Ar name=value
788Specify a backend-specific name/value pair.
789Multiple
790.Fl o
791arguments may be specified.
792Refer to the backend documentation for arguments that may be used.
793.It Fl s Ar size_bytes
794Specify the size of the LUN in bytes.
795For the
796.Dq block
797backend, an
798.Dq auto
799keyword may be passed instead; this will make CTL use the size of backing
800file or device.
801.El
802.It Ic devlist
803Get a list of all configured LUNs.
804This also includes the LUN size and blocksize, serial number and device ID.
805.Bl -tag -width 11n
806.It Fl b Ar backend
807Specify the backend.
808This restricts the LUN list to the named backend.
809Examples are
810.Dq ramdisk
811and
812.Dq block .
813.It Fl v
814Be verbose.
815This will also display any backend-specific LUN attributes in addition to
816the standard per-LUN information.
817.It Fl x
818Dump the raw XML.
819The LUN list information from the kernel comes in XML format, and this
820option allows the display of the raw XML data.
821This option and the
822.Fl v
823and
824.Fl b
825options are mutually exclusive.
826If you specify
827.Fl x ,
828the entire LUN database is displayed in XML format.
829.El
830.It Ic islist
831Get a list of currently running iSCSI sessions.
832This includes initiator and target names and the unique connection IDs.
833.Bl -tag -width 11n
834.It Fl v
835Verbose mode.
836.It Fl x
837Dump the raw XML.
838The sessions list information from the kernel comes in XML format, and this
839option allows the display of the raw XML data.
840.El
841.It Ic islogout
842Ask the initiator to log out iSCSI sessions matching criteria.
843.Bl -tag -width 11n
844.It Fl a
845Log out all sessions.
846.It Fl c
847Specify connection ID.
848.It Fl i
849Specify initiator name.
850.It Fl p
851Specify initiator portal (hostname or IP address).
852.El
853.It Ic isterminate
854Forcibly terminate iSCSI sessions matching criteria.
855.Bl -tag -width 11n
856.It Fl a
857Terminate all sessions.
858.It Fl c
859Specify connection ID.
860.It Fl i
861Specify initiator name.
862.It Fl p
863Specify initiator portal (hostname or IP address).
864.El
865.It Ic help
866Display
867.Nm
868usage information.
869.El
870.Sh OPTIONS
871Number of additional configuration options may be specified for LUNs.
872Some options are global, others are backend-specific.
873.Pp
874Global options:
875.Bl -tag -width 12n
876.It Va vendor
877Specifies LUN vendor string up to 8 chars.
878.It Va product
879Specifies LUN product string up to 16 chars.
880.It Va revision
881Specifies LUN revision string up to 4 chars.
882.It Va scsiname
883Specifies LUN SCSI name string.
884.It Va eui
885Specifies LUN EUI-64 identifier.
886.It Va naa
887Specifies LUN NAA identifier.
888.It Va uuid
889Specifies LUN locally assigned RFC 4122 UUID identifier.
890EUI, NAA or UUID identifier should be set to UNIQUE value to allow
891EXTENDED COPY command access the LUN.
892Non-unique LUN identifiers may lead to data corruption.
893Some initiators may not support later introduced UUID identifiers.
894.It Va ident_info
895Specified LUN identification information (string or 0x + hex).
896.It Va text_ident_info
897Specified LUN text identification information (UTF-8 string).
898.It Va ha_role
899Setting to "primary" or "secondary" overrides default role of the node
900in HA cluster, set by kern.cam.ctl.ha_role sysctl.
901.It Va insecure_tpc
902Setting to "on" allows EXTENDED COPY command sent to this LUN access
903other LUNs on this host, not accessible otherwise.
904This allows to offload copying between different iSCSI targets residing
905on the same host in trusted environments.
906.It Va readcache
907Set to "off", disables read caching for the LUN, if supported by the backend.
908.It Va readonly
909Set to "on", blocks all media write operations to the LUN, reporting it
910as write protected.
911.It Va removable
912Set to "on", makes LUN removable.
913.It Va reordering
914Set to "unrestricted", allows target to process commands with SIMPLE task
915attribute in arbitrary order.
916Any data integrity exposures related to command sequence order shall be
917explicitly handled by the application client through the selection of
918appropriate commands and task attributes.
919The default value is "restricted".
920It improves data integrity, but may introduce some additional delays.
921.It Va serseq
922Set to "on" to fully serialize consecutive reads/writes.
923Set to "read" to fully serialize consecutive reads.
924Set to "soft" to slightly serialize consecutive reads.
925Set to "off" to allow them be issued in parallel.
926Parallel issue of consecutive operations may confuse logic of the
927backing file system, hurting performance; but it may improve performance
928of backing stores without prefetch/write-back.
929.It Va pblocksize
930.It Va pblockoffset
931Specify physical block size and offset of the device.
932.It Va ublocksize
933.It Va ublockoffset
934Specify UNMAP block size and offset of the device.
935.It Va rpm
936Specifies medium rotation rate of the device: 0 -- not reported,
9371 -- non-rotating (SSD), >1024 -- value in revolutions per minute.
938.It Va formfactor
939Specifies nominal form factor of the device: 0 -- not reported, 1 -- 5.25",
9402 -- 3.5", 3 -- 2.5", 4 -- 1.8", 5 -- less then 1.8".
941.It Va temperature
942.It Va reftemperature
943Specify current and reference (maximum) temperatures of the device.
944.It Va provisioning_type
945When UNMAP support is enabled, this option specifies provisioning type:
946"resource", "thin" or "unknown".
947Default value is "thin".
948Logical units without UNMAP support are reported as fully provisioned.
949.It Va unmap
950Setting to "on" or "off" controls UNMAP support for the logical unit.
951Default value is "on" if supported by the backend.
952.It Va unmap_max_lba
953.It Va unmap_max_descr
954Specify maximum allowed number of LBAs and block descriptors per UNMAP
955command to report in Block Limits VPD page.
956.It Va write_same_max_lba
957Specify maximum allowed number of LBAs per WRITE SAME command to report
958in Block Limits VPD page.
959.It Va avail-threshold
960.It Va used-threshold
961.It Va pool-avail-threshold
962.It Va pool-used-threshold
963Set per-LUN/-pool thin provisioning soft thresholds.
964LUN will establish UNIT ATTENTION condition if its or pool available space
965get below configured avail values, or its or pool used space get above
966configured used values.
967Pool thresholds are working only for ZVOL-backed LUNs.
968.It Va writecache
969Set to "off", disables write caching for the LUN, if supported by the backend.
970.El
971.Pp
972Options specific for block backend:
973.Bl -tag -width 12n
974.It Va file
975Specifies file or device name to use for backing store.
976.It Va num_threads
977Specifies number of backend threads to use for this LUN.
978.El
979.Pp
980Options specific for ramdisk backend:
981.Bl -tag -width 12n
982.It Va capacity
983Specifies capacity of backing store (maximum RAM for data).
984The default value is zero, that disables backing store completely,
985making all writes go to nowhere, while all reads return zeroes.
986.El
987.Sh EXAMPLES
988.Pp
989Send a
990.Tn SCSI
991TEST UNIT READY command to LUN 1.
992.Pp
993.Dl ctladm tur 1
994.Pp
995Display the list of mode pages supported by LUN 1.
996.Pp
997.Dl ctladm modesense 1 -l
998.Pp
999Display the saved version of the Control mode page (page 10) on LUN 0.
1000Disable fetching block descriptors, and use a 10 byte MODE SENSE command
1001instead of the default 6 byte command.
1002.Pp
1003.Dl ctladm modesense 0 -m 10 -P 3 -d -c 10
1004.Pp
1005Read the first 512 byte block from LUN 2 and dump it to the file
1006.Bd -literal
1007.Dl ctladm read 2 -l 0 -d 1 -b 512 -f - > foo
1008.Ed
1009.Pp
1010Read 10240 bytes from the file
1011.Pa /tmp/bar
1012and write it to LUN 3.
1013starting at LBA 0xff432140.
1014.Pp
1015.Bd -literal
1016.Dl ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
1017.Ed
1018.Pp
1019Create a LUN with the
1020.Dq fake
1021ramdisk as a backing store.
1022The LUN will claim to have a size of approximately 10 terabytes,
1023while having no real data store (all written data are lost).
1024.Pp
1025.Dl ctladm create -b ramdisk -s 10485760000000000
1026.Pp
1027Create a thin provisioned LUN with a ramdisk as a backing store.
1028The LUN will have maximal backing store capacity of 10 gigabytes,
1029while reporting size of 10 terabytes,
1030.Pp
1031.Dl ctladm create -b ramdisk -s 10T -o capacity=10G
1032.Pp
1033Create a LUN using the block backend, specify the ZFS volume
1034.Pa tank/example
1035as the backing store, and specify the
1036.Tn SCSI
1037VPD page 0x80 and 0x83 serial number
1038.Fl ( S )
1039and device ID
1040.Fl ( d ) .
1041The size of the LUN will be derived from the size of the ZVOL.
1042.Pp
1043.Dl ctladm create -b block -o file=/dev/zvol/tank/example -S MYSERIAL321 -d MYDEVID123
1044.Pp
1045Use to specify generic options on ioctl frontend port, now it is
1046only possible to set pp and/or vp port number.
1047.Pp
1048.Dl ctladm port -c -O pp=11 -O vp=12
1049.Pp
1050Remove specified targ_port.
1051.Pp
1052.Dl ctladm port -r -p 4
1053.Pp
1054.Pp
1055Remove LUN 12, which is handled by the block backend, from the system.
1056.Pp
1057.Dl ctladm remove -b block -l 12
1058.Pp
1059List configured LUNs in the system, along with their backend and serial
1060number.
1061This works when the Front End Target Drivers are enabled or disabled.
1062.Pp
1063.Dl ctladm devlist
1064.Pp
1065List all LUNs in the system, along with their inquiry data and device type.
1066This only works when the FETDs are enabled, since the commands go through the
1067ioctl port.
1068.Pp
1069.Dl ctladm lunlist
1070.Pp
1071Inject a medium error on LUN 6 for every read that covers the first 512
1072blocks of the LUN.
1073.Pp
1074.Dl ctladm inject 6 -i mediumerr -p read -r 0,512 -c
1075.Pp
1076Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
1077This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
10780x04,0x02 ("Logical unit not ready, initializing command required").
1079.Pp
1080.Bd -literal -offset indent
1081ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
1082.Ed
1083.Sh SEE ALSO
1084.Xr cam 3 ,
1085.Xr cam_cdbparse 3 ,
1086.Xr cam 4 ,
1087.Xr ctl 4 ,
1088.Xr xpt 4 ,
1089.Xr camcontrol 8 ,
1090.Xr ctld 8 ,
1091.Xr ctlstat 8
1092.Sh HISTORY
1093The
1094.Nm
1095utility was originally written during the Winter/Spring of 2003 as an
1096interface to CTL.
1097.Sh AUTHORS
1098.An Ken Merry Aq Mt ken@FreeBSD.org
1099