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