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