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