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