1.\" 2.\" Copyright (c) 2003 Silicon Graphics International Corp. 3.\" Copyright (c) 2015 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 July 25, 2019 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. This allows opening a device other than the 237default 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. This can be 276specified in decimal, octal (starting with 0), hexadecimal (starting with 2770x) 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. Either a 283filename 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. Allowable 290values are 6, 10, 12 and 16. Depending upon the LBA and amount of data 291requested, a larger CDB size may be used to satisfy the request. (e.g., 292for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) 293.It Fl b Ar blocksize 294Specify the blocksize of the underlying 295.Tn SCSI 296device, so the transfer length 297can be calculated accurately. The blocksize can be obtained via the 298.Tn SCSI 299READ CAPACITY command. 300.It Fl N 301Do not copy data to 302.Nm 303from the kernel when doing a read, just execute the command without copying 304data. 305This is to be used for performance testing. 306.El 307.It Ic write 308Read data from a file or stdin, and write the data to the device using the 309.Tn SCSI 310WRITE command. 311.Bl -tag -width 12n 312.It Fl l Ar lba 313Specify the starting Logical Block Address for the WRITE. This can be 314specified in decimal, octal (starting with 0), hexadecimal (starting with 3150x) or any other base supported by 316.Xr strtoull 3 . 317.It Fl d Ar atalen 318Specify the length, in 512 byte blocks, of the WRITE request. 319.It Fl f Ar file 320Specify the source for the data to be written by the WRITE command. Either a 321filename or 322.Sq - 323for stdin may be specified. 324.It Fl c Ar cdbsize 325Specify the minimum 326.Tn SCSI 327CDB (Command Data Block) size to be used for the READ request. Allowable 328values are 6, 10, 12 and 16. Depending upon the LBA and amount of data 329requested, a larger CDB size may be used to satisfy the request. (e.g., 330for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) 331.It Fl b Ar blocksize 332Specify the blocksize of the underlying 333.Tn SCSI 334device, so the transfer length 335can be calculated accurately. The blocksize can be obtained via the 336.Tn SCSI 337READ CAPACITY command. 338.It Fl N 339Do not copy data to 340.Nm 341to the kernel when doing a write, just execute the command without copying 342data. 343This is to be used for performance testing. 344.El 345.It Ic readcap 346Send the 347.Tn SCSI 348READ CAPACITY command to the device and display the device size and device 349block size. By default, READ CAPACITY(10) is 350used. If the device returns a maximum LBA of 0xffffffff, however, 351.Nm 352will automatically issue a READ CAPACITY(16), which is implemented as a 353service action of the SERVICE ACTION IN(16) opcode. The user can specify 354the minimum CDB size with the 355.Fl c 356argument. Valid values for the 357.Fl c 358option are 10 and 16. If a 10 byte CDB is specified, the request will be 359automatically reissued with a 16 byte CDB if the maximum LBA returned is 3600xffffffff. 361.It Ic modesense 362Send a 363.Tn SCSI 364MODE SENSE command to the device, and display the requested mode page(s) or 365page list. 366.Bl -tag -width 10n 367.It Fl m Ar page 368Specify the mode page to display. This option and the 369.Fl l 370option are mutually exclusive. One of the two must be specified, though. 371Mode page numbers may be specified in decimal or hexadecimal. 372.It Fl l 373Request that the list of mode pages supported by the device be returned. 374This option and the 375.Fl m 376option are mutually exclusive. One of the two must be specified, though. 377.It Fl P Ar pc 378Specify the mode page control value. Possible values are: 379.Bl -tag -width 2n -compact 380.It 0 381Current values. 382.It 1 383Changeable value bitmask. 384.It 2 385Default values. 386.It 3 387Saved values. 388.El 389.It Fl d 390Disable block descriptors when sending the mode sense request. 391.It Fl S Ar subpage 392Specify the subpage used with the mode sense request. 393.It Fl c Ar cdbsize 394Specify the CDB size used for the mode sense request. Supported values are 3956 and 10. 396.El 397.It Ic start 398Send the 399.Tn SCSI 400START STOP UNIT command to the specified LUN with the start 401bit set. 402.Bl -tag -width 4n 403.It Fl i 404Set the immediate bit in the CDB. Note that CTL does not support the 405immediate bit, so this is primarily useful for making sure that CTL returns 406the proper error. 407.El 408.It Ic stop 409Send the 410.Tn SCSI 411START STOP UNIT command to the specified LUN with the start 412bit cleared. We use an ordered tag to stop the LUN, so we can guarantee 413that all pending I/O executes before it is stopped. (CTL guarantees this 414anyway, but 415.Nm 416sends an ordered tag for completeness.) 417.Bl -tag -width 4n 418.It Fl i 419Set the immediate bit in the CDB. Note that CTL does not support the 420immediate bit, so this is primarily useful for making sure that CTL returns 421the proper error. 422.El 423.It Ic synccache 424Send the 425.Tn SCSI 426SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE 427CACHE(10) is used. If the specified starting LBA is greater than 4280xffffffff or the length is greater than 0xffff, though, 429SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used 430if the user specifies a 16 byte CDB with the 431.Fl c 432argument. 433.Bl -tag -width 14n 434.It Fl l Ar lba 435Specify the starting LBA 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 b Ar blockcount 439Specify the length of the cache region to synchronize. This option is a 440no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the 441cache for the entire LUN. 442.It Fl r 443Specify relative addressing for the starting LBA. CTL does not support 444relative addressing, since it only works for linked commands, and CTL 445does not support linked commands. 446.It Fl i 447Tell the target to return status immediately after issuing the SYNCHRONIZE CACHE 448command rather than waiting for the cache to finish syncing. CTL does not 449support this bit. 450.It Fl c Ar cdbsize 451Specify the minimum CDB size. Valid values are 10 and 16 bytes. 452.El 453.It Ic lunlist 454List all LUNs registered with CTL. 455Because this command uses the ioctl port, it will only work when the FETDs 456(Front End Target Drivers) are enabled. 457This command is the equivalent of doing a REPORT LUNS on one LUN and then 458an INQUIRY on each LUN in the system. 459.It Ic delay 460Delay commands at the given location. There are two places where commands 461may be delayed currently: before data is transferred 462.Pq Dq datamove 463and just prior to sending status to the host 464.Pq Dq done . 465One of the two must be supplied as an argument to the 466.Fl l 467option. The 468.Fl t 469option must also be specified. 470.Bl -tag -width 12n 471.It Fl l Ar delayloc 472Delay command(s) at the specified location. 473This can either be at the data movement stage (datamove) or prior to 474command completion (done). 475.It Fl t Ar delaytime 476Delay command(s) for the specified number of seconds. This must be 477specified. If set to 0, it will clear out any previously set delay for 478this particular location (datamove or done). 479.It Fl T Ar delaytype 480Specify the delay type. 481By default, the 482.Ic delay 483option will delay the next command sent to the given LUN. 484With the 485.Fl T Ar cont 486option, every command will be delayed by the specified period of time. 487With the 488.Fl T Ar oneshot 489the next command sent to the given LUN will be delayed and all subsequent 490commands will be completed normally. 491This is the default. 492.El 493.It Ic inject 494Inject the specified type of error for the LUN specified, when a command 495that matches the given pattern is seen. 496The sense data returned is in either fixed or descriptor format, depending 497upon the status of the D_SENSE bit in the control mode page (page 0xa) for 498the LUN. 499.Pp 500Errors are only injected for commands that have not already failed for 501other reasons. 502By default, only the first command matching the pattern specified is 503returned with the supplied error. 504.Pp 505If the 506.Fl c 507flag is specified, all commands matching the pattern will be returned with 508the specified error until the error injection command is deleted with 509.Fl d 510flag. 511.Bl -tag -width 17n 512.It Fl i Ar action 513Specify the error to return: 514.Bl -tag -width 10n 515.It aborted 516Return the next matching command on the specified LUN with the sense key 517ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect 518failure"). 519.It mediumerr 520Return the next matching command on the specified LUN with the sense key 521MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for 522reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed") 523for write errors. 524.It ua 525Return the next matching command on the specified LUN with the sense key 526UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS 527DEVICE RESET OCCURRED"). 528.It custom 529Return the next matching command on the specified LUN with the supplied 530sense data. 531The 532.Fl s 533argument must be specified. 534.El 535.It Fl p Ar pattern 536Specify which commands should be returned with the given error. 537.Bl -tag -width 10n 538.It read 539The error should apply to READ(6), READ(10), READ(12), READ(16), etc. 540.It write 541The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE 542AND VERIFY(10), etc. 543.It rw 544The error should apply to both read and write type commands. 545.It readcap 546The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands. 547.It tur 548The error should apply to TEST UNIT READY commands. 549.It any 550The error should apply to any command. 551.El 552.It Fl r Ar lba,len 553Specify the starting lba and length of the range of LBAs which should 554trigger an error. 555This option is only applies when read and/or write patterns are specified. 556If used with other command types, the error will never be triggered. 557.It Fl s Ar len fmt Op Ar args 558Specify the sense data that is to be returned for custom actions. 559If the format is 560.Sq - , 561len bytes of sense data will be read from standard input and written to the 562sense buffer. 563If len is longer than 252 bytes (the maximum allowable 564.Tn SCSI 565sense data length), it will be truncated to that length. 566The sense data format is described in 567.Xr cam_cdbparse 3 . 568.It Fl c 569The error injection should be persistent, instead of happening once. 570Persistent errors must be deleted with the 571.Fl d 572argument. 573.It Fl d Ar delete_id 574Delete the specified error injection serial number. 575The serial number is returned when the error is injected. 576.El 577.It Ic port 578Perform one of several CTL frontend port operations. 579Either get a list of frontend ports 580.Pq Fl l , 581turn one or more frontends on 582or off 583.Pq Fl o Ar on|off , 584or set the World Wide Node Name 585.Pq Fl w Ar wwnn 586or World Wide Port Name 587.Pq Fl W Ar wwpn 588for a given port. 589One of 590.Fl l , 591.Fl o , 592or 593.Fl w 594or 595.Fl W 596must be specified. 597The WWNN and WWPN may both be specified at the same time, but cannot be 598combined with enabling/disabling or listing ports. 599.Bl -tag -width 12n 600.It Fl c 601Create new frontend port using free pp and vp=0. 602.It Fl o Ar on|off 603Turn the specified CTL frontend ports on or off. 604If no port number or port type is specified, all ports are turned on or 605off. 606.It Fl O Ar pp|vp 607Specify generic options on the ioctl frontend port. 608At present, only pp and vp port numbers can be set. 609.It Fl p Ar targ_port 610Specify the frontend port number. 611The port numbers can be found in the frontend port list. 612.It Fl r 613Remove port specified with 614.Pq Fl p Ar targ_port . 615.It Fl t Ar fe_type 616Specify the frontend type. 617Currently defined port types are 618.Dq fc 619(Fibre Channel), 620.Dq scsi 621(Parallel SCSI), 622.Dq ioctl 623(CTL ioctl interface), 624and 625.Dq internal 626(CTL CAM SIM). 627.It Fl w Ar wwnn 628Set the World Wide Node Name for the given port. 629The 630.Fl n 631argument must be specified, since this is only possible to implement on a 632single port. 633As a general rule, the WWNN should be the same across all ports on the 634system. 635.It Fl W Ar wwpn 636Set the World Wide Port Name for the given port. 637The 638.Fl n 639argument must be specified, since this is only possible to implement on a 640single port. 641As a general rule, the WWPN must be different for every port in the system. 642.El 643.It Ic portlist 644List CTL frontend ports. 645.Bl -tag -width 12n 646.It Fl f Ar frontend 647Specify the frontend type. 648.It Fl i 649Report target and connected initiators addresses. 650.It Fl l 651Report LUN mapping. 652.It Fl p Ar targ_port 653Specify the frontend port number. 654.It Fl q 655Omit the header in the port list output. 656.It Fl v 657Enable verbose output (report all port options). 658.It Fl x 659Output the port list in XML format. 660.El 661.It Ic lunmap 662Change LUN mapping for specified port. 663If both 664.Ar pLUN 665and 666.Ar cLUN 667are specified -- LUN will be mapped. 668If 669.Ar pLUN 670is specified, but 671.Ar cLUN 672is not -- LUN will be unmapped. 673If neither 674.Ar pLUN 675nor 676.Ar cLUN 677are specified -- LUN mapping will be disabled, exposing all CTL LUNs. 678.Bl -tag -width 12n 679.It Fl p Ar targ_port 680Specify the frontend port number. 681.It Fl l Ar pLUN 682LUN number visible by specified port. 683.It Fl L Ar cLUN 684CTL LUN number. 685.El 686.It Ic dumpooa 687Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL. 688.It Ic dumpstructs 689Dump the CTL structures to the console. 690.It Ic create 691Create a new LUN. 692The backend must be specified, and depending upon the backend requested, 693some of the other options may be required. 694If the LUN is created successfully, the LUN configuration will be 695displayed. 696If LUN creation fails, a message will be displayed describing the failure. 697.Bl -tag -width 14n 698.It Fl b Ar backend 699The 700.Fl b 701flag is required. 702This specifies the name backend to use when creating the LUN. 703Examples are 704.Dq ramdisk 705and 706.Dq block . 707.It Fl B Ar blocksize 708Specify the blocksize of the backend in bytes. 709.It Fl d Ar device_id 710Specify the LUN-associated string to use in the 711.Tn SCSI 712INQUIRY VPD page 0x83 data. 713.It Fl l Ar lun_id 714Request that a particular LUN number be assigned. 715If the requested LUN number is not available, the request will fail. 716.It Fl o Ar name=value 717Specify a backend-specific name/value pair. 718Multiple 719.Fl o 720arguments may be specified. 721Refer to the backend documentation for arguments that may be used. 722.It Fl s Ar size_bytes 723Specify the size of the LUN in bytes. 724Some backends may allow setting the size (e.g. the ramdisk backend) and for 725others the size may be implicit (e.g. the block backend). 726.It Fl S Ar serial_num 727Specify the serial number to be used in the 728.Tn SCSI 729INQUIRY VPD page 0x80 data. 730.It Fl t Ar device_type 731Specify the numeric SCSI device type to use when creating the LUN. 732If this flag is not used, the type of LUN created is backend-specific. 733Not all LUN types are supported. 734Currently CTL supports Direct Access (type 0), Processor (type 3) 735and CD/DVD (type 5) LUNs. 736The backend requested may or may not support all of the LUN types that CTL 737supports. 738.El 739.It Ic remove 740Remove a LUN. 741The backend must be specified, and the LUN number must also be specified. 742Backend-specific options may also be specified with the 743.Fl o 744flag. 745.Bl -tag -width 14n 746.It Fl b Ar backend 747Specify the backend that owns the LUN to be removed. 748Examples are 749.Dq ramdisk 750and 751.Dq block . 752.It Fl l Ar lun_id 753Specify the LUN number to remove. 754.It Fl o Ar name=value 755Specify a backend-specific name/value pair. 756Multiple 757.Fl o 758arguments may be specified. 759Refer to the backend documentation for arguments that may be used. 760.El 761.It Ic modify 762Modify a LUN size. 763The backend, the LUN number, and the size must be specified. 764.Bl -tag -width 14n 765.It Fl b Ar backend 766Specify the backend that owns the LUN to be modified. 767Examples are 768.Dq ramdisk 769and 770.Dq block . 771.It Fl l Ar lun_id 772Specify the LUN number to modify. 773.It Fl o Ar name=value 774Specify a backend-specific name/value pair. 775Multiple 776.Fl o 777arguments may be specified. 778Refer to the backend documentation for arguments that may be used. 779.It Fl s Ar size_bytes 780Specify the size of the LUN in bytes. 781For the 782.Dq block 783backend, an 784.Dq auto 785keyword may be passed instead; this will make CTL use the size of backing 786file or device. 787.El 788.It Ic devlist 789Get a list of all configured LUNs. 790This also includes the LUN size and blocksize, serial number and device ID. 791.Bl -tag -width 11n 792.It Fl b Ar backend 793Specify the backend. 794This restricts the LUN list to the named backend. 795Examples are 796.Dq ramdisk 797and 798.Dq block . 799.It Fl v 800Be verbose. 801This will also display any backend-specific LUN attributes in addition to 802the standard per-LUN information. 803.It Fl x 804Dump the raw XML. 805The LUN list information from the kernel comes in XML format, and this 806option allows the display of the raw XML data. 807This option and the 808.Fl v 809and 810.Fl b 811options are mutually exclusive. 812If you specify 813.Fl x , 814the entire LUN database is displayed in XML format. 815.El 816.It Ic islist 817Get a list of currently running iSCSI sessions. 818This includes initiator and target names and the unique connection IDs. 819.Bl -tag -width 11n 820.It Fl v 821Verbose mode. 822.It Fl x 823Dump the raw XML. 824The sessions list information from the kernel comes in XML format, and this 825option allows the display of the raw XML data. 826.El 827.It Ic islogout 828Ask the initiator to log out iSCSI sessions matching criteria. 829.Bl -tag -width 11n 830.It Fl a 831Log out 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 isterminate 840Forcibly terminate iSCSI sessions matching criteria. 841.Bl -tag -width 11n 842.It Fl a 843Terminate all sessions. 844.It Fl c 845Specify connection ID. 846.It Fl i 847Specify initiator name. 848.It Fl p 849Specify initiator portal (hostname or IP address). 850.El 851.It Ic help 852Display 853.Nm 854usage information. 855.El 856.Sh OPTIONS 857Number of additional configuration options may be specified for LUNs. 858Some options are global, others are backend-specific. 859.Pp 860Global options: 861.Bl -tag -width 12n 862.It Va vendor 863Specifies LUN vendor string up to 8 chars. 864.It Va product 865Specifies LUN product string up to 16 chars. 866.It Va revision 867Specifies LUN revision string up to 4 chars. 868.It Va scsiname 869Specifies LUN SCSI name string. 870.It Va eui 871Specifies LUN EUI-64 identifier. 872.It Va naa 873Specifies LUN NAA identifier. 874.It Va uuid 875Specifies LUN locally assigned RFC 4122 UUID identifier. 876EUI, NAA or UUID identifier should be set to UNIQUE value to allow 877EXTENDED COPY command access the LUN. 878Non-unique LUN identifiers may lead to data corruption. 879Some initiators may not support later introduced UUID identifiers. 880.It Va ha_role 881Setting to "primary" or "secondary" overrides default role of the node 882in HA cluster, set by kern.cam.ctl.ha_role sysctl. 883.It Va insecure_tpc 884Setting to "on" allows EXTENDED COPY command sent to this LUN access 885other LUNs on this host, not accessible otherwise. 886This allows to offload copying between different iSCSI targets residing 887on the same host in trusted environments. 888.It Va readcache 889Set to "off", disables read caching for the LUN, if supported by the backend. 890.It Va readonly 891Set to "on", blocks all media write operations to the LUN, reporting it 892as write protected. 893.It Va removable 894Set to "on", makes LUN removable. 895.It Va reordering 896Set to "unrestricted", allows target to process commands with SIMPLE task 897attribute in arbitrary order. Any data integrity exposures related to 898command sequence order shall be explicitly handled by the application 899client through the selection of appropriate commands and task attributes. 900The default value is "restricted". It improves data integrity, but may 901introduce some additional delays. 902.It Va serseq 903Set to "on" to serialize consecutive reads/writes. 904Set to "read" to serialize consecutive reads. 905Set to "off" to allow them be issued in parallel. 906Parallel issue of consecutive operations may confuse logic of the 907backing file system, hurting performance; but it may improve performance 908of backing stores without prefetch/write-back. 909.It Va pblocksize 910.It Va pblockoffset 911Specify physical block size and offset of the device. 912.It Va ublocksize 913.It Va ublockoffset 914Specify UNMAP block size and offset of the device. 915.It Va rpm 916Specifies medium rotation rate of the device: 0 -- not reported, 9171 -- non-rotating (SSD), >1024 -- value in revolutions per minute. 918.It Va formfactor 919Specifies nominal form factor of the device: 0 -- not reported, 1 -- 5.25", 9202 -- 3.5", 3 -- 2.5", 4 -- 1.8", 5 -- less then 1.8". 921.It Va temperature 922.It Va reftemperature 923Specify current and reference (maximum) temperatures of the device. 924.It Va provisioning_type 925When UNMAP support is enabled, this option specifies provisioning type: 926"resource", "thin" or "unknown". 927Default value is "thin". 928Logical units without UNMAP support are reported as fully provisioned. 929.It Va unmap 930Setting to "on" or "off" controls UNMAP support for the logical unit. 931Default value is "on" if supported by the backend. 932.It Va unmap_max_lba 933.It Va unmap_max_descr 934Specify maximum allowed number of LBAs and block descriptors per UNMAP 935command to report in Block Limits VPD page. 936.It Va write_same_max_lba 937Specify maximum allowed number of LBAs per WRITE SAME command to report 938in Block Limits VPD page. 939.It Va avail-threshold 940.It Va used-threshold 941.It Va pool-avail-threshold 942.It Va pool-used-threshold 943Set per-LUN/-pool thin provisioning soft thresholds. 944LUN will establish UNIT ATTENTION condition if its or pool available space 945get below configured avail values, or its or pool used space get above 946configured used values. 947Pool thresholds are working only for ZVOL-backed LUNs. 948.It Va writecache 949Set to "off", disables write caching for the LUN, if supported by the backend. 950.El 951.Pp 952Options specific for block backend: 953.Bl -tag -width 12n 954.It Va file 955Specifies file or device name to use for backing store. 956.It Va num_threads 957Specifies number of backend threads to use for this LUN. 958.El 959.Pp 960Options specific for ramdisk backend: 961.Bl -tag -width 12n 962.It Va capacity 963Specifies capacity of backing store (maximum RAM for data). 964The default value is zero, that disables backing store completely, 965making all writes go to nowhere, while all reads return zeroes. 966.El 967.Sh EXAMPLES 968.Pp 969Send a 970.Tn SCSI 971TEST UNIT READY command to LUN 1. 972.Pp 973.Dl ctladm tur 1 974.Pp 975Display the list of mode pages supported by LUN 1. 976.Pp 977.Dl ctladm modesense 1 -l 978.Pp 979Display the saved version of the Control mode page (page 10) on LUN 0. 980Disable fetching block descriptors, and use a 10 byte MODE SENSE command 981instead of the default 6 byte command. 982.Pp 983.Dl ctladm modesense 0 -m 10 -P 3 -d -c 10 984.Pp 985Read the first 512 byte block from LUN 2 and dump it to the file 986.Bd -literal 987.Dl ctladm read 2 -l 0 -d 1 -b 512 -f - > foo 988.Ed 989.Pp 990Read 10240 bytes from the file 991.Pa /tmp/bar 992and write it to LUN 3. 993starting at LBA 0xff432140. 994.Pp 995.Bd -literal 996.Dl ctladm write 3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar 997.Ed 998.Pp 999Create a LUN with the 1000.Dq fake 1001ramdisk as a backing store. 1002The LUN will claim to have a size of approximately 10 terabytes, 1003while having no real data store (all written data are lost). 1004.Pp 1005.Dl ctladm create -b ramdisk -s 10485760000000000 1006.Pp 1007Create a thin provisioned LUN with a ramdisk as a backing store. 1008The LUN will have maximal backing store capacity of 10 gigabytes, 1009while reporting size of 10 terabytes, 1010.Pp 1011.Dl ctladm create -b ramdisk -s 10T -o capacity=10G 1012.Pp 1013Create a LUN using the block backend, and specify the file 1014.Pa src/usr.sbin/ctladm/ctladm.8 1015as the backing store. 1016The size of the LUN will be derived from the size of the file. 1017.Pp 1018.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 1019.Pp 1020Create a LUN using the block backend, specify the file 1021.Pa src/usr.sbin/ctladm/ctladm.8 1022as the backing store, and specify the 1023.Tn SCSI 1024VPD page 0x80 and 0x83 serial number 1025.Fl ( S ) 1026and device ID 1027.Fl ( d ) . 1028.Pp 1029.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123 1030.Pp 1031Use to specify generic options on ioctl frontend port, now it is 1032only possible to set pp and/or vp port number. 1033.Pp 1034.Dl ctladm port -c -O pp=11 -O vp=12 1035.Pp 1036Remove specified targ_port. 1037.Pp 1038.Dl ctladm port -r -p 4 1039.Pp 1040.Pp 1041Remove LUN 12, which is handled by the block backend, from the system. 1042.Pp 1043.Dl ctladm remove -b block -l 12 1044.Pp 1045List configured LUNs in the system, along with their backend and serial 1046number. 1047This works when the Front End Target Drivers are enabled or disabled. 1048.Pp 1049.Dl ctladm devlist 1050.Pp 1051List all LUNs in the system, along with their inquiry data and device type. 1052This only works when the FETDs are enabled, since the commands go through the 1053ioctl port. 1054.Pp 1055.Dl ctladm lunlist 1056.Pp 1057Inject a medium error on LUN 6 for every read that covers the first 512 1058blocks of the LUN. 1059.Pp 1060.Dl ctladm inject 6 -i mediumerr -p read -r 0,512 -c 1061.Pp 1062Inject a custom error on LUN 6 for the next TEST UNIT READY command only. 1063This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of 10640x04,0x02 ("Logical unit not ready, initializing command required"). 1065.Pp 1066.Bd -literal -offset indent 1067ctladm inject 6 -i custom -p tur -s 18 "f0 0 02 s12 04 02" 1068.Ed 1069.Sh SEE ALSO 1070.Xr cam 3 , 1071.Xr cam_cdbparse 3 , 1072.Xr cam 4 , 1073.Xr ctl 4 , 1074.Xr xpt 4 , 1075.Xr camcontrol 8 , 1076.Xr ctld 8 , 1077.Xr ctlstat 8 1078.Sh HISTORY 1079The 1080.Nm 1081utility was originally written during the Winter/Spring of 2003 as an 1082interface to CTL. 1083.Sh AUTHORS 1084.An Ken Merry Aq Mt ken@FreeBSD.org 1085