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 26, 2014 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 portlist 197.Op Fl f Ar frontend 198.Op Fl i 199.Op Fl p Ar targ_port 200.Op Fl q 201.Op Fl v 202.Op Fl x 203.Nm 204.Ic dumpooa 205.Nm 206.Ic dumpstructs 207.Nm 208.Ic islist 209.Op Fl v 210.Op Fl x 211.Nm 212.Ic islogout 213.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal 214.Nm 215.Ic isterminate 216.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal 217.Nm 218.Ic help 219.Sh DESCRIPTION 220The 221.Nm 222utility is designed to provide a way to access and control the CAM Target 223Layer (CTL). 224It provides a way to send 225.Tn SCSI 226commands to the CTL layer, and also provides 227some meta-commands that utilize 228.Tn SCSI 229commands. 230(For instance, the 231.Ic lunlist 232command is implemented using the 233.Tn SCSI 234REPORT LUNS and INQUIRY commands.) 235.Pp 236The 237.Nm 238utility has a number of primary functions, many of which require a device 239identifier. 240The device identifier takes the following form: 241.Bl -tag -width 14n 242.It target:lun 243Specify the target (almost always 0) and LUN number to operate on. 244.El 245Many of the primary functions of the 246.Nm 247utility take the following optional arguments: 248.Bl -tag -width 10n 249.It Fl C Ar retries 250Specify the number of times to retry a command in the event of failure. 251.It Fl D Ar device 252Specify the device to open. This allows opening a device other than the 253default device, 254.Pa /dev/cam/ctl , 255to be opened for sending commands. 256.It Fl I Ar id 257Specify the initiator number to use. 258By default, 259.Nm 260will use 7 as the initiator number. 261.El 262.Pp 263Primary commands: 264.Bl -tag -width 11n 265.It Ic tur 266Send the 267.Tn SCSI 268TEST UNIT READY command to the device and report whether or not it is 269ready. 270.It Ic inquiry 271Send the 272.Tn SCSI 273INQUIRY command to the device and display some of the returned inquiry 274data. 275.It Ic reqsense 276Send the 277.Tn SCSI 278REQUEST SENSE command to the device and display the returned sense 279information. 280.It Ic reportluns 281Send the 282.Tn SCSI 283REPORT LUNS command to the device and display supported LUNs. 284.It Ic read 285Send a 286.Tn SCSI 287READ command to the device, and write the requested data to a file or 288stdout. 289.Bl -tag -width 12n 290.It Fl l Ar lba 291Specify the starting Logical Block Address for the READ. This can be 292specified in decimal, octal (starting with 0), hexadecimal (starting with 2930x) or any other base supported by 294.Xr strtoull 3 . 295.It Fl d Ar datalen 296Specify the length, in 512 byte blocks, of the READ request. 297.It Fl f Ar file 298Specify the destination for the data read by the READ command. Either a 299filename or 300.Sq - 301for stdout may be specified. 302.It Fl c Ar cdbsize 303Specify the minimum 304.Tn SCSI 305CDB (Command Data Block) size to be used for the READ request. Allowable 306values are 6, 10, 12 and 16. Depending upon the LBA and amount of data 307requested, a larger CDB size may be used to satisfy the request. (e.g., 308for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) 309.It Fl b Ar blocksize 310Specify the blocksize of the underlying 311.Tn SCSI 312device, so the transfer length 313can be calculated accurately. The blocksize can be obtained via the 314.Tn SCSI 315READ CAPACITY command. 316.It Fl N 317Do not copy data to 318.Nm 319from the kernel when doing a read, just execute the command without copying 320data. 321This is to be used for performance testing. 322.El 323.It Ic write 324Read data from a file or stdin, and write the data to the device using the 325.Tn SCSI 326WRITE command. 327.Bl -tag -width 12n 328.It Fl l Ar lba 329Specify the starting Logical Block Address for the WRITE. This can be 330specified in decimal, octal (starting with 0), hexadecimal (starting with 3310x) or any other base supported by 332.Xr strtoull 3 . 333.It Fl d Ar atalen 334Specify the length, in 512 byte blocks, of the WRITE request. 335.It Fl f Ar file 336Specify the source for the data to be written by the WRITE command. Either a 337filename or 338.Sq - 339for stdin may be specified. 340.It Fl c Ar cdbsize 341Specify the minimum 342.Tn SCSI 343CDB (Command Data Block) size to be used for the READ request. Allowable 344values are 6, 10, 12 and 16. Depending upon the LBA and amount of data 345requested, a larger CDB size may be used to satisfy the request. (e.g., 346for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) 347.It Fl b Ar blocksize 348Specify the blocksize of the underlying 349.Tn SCSI 350device, so the transfer length 351can be calculated accurately. The blocksize can be obtained via the 352.Tn SCSI 353READ CAPACITY command. 354.It Fl N 355Do not copy data to 356.Nm 357to the kernel when doing a write, just execute the command without copying 358data. 359This is to be used for performance testing. 360.El 361.It Ic bbrread 362Issue a SCSI READ command to the logical device to potentially force a bad 363block on a disk in the RAID set to be reconstructed from the other disks in 364the array. This command should only be used on an array that is in the 365normal state. If used on a critical array, it could cause the array to go 366offline if the bad block to be remapped is on one of the disks that is 367still active in the array. 368.Pp 369The data for this particular command will be discarded, and not returned to 370the user. 371.Pp 372In order to determine which LUN to read from, the user should first 373determine which LUN the disk with a bad block belongs to. Then he should 374map the bad disk block back to the logical block address for the array in 375order to determine which LBA to pass in to the 376.Ic bbrread 377command. 378.Pp 379This command is primarily intended for testing. In practice, bad block 380remapping will generally be triggered by the in-kernel Disk Aerobics and 381Disk Scrubbing code. 382.Bl -tag -width 10n 383.It Fl l Ar lba 384Specify the starting Logical Block Address. 385.It Fl d Ar datalen 386Specify the amount of data in bytes to read from the LUN. This must be a 387multiple of the LUN blocksize. 388.El 389.It Ic readcap 390Send the 391.Tn SCSI 392READ CAPACITY command to the device and display the device size and device 393block size. By default, READ CAPACITY(10) is 394used. If the device returns a maximum LBA of 0xffffffff, however, 395.Nm 396will automatically issue a READ CAPACITY(16), which is implemented as a 397service action of the SERVICE ACTION IN(16) opcode. The user can specify 398the minimum CDB size with the 399.Fl c 400argument. Valid values for the 401.Fl c 402option are 10 and 16. If a 10 byte CDB is specified, the request will be 403automatically reissued with a 16 byte CDB if the maximum LBA returned is 4040xffffffff. 405.It Ic modesense 406Send a 407.Tn SCSI 408MODE SENSE command to the device, and display the requested mode page(s) or 409page list. 410.Bl -tag -width 10n 411.It Fl m Ar page 412Specify the mode page to display. This option and the 413.Fl l 414option are mutually exclusive. One of the two must be specified, though. 415Mode page numbers may be specified in decimal or hexadecimal. 416.It Fl l 417Request that the list of mode pages supported by the device be returned. 418This option and the 419.Fl m 420option are mutually exclusive. One of the two must be specified, though. 421.It Fl P Ar pc 422Specify the mode page control value. Possible values are: 423.Bl -tag -width 2n -compact 424.It 0 425Current values. 426.It 1 427Changeable value bitmask. 428.It 2 429Default values. 430.It 3 431Saved values. 432.El 433.It Fl d 434Disable block descriptors when sending the mode sense request. 435.It Fl S Ar subpage 436Specify the subpage used with the mode sense request. 437.It Fl c Ar cdbsize 438Specify the CDB size used for the mode sense request. Supported values are 4396 and 10. 440.El 441.It Ic start 442Send the 443.Tn SCSI 444START STOP UNIT command to the specified LUN with the start 445bit set. 446.Bl -tag -width 4n 447.It Fl i 448Set the immediate bit in the CDB. Note that CTL does not support the 449immediate bit, so this is primarily useful for making sure that CTL returns 450the proper error. 451.It Fl o 452Set the Copan proprietary on/offline bit in the CDB. When this flag is 453used, the LUN will be marked online again (see the description of the 454.Ic shutdown 455and 456.Ic startup 457commands). When this flag is used with a 458start command, the LUN will NOT be spun up. You need to use a start 459command without the 460.Fl o 461flag to spin up the disks in the LUN. 462.El 463.It Ic stop 464Send the 465.Tn SCSI 466START STOP UNIT command to the specified LUN with the start 467bit cleared. We use an ordered tag to stop the LUN, so we can guarantee 468that all pending I/O executes before it is stopped. (CTL guarantees this 469anyway, but 470.Nm 471sends an ordered tag for completeness.) 472.Bl -tag -width 4n 473.It Fl i 474Set the immediate bit in the CDB. Note that CTL does not support the 475immediate bit, so this is primarily useful for making sure that CTL returns 476the proper error. 477.It Fl o 478Set the Copan proprietary on/offline bit in the CDB. When this flag is 479used, the LUN will be spun down and taken offline ("Logical unit not ready, 480manual intervention required"). See the description of the 481.Ic shutdown 482and 483.Ic startup 484options. 485.El 486.It Ic synccache 487Send the 488.Tn SCSI 489SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE 490CACHE(10) is used. If the specified starting LBA is greater than 4910xffffffff or the length is greater than 0xffff, though, 492SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used 493if the user specifies a 16 byte CDB with the 494.Fl c 495argument. 496.Bl -tag -width 14n 497.It Fl l Ar lba 498Specify the starting LBA of the cache region to synchronize. This option is a 499no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the 500cache for the entire LUN. 501.It Fl b Ar blockcount 502Specify the length of the cache region to synchronize. This option is a 503no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the 504cache for the entire LUN. 505.It Fl r 506Specify relative addressing for the starting LBA. CTL does not support 507relative addressing, since it only works for linked commands, and CTL 508does not support linked commands. 509.It Fl i 510Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE 511command rather than waiting for the cache to finish syncing. CTL does not 512support this bit. 513.It Fl c Ar cdbsize 514Specify the minimum CDB size. Valid values are 10 and 16 bytes. 515.El 516.It Ic shutdown 517Issue a 518.Tn SCSI 519START STOP UNIT command with the start bit cleared and the on/offline bit 520set to all direct access LUNs. This will spin down all direct access LUNs, 521and mark them offline ("Logical unit not ready, manual intervention 522required"). Once marked offline, the state can only be cleared by sending 523a START STOP UNIT command with the start bit set and the on/offline bit 524set. The 525.Nm 526commands 527.Ic startup 528and 529.Ic start 530will accomplish this. Note that the 531on/offline bit is a non-standard Copan extension to the 532.Tn SCSI 533START STOP UNIT command, so merely sending a normal start command from an 534initiator will not clear the condition. (This is by design.) 535.It Ic startup 536Issue a 537.Tn SCSI 538START STOP UNIT command with the start bit set and the on/offline bit set 539to all direct access LUNs. This will mark all direct access LUNs "online" 540again. It will not cause any LUNs to start up. A separate start command 541without the on/offline bit set is necessary for that. 542.It Ic hardstop 543Use the kernel facility for stopping all direct access LUNs and setting the 544offline bit. Unlike the 545.Ic shutdown 546command above, this command allows shutting down LUNs with I/O active. It 547will also issue a LUN reset to any reserved LUNs to break the reservation 548so that the LUN can be stopped. 549.Ic shutdown 550command instead. 551.It Ic hardstart 552This command is functionally identical to the 553.Ic startup 554command described above. The primary difference is that the LUNs are 555enumerated and commands sent by the in-kernel Front End Target Driver 556instead of by 557.Nm . 558.It Ic lunlist 559List all LUNs registered with CTL. 560Because this command uses the ioctl port, it will only work when the FETDs 561(Front End Target Drivers) are enabled. 562This command is the equivalent of doing a REPORT LUNS on one LUN and then 563an INQUIRY on each LUN in the system. 564.It Ic delay 565Delay commands at the given location. There are two places where commands 566may be delayed currently: before data is transferred 567.Pq Dq datamove 568and just prior to sending status to the host 569.Pq Dq done . 570One of the two must be supplied as an argument to the 571.Fl l 572option. The 573.Fl t 574option must also be specified. 575.Bl -tag -width 12n 576.It Fl l Ar delayloc 577Delay command(s) at the specified location. 578This can either be at the data movement stage (datamove) or prior to 579command completion (done). 580.It Fl t Ar delaytime 581Delay command(s) for the specified number of seconds. This must be 582specified. If set to 0, it will clear out any previously set delay for 583this particular location (datamove or done). 584.It Fl T Ar delaytype 585Specify the delay type. 586By default, the 587.Ic delay 588option will delay the next command sent to the given LUN. 589With the 590.Fl T Ar cont 591option, every command will be delayed by the specified period of time. 592With the 593.Fl T Ar oneshot 594the next command sent to the given LUN will be delayed and all subsequent 595commands will be completed normally. 596This is the default. 597.El 598.It Ic realsync 599Query and control CTL's SYNCHRONIZE CACHE behavior. The 600.Sq query 601argument 602will show whether SYNCHRONIZE CACHE commands are being sent to the backend 603or not. 604The default is to send SYNCHRONIZE CACHE commands to the backend. 605The 606.Sq on 607argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be 608sent to the backend. 609The 610.Sq off 611argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be 612immediately returned to the initiator with successful status. 613.It Ic setsync 614For a given lun, only actually service every Nth SYNCHRONIZE CACHE command 615that is sent. This can be used for debugging the optimal time period for 616sending SYNCHRONIZE cache commands. An interval of 0 means that the cache 617will be flushed for this LUN every time a SYNCHRONIZE CACHE command is 618received. 619.Pp 620You must specify the target and LUN you want to modify. 621.It Ic getsync 622Get the interval at which we actually service the SYNCHRONIZE CACHE 623command, as set by the 624.Ic setsync 625command above. 626The reported number means that we will actually flush the cache on every 627Nth SYNCHRONIZE CACHE command. A value of 0 means that we will flush the 628cache every time. 629.Pp 630You must specify the target and LUN you want to query. 631.It Ic inject 632Inject the specified type of error for the LUN specified, when a command 633that matches the given pattern is seen. 634The sense data returned is in either fixed or descriptor format, depending 635upon the status of the D_SENSE bit in the control mode page (page 0xa) for 636the LUN. 637.Pp 638Errors are only injected for commands that have not already failed for 639other reasons. 640By default, only the first command matching the pattern specified is 641returned with the supplied error. 642.Pp 643If the 644.Fl c 645flag is specified, all commands matching the pattern will be returned with 646the specified error until the error injection command is deleted with 647.Fl d 648flag. 649.Bl -tag -width 17n 650.It Fl i Ar action 651Specify the error to return: 652.Bl -tag -width 10n 653.It aborted 654Return the next matching command on the specified LUN with the sense key 655ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect 656failure"). 657.It mediumerr 658Return the next matching command on the specified LUN with the sense key 659MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for 660reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed") 661for write errors. 662.It ua 663Return the next matching command on the specified LUN with the sense key 664UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS 665DEVICE RESET OCCURRED"). 666.It custom 667Return the next matching command on the specified LUN with the supplied 668sense data. 669The 670.Fl s 671argument must be specified. 672.El 673.It Fl p Ar pattern 674Specify which commands should be returned with the given error. 675.Bl -tag -width 10n 676.It read 677The error should apply to READ(6), READ(10), READ(12), READ(16), etc. 678.It write 679The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE 680AND VERIFY(10), etc. 681.It rw 682The error should apply to both read and write type commands. 683.It readcap 684The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands. 685.It tur 686The error should apply to TEST UNIT READY commands. 687.It any 688The error should apply to any command. 689.El 690.It Fl r Ar lba,len 691Specify the starting lba and length of the range of LBAs which should 692trigger an error. 693This option is only applies when read and/or write patterns are specified. 694If used with other command types, the error will never be triggered. 695.It Fl s Ar len fmt Op Ar args 696Specify the sense data that is to be returned for custom actions. 697If the format is 698.Sq - , 699len bytes of sense data will be read from standard input and written to the 700sense buffer. 701If len is longer than 252 bytes (the maximum allowable 702.Tn SCSI 703sense data length), it will be truncated to that length. 704The sense data format is described in 705.Xr cam_cdparse 3 . 706.It Fl c 707The error injection should be persistent, instead of happening once. 708Persistent errors must be deleted with the 709.Fl d 710argument. 711.It Fl d Ar delete_id 712Delete the specified error injection serial number. 713The serial number is returned when the error is injected. 714.El 715.It Ic port 716Perform one of several CTL frontend port operations. 717Either get a list of frontend ports 718.Pq Fl l , 719turn one or more frontends on 720or off 721.Pq Fl o Ar on|off , 722or set the World Wide Node Name 723.Pq Fl w Ar wwnn 724or World Wide Port Name 725.Pq Fl W Ar wwpn 726for a given port. 727One of 728.Fl l , 729.Fl o , 730or 731.Fl w 732or 733.Fl W 734must be specified. 735The WWNN and WWPN may both be specified at the same time, but cannot be 736combined with enabling/disabling or listing ports. 737.Bl -tag -width 12n 738.It Fl l 739List all CTL frontend ports or a specific port type or number. 740.It Fl o Ar on|off 741Turn the specified CTL frontend ports off or on. 742If no port number or port type is specified, all ports are turned on or 743off. 744.It Fl p Ar targ_port 745Specify the frontend port number. 746The port numbers can be found in the frontend port list. 747.It Fl q 748Omit the header in the port list output. 749.It Fl t Ar fe_type 750Specify the frontend type. 751Currently defined port types are 752.Dq fc 753(Fibre Channel), 754.Dq scsi 755(Parallel SCSI), 756.Dq ioctl 757(CTL ioctl interface), 758and 759.Dq internal 760(CTL CAM SIM). 761.It Fl w Ar wwnn 762Set the World Wide Node 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 WWNN should be the same across all ports on the 768system. 769.It Fl W Ar wwpn 770Set the World Wide Port Name for the given port. 771The 772.Fl n 773argument must be specified, since this is only possible to implement on a 774single port. 775As a general rule, the WWPN must be different for every port in the system. 776.It Fl x 777Output the port list in XML format. 778.El 779.It Ic portlist 780List CTL frontend ports. 781.Bl -tag -width 12n 782.It Fl f Ar frontend 783Specify the frontend type. 784.It Fl i 785Report target and connected initiators addresses 786.It Fl p Ar targ_port 787Specify the frontend port number. 788.It Fl q 789Omit the header in the port list output. 790.It Fl v 791Enable verbose output (report all port options). 792.It Fl x 793Output the port list in XML format. 794.El 795.It Ic dumpooa 796Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL. 797.It Ic dumpstructs 798Dump the CTL structures to the console. 799.It Ic create 800Create a new LUN. 801The backend must be specified, and depending upon the backend requested, 802some of the other options may be required. 803If the LUN is created successfully, the LUN configuration will be 804displayed. 805If LUN creation fails, a message will be displayed describing the failure. 806.Bl -tag -width 14n 807.It Fl b Ar backend 808The 809.Fl b 810flag is required. 811This specifies the name backend to use when creating the LUN. 812Examples are 813.Dq ramdisk 814and 815.Dq block . 816.It Fl B Ar blocksize 817Specify the blocksize of the backend in bytes. 818.It Fl d Ar device_id 819Specify the LUN-associated string to use in the 820.Tn SCSI 821INQUIRY VPD page 0x83 data. 822.It Fl l Ar lun_id 823Request that a particular LUN number be assigned. 824If the requested LUN number is not available, the request will fail. 825.It Fl o Ar name=value 826Specify a backend-specific name/value pair. 827Multiple 828.Fl o 829arguments may be specified. 830Refer to the backend documentation for arguments that may be used. 831.It Fl s Ar size_bytes 832Specify the size of the LUN in bytes. 833Some backends may allow setting the size (e.g. the ramdisk backend) and for 834others the size may be implicit (e.g. the block backend). 835.It Fl S Ar serial_num 836Specify the serial number to be used in the 837.Tn SCSI 838INQUIRY VPD page 0x80 data. 839.It Fl t Ar device_type 840Specify the numeric SCSI device type to use when creating the LUN. 841For example, the Direct Access type is 0. 842If this flag is not used, the type of LUN created is backend-specific. 843Not all LUN types are supported. 844Currently CTL only supports Direct Access (type 0) and Processor (type 3) 845LUNs. 846The backend requested may or may not support all of the LUN types that CTL 847supports. 848.El 849.It Ic remove 850Remove a LUN. 851The backend must be specified, and the LUN number must also be specified. 852Backend-specific options may also be specified with the 853.Fl o 854flag. 855.Bl -tag -width 14n 856.It Fl b Ar backend 857Specify the backend that owns the LUN to be removed. 858Examples are 859.Dq ramdisk 860and 861.Dq block . 862.It Fl l Ar lun_id 863Specify the LUN number to remove. 864.It Fl o Ar name=value 865Specify a backend-specific name/value pair. 866Multiple 867.Fl o 868arguments may be specified. 869Refer to the backend documentation for arguments that may be used. 870.El 871.It Ic modify 872Modify a LUN size. 873The backend, the LUN number, and the size must be specified. 874.Bl -tag -width 14n 875.It Fl b Ar backend 876Specify the backend that owns the LUN to be removed. 877Examples are 878.Dq ramdisk 879and 880.Dq block . 881.It Fl l Ar lun_id 882Specify the LUN number to remove. 883.It Fl s Ar size_bytes 884Specify the size of the LUN in bytes. 885For the 886.Dq block 887backend, an 888.Dq auto 889keyword may be passed instead; this will make CTL use the size of backing 890file or device. 891.El 892.It Ic devlist 893Get a list of all configured LUNs. 894This also includes the LUN size and blocksize, serial number and device ID. 895.Bl -tag -width 11n 896.It Fl b Ar backend 897Specify the backend. 898This restricts the LUN list to the named backend. 899Examples are 900.Dq ramdisk 901and 902.Dq block . 903.It Fl v 904Be verbose. 905This will also display any backend-specific LUN attributes in addition to 906the standard per-LUN information. 907.It Fl x 908Dump the raw XML. 909The LUN list information from the kernel comes in XML format, and this 910option allows the display of the raw XML data. 911This option and the 912.Fl v 913and 914.Fl b 915options are mutually exclusive. 916If you specify 917.Fl x , 918the entire LUN database is displayed in XML format. 919.El 920.It Ic islist 921Get a list of currently running iSCSI connections. 922This includes initiator and target names and the unique connection IDs. 923.Bl -tag -width 11n 924.It Fl v 925Verbose mode. 926.It Fl x 927Dump the raw XML. 928The connections list information from the kernel comes in XML format, and this 929option allows the display of the raw XML data. 930.El 931.It Ic islogout 932Ask the initiator to log out iSCSI connections matching criteria. 933.Bl -tag -width 11n 934.It Fl a 935Log out all connections. 936.It Fl c 937Specify connection ID. 938.It Fl i 939Specify initiator name. 940.It Fl p 941Specify initiator portal (hostname or IP address). 942.El 943.It Ic isterminate 944Forcibly terminate iSCSI connections matching criteria. 945.Bl -tag -width 11n 946.It Fl a 947Terminate all connections. 948.It Fl c 949Specify connection ID. 950.It Fl i 951Specify initiator name. 952.It Fl p 953Specify initiator portal (hostname or IP address). 954.El 955.It Ic help 956Display 957.Nm 958usage information. 959.El 960.Sh OPTIONS 961Number of additional configuration options may be specified for LUNs. 962Some options are global, others are backend-specific. 963.Pp 964Global options: 965.Bl -tag -width 12n 966.It Va vendor 967Specifies LUN vendor string up to 8 chars. 968.It Va product 969Specifies LUN product string up to 16 chars. 970.It Va revision 971Specifies LUN revision string up to 4 chars. 972.It Va scsiname 973Specifies LUN SCSI name string. 974.It Va eui 975Specifies LUN EUI-64 identifier. 976.It Va naa 977Specifies LUN NAA identifier. 978Either EUI or NAA identifier should be set to UNIQUE value to allow 979EXTENDED COPY command access the LUN. 980Non-unique LUN identifiers may lead to data corruption. 981.It Va insecure_tpc 982Setting to "on" allows EXTENDED COPY command sent to this LUN access 983other LUNs on this host, not accessible otherwise. 984This allows to offload copying between different iSCSI targets residing 985on the same host in trusted environments. 986.It Va readcache 987Set to "off", disables read caching for the LUN, if supported by the backend. 988.It Va readonly 989Set to "on", blocks all media write operations to the LUN, reporting it 990as write protected. 991.It Va reordering 992Set to "unrestricted", allows target to process commands with SIMPLE task 993attribute in arbitrary order. Any data integrity exposures related to 994command sequence order shall be explicitly handled by the application 995client through the selection of appropriate commands and task attributes. 996The default value is "restricted". It improves data integrity, but may 997introduce some additional delays. 998.It Va rpm 999Specifies medium rotation rate of the device: 0 -- not reported, 10001 -- non-rotating (SSD), >1024 -- value in revolutions per minute. 1001.It Va formfactor 1002Specifies nominal form factor of the device: 0 -- not reported, 1 -- 5.25", 10032 -- 3.5", 3 -- 2.5", 4 -- 1.8", 5 -- less then 1.8". 1004.It Va unmap 1005Set to "on", enables UNMAP support for the LUN, if supported by the backend. 1006.It Va writecache 1007Set to "off", disables write caching for the LUN, if supported by the backend. 1008.El 1009.Pp 1010Options specific for block backend: 1011.Bl -tag -width 12n 1012.It Va file 1013Specifies file or device name to use for backing store. 1014.It Va num_threads 1015Specifies number of backend threads to use for this LUN. 1016.El 1017.Sh EXAMPLES 1018.Dl ctladm tur 0:1 1019.Pp 1020Send a 1021.Tn SCSI 1022TEST UNIT READY command to LUN 1. 1023.Pp 1024.Dl ctladm modesense 0:1 -l 1025.Pp 1026Display the list of mode pages supported by LUN 1. 1027.Pp 1028.Dl ctladm modesense 0:0 -m 10 -P 3 -d -c 10 1029.Pp 1030Display the saved version of the Control mode page (page 10) on LUN 0. 1031Disable fetching block descriptors, and use a 10 byte MODE SENSE command 1032instead of the default 6 byte command. 1033.Bd -literal 1034ctladm read 0:2 -l 0 -d 1 -b 512 -f - > foo 1035.Ed 1036.Pp 1037Read the first 512 byte block from LUN 2 and dump it to the file 1038.Pa foo . 1039.Bd -literal 1040ctladm write 0:3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar 1041.Ed 1042.Pp 1043Read 10240 bytes from the file 1044.Pa /tmp/bar 1045and write it to target 0, LUN 3. 1046starting at LBA 0xff432140. 1047.Pp 1048.Dl ctladm create -b ramdisk -s 10485760000000000 1049.Pp 1050Create a LUN with the 1051.Dq fake 1052ramdisk as a backing store. 1053The LUN will claim to have a size of approximately 10 terabytes. 1054.Pp 1055.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 1056.Pp 1057Create a LUN using the block backend, and specify the file 1058.Pa src/usr.sbin/ctladm/ctladm.8 1059as the backing store. 1060The size of the LUN will be derived from the size of the file. 1061.Pp 1062.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123 1063.Pp 1064Create a LUN using the block backend, specify the file 1065.Pa src/usr.sbin/ctladm/ctladm.8 1066as the backing store, and specify the 1067.Tn SCSI 1068VPD page 0x80 and 0x83 serial number 1069.Fl ( S ) 1070and device ID 1071.Fl ( d ) . 1072.Pp 1073.Dl ctladm remove -b block -l 12 1074.Pp 1075Remove LUN 12, which is handled by the block backend, from the system. 1076.Pp 1077.Dl ctladm devlist 1078.Pp 1079List configured LUNs in the system, along with their backend and serial 1080number. 1081This works when the Front End Target Drivers are enabled or disabled. 1082.Pp 1083.Dl ctladm lunlist 1084.Pp 1085List all LUNs in the system, along with their inquiry data and device type. 1086This only works when the FETDs are enabled, since the commands go through the 1087ioctl port. 1088.Pp 1089.Dl ctladm inject 0:6 -i mediumerr -p read -r 0,512 -c 1090.Pp 1091Inject a medium error on LUN 6 for every read that covers the first 512 1092blocks of the LUN. 1093.Bd -literal -offset indent 1094ctladm inject 0:6 -i custom -p tur -s 18 "f0 0 02 s12 04 02" 1095.Ed 1096.Pp 1097Inject a custom error on LUN 6 for the next TEST UNIT READY command only. 1098This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of 10990x04,0x02 ("Logical unit not ready, initializing command required"). 1100.Sh SEE ALSO 1101.Xr cam 3 , 1102.Xr cam_cdbparse 3 , 1103.Xr cam 4 , 1104.Xr ctl 4 , 1105.Xr xpt 4 , 1106.Xr camcontrol 8 , 1107.Xr ctld 8 1108.Sh HISTORY 1109The 1110.Nm 1111utility was originally written during the Winter/Spring of 2003 as an 1112interface to CTL. 1113.Sh AUTHORS 1114.An Ken Merry Aq Mt ken@FreeBSD.org 1115