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