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