diff options
Diffstat (limited to 'usr.sbin/ctladm/ctladm.8')
| -rw-r--r-- | usr.sbin/ctladm/ctladm.8 | 986 |
1 files changed, 986 insertions, 0 deletions
diff --git a/usr.sbin/ctladm/ctladm.8 b/usr.sbin/ctladm/ctladm.8 new file mode 100644 index 0000000..2e73aeb --- /dev/null +++ b/usr.sbin/ctladm/ctladm.8 @@ -0,0 +1,986 @@ +.\" +.\" Copyright (c) 2003 Silicon Graphics International Corp. +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions, and the following disclaimer, +.\" without modification. +.\" 2. Redistributions in binary form must reproduce at minimum a disclaimer +.\" substantially similar to the "NO WARRANTY" disclaimer below +.\" ("Disclaimer") and any redistribution must be conditioned upon +.\" including a substantially similar Disclaimer requirement for further +.\" binary redistribution. +.\" +.\" NO WARRANTY +.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS +.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT +.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR +.\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT +.\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, +.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING +.\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGES. +.\" +.\" ctladm utility man page. +.\" +.\" Author: Ken Merry <ken@FreeBSD.org> +.\" +.\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $ +.\" $FreeBSD$ +.\" +.Dd March 6, 2012 +.Dt CTLADM 8 +.Os +.Sh NAME +.Nm ctladm +.Nd CAM Target Layer control utility +.Sh SYNOPSIS +.Nm +.Aq Ar command +.Op target:lun +.Op generic args +.Op command args +.Nm +.Ic tur +.Aq target:lun +.Op general options +.Nm +.Ic inquiry +.Aq target:lun +.Op general options +.Nm +.Ic reqsense +.Aq target:lun +.Op general options +.Nm +.Ic reportluns +.Aq target:lun +.Op general options +.Nm +.Ic read +.Aq target:lun +.Op general options +.Aq Fl l Ar lba +.Aq Fl d Ar datalen +.Aq Fl f Ar file|- +.Aq Fl b Ar blocksize_bytes +.Op Fl c Ar cdbsize +.Op Fl N +.Nm +.Ic write +.Aq target:lun +.Op general options +.Aq Fl l Ar lba +.Aq Fl d Ar datalen +.Aq Fl f Ar file|- +.Aq Fl b Ar blocksize_bytes +.Op Fl c Ar cdbsize +.Op Fl N +.Nm +.Ic bbrread +.Aq target:lun +.Op general options +.Aq Fl -l Ar lba +.Aq Fl -d Ar datalen +.Nm +.Ic readcap +.Aq target:lun +.Op general options +.Op Fl c Ar cdbsize +.Nm +.Ic modesense +.Aq target:lun +.Aq Fl m Ar page | Fl l +.Op Fl P Ar pc +.Op Fl d +.Op Fl S Ar subpage +.Op Fl c Ar size +.Nm +.Ic start +.Aq target:lun +.Op general options +.Op Fl i +.Op Fl o +.Nm +.Ic stop +.Aq target:lun +.Op general options +.Op Fl i +.Op Fl o +.Nm +.Ic synccache +.Aq target:lun +.Op general options +.Op Fl l Ar lba +.Op Fl b Ar blockcount +.Op Fl r +.Op Fl i +.Op Fl c Ar cdbsize +.Nm +.Ic shutdown +.Op general options +.Nm +.Ic startup +.Op general options +.Nm +.Ic hardstop +.Nm +.Ic hardstart +.Nm +.Ic lunlist +.Nm +.Ic delay +.Aq target:lun +.Aq Fl l Ar datamove|done +.Aq Fl t Ar secs +.Op Fl T Ar oneshot|cont +.Nm +.Ic realsync Aq on|off|query +.Nm +.Ic setsync interval +.Aq target:lun +.Aq Fl i Ar interval +.Nm +.Ic getsync +.Aq target:lun +.Nm +.Ic inject +.Aq Fl i Ar action +.Aq Fl p Ar pattern +.Op Fl r Ar lba,len +.Op Fl s Ar len fmt Op Ar args +.Op Fl c +.Op Fl d Ar delete_id +.Nm +.Ic create +.Aq Fl b Ar backend +.Op Fl B Ar blocksize +.Op Fl d Ar device_id +.Op Fl l Ar lun_id +.Op Fl o Ar name=value +.Op Fl s Ar size_bytes +.Op Fl S Ar serial_num +.Op Fl t Ar device_type +.Nm +.Ic remove +.Aq Fl b Ar backend +.Aq Fl l Ar lun_id +.Op Fl o Ar name=value +.Nm +.Ic modify +.Aq Fl b Ar backend +.Aq Fl l Ar lun_id +.Aq Fl s Ar size_bytes +.Nm +.Ic devlist +.Op Fl b Ar backend +.Op Fl v +.Op Fl x +.Nm +.Ic port +.Op Fl l +.Op Fl o Ar on|off +.Op Fl w Ar wwpn +.Op Fl W Ar wwnn +.Op Fl p Ar targ_port +.Op Fl t Ar fe_type +.Op Fl q +.Op Fl x +.Nm +.Ic dumpooa +.Nm +.Ic dumpstructs +.Nm +.Ic help +.Sh DESCRIPTION +The +.Nm +utility is designed to provide a way to access and control the CAM Target +Layer (CTL). +It provides a way to send +.Tn SCSI +commands to the CTL layer, and also provides +some meta-commands that utilize +.Tn SCSI +commands. +(For instance, the +.Ic lunlist +command is implemented using the +.Tn SCSI +REPORT LUNS and INQUIRY commands.) +.Pp +The +.Nm +utility has a number of primary functions, many of which require a device +identifier. +The device identifier takes the following form: +.Bl -tag -width 14n +.It target:lun +Specify the target (almost always 0) and LUN number to operate on. +.El +Many of the primary functions of the +.Nm +utility take the following optional arguments: +.Bl -tag -width 10n +.It Fl C Ar retries +Specify the number of times to retry a command in the event of failure. +.It Fl D Ar device +Specify the device to open. This allows opening a device other than the +default device, +.Pa /dev/cam/ctl , +to be opened for sending commands. +.It Fl I Ar id +Specify the initiator number to use. +By default, +.Nm +will use 7 as the initiator number. +.El +.Pp +Primary commands: +.Bl -tag -width 11n +.It Ic tur +Send the +.Tn SCSI +TEST UNIT READY command to the device and report whether or not it is +ready. +.It Ic inquiry +Send the +.Tn SCSI +INQUIRY command to the device and display some of the returned inquiry +data. +.It Ic reqsense +Send the +.Tn SCSI +REQUEST SENSE command to the device and display the returned sense +information. +.It Ic reportluns +Send the +.Tn SCSI +REPORT LUNS command to the device and display supported LUNs. +.It Ic read +Send a +.Tn SCSI +READ command to the device, and write the requested data to a file or +stdout. +.Bl -tag -width 12n +.It Fl l Ar lba +Specify the starting Logical Block Address for the READ. This can be +specified in decimal, octal (starting with 0), hexadecimal (starting with +0x) or any other base supported by +.Xr strtoull 3 . +.It Fl d Ar datalen +Specify the length, in 512 byte blocks, of the READ request. +.It Fl f Ar file +Specify the destination for the data read by the READ command. Either a +filename or +.Sq - +for stdout may be specified. +.It Fl c Ar cdbsize +Specify the minimum +.Tn SCSI +CDB (Command Data Block) size to be used for the READ request. Allowable +values are 6, 10, 12 and 16. Depending upon the LBA and amount of data +requested, a larger CDB size may be used to satisfy the request. (e.g., +for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) +.It Fl b Ar blocksize +Specify the blocksize of the underlying +.Tn SCSI +device, so the transfer length +can be calculated accurately. The blocksize can be obtained via the +.Tn SCSI +READ CAPACITY command. +.It Fl N +Do not copy data to +.Nm +from the kernel when doing a read, just execute the command without copying +data. +This is to be used for performance testing. +.El +.It Ic write +Read data from a file or stdin, and write the data to the device using the +.Tn SCSI +WRITE command. +.Bl -tag -width 12n +.It Fl l Ar lba +Specify the starting Logical Block Address for the WRITE. This can be +specified in decimal, octal (starting with 0), hexadecimal (starting with +0x) or any other base supported by +.Xr strtoull 3 . +.It Fl d Ar atalen +Specify the length, in 512 byte blocks, of the WRITE request. +.It Fl f Ar file +Specify the source for the data to be written by the WRITE command. Either a +filename or +.Sq - +for stdin may be specified. +.It Fl c Ar cdbsize +Specify the minimum +.Tn SCSI +CDB (Command Data Block) size to be used for the READ request. Allowable +values are 6, 10, 12 and 16. Depending upon the LBA and amount of data +requested, a larger CDB size may be used to satisfy the request. (e.g., +for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) +.It Fl b Ar blocksize +Specify the blocksize of the underlying +.Tn SCSI +device, so the transfer length +can be calculated accurately. The blocksize can be obtained via the +.Tn SCSI +READ CAPACITY command. +.It Fl N +Do not copy data to +.Nm +to the kernel when doing a write, just execute the command without copying +data. +This is to be used for performance testing. +.El +.It Ic bbrread +Issue a SCSI READ command to the logical device to potentially force a bad +block on a disk in the RAID set to be reconstructed from the other disks in +the array. This command should only be used on an array that is in the +normal state. If used on a critical array, it could cause the array to go +offline if the bad block to be remapped is on one of the disks that is +still active in the array. +.Pp +The data for this particular command will be discarded, and not returned to +the user. +.Pp +In order to determine which LUN to read from, the user should first +determine which LUN the disk with a bad block belongs to. Then he should +map the bad disk block back to the logical block address for the array in +order to determine which LBA to pass in to the +.Ic bbrread +command. +.Pp +This command is primarily intended for testing. In practice, bad block +remapping will generally be triggered by the in-kernel Disk Aerobics and +Disk Scrubbing code. +.Bl -tag -width 10n +.It Fl l Ar lba +Specify the starting Logical Block Address. +.It Fl d Ar datalen +Specify the amount of data in bytes to read from the LUN. This must be a +multiple of the LUN blocksize. +.El +.It Ic readcap +Send the +.Tn SCSI +READ CAPACITY command to the device and display the device size and device +block size. By default, READ CAPACITY(10) is +used. If the device returns a maximum LBA of 0xffffffff, however, +.Nm +will automatically issue a READ CAPACITY(16), which is implemented as a +service action of the SERVICE ACTION IN(16) opcode. The user can specify +the minimum CDB size with the +.Fl c +argument. Valid values for the +.Fl c +option are 10 and 16. If a 10 byte CDB is specified, the request will be +automatically reissued with a 16 byte CDB if the maximum LBA returned is +0xffffffff. +.It Ic modesense +Send a +.Tn SCSI +MODE SENSE command to the device, and display the requested mode page(s) or +page list. +.Bl -tag -width 10n +.It Fl m Ar page +Specify the mode page to display. This option and the +.Fl l +option are mutually exclusive. One of the two must be specified, though. +Mode page numbers may be specified in decimal or hexadecimal. +.It Fl l +Request that the list of mode pages supported by the device be returned. +This option and the +.Fl m +option are mutually exclusive. One of the two must be specified, though. +.It Fl P Ar pc +Specify the mode page control value. Possible values are: +.Bl -tag -width 2n -compact +.It 0 +Current values. +.It 1 +Changeable value bitmask. +.It 2 +Default values. +.It 3 +Saved values. +.El +.It Fl d +Disable block descriptors when sending the mode sense request. +.It Fl S Ar subpage +Specify the subpage used with the mode sense request. +.It Fl c Ar cdbsize +Specify the CDB size used for the mode sense request. Supported values are +6 and 10. +.El +.It Ic start +Send the +.Tn SCSI +START STOP UNIT command to the specified LUN with the start +bit set. +.Bl -tag -width 4n +.It Fl i +Set the immediate bit in the CDB. Note that CTL does not support the +immediate bit, so this is primarily useful for making sure that CTL returns +the proper error. +.It Fl o +Set the Copan proprietary on/offline bit in the CDB. When this flag is +used, the LUN will be marked online again (see the description of the +.Ic shutdown +and +.Ic startup +commands). When this flag is used with a +start command, the LUN will NOT be spun up. You need to use a start +command without the +.Fl o +flag to spin up the disks in the LUN. +.El +.It Ic stop +Send the +.Tn SCSI +START STOP UNIT command to the specified LUN with the start +bit cleared. We use an ordered tag to stop the LUN, so we can guarantee +that all pending I/O executes before it is stopped. (CTL guarantees this +anyway, but +.Nm +sends an ordered tag for completeness.) +.Bl -tag -width 4n +.It Fl i +Set the immediate bit in the CDB. Note that CTL does not support the +immediate bit, so this is primarily useful for making sure that CTL returns +the proper error. +.It Fl o +Set the Copan proprietary on/offline bit in the CDB. When this flag is +used, the LUN will be spun down and taken offline ("Logical unit not ready, +manual intervention required"). See the description of the +.Ic shutdown +and +.Ic startup +options. +.El +.It Ic synccache +Send the +.Tn SCSI +SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE +CACHE(10) is used. If the specified starting LBA is greater than +0xffffffff or the length is greater than 0xffff, though, +SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used +if the user specifies a 16 byte CDB with the +.Fl c +argument. +.Bl -tag -width 14n +.It Fl l Ar lba +Specify the starting LBA of the cache region to synchronize. This option is a +no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the +cache for the entire LUN. +.It Fl b Ar blockcount +Specify the length of the cache region to synchronize. This option is a +no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the +cache for the entire LUN. +.It Fl r +Specify relative addressing for the starting LBA. CTL does not support +relative addressing, since it only works for linked commands, and CTL +doesn't support linked commands. +.It Fl i +Tell the target to return status immediately after issuing the SYHCHRONIZE CACHE +command rather than waiting for the cache to finish syncing. CTL does not +support this bit. +.It Fl c Ar cdbsize +Specify the minimum CDB size. Valid values are 10 and 16 bytes. +.El +.It Ic shutdown +Issue a +.Tn SCSI +START STOP UNIT command with the start bit cleared and the on/offline bit +set to all direct access LUNs. This will spin down all direct access LUNs, +and mark them offline ("Logical unit not ready, manual intervention +required"). Once marked offline, the state can only be cleared by sending +a START STOP UNIT command with the start bit set and the on/offline bit +set. The +.Nm +commands +.Ic startup +and +.Ic start +will accomplish this. Note that the +on/offline bit is a non-standard Copan extension to the +.Tn SCSI +START STOP UNIT command, so merely sending a normal start command from an +initiator will not clear the condition. (This is by design.) +.It Ic startup +Issue a +.Tn SCSI +START STOP UNIT command with the start bit set and the on/offline bit set +to all direct access LUNs. This will mark all direct access LUNs "online" +again. It will not cause any LUNs to start up. A separate start command +without the on/offline bit set is necessary for that. +.It Ic hardstop +Use the kernel facility for stopping all direct access LUNs and setting the +offline bit. Unlike the +.Ic shutdown +command above, this command allows shutting down LUNs with I/O active. It +will also issue a LUN reset to any reserved LUNs to break the reservation +so that the LUN can be stopped. +.Ic shutdown +command instead. +.It Ic hardstart +This command is functionally identical to the +.Ic startup +command described above. The primary difference is that the LUNs are +enumerated and commands sent by the in-kernel Front End Target Driver +instead of by +.Nm . +.It Ic lunlist +List all LUNs registered with CTL. +Because this command uses the ioctl port, it will only work when the FETDs +(Front End Target Drivers) are enabled. +This command is the equivalent of doing a REPORT LUNS on one LUN and then +an INQUIRY on each LUN in the system. +.It Ic delay +Delay commands at the given location. There are two places where commands +may be delayed currently: before data is transferred +.Pq Dq datamove +and just prior to sending status to the host +.Pq Dq done . +One of the two must be supplied as an argument to the +.Fl l +option. The +.Fl t +option must also be specified. +.Bl -tag -width 12n +.It Fl l Ar delayloc +Delay command(s) at the specified location. +This can either be at the data movement stage (datamove) or prior to +command completion (done). +.It Fl t Ar delaytime +Delay command(s) for the specified number of seconds. This must be +specified. If set to 0, it will clear out any previously set delay for +this particular location (datamove or done). +.It Fl T Ar delaytype +Specify the delay type. +By default, the +.Ic delay +option will delay the next command sent to the given LUN. +With the +.Fl T Ar cont +option, every command will be delayed by the specified period of time. +With the +.Fl T Ar oneshot +the next command sent to the given LUN will be delayed and all subsequent +commands will be completed normally. +This is the default. +.El +.It Ic realsync +Query and control CTL's SYNCHRONIZE CACHE behavior. The +.Sq query +argument +will show whether SYNCHRONIZE CACHE commands are being sent to the backend +or not. +The default is to send SYNCHRONIZE CACHE commands to the backend. +The +.Sq on +argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be +sent to the backend. +The +.Sq off +argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be +immediately returned to the initiator with successful status. +.It Ic setsync +For a given lun, only actually service every Nth SYNCHRONIZE CACHE command +that is sent. This can be used for debugging the optimal time period for +sending SYNCHRONIZE cache commands. An interval of 0 means that the cache +will be flushed for this LUN every time a SYNCHRONIZE CACHE command is +received. +.Pp +You must specify the target and LUN you want to modify. +.It Ic getsync +Get the interval at which we actually service the SYNCHRONIZE CACHE +command, as set by the +.Ic setsync +command above. +The reported number means that we will actually flush the cache on every +Nth SYNCHRONIZE CACHE command. A value of 0 means that we will flush the +cache every time. +.Pp +You must specify the target and LUN you want to query. +.It Ic inject +Inject the specified type of error for the LUN specified, when a command +that matches the given pattern is seen. +The sense data returned is in either fixed or descriptor format, depending +upon the status of the D_SENSE bit in the control mode page (page 0xa) for +the LUN. +.Pp +Errors are only injected for commands that have not already failed for +other reasons. +By default, only the first command matching the pattern specified is +returned with the supplied error. +.Pp +If the +.Fl c +flag is specified, all commands matching the pattern will be returned with +the specified error until the error injection command is deleted with +.Fl d +flag. +.Bl -tag -width 17n +.It Fl i Ar action +Specify the error to return: +.Bl -tag -width 10n +.It aborted +Return the next matching command on the specified LUN with the sense key +ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect +failure"). +.It mediumerr +Return the next matching command on the specified LUN with the sense key +MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for +reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed") +for write errors. +.It ua +Return the next matching command on the specified LUN with the sense key +UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS +DEVICE RESET OCCURRED"). +.It custom +Return the next matching command on the specified LUN with the supplied +sense data. +The +.Fl s +argument must be specified. +.El +.It Fl p Ar pattern +Specify which commands should be returned with the given error. +.Bl -tag -width 10n +.It read +The error should apply to READ(6), READ(10), READ(12), READ(16), etc. +.It write +The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE +AND VERIFY(10), etc. +.It rw +The error should apply to both read and write type commands. +.It readcap +The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands. +.It tur +The error should apply to TEST UNIT READY commands. +.It any +The error should apply to any command. +.El +.It Fl r Ar lba,len +Specify the starting lba and length of the range of LBAs which should +trigger an error. +This option is only applies when read and/or write patterns are specified. +If used with other command types, the error will never be triggered. +.It Fl s Ar len fmt Op Ar args +Specify the sense data that is to be returned for custom actions. +If the format is +.Sq - , +len bytes of sense data will be read from standard input and written to the +sense buffer. +If len is longer than 252 bytes (the maximum allowable +.Tn SCSI +sense data length), it will be truncated to that length. +The sense data format is described in +.Xr cam_cdparse 3 . +.It Fl c +The error injection should be persistent, instead of happening once. +Persistent errors must be deleted with the +.Fl d +argument. +.It Fl d Ar delete_id +Delete the specified error injection serial number. +The serial number is returned when the error is injected. +.El +.It Ic port +Perform one of several CTL frontend port operations. +Either get a list of frontend ports +.Pq Fl l , +turn one or more frontends on +or off +.Pq Fl o Ar on|off , +or set the World Wide Node Name +.Pq Fl w Ar wwnn +or World Wide Port Name +.Pq Fl W Ar wwpn +for a given port. +One of +.Fl l , +.Fl o , +or +.Fl w +or +.Fl W +must be specified. +The WWNN and WWPN may both be specified at the same time, but cannot be +combined with enabling/disabling or listing ports. +.Bl -tag -width 12n +.It Fl l +List all CTL frontend ports or a specific port type or number. +.It Fl o Ar on|off +Turn the specified CTL frontend ports off or on. +If no port number or port type is specified, all ports are turned on or +off. +.It Fl p Ar targ_port +Specify the frontend port number. +The port numbers can be found in the frontend port list. +.It Fl q +Omit the header in the port list output. +.It Fl t Ar fe_type +Specify the frontend type. +Currently defined port types are +.Dq fc +(Fibre Channel), +.Dq scsi +(Parallel SCSI), +.Dq ioctl +(CTL ioctl interface), +and +.Dq internal +(CTL CAM SIM). +.It Fl w Ar wwnn +Set the World Wide Node Name for the given port. +The +.Fl n +argument must be specified, since this is only possible to implement on a +single port. +As a general rule, the WWNN should be the same across all ports on the +system. +.It Fl W Ar wwpn +Set the World Wide Port Name for the given port. +The +.Fl n +argument must be specified, since this is only possible to implement on a +single port. +As a general rule, the WWPN must be different for every port in the system. +.It Fl x +Output the port list in XML format. +.El +.It Ic dumpooa +Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL. +.It Ic dumpstructs +Dump the CTL structures to the console. +.It Ic create +Create a new LUN. +The backend must be specified, and depending upon the backend requested, +some of the other options may be required. +If the LUN is created successfully, the LUN configuration will be +displayed. +If LUN creation fails, a message will be displayed describing the failure. +.Bl -tag -width 14n +.It Fl b Ar backend +The +.Fl b +flag is required. +This specifies the name backend to use when creating the LUN. +Examples are +.Dq ramdisk +and +.Dq block . +.It Fl B Ar blocksize +Specify the blocksize of the backend in bytes. +.It Fl d Ar device_id +Specify the LUN-associated string to use in the +.Tn SCSI +INQUIRY VPD page 0x83 data. +.It Fl l Ar lun_id +Request that a particular LUN number be assigned. +If the requested LUN number is not available, the request will fail. +.It Fl o Ar name=value +Specify a backend-specific name/value pair. +Multiple +.Fl o +arguments may be specified. +Refer to the backend documentation for arguments that may be used. +.It Fl s Ar size_bytes +Specify the size of the LUN in bytes. +Some backends may allow setting the size (e.g. the ramdisk backend) and for +others the size may be implicit (e.g. the block backend). +.It Fl S Ar serial_num +Specify the serial number to be used in the +.Tn SCSI +INQUIRY VPD page 0x80 data. +.It Fl t Ar device_type +Specify the numeric SCSI device type to use when creating the LUN. +For example, the Direct Access type is 0. +If this flag is not used, the type of LUN created is backend-specific. +Not all LUN types are supported. +Currently CTL only supports Direct Access (type 0) and Processor (type 3) +LUNs. +The backend requested may or may not support all of the LUN types that CTL +supports. +.El +.It Ic remove +Remove a LUN. +The backend must be specified, and the LUN number must also be specified. +Backend-specific options may also be specified with the +.Fl o +flag. +.Bl -tag -width 14n +.It Fl b Ar backend +Specify the backend that owns the LUN to be removed. +Examples are +.Dq ramdisk +and +.Dq block . +.It Fl l Ar lun_id +Specify the LUN number to remove. +.It Fl o Ar name=value +Specify a backend-specific name/value pair. +Multiple +.Fl o +arguments may be specified. +Refer to the backend documentation for arguments that may be used. +.El +.It Ic modify +Modify a LUN size. +The backend, the LUN number, and the size must be specified. +.Bl -tag -width 14n +.It Fl b Ar backend +Specify the backend that owns the LUN to be removed. +Examples are +.Dq ramdisk +and +.Dq block . +.It Fl l Ar lun_id +Specify the LUN number to remove. +.It Fl s Ar size_bytes +Specify the size of the LUN in bytes. +For the +.Dq block +backend, an +.Dq auto +keyword may be passed instead; this will make CTL use the size of backing +file or device. +.El +.It Ic devlist +Get a list of all configured LUNs. +This also includes the LUN size and blocksize, serial number and device ID. +.Bl -tag -width 11n +.It Fl b Ar backend +Specify the backend. +This restricts the LUN list to the named backend. +Examples are +.Dq ramdisk +and +.Dq block . +.It Fl v +Be verbose. +This will also display any backend-specific LUN attributes in addition to +the standard per-LUN information. +.It Fl x +Dump the raw XML. +The LUN list information from the kernel comes in XML format, and this +option allows the display of the raw XML data. +This option and the +.Fl v +and +.Fl b +options are mutually exclusive. +If you specify +.Fl x , +the entire LUN database is displayed in XML format. +.El +.It Ic help +Display +.Nm +usage information. +.El +.Sh EXAMPLES +.Dl ctladm tur 0:1 +.Pp +Send a +.Tn SCSI +TEST UNIT READY command to LUN 1. +.Pp +.Dl ctladm modesense 0:1 -l +.Pp +Display the list of mode pages supported by LUN 1. +.Pp +.Dl ctladm modesense 0:0 -m 10 -P 3 -d -c 10 +.Pp +Display the saved version of the Control mode page (page 10) on LUN 0. +Disable fetching block descriptors, and use a 10 byte MODE SENSE command +instead of the default 6 byte command. +.Bd -literal +ctladm read 0:2 -l 0 -d 1 -b 512 -f - > foo +.Ed +.Pp +Read the first 512 byte block from LUN 2 and dump it to the file +.Pa foo . +.Bd -literal +ctladm write 0:3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar +.Ed +.Pp +Read 10240 bytes from the file +.Pa /tmp/bar +and write it to target 0, LUN 3. +starting at LBA 0xff432140. +.Pp +.Dl ctladm create -b ramdisk -s 10485760000000000 +.Pp +Create a LUN with the +.Dq fake +ramdisk as a backing store. +The LUN will claim to have a size of approximately 10 terabytes. +.Pp +.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 +.Pp +Create a LUN using the block backend, and specify the file +.Pa src/usr.sbin/ctladm/ctladm.8 +as the backing store. +The size of the LUN will be derived from the size of the file. +.Pp +.Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123 +.Pp +Create a LUN using the block backend, specify the file +.Pa src/usr.sbin/ctladm/ctladm.8 +as the backing store, and specify the +.Tn SCSI +VPD page 0x80 and 0x83 serial number +.Fl ( S ) +and device ID +.Fl ( d ) . +.Pp +.Dl ctladm remove -b block -l 12 +.Pp +Remove LUN 12, which is handled by the block backend, from the system. +.Pp +.Dl ctladm devlist +.Pp +List configured LUNs in the system, along with their backend and serial +number. +This works when the Front End Target Drivers are enabled or disabled. +.Pp +.Dl ctladm lunlist +.Pp +List all LUNs in the system, along with their inquiry data and device type. +This only works when the FETDs are enabled, since the commands go through the +ioctl port. +.Pp +.Dl ctladm inject 0:6 -i mediumerr -p read -r 0,512 -c +.Pp +Inject a medium error on LUN 6 for every read that covers the first 512 +blocks of the LUN. +.Bd -literal -offset indent +ctladm inject 0:6 -i custom -p tur -s 18 "f0 0 02 s12 04 02" +.Ed +.Pp +Inject a custom error on LUN 6 for the next TEST UNIT READY command only. +This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of +0x04,0x02 ("Logical unit not ready, initializing command required"). +.Sh SEE ALSO +.Xr cam 3 , +.Xr cam_cdbparse 3 , +.Xr cam 4 , +.Xr xpt 4 , +.Xr camcontrol 8 +.Sh HISTORY +The +.Nm +utility was originally written during the Winter/Spring of 2003 as an +interface to CTL. +.Sh AUTHORS +.An Ken Merry Aq ken@FreeBSD.org |
