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