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