summaryrefslogtreecommitdiffstats
path: root/usr.sbin/ctladm/ctladm.8
blob: d4d044f6c8b287d56389656d7752b62e34456336 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
.\" 
.\" Copyright (c) 2003 Silicon Graphics International Corp.
.\" All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions, and the following disclaimer,
.\"    without modification.
.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer
.\"    substantially similar to the "NO WARRANTY" disclaimer below
.\"    ("Disclaimer") and any redistribution must be conditioned upon
.\"    including a substantially similar Disclaimer requirement for further
.\"    binary redistribution.
.\" 
.\" NO WARRANTY
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR
.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING
.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGES.
.\" 
.\" ctladm utility man page.
.\"
.\" Author: Ken Merry <ken@FreeBSD.org>
.\"
.\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $
.\" $FreeBSD$
.\"
.Dd March 6, 2012
.Dt CTLADM 8
.Os
.Sh NAME
.Nm ctladm
.Nd CAM Target Layer control utility
.Sh SYNOPSIS
.Nm
.Aq Ar command
.Op target:lun
.Op generic args
.Op command args
.Nm
.Ic tur
.Aq target:lun
.Op general options
.Nm
.Ic inquiry
.Aq target:lun
.Op general options
.Nm
.Ic reqsense
.Aq target:lun
.Op general options
.Nm
.Ic reportluns
.Aq target:lun
.Op general options
.Nm
.Ic read
.Aq target:lun
.Op general options
.Aq Fl l Ar lba
.Aq Fl d Ar datalen
.Aq Fl f Ar file|-
.Aq Fl b Ar blocksize_bytes
.Op Fl c Ar cdbsize
.Op Fl N
.Nm
.Ic write
.Aq target:lun
.Op general options
.Aq Fl l Ar lba
.Aq Fl d Ar datalen
.Aq Fl f Ar file|-
.Aq Fl b Ar blocksize_bytes
.Op Fl c Ar cdbsize
.Op Fl N
.Nm
.Ic bbrread
.Aq target:lun
.Op general options
.Aq Fl -l Ar lba
.Aq Fl -d Ar datalen
.Nm
.Ic readcap
.Aq target:lun
.Op general options
.Op Fl c Ar cdbsize
.Nm
.Ic modesense
.Aq target:lun
.Aq Fl m Ar page | Fl l
.Op Fl P Ar pc
.Op Fl d
.Op Fl S Ar subpage
.Op Fl c Ar size
.Nm
.Ic start
.Aq target:lun
.Op general options
.Op Fl i
.Op Fl o
.Nm
.Ic stop
.Aq target:lun
.Op general options
.Op Fl i
.Op Fl o
.Nm
.Ic synccache
.Aq target:lun
.Op general options
.Op Fl l Ar lba
.Op Fl b Ar blockcount
.Op Fl r
.Op Fl i
.Op Fl c Ar cdbsize
.Nm
.Ic shutdown
.Op general options
.Nm
.Ic startup
.Op general options
.Nm
.Ic hardstop
.Nm
.Ic hardstart
.Nm
.Ic lunlist
.Nm
.Ic delay
.Aq target:lun
.Aq Fl l Ar datamove|done
.Aq Fl t Ar secs
.Op Fl T Ar oneshot|cont
.Nm
.Ic realsync Aq on|off|query
.Nm
.Ic setsync interval
.Aq target:lun
.Aq Fl i Ar interval
.Nm
.Ic getsync
.Aq target:lun
.Nm
.Ic inject
.Aq Fl i Ar action
.Aq Fl p Ar pattern
.Op Fl r Ar lba,len
.Op Fl s Ar len fmt Op Ar args
.Op Fl c
.Op Fl d Ar delete_id
.Nm
.Ic create
.Aq Fl b Ar backend
.Op Fl B Ar blocksize
.Op Fl d Ar device_id
.Op Fl l Ar lun_id
.Op Fl o Ar name=value
.Op Fl s Ar size_bytes
.Op Fl S Ar serial_num
.Op Fl t Ar device_type
.Nm
.Ic remove
.Aq Fl b Ar backend
.Aq Fl l Ar lun_id
.Op Fl o Ar name=value
.Nm
.Ic modify
.Aq Fl b Ar backend
.Aq Fl l Ar lun_id
.Aq Fl s Ar size_bytes
.Nm
.Ic devlist
.Op Fl b Ar backend
.Op Fl v
.Op Fl x
.Nm
.Ic port
.Op Fl l
.Op Fl o Ar on|off
.Op Fl w Ar wwpn
.Op Fl W Ar wwnn
.Op Fl p Ar targ_port
.Op Fl t Ar fe_type
.Op Fl q
.Op Fl x
.Nm
.Ic dumpooa
.Nm
.Ic dumpstructs
.Nm
.Ic help
.Sh DESCRIPTION
The
.Nm
utility is designed to provide a way to access and control the CAM Target
Layer (CTL).
It provides a way to send
.Tn SCSI
commands to the CTL layer, and also provides
some meta-commands that utilize
.Tn SCSI
commands.
(For instance, the
.Ic lunlist
command is implemented using the
.Tn SCSI
REPORT LUNS and INQUIRY commands.)
.Pp
The
.Nm
utility has a number of primary functions, many of which require a device
identifier.
The device identifier takes the following form:
.Bl -tag -width 14n
.It target:lun
Specify the target (almost always 0) and LUN number to operate on.
.El
Many of the primary functions of the
.Nm
utility take the following optional arguments:
.Bl -tag -width 10n
.It Fl C Ar retries
Specify the number of times to retry a command in the event of failure.
.It Fl D Ar device
Specify the device to open.  This allows opening a device other than the
default device,
.Pa /dev/cam/ctl ,
to be opened for sending commands.
.It Fl I Ar id
Specify the initiator number to use.
By default,
.Nm
will use 7 as the initiator number.
.El
.Pp
Primary commands:
.Bl -tag -width 11n
.It Ic tur
Send the
.Tn SCSI
TEST UNIT READY command to the device and report whether or not it is
ready.
.It Ic inquiry
Send the
.Tn SCSI
INQUIRY command to the device and display some of the returned inquiry
data.
.It Ic reqsense
Send the
.Tn SCSI
REQUEST SENSE command to the device and display the returned sense
information.
.It Ic reportluns
Send the
.Tn SCSI
REPORT LUNS command to the device and display supported LUNs.
.It Ic read
Send a
.Tn SCSI
READ command to the device, and write the requested data to a file or
stdout.
.Bl -tag -width 12n
.It Fl l Ar lba
Specify the starting Logical Block Address for the READ.  This can be
specified in decimal, octal (starting with 0), hexadecimal (starting with
0x) or any other base supported by
.Xr strtoull 3 .
.It Fl d Ar datalen
Specify the length, in 512 byte blocks, of the READ request.
.It Fl f Ar file
Specify the destination for the data read by the READ command.  Either a
filename or
.Sq -
for stdout may be specified.
.It Fl c Ar cdbsize
Specify the minimum
.Tn SCSI
CDB (Command Data Block) size to be used for the READ request.  Allowable
values are 6, 10, 12 and 16.  Depending upon the LBA and amount of data
requested, a larger CDB size may be used to satisfy the request.  (e.g.,
for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
.It Fl b Ar blocksize
Specify the blocksize of the underlying
.Tn SCSI
device, so the transfer length
can be calculated accurately.  The blocksize can be obtained via the
.Tn SCSI
READ CAPACITY command.
.It Fl N 
Do not copy data to
.Nm
from the kernel when doing a read, just execute the command without copying
data.
This is to be used for performance testing.
.El
.It Ic write
Read data from a file or stdin, and write the data to the device using the
.Tn SCSI
WRITE command.
.Bl -tag -width 12n
.It Fl l Ar lba
Specify the starting Logical Block Address for the WRITE.  This can be
specified in decimal, octal (starting with 0), hexadecimal (starting with
0x) or any other base supported by
.Xr strtoull 3 .
.It Fl d Ar atalen
Specify the length, in 512 byte blocks, of the WRITE request.
.It Fl f Ar file
Specify the source for the data to be written by the WRITE command.  Either a
filename or
.Sq -
for stdin may be specified.
.It Fl c Ar cdbsize
Specify the minimum
.Tn SCSI
CDB (Command Data Block) size to be used for the READ request.  Allowable
values are 6, 10, 12 and 16.  Depending upon the LBA and amount of data
requested, a larger CDB size may be used to satisfy the request.  (e.g.,
for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.)
.It Fl b Ar blocksize
Specify the blocksize of the underlying
.Tn SCSI
device, so the transfer length
can be calculated accurately.  The blocksize can be obtained via the
.Tn SCSI
READ CAPACITY command.
.It Fl N
Do not copy data to
.Nm
to the kernel when doing a write, just execute the command without copying
data.
This is to be used for performance testing.
.El
.It Ic bbrread
Issue a SCSI READ command to the logical device to potentially force a bad
block on a disk in the RAID set to be reconstructed from the other disks in
the array.  This command should only be used on an array that is in the
normal state.  If used on a critical array, it could cause the array to go
offline if the bad block to be remapped is on one of the disks that is
still active in the array.
.Pp
The data for this particular command will be discarded, and not returned to
the user.
.Pp
In order to determine which LUN to read from, the user should first
determine which LUN the disk with a bad block belongs to.  Then he should
map the bad disk block back to the logical block address for the array in
order to determine which LBA to pass in to the
.Ic bbrread
command.
.Pp
This command is primarily intended for testing.  In practice, bad block
remapping will generally be triggered by the in-kernel Disk Aerobics and
Disk Scrubbing code.
.Bl -tag -width 10n
.It Fl l Ar lba
Specify the starting Logical Block Address.
.It Fl d Ar datalen
Specify the amount of data in bytes to read from the LUN.  This must be a
multiple of the LUN blocksize.
.El
.It Ic readcap
Send the
.Tn SCSI
READ CAPACITY command to the device and display the device size and device
block size.  By default, READ CAPACITY(10) is
used.  If the device returns a maximum LBA of 0xffffffff, however,
.Nm
will automatically issue a READ CAPACITY(16), which is implemented as a
service action of the SERVICE ACTION IN(16) opcode.  The user can specify
the minimum CDB size with the
.Fl c
argument.  Valid values for the
.Fl c
option are 10 and 16.  If a 10 byte CDB is specified, the request will be
automatically reissued with a 16 byte CDB if the maximum LBA returned is
0xffffffff.
.It Ic modesense
Send a
.Tn SCSI
MODE SENSE command to the device, and display the requested mode page(s) or
page list.
.Bl -tag -width 10n
.It Fl m Ar page
Specify the mode page to display.  This option and the
.Fl l
option are mutually exclusive.  One of the two must be specified, though.
Mode page numbers may be specified in decimal or hexadecimal.
.It Fl l
Request that the list of mode pages supported by the device be returned.
This option and the
.Fl m
option are mutually exclusive.  One of the two must be specified, though.
.It Fl P Ar pc
Specify the mode page page control value.  Possible values are:
.Bl -tag -width 2n -compact
.It 0
Current values.
.It 1
Changeable value bitmask.
.It 2
Default values.
.It 3
Saved values.
.El
.It Fl d
Disable block descriptors when sending the mode sense request.
.It Fl S Ar subpage
Specify the subpage used with the mode sense request.
.It Fl c Ar cdbsize
Specify the CDB size used for the mode sense request.  Supported values are
6 and 10.
.El
.It Ic start
Send the
.Tn SCSI
START STOP UNIT command to the specified LUN with the start
bit set.
.Bl -tag -width 4n
.It Fl i
Set the immediate bit in the CDB.  Note that CTL does not support the
immediate bit, so this is primarily useful for making sure that CTL returns
the proper error.
.It Fl o
Set the Copan proprietary on/offline bit in the CDB.  When this flag is
used, the LUN will be marked online again (see the description of the
.Ic shutdown
and
.Ic startup
commands).  When this flag is used with a
start command, the LUN will NOT be spun up.  You need to use a start
command without the
.Fl o
flag to spin up the disks in the LUN.
.El
.It Ic stop
Send the
.Tn SCSI
START STOP UNIT command to the specified LUN with the start
bit cleared.  We use an ordered tag to stop the LUN, so we can guarantee
that all pending I/O executes before it is stopped.  (CTL guarantees this
anyway, but
.Nm
sends an ordered tag for completeness.)
.Bl -tag -width 4n
.It Fl i
Set the immediate bit in the CDB.  Note that CTL does not support the
immediate bit, so this is primarily useful for making sure that CTL returns
the proper error.
.It Fl o
Set the Copan proprietary on/offline bit in the CDB.  When this flag is
used, the LUN will be spun down and taken offline ("Logical unit not ready,
manual intervention required").  See the description of the 
.Ic shutdown
and
.Ic startup
options.
.El
.It Ic synccache
Send the
.Tn SCSI 
SYNCHRONIZE CACHE command to the device.  By default, SYNCHRONIZE
CACHE(10) is used.  If the specified starting LBA is greater than
0xffffffff or the length is greater than 0xffff, though,
SYNCHRONIZE CACHE(16) will be used.  The 16 byte command will also be used
if the user specifies a 16 byte CDB with the
.Fl c
argument.
.Bl -tag -width 14n
.It Fl l Ar lba
Specify the starting LBA of the cache region to synchronize.  This option is a
no-op for CTL.  If you send a SYNCHRONIZE CACHE command, it will sync the
cache for the entire LUN.
.It Fl b Ar blockcount
Specify the length of the cache region to synchronize.  This option is a
no-op for CTL.  If you send a SYNCHRONIZE CACHE command, it will sync the
cache for the entire LUN.
.It Fl r
Specify relative addressing for the starting LBA.  CTL does not support
relative addressing, since it only works for linked commands, and CTL
doesn't support linked commands.
.It Fl i
Tell the target to return status immediately after issuing the SYHCHRONIZE CACHE
command rather than waiting for the cache to finish syncing.  CTL does not
support this bit.
.It Fl c Ar cdbsize
Specify the minimum CDB size.  Valid values are 10 and 16 bytes.
.El
.It Ic shutdown
Issue a
.Tn SCSI
START STOP UNIT command with the start bit cleared and the on/offline bit
set to all direct access LUNs.  This will spin down all direct access LUNs,
and mark them offline ("Logical unit not ready, manual intervention
required").  Once marked offline, the state can only be cleared by sending
a START STOP UNIT command with the start bit set and the on/offline bit
set.  The
.Nm
commands
.Ic startup
and
.Ic start
will accomplish this.  Note that the
on/offline bit is a non-standard Copan extension to the
.Tn SCSI
START STOP UNIT command, so merely sending a normal start command from an
initiator will not clear the condition.  (This is by design.)
.It Ic startup
Issue a
.Tn SCSI
START STOP UNIT command with the start bit set and the on/offline bit set
to all direct access LUNs.  This will mark all direct access LUNs "online"
again.  It will not cause any LUNs to start up.  A separate start command
without the on/offline bit set is necessary for that.
.It Ic hardstop
Use the kernel facility for stopping all direct access LUNs and setting the
offline bit.  Unlike the
.Ic shutdown
command above, this command allows shutting down LUNs with I/O active.  It
will also issue a LUN reset to any reserved LUNs to break the reservation
so that the LUN can be stopped.
.Ic shutdown
command instead.
.It Ic hardstart
This command is functionally identical to the
.Ic startup
command described above.  The primary difference is that the LUNs are
enumerated and commands sent by the in-kernel Front End Target Driver
instead of by
.Nm .
.It Ic lunlist
List all LUNs registered with CTL.
Because this command uses the ioctl port, it will only work when the FETDs
(Front End Target Drivers) are enabled.
This command is the equivalent of doing a REPORT LUNS on one LUN and then
and then an INQUIRY on each LUN in the system.
.It Ic delay
Delay commands at the given location.  There are two places where commands
may be delayed currently: before data is transferred
.Pq Dq datamove
and just prior to sending status to the host
.Pq Dq done .
One of the two must be supplied as an argument to the
.Fl l 
option.  The
.Fl t
option must also be specified.
.Bl -tag -width 12n
.It Fl l Ar delayloc
Delay command(s) at the specified location.
This can either be at the data movement stage (datamove) or prior to
command completion (done).
.It Fl t Ar delaytime
Delay command(s) for the specified number of seconds.  This must be
specified.  If set to 0, it will clear out any previously set delay for
this particular location (datamove or done).
.It Fl T Ar delaytype
Specify the delay type.
By default, the
.Ic delay
option will delay the next command sent to the given LUN.
With the
.Fl T Ar cont
option, every command will be delayed by the specified period of time.
With the
.Fl T Ar oneshot
the next command sent to the given LUN will be delayed and all subsequent
commands will be completed normally.
This is the default.
.El
.It Ic realsync
Query and control CTL's SYNCHRONIZE CACHE behavior.  The
.Sq query
argument
will show whether SYNCHRONIZE CACHE commands are being sent to the backend
or not.
The default is to send SYNCHRONIZE CACHE commands to the backend.
The 
.Sq on
argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be
sent to the backend.
The
.Sq off
argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be
immediately returned to the initiator with successful status.
.It Ic setsync
For a given lun, only actually service every Nth SYNCHRONIZE CACHE command
that is sent.  This can be used for debugging the optimal time period for
sending SYNCHRONIZE cache commands.  An interval of 0 means that the cache
will be flushed for this LUN every time a SYNCHRONIZE CACHE command is
received.
.Pp
You must specify the target and LUN you want to modify.
.It Ic getsync
Get the interval at which we actually service the SYNCHRONIZE CACHE
command, as set by the
.Ic setsync
command above.
The reported number means that we will actually flush the cache on every
Nth SYNCHRONIZE CACHE command.  A value of 0 means that we will flush the
cache every time.
.Pp
You must specify the target and LUN you want to query.
.It Ic inject
Inject the specified type of error for the LUN specified, when a command
that matches the given pattern is seen.
The sense data returned is in either fixed or descriptor format, depending
upon the status of the D_SENSE bit in the control mode page (page 0xa) for
the LUN.
.Pp
Errors are only injected for commands that have not already failed for
other reasons.
By default, only the first command matching the pattern specified is
returned with the supplied error.
.Pp
If the
.Fl c
flag is specified, all commands matching the pattern will be returned with
the specified error until the error injection command is deleted with
.Fl d 
flag.
.Bl -tag -width 17n
.It Fl i Ar action
Specify the error to return:
.Bl -tag -width 10n
.It aborted
Return the next matching command on the specified LUN with the sense key
ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect
failure").
.It mediumerr
Return the next matching command on the specified LUN with the sense key
MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for
reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed")
for write errors.
.It ua
Return the next matching command on the specified LUN with the sense key
UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS
DEVICE RESET OCCURRED").
.It custom
Return the next matching command on the specified LUN with the supplied
sense data.
The
.Fl s
argument must be specified.
.El
.It Fl p Ar pattern
Specify which commands should be returned with the given error.
.Bl -tag -width 10n
.It read
The error should apply to READ(6), READ(10), READ(12), READ(16), etc.
.It write
The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE
AND VERIFY(10), etc.
.It rw
The error should apply to both read and write type commands.
.It readcap
The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands.
.It tur
The error should apply to TEST UNIT READY commands.
.It any
The error should apply to any command.
.El
.It Fl r Ar lba,len
Specify the starting lba and length of the range of LBAs which should
trigger an error.
This option is only applies when read and/or write patterns are specified.
If used with other command types, the error will never be triggered.
.It Fl s Ar len fmt Op Ar args
Specify the sense data that is to be returned for custom actions.
If the format is
.Sq - ,
len bytes of sense data will be read from standard input and written to the
sense buffer.
If len is longer than 252 bytes (the maximum allowable
.Tn SCSI
sense data length), it will be truncated to that length.
The sense data format is described in
.Xr cam_cdparse 3 .
.It Fl c
The error injection should be persistent, instead of happening once.
Persistent errors must be deleted with the
.Fl d
argument.
.It Fl d Ar delete_id
Delete the specified error injection serial number.
The serial number is returned when the error is injected.
.El
.It Ic port
Perform one of several CTL frontend port operations.
Either get a list of frontend ports
.Pq Fl l ,
turn one or more frontends on
or off
.Pq Fl o Ar on|off ,
or set the World Wide Node Name
.Pq Fl w Ar wwnn
or World Wide Port Name
.Pq Fl W Ar wwpn
for a given port.
One of
.Fl l ,
.Fl o ,
or 
.Fl w
or
.Fl W
must be specified.
The WWNN and WWPN may both be specified at the same time, but cannot be
combined with enabling/disabling or listing ports.
.Bl -tag -width 12n
.It Fl l
List all CTL frontend ports or a specific port type or number.
.It Fl o Ar on|off
Turn the specified CTL frontend ports off or on.
If no port number or port type is specified, all ports are turned on or
off.
.It Fl p Ar targ_port 
Specify the frontend port number.
The port numbers can be found in the frontend port list.
.It Fl q
Omit the header in the port list output.
.It Fl t Ar fe_type
Specify the frontend type.
Currently defined port types are
.Dq fc
(Fibre Channel),
.Dq scsi
(Parallel SCSI),
.Dq ioctl
(CTL ioctl interface),
and
.Dq internal
(CTL CAM SIM).
.It Fl w Ar wwnn
Set the World Wide Node Name for the given port.
The
.Fl n 
argument must be specified, since this is only possible to implement on a
single port.
As a general rule, the WWNN should be the same across all ports on the
system.
.It Fl W Ar wwpn
Set the World Wide Node Name for the given port.
The
.Fl n
argument must be specified, since this is only possible to implement on a
single port.
As a general rule, the WWPN must be different for every port in the system.
.It Fl x
Output the port list in XML format.
.El
.It Ic dumpooa
Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL.
.It Ic dumpstructs
Dump the CTL structures to the console.
.It Ic create
Create a new LUN.
The backend must be specified, and depending upon the backend requested,
some of the other options may be required.
If the LUN is created successfully, the LUN configuration will be
displayed.
If LUN creation fails, a message will be displayed describing the failure.
.Bl -tag -width 14n
.It Fl b Ar backend
The
.Fl b
flag is required.
This specifies the name backend to use when creating the LUN.
Examples are
.Dq ramdisk
and
.Dq block .
.It Fl B Ar blocksize
Specify the blocksize of the backend in bytes.
.It Fl d Ar device_id
Specify the LUN-associated string to use in the
.Tn SCSI
INQUIRY VPD page 0x83 data.
.It Fl l Ar lun_id
Request that a particular LUN number be assigned.
If the requested LUN number is not available, the request will fail.
.It Fl o Ar name=value
Specify a backend-specific name/value pair.
Multiple
.Fl o
arguments may be specified.
Refer to the backend documentation for arguments that may be used.
.It Fl s Ar size_bytes
Specify the size of the LUN in bytes.
Some backends may allow setting the size (e.g. the ramdisk backend) and for
others the size may be implicit (e.g. the block backend).
.It Fl S Ar serial_num
Specify the serial number to be used in the
.Tn SCSI
INQUIRY VPD page 0x80 data.
.It Fl t Ar device_type
Specify the numeric SCSI device type to use when creating the LUN.
For example, the Direct Access type is 0.
If this flag is not used, the type of LUN created is backend-specific.
Not all LUN types are supported.
Currently CTL only supports Direct Access (type 0) and Processor (type 3)
LUNs.
The backend requested may or may not support all of the LUN types that CTL
supports.
.El
.It Ic remove
Remove a LUN.
The backend must be specified, and the LUN number must also be specified.
Backend-specific options may also be specified with the
.Fl o
flag.
.Bl -tag -width 14n
.It Fl b Ar backend
Specify the backend that owns the LUN to be removed.
Examples are
.Dq ramdisk
and
.Dq block .
.It Fl l Ar lun_id
Specify the LUN number to remove.
.It Fl o Ar name=value
Specify a backend-specific name/value pair.
Multiple
.Fl o
arguments may be specified.
Refer to the backend documentation for arguments that may be used.
.El
.It Ic modify
Modify a LUN size.
The backend, the LUN number, and the size must be specified.
.Bl -tag -width 14n
.It Fl b Ar backend
Specify the backend that owns the LUN to be removed.
Examples are
.Dq ramdisk
and
.Dq block .
.It Fl l Ar lun_id
Specify the LUN number to remove.
.It Fl s Ar size_bytes
Specify the size of the LUN in bytes.
For the
.Dq block
backend, an
.Dq auto
keyword may be passed instead; this will make CTL use the size of backing
file or device.
.El
.It Ic devlist
Get a list of all configured LUNs.
This also includes the LUN size and blocksize, serial number and device ID.
.Bl -tag -width 11n
.It Fl b Ar backend
Specify the backend.
This restricts the LUN list to the named backend.
Examples are
.Dq ramdisk
and
.Dq block .
.It Fl v
Be verbose.
This will also display any backend-specific LUN attributes in addition to
the standard per-LUN information.
.It Fl x
Dump the raw XML.
The LUN list information from the kernel comes in XML format, and this
option allows the display of the raw XML data.
This option and the
.Fl v
and
.Fl b
options are mutually exclusive.
If you specify
.Fl x ,
the entire LUN database is displayed in XML format.
.El
.It Ic help
Display
.Nm
usage information.
.El
.Sh EXAMPLES
.Dl ctladm tur 0:1
.Pp
Send a
.Tn SCSI
TEST UNIT READY command to LUN 1.
.Pp
.Dl ctladm modesense 0:1 -l
.Pp
Display the list of mode pages supported by LUN 1.
.Pp
.Dl ctladm modesense 0:0 -m 10 -P 3 -d -c 10
.Pp
Display the saved version of the Control mode page (page 10) on LUN 0.
Disable fetching block descriptors, and use a 10 byte MODE SENSE command
instead of the default 6 byte command.
.Bd -literal
ctladm read 0:2 -l 0 -d 1 -b 512 -f - > foo
.Ed
.Pp
Read the first 512 byte block from LUN 2 and dump it to the file
.Pa foo .
.Bd -literal
ctladm write 0:3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar
.Ed
.Pp
Read 10240 bytes from the file
.Pa /tmp/bar
and write it to target 0, LUN 3.
starting at LBA 0xff432140.
.Pp
.Dl ctladm create -b ramdisk -s 10485760000000000
.Pp
Create a LUN with the
.Dq fake
ramdisk as a backing store.
The LUN will claim to have a size of approximately 10 terabytes.
.Pp
.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8
.Pp
Create a LUN using the block backend, and specify the file
.Pa src/usr.sbin/ctladm/ctladm.8
as the backing store.
The size of the LUN will be derived from the size of the file.
.Pp
.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123
.Pp
Create a LUN using the block backend, specify the file
.Pa src/usr.sbin/ctladm/ctladm.8
as the backing store, and specify the
.Tn SCSI
VPD page 0x80 and 0x83 serial number (
.Fl S)
and device ID (
.Fl d).
.Pp
.Dl ctladm remove -b block -l 12
.Pp
Remove LUN 12, which is handled by the block backend, from the system.
.Pp
.Dl ctladm devlist
.Pp
List configured LUNs in the system, along with their backend and serial
number.
This works when the Front End Target Drivers are enabled or disabled.
.Pp
.Dl ctladm lunlist
.Pp
List all LUNs in the system, along with their inquiry data and device type.
This only works when the FETDs are enabled, since the commands go through the 
ioctl port.
.Pp
.Dl ctladm inject 0:6 -i mediumerr -p read -r 0,512 -c
.Pp
Inject a medium error on LUN 6 for every read that covers the first 512
blocks of the LUN.
.Bd -literal -offset indent
ctladm inject 0:6 -i custom -p tur -s 18 "f0 0 02 s12 04 02"
.Ed
.Pp
Inject a custom error on LUN 6 for the next TEST UNIT READY command only.
This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of
0x04,0x02 ("Logical unit not ready, initializing command required").
.Sh SEE ALSO
.Xr cam 3 ,
.Xr cam_cdbparse 3 ,
.Xr cam 4 ,
.Xr xpt 4 ,
.Xr camcontrol 8
.Sh HISTORY
The
.Nm
utility was originally written during the Winter/Spring of 2003 as an
interface to CTL.
.Sh AUTHORS
.An Ken Merry Aq ken@FreeBSD.org
OpenPOWER on IntegriCloud