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 March 6, 2012 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 dumpooa 197.Nm 198.Ic dumpstructs 199.Nm 200.Ic help 201.Sh DESCRIPTION 202The 203.Nm 204utility is designed to provide a way to access and control the CAM Target 205Layer (CTL). 206It provides a way to send 207.Tn SCSI 208commands to the CTL layer, and also provides 209some meta-commands that utilize 210.Tn SCSI 211commands. 212(For instance, the 213.Ic lunlist 214command is implemented using the 215.Tn SCSI 216REPORT LUNS and INQUIRY commands.) 217.Pp 218The 219.Nm 220utility has a number of primary functions, many of which require a device 221identifier. 222The device identifier takes the following form: 223.Bl -tag -width 14n 224.It target:lun 225Specify the target (almost always 0) and LUN number to operate on. 226.El 227Many of the primary functions of the 228.Nm 229utility take the following optional arguments: 230.Pp 231.Bl -tag -width 10n 232.It Fl C Ar retries 233Specify the number of times to retry a command in the event of failure. 234.It Fl D Ar device 235Specify the device to open. This allows opening a device other than the 236default device, 237.Pa /dev/cam/ctl , 238to be opened for sending commands. 239.It Fl I Ar id 240Specify the initiator number to use. 241By default, 242.Nm 243will use 7 as the initiator number. 244.El 245.Pp 246Primary commands: 247.Bl -tag -width 11n 248.It Ic tur 249Send the 250.Tn SCSI 251TEST UNIT READY command to the device and report whether or not it is 252ready. 253.It Ic inquiry 254Send the 255.Tn SCSI 256INQUIRY command to the device and display some of the returned inquiry 257data. 258.It Ic reqsense 259Send the 260.Tn SCSI 261REQUEST SENSE command to the device and display the returned sense 262information. 263.It Ic reportluns 264Send the 265.Tn SCSI 266REPORT LUNS command to the device and display supported LUNs. 267.It Ic read 268Send a 269.Tn SCSI 270READ command to the device, and write the requested data to a file or 271stdout. 272.Bl -tag -width 12n 273.It Fl l Ar lba 274Specify the starting Logical Block Address for the READ. This can be 275specified in decimal, octal (starting with 0), hexadecimal (starting with 2760x) or any other base supported by 277.Xr strtoull 3 . 278.It Fl d Ar datalen 279Specify the length, in 512 byte blocks, of the READ request. 280.It Fl f Ar file 281Specify the destination for the data read by the READ command. Either a 282filename or 283.Sq - 284for stdout may be specified. 285.It Fl c Ar cdbsize 286Specify the minimum 287.Tn SCSI 288CDB (Command Data Block) size to be used for the READ request. Allowable 289values are 6, 10, 12 and 16. Depending upon the LBA and amount of data 290requested, a larger CDB size may be used to satisfy the request. (e.g., 291for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) 292.It Fl b Ar blocksize 293Specify the blocksize of the underlying 294.Tn SCSI 295device, so the transfer length 296can be calculated accurately. The blocksize can be obtained via the 297.Tn SCSI 298READ CAPACITY command. 299.It Fl N 300Do not copy data to 301.Nm 302from the kernel when doing a read, just execute the command without copying 303data. 304This is to be used for performance testing. 305.El 306.It Ic write 307Read data from a file or stdin, and write the data to the device using the 308.Tn SCSI 309WRITE command. 310.Bl -tag -width 12n 311.It Fl l Ar lba 312Specify the starting Logical Block Address for the WRITE. This can be 313specified in decimal, octal (starting with 0), hexadecimal (starting with 3140x) or any other base supported by 315.Xr strtoull 3 . 316.It Fl d Ar atalen 317Specify the length, in 512 byte blocks, of the WRITE request. 318.It Fl f Ar file 319Specify the source for the data to be written by the WRITE command. Either a 320filename or 321.Sq - 322for stdin may be specified. 323.It Fl c Ar cdbsize 324Specify the minimum 325.Tn SCSI 326CDB (Command Data Block) size to be used for the READ request. Allowable 327values are 6, 10, 12 and 16. Depending upon the LBA and amount of data 328requested, a larger CDB size may be used to satisfy the request. (e.g., 329for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) 330.It Fl b Ar blocksize 331Specify the blocksize of the underlying 332.Tn SCSI 333device, so the transfer length 334can be calculated accurately. The blocksize can be obtained via the 335.Tn SCSI 336READ CAPACITY command. 337.It Fl N 338Do not copy data to 339.Nm 340to the kernel when doing a write, just execute the command without copying 341data. 342This is to be used for performance testing. 343.El 344.It Ic bbrread 345Issue a SCSI READ command to the logical device to potentially force a bad 346block on a disk in the RAID set to be reconstructed from the other disks in 347the array. This command should only be used on an array that is in the 348normal state. If used on a critical array, it could cause the array to go 349offline if the bad block to be remapped is on one of the disks that is 350still active in the array. 351.Pp 352The data for this particular command will be discarded, and not returned to 353the user. 354.Pp 355In order to determine which LUN to read from, the user should first 356determine which LUN the disk with a bad block belongs to. Then he should 357map the bad disk block back to the logical block address for the array in 358order to determine which LBA to pass in to the 359.Ic bbrread 360command. 361.Pp 362This command is primarily intended for testing. In practice, bad block 363remapping will generally be triggered by the in-kernel Disk Aerobics and 364Disk Scrubbing code. 365.Bl -tag -width 10n 366.It Fl l Ar lba 367Specify the starting Logical Block Address. 368.It Fl d Ar datalen 369Specify the amount of data in bytes to read from the LUN. This must be a 370multiple of the LUN blocksize. 371.El 372.It Ic readcap 373Send the 374.Tn SCSI 375READ CAPACITY command to the device and display the device size and device 376block size. By default, READ CAPACITY(10) is 377used. If the device returns a maximum LBA of 0xffffffff, however, 378.Nm 379will automatically issue a READ CAPACITY(16), which is implemented as a 380service action of the SERVICE ACTION IN(16) opcode. The user can specify 381the minimum CDB size with the 382.Fl c 383argument. Valid values for the 384.Fl c 385option are 10 and 16. If a 10 byte CDB is specified, the request will be 386automatically reissued with a 16 byte CDB if the maximum LBA returned is 3870xffffffff. 388.It Ic modesense 389Send a 390.Tn SCSI 391MODE SENSE command to the device, and display the requested mode page(s) or 392page list. 393.Bl -tag -width 10n 394.It Fl m Ar page 395Specify the mode page to display. This option and the 396.Fl l 397option are mutually exclusive. One of the two must be specified, though. 398Mode page numbers may be specified in decimal or hexadecimal. 399.It Fl l 400Request that the list of mode pages supported by the device be returned. 401This option and the 402.Fl m 403option are mutually exclusive. One of the two must be specified, though. 404.It Fl P Ar pc 405Specify the mode page page control value. Possible values are: 406.Bl -tag -width 2n -compact 407.It 0 408Current values. 409.It 1 410Changeable value bitmask. 411.It 2 412Default values. 413.It 3 414Saved values. 415.El 416.It Fl d 417Disable block descriptors when sending the mode sense request. 418.It Fl S Ar subpage 419Specify the subpage used with the mode sense request. 420.It Fl c Ar cdbsize 421Specify the CDB size used for the mode sense request. Supported values are 4226 and 10. 423.El 424.It Ic start 425Send the 426.Tn SCSI 427START STOP UNIT command to the specified LUN with the start 428bit set. 429.Bl -tag -width 4n 430.It Fl i 431Set the immediate bit in the CDB. Note that CTL does not support the 432immediate bit, so this is primarily useful for making sure that CTL returns 433the proper error. 434.It Fl o 435Set the Copan proprietary on/offline bit in the CDB. When this flag is 436used, the LUN will be marked online again (see the description of the 437.Ic shutdown 438and 439.Ic startup 440commands). When this flag is used with a 441start command, the LUN will NOT be spun up. You need to use a start 442command without the 443.Fl o 444flag to spin up the disks in the LUN. 445.El 446.It Ic stop 447Send the 448.Tn SCSI 449START STOP UNIT command to the specified LUN with the start 450bit cleared. We use an ordered tag to stop the LUN, so we can guarantee 451that all pending I/O executes before it is stopped. (CTL guarantees this 452anyway, but 453.Nm 454sends an ordered tag for completeness.) 455.Bl -tag -width 4n 456.It Fl i 457Set the immediate bit in the CDB. Note that CTL does not support the 458immediate bit, so this is primarily useful for making sure that CTL returns 459the proper error. 460.It Fl o 461Set the Copan proprietary on/offline bit in the CDB. When this flag is 462used, the LUN will be spun down and taken offline ("Logical unit not ready, 463manual intervention required"). See the description of the 464.Ic shutdown 465and 466.Ic startup 467options. 468.El 469.It Ic synccache 470Send the 471.Tn SCSI 472SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE 473CACHE(10) is used. If the specified starting LBA is greater than 4740xffffffff or the length is greater than 0xffff, though, 475SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used 476if the user specifies a 16 byte CDB with the 477.Fl c 478argument. 479.Bl -tag -width 14n 480.It Fl l Ar lba 481Specify the starting LBA of the cache region to synchronize. This option is a 482no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the 483cache for the entire LUN. 484.It Fl b Ar blockcount 485Specify the length of the cache region to synchronize. This option is a 486no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the 487cache for the entire LUN. 488.It Fl r 489Specify relative addressing for the starting LBA. CTL does not support 490relative addressing, since it only works for linked commands, and CTL 491doesn't support linked commands. 492.It Fl i 493Tell the target to return status immediately after issuing the SYHCHRONIZE CACHE 494command rather than waiting for the cache to finish syncing. CTL does not 495support this bit. 496.It Fl c Ar cdbsize 497Specify the minimum CDB size. Valid values are 10 and 16 bytes. 498.El 499.It Ic shutdown 500Issue a 501.Tn SCSI 502START STOP UNIT command with the start bit cleared and the on/offline bit 503set to all direct access LUNs. This will spin down all direct access LUNs, 504and mark them offline ("Logical unit not ready, manual intervention 505required"). Once marked offline, the state can only be cleared by sending 506a START STOP UNIT command with the start bit set and the on/offline bit 507set. The 508.Nm 509commands 510.Ic startup 511and 512.Ic start 513will accomplish this. Note that the 514on/offline bit is a non-standard Copan extension to the 515.Tn SCSI 516START STOP UNIT command, so merely sending a normal start command from an 517initiator will not clear the condition. (This is by design.) 518.It Ic startup 519Issue a 520.Tn SCSI 521START STOP UNIT command with the start bit set and the on/offline bit set 522to all direct access LUNs. This will mark all direct access LUNs "online" 523again. It will not cause any LUNs to start up. A separate start command 524without the on/offline bit set is necessary for that. 525.It Ic hardstop 526Use the kernel facility for stopping all direct access LUNs and setting the 527offline bit. Unlike the 528.Ic shutdown 529command above, this command allows shutting down LUNs with I/O active. It 530will also issue a LUN reset to any reserved LUNs to break the reservation 531so that the LUN can be stopped. 532.Ic shutdown 533command instead. 534.It Ic hardstart 535This command is functionally identical to the 536.Ic startup 537command described above. The primary difference is that the LUNs are 538enumerated and commands sent by the in-kernel Front End Target Driver 539instead of by 540.Nm . 541.It Ic lunlist 542List all LUNs registered with CTL. 543Because this command uses the ioctl port, it will only work when the FETDs 544(Front End Target Drivers) are enabled. 545This command is the equivalent of doing a REPORT LUNS on one LUN and then 546and then an INQUIRY on each LUN in the system. 547.It Ic delay 548Delay commands at the given location. There are two places where commands 549may be delayed currently: before data is transferred 550.Pq Dq datamove 551and just prior to sending status to the host 552.Pq Dq done . 553One of the two must be supplied as an argument to the 554.Fl l 555option. The 556.Fl t 557option must also be specified. 558.Bl -tag -width 12n 559.It Fl l Ar delayloc 560Delay command(s) at the specified location. 561This can either be at the data movement stage (datamove) or prior to 562command completion (done). 563.It Fl t Ar delaytime 564Delay command(s) for the specified number of seconds. This must be 565specified. If set to 0, it will clear out any previously set delay for 566this particular location (datamove or done). 567.It Fl T Ar delaytype 568Specify the delay type. 569By default, the 570.Ic delay 571option will delay the next command sent to the given LUN. 572With the 573.Fl T Ar cont 574option, every command will be delayed by the specified period of time. 575With the 576.Fl T Ar oneshot 577the next command sent to the given LUN will be delayed and all subsequent 578commands will be completed normally. 579This is the default. 580.El 581.It Ic realsync 582Query and control CTL's SYNCHRONIZE CACHE behavior. The 583.Sq query 584argument 585will show whether SYNCHRONIZE CACHE commands are being sent to the backend 586or not. 587The default is to send SYNCHRONIZE CACHE commands to the backend. 588The 589.Sq on 590argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be 591sent to the backend. 592The 593.Sq off 594argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be 595immediately returned to the initiator with successful status. 596.It Ic setsync 597For a given lun, only actually service every Nth SYNCHRONIZE CACHE command 598that is sent. This can be used for debugging the optimal time period for 599sending SYNCHRONIZE cache commands. An interval of 0 means that the cache 600will be flushed for this LUN every time a SYNCHRONIZE CACHE command is 601received. 602.Pp 603You must specify the target and LUN you want to modify. 604.It Ic getsync 605Get the interval at which we actually service the SYNCHRONIZE CACHE 606command, as set by the 607.Ic setsync 608command above. 609The reported number means that we will actually flush the cache on every 610Nth SYNCHRONIZE CACHE command. A value of 0 means that we will flush the 611cache every time. 612.Pp 613You must specify the target and LUN you want to query. 614.It Ic inject 615Inject the specified type of error for the LUN specified, when a command 616that matches the given pattern is seen. 617The sense data returned is in either fixed or descriptor format, depending 618upon the status of the D_SENSE bit in the control mode page (page 0xa) for 619the LUN. 620.Pp 621Errors are only injected for commands that have not already failed for 622other reasons. 623By default, only the first command matching the pattern specified is 624returned with the supplied error. 625.Pp 626If the 627.Fl c 628flag is specified, all commands matching the pattern will be returned with 629the specified error until the error injection command is deleted with 630.Fl d 631flag. 632.Bl -tag -width 17n 633.It Fl i Ar action 634Specify the error to return: 635.Bl -tag -width 10n 636.It aborted 637Return the next matching command on the specified LUN with the sense key 638ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect 639failure"). 640.It mediumerr 641Return the next matching command on the specified LUN with the sense key 642MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for 643reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed") 644for write errors. 645.It ua 646Return the next matching command on the specified LUN with the sense key 647UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS 648DEVICE RESET OCCURRED"). 649.It custom 650Return the next matching command on the specified LUN with the supplied 651sense data. 652The 653.Fl s 654argument must be specified. 655.El 656.It Fl p Ar pattern 657Specify which commands should be returned with the given error. 658.Bl -tag -width 10n 659.It read 660The error should apply to READ(6), READ(10), READ(12), READ(16), etc. 661.It write 662The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE 663AND VERIFY(10), etc. 664.It rw 665The error should apply to both read and write type commands. 666.It readcap 667The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands. 668.It tur 669The error should apply to TEST UNIT READY commands. 670.It any 671The error should apply to any command. 672.El 673.It Fl r Ar lba,len 674Specify the starting lba and length of the range of LBAs which should 675trigger an error. 676This option is only applies when read and/or write patterns are specified. 677If used with other command types, the error will never be triggered. 678.It Fl s Ar len fmt Op Ar args 679Specify the sense data that is to be returned for custom actions. 680If the format is 681.Sq - , 682len bytes of sense data will be read from standard input and written to the 683sense buffer. 684If len is longer than 252 bytes (the maximum allowable 685.Tn SCSI 686sense data length), it will be truncated to that length. 687The sense data format is described in 688.Xr cam_cdparse 3 . 689.It Fl c 690The error injection should be persistent, instead of happening once. 691Persistent errors must be deleted with the 692.Fl d 693argument. 694.It Fl d Ar delete_id 695Delete the specified error injection serial number. 696The serial number is returned when the error is injected. 697.El 698.It Ic port 699Perform one of several CTL frontend port operations. 700Either get a list of frontend ports 701.Pq Fl l , 702turn one or more frontends on 703or off 704.Pq Fl o Ar on|off , 705or set the World Wide Node Name 706.Pq Fl w Ar wwnn 707or World Wide Port Name 708.Pq Fl W Ar wwpn 709for a given port. 710One of 711.Fl l , 712.Fl o , 713or 714.Fl w 715or 716.Fl W 717must be specified. 718The WWNN and WWPN may both be specified at the same time, but cannot be 719combined with enabling/disabling or listing ports. 720.Bl -tag -width 12n 721.It Fl l 722List all CTL frontend ports or a specific port type or number. 723.It Fl o Ar on|off 724Turn the specified CTL frontend ports off or on. 725If no port number or port type is specified, all ports are turned on or 726off. 727.It Fl p Ar targ_port 728Specify the frontend port number. 729The port numbers can be found in the frontend port list. 730.It Fl q 731Omit the header in the port list output. 732.It Fl t Ar fe_type 733Specify the frontend type. 734Currently defined port types are 735.Dq fc 736(Fibre Channel), 737.Dq scsi 738(Parallel SCSI), 739.Dq ioctl 740(CTL ioctl interface), 741and 742.Dq internal 743(CTL CAM SIM). 744.It Fl w Ar wwnn 745Set the World Wide Node Name for the given port. 746The 747.Fl n 748argument must be specified, since this is only possible to implement on a 749single port. 750As a general rule, the WWNN should be the same across all ports on the 751system. 752.It Fl W Ar wwpn 753Set the World Wide Node Name for the given port. 754The 755.Fl n 756argument must be specified, since this is only possible to implement on a 757single port. 758As a general rule, the WWPN must be different for every port in the system. 759.It Fl x 760Output the port list in XML format. 761.El 762.It Ic dumpooa 763Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL. 764.It Ic dumpstructs 765Dump the CTL structures to the console. 766.It Ic create 767Create a new LUN. 768The backend must be specified, and depending upon the backend requested, 769some of the other options may be required. 770If the LUN is created successfully, the LUN configuration will be 771displayed. 772If LUN creation fails, a message will be displayed describing the failure. 773.Bl -tag -width 14n 774.It Fl b Ar backend 775The 776.Fl b 777flag is required. 778This specifies the name backend to use when creating the LUN. 779Examples are 780.Dq ramdisk 781and 782.Dq block . 783.It Fl B Ar blocksize 784Specify the blocksize of the backend in bytes. 785.It Fl d Ar device_id 786Specify the LUN-associated string to use in the 787.Tn SCSI 788INQUIRY VPD page 0x83 data. 789.It Fl l Ar lun_id 790Request that a particular LUN number be assigned. 791If the requested LUN number is not available, the request will fail. 792.It Fl o Ar name=value 793Specify a backend-specific name/value pair. 794Multiple 795.Fl o 796arguments may be specified. 797Refer to the backend documentation for arguments that may be used. 798.It Fl s Ar size_bytes 799Specify the size of the LUN in bytes. 800Some backends may allow setting the size (e.g. the ramdisk backend) and for 801others the size may be implicit (e.g. the block backend). 802.It Fl S Ar serial_num 803Specify the serial number to be used in the 804.Tn SCSI 805INQUIRY VPD page 0x80 data. 806.It Fl t Ar device_type 807Specify the numeric SCSI device type to use when creating the LUN. 808For example, the Direct Access type is 0. 809If this flag is not used, the type of LUN created is backend-specific. 810Not all LUN types are supported. 811Currently CTL only supports Direct Access (type 0) and Processor (type 3) 812LUNs. 813The backend requested may or may not support all of the LUN types that CTL 814supports. 815.El 816.It Ic remove 817Remove a LUN. 818The backend must be specified, and the LUN number must also be specified. 819Backend-specific options may also be specified with the 820.Fl o 821flag. 822.Bl -tag -width 14n 823.It Fl b Ar backend 824Specify the backend that owns the LUN to be removed. 825Examples are 826.Dq ramdisk 827and 828.Dq block . 829.It Fl l Ar lun_id 830Specify the LUN number to remove. 831.It Fl o Ar name=value 832Specify a backend-specific name/value pair. 833Multiple 834.Fl o 835arguments may be specified. 836Refer to the backend documentation for arguments that may be used. 837.El 838.It Ic modify 839Modify a LUN size. 840The backend, the LUN number, and the size must be specified. 841.Bl -tag -width 14n 842.It Fl b Ar backend 843Specify the backend that owns the LUN to be removed. 844Examples are 845.Dq ramdisk 846and 847.Dq block . 848.It Fl l Ar lun_id 849Specify the LUN number to remove. 850.It Fl s Ar size_bytes 851Specify the size of the LUN in bytes. 852For the 853.Dq block 854backend, an 855.Dq auto 856keyword may be passed instead; this will make CTL use the size of backing 857file or device. 858.El 859.It Ic devlist 860Get a list of all configured LUNs. 861This also includes the LUN size and blocksize, serial number and device ID. 862.Bl -tag -width 11n 863.It Fl b Ar backend 864Specify the backend. 865This restricts the LUN list to the named backend. 866Examples are 867.Dq ramdisk 868and 869.Dq block . 870.It Fl v 871Be verbose. 872This will also display any backend-specific LUN attributes in addition to 873the standard per-LUN information. 874.It Fl x 875Dump the raw XML. 876The LUN list information from the kernel comes in XML format, and this 877option allows the display of the raw XML data. 878This option and the 879.Fl v 880and 881.Fl b 882options are mutually exclusive. 883If you specify 884.Fl x , 885the entire LUN database is displayed in XML format. 886.El 887.It Ic help 888Display 889.Nm 890usage information. 891.El 892.Sh EXAMPLES 893.Dl ctladm tur 0:1 894.Pp 895Send a 896.Tn SCSI 897TEST UNIT READY command to LUN 1. 898.Pp 899.Dl ctladm modesense 0:1 -l 900.Pp 901Display the list of mode pages supported by LUN 1. 902.Pp 903.Dl ctladm modesense 0:0 -m 10 -P 3 -d -c 10 904.Pp 905Display the saved version of the Control mode page (page 10) on LUN 0. 906Disable fetching block descriptors, and use a 10 byte MODE SENSE command 907instead of the default 6 byte command. 908.Pp 909.Bd -literal 910ctladm read 0:2 -l 0 -d 1 -b 512 -f - > foo 911.Ed 912.Pp 913Read the first 512 byte block from LUN 2 and dump it to the file 914.Pa foo . 915.Bd -literal 916ctladm write 0:3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar 917.Ed 918.Pp 919Read 10240 bytes from the file 920.Pa /tmp/bar 921and write it to target 0, LUN 3. 922starting at LBA 0xff432140. 923.Pp 924.Dl ctladm create -b ramdisk -s 10485760000000000 925.Pp 926Create a LUN with the 927.Dq fake 928ramdisk as a backing store. 929The LUN will claim to have a size of approximately 10 terabytes. 930.Pp 931.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 932.Pp 933Create a LUN using the block backend, and specify the file 934.Pa src/usr.sbin/ctladm/ctladm.8 935as the backing store. 936The size of the LUN will be derived from the size of the file. 937.Pp 938.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123 939.Pp 940Create a LUN using the block backend, specify the file 941.Pa src/usr.sbin/ctladm/ctladm.8 942as the backing store, and specify the 943.Tn SCSI 944VPD page 0x80 and 0x83 serial number ( 945.Fl S) 946and device ID ( 947.Fl d). 948.Pp 949.Dl ctladm remove -b block -l 12 950.Pp 951Remove LUN 12, which is handled by the block backend, from the system. 952.Pp 953.Dl ctladm devlist 954.Pp 955List configured LUNs in the system, along with their backend and serial 956number. 957This works when the Front End Target Drivers are enabled or disabled. 958.Pp 959.Dl ctladm lunlist 960.Pp 961List all LUNs in the system, along with their inquiry data and device type. 962This only works when the FETDs are enabled, since the commands go through the 963ioctl port. 964.Pp 965.Dl ctladm inject 0:6 -i mediumerr -p read -r 0,512 -c 966.Pp 967Inject a medium error on LUN 6 for every read that covers the first 512 968blocks of the LUN. 969.Pp 970.Bd -literal -offset indent 971ctladm inject 0:6 -i custom -p tur -s 18 "f0 0 02 s12 04 02" 972.Ed 973.Pp 974Inject a custom error on LUN 6 for the next TEST UNIT READY command only. 975This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of 9760x04,0x02 ("Logical unit not ready, initializing command required"). 977.Sh SEE ALSO 978.Xr cam 3 , 979.Xr cam_cdbparse 3 , 980.Xr cam 4 , 981.Xr xpt 4 , 982.Xr camcontrol 8 983.Sh HISTORY 984The 985.Nm 986utility was originally written during the Winter/Spring of 2003 as an 987interface to CTL. 988.Sh AUTHORS 989.An Ken Merry Aq ken@FreeBSD.org 990