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