1115 lines
31 KiB
Groff
1115 lines
31 KiB
Groff
.\"
|
|
.\" 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 October 26, 2014
|
|
.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 portlist
|
|
.Op Fl f Ar frontend
|
|
.Op Fl i
|
|
.Op Fl p Ar targ_port
|
|
.Op Fl q
|
|
.Op Fl v
|
|
.Op Fl x
|
|
.Nm
|
|
.Ic dumpooa
|
|
.Nm
|
|
.Ic dumpstructs
|
|
.Nm
|
|
.Ic islist
|
|
.Op Fl v
|
|
.Op Fl x
|
|
.Nm
|
|
.Ic islogout
|
|
.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
|
|
.Nm
|
|
.Ic isterminate
|
|
.Aq Fl a | Fl c Ar connection-id | Fl i Ar name | Fl p Ar portal
|
|
.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
|
|
does not support linked commands.
|
|
.It Fl i
|
|
Tell the target to return status immediately after issuing the SYNCHRONIZE 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 portlist
|
|
List CTL frontend ports.
|
|
.Bl -tag -width 12n
|
|
.It Fl f Ar frontend
|
|
Specify the frontend type.
|
|
.It Fl i
|
|
Report target and connected initiators addresses
|
|
.It Fl p Ar targ_port
|
|
Specify the frontend port number.
|
|
.It Fl q
|
|
Omit the header in the port list output.
|
|
.It Fl v
|
|
Enable verbose output (report all port options).
|
|
.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 islist
|
|
Get a list of currently running iSCSI connections.
|
|
This includes initiator and target names and the unique connection IDs.
|
|
.Bl -tag -width 11n
|
|
.It Fl v
|
|
Verbose mode.
|
|
.It Fl x
|
|
Dump the raw XML.
|
|
The connections list information from the kernel comes in XML format, and this
|
|
option allows the display of the raw XML data.
|
|
.El
|
|
.It Ic islogout
|
|
Ask the initiator to log out iSCSI connections matching criteria.
|
|
.Bl -tag -width 11n
|
|
.It Fl a
|
|
Log out all connections.
|
|
.It Fl c
|
|
Specify connection ID.
|
|
.It Fl i
|
|
Specify initiator name.
|
|
.It Fl p
|
|
Specify initiator portal (hostname or IP address).
|
|
.El
|
|
.It Ic isterminate
|
|
Forcibly terminate iSCSI connections matching criteria.
|
|
.Bl -tag -width 11n
|
|
.It Fl a
|
|
Terminate all connections.
|
|
.It Fl c
|
|
Specify connection ID.
|
|
.It Fl i
|
|
Specify initiator name.
|
|
.It Fl p
|
|
Specify initiator portal (hostname or IP address).
|
|
.El
|
|
.It Ic help
|
|
Display
|
|
.Nm
|
|
usage information.
|
|
.El
|
|
.Sh OPTIONS
|
|
Number of additional configuration options may be specified for LUNs.
|
|
Some options are global, others are backend-specific.
|
|
.Pp
|
|
Global options:
|
|
.Bl -tag -width 12n
|
|
.It Va vendor
|
|
Specifies LUN vendor string up to 8 chars.
|
|
.It Va product
|
|
Specifies LUN product string up to 16 chars.
|
|
.It Va revision
|
|
Specifies LUN revision string up to 4 chars.
|
|
.It Va scsiname
|
|
Specifies LUN SCSI name string.
|
|
.It Va eui
|
|
Specifies LUN EUI-64 identifier.
|
|
.It Va naa
|
|
Specifies LUN NAA identifier.
|
|
Either EUI or NAA identifier should be set to UNIQUE value to allow
|
|
EXTENDED COPY command access the LUN.
|
|
Non-unique LUN identifiers may lead to data corruption.
|
|
.It Va insecure_tpc
|
|
Setting to "on" allows EXTENDED COPY command sent to this LUN access
|
|
other LUNs on this host, not accessible otherwise.
|
|
This allows to offload copying between different iSCSI targets residing
|
|
on the same host in trusted environments.
|
|
.It Va readcache
|
|
Set to "off", disables read caching for the LUN, if supported by the backend.
|
|
.It Va readonly
|
|
Set to "on", blocks all media write operations to the LUN, reporting it
|
|
as write protected.
|
|
.It Va reordering
|
|
Set to "unrestricted", allows target to process commands with SIMPLE task
|
|
attribute in arbitrary order. Any data integrity exposures related to
|
|
command sequence order shall be explicitly handled by the application
|
|
client through the selection of appropriate commands and task attributes.
|
|
The default value is "restricted". It improves data integrity, but may
|
|
introduce some additional delays.
|
|
.It Va rpm
|
|
Specifies medium rotation rate of the device: 0 -- not reported,
|
|
1 -- non-rotating (SSD), >1024 -- value in revolutions per minute.
|
|
.It Va formfactor
|
|
Specifies nominal form factor of the device: 0 -- not reported, 1 -- 5.25",
|
|
2 -- 3.5", 3 -- 2.5", 4 -- 1.8", 5 -- less then 1.8".
|
|
.It Va unmap
|
|
Set to "on", enables UNMAP support for the LUN, if supported by the backend.
|
|
.It Va writecache
|
|
Set to "off", disables write caching for the LUN, if supported by the backend.
|
|
.El
|
|
.Pp
|
|
Options specific for block backend:
|
|
.Bl -tag -width 12n
|
|
.It Va file
|
|
Specifies file or device name to use for backing store.
|
|
.It Va num_threads
|
|
Specifies number of backend threads to use for this LUN.
|
|
.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 ctl 4 ,
|
|
.Xr xpt 4 ,
|
|
.Xr camcontrol 8 ,
|
|
.Xr ctld 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 Mt ken@FreeBSD.org
|