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