Index: head/usr.bin/ctlstat/ctlstat.8 =================================================================== --- head/usr.bin/ctlstat/ctlstat.8 (revision 283284) +++ head/usr.bin/ctlstat/ctlstat.8 (revision 283285) @@ -1,123 +1,124 @@ .\" .\" Copyright (c) 2010 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. .\" .\" ctlstat utility man page. .\" .\" Author: Ken Merry .\" .\" $Id: //depot/users/kenm/FreeBSD-test2/usr.bin/ctlstat/ctlstat.8#2 $ .\" $FreeBSD$ .\" -.Dd March 8, 2015 +.Dd May 22, 2015 .Dt CTLSTAT 8 .Os .Sh NAME .Nm ctlstat .Nd CAM Target Layer statistics utility .Sh SYNOPSIS .Nm .Op Fl t .Op Fl c Ar count .Op Fl C .Op Fl d .Op Fl D .Op Fl j .Op Fl l Ar lun .Op Fl n Ar numdevs .Op Fl w Ar wait .Sh DESCRIPTION The .Nm utility provides statistics information for the CAM Target Layer. The first display (except for dump and JSON modes) shows average statistics since system startup. Subsequent displays show average statistics during the measurement interval. .Pp The options are as follows: .Bl -tag -width 10n .It Fl t Total mode. This displays separate columns with the total CTL read and write output, and a combined total column that also includes non I/O operations. .It Fl c Ar count Display statistics this many times. .It Fl C Disable CPU statistics display. .It Fl d Display DMA operation time (latency) instead of overall I/O time (latency). .It Fl D Text dump mode. Dump all available statistics every 30 seconds in a text format suitable for parsing. No statistics are computed in this mode, only raw numbers are displayed. .It Fl h Suppress display of the header. .It Fl j JSON dump mode. Dump all available statistics every 30 seconds in JavaScript Object Notation (JSON) format. No statistics are computed in this mode, only raw numbers are displayed. .It Fl l Ar lun Request statistics for the specified LUN. This option is incompatible with total .Fl ( t ) mode. .It Fl n Ar numdevs Display statistics for this many devices. .It Fl w Ar wait Wait this many seconds in between displays. If this option is not specified, .Nm defaults to a 1 second interval. .El .Sh EXAMPLES .Dl ctlstat -t .Pp Display total statistics for the system with a one second interval. .Pp .Dl ctlstat -d -l 5 -C .Pp Display average DMA time for LUN 5 and omit CPU utilization. .Pp .Dl ctlstat -n 7 -w 10 .Pp Display statistics for the first 7 LUNs, and display average statistics every 10 seconds. .Sh SEE ALSO .Xr cam 3 , .Xr cam 4 , .Xr ctl 4 , .Xr xpt 4 , .Xr camcontrol 8 , .Xr ctladm 8 , +.Xr ctld 8 , .Xr iostat 8 .Sh AUTHORS .An Ken Merry Aq Mt ken@FreeBSD.org .An Will Andrews Aq Mt will@FreeBSD.org Index: head/usr.sbin/ctladm/ctladm.8 =================================================================== --- head/usr.sbin/ctladm/ctladm.8 (revision 283284) +++ head/usr.sbin/ctladm/ctladm.8 (revision 283285) @@ -1,1170 +1,1171 @@ .\" .\" 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 .\" .\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $ .\" $FreeBSD$ .\" -.Dd February 1, 2015 +.Dd May 22, 2015 .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 l .Op Fl p Ar targ_port .Op Fl q .Op Fl v .Op Fl x .Nm .Ic lunmap .Aq Fl p Ar targ_port .Op Fl l Ar pLUN .Op Fl L Ar cLUN .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 l Report LUN mapping. .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 lunmap Change LUN mapping for specified port. If both .Ar pLUN and .Ar cLUN are specified -- LUN will be mapped. If .Ar pLUN is specified, but .Ar cLUN is not -- LUN will be unmapped. If neither .Ar pLUN nor .Ar cLUN are specified -- LUN mapping will be disabled, exposing all CTL LUNs. .Bl -tag -width 12n .It Fl p Ar targ_port Specify the frontend port number. .It Fl l Ar pLUN LUN number visible by specified port. .It Fl L Ar cLUN CTL LUN number. .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 serseq Set to "on" to serialize conseсutive reads/writes. Set to "read" to serialize conseсutive reads. Set to "off" to allow them be issued in parallel. Parallel issue of consecutive operations may confuse logic of the backing file system, hurting performance; but it may improve performance of backing stores without prefetch/write-back. .It Va pblocksize .It Va pblockoffset Specify physical block size and offset of the device. .It Va ublocksize .It Va ublockoffset Specify UNMAP block size and offset of the device. .It Va rpm .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 avail-threshold .It Va used-threshold .It Va pool-avail-threshold .It Va pool-used-threshold Set per-LUN/-pool thin provisioning soft thresholds. LUN will establish UNIT ATTENTION condition if its or pool available space get below configured avail values, or its or pool used space get above configured used values. Pool thresholds are working only for ZVOL-backed LUNs. .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 +.Xr ctld 8 , +.Xr ctlstat 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 Index: head/usr.sbin/ctld/ctld.8 =================================================================== --- head/usr.sbin/ctld/ctld.8 (revision 283284) +++ head/usr.sbin/ctld/ctld.8 (revision 283285) @@ -1,118 +1,119 @@ .\" Copyright (c) 2012 The FreeBSD Foundation .\" All rights reserved. .\" .\" This software was developed by Edward Tomasz Napierala under sponsorship .\" from the FreeBSD Foundation. .\" .\" 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. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, 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 DAMAGE. .\" .\" $FreeBSD$ .\" -.Dd November 9, 2014 +.Dd May 22, 2015 .Dt CTLD 8 .Os .Sh NAME .Nm ctld .Nd CAM Target Layer / iSCSI target daemon .Sh SYNOPSIS .Nm .Op Fl d .Op Fl f Ar config-file .Sh DESCRIPTION The .Nm daemon is responsible for managing the CAM Target Layer configuration, accepting incoming iSCSI connections, performing authentication and passing connections to the kernel part of the native iSCSI target. .Pp Upon startup, the .Nm daemon parses the configuration file and exits, if it encounters any errors. Then it compares the configuration with the kernel list of LUNs managed by previously running .Nm instances, removes LUNs no longer existing in the configuration file, and creates new LUNs as necessary. After that it listens for the incoming iSCSI connections, performs authentication, and, if successful, passes the connections to the kernel part of CTL iSCSI target, which handles it from that point. .Pp When it receives a SIGHUP signal, the .Nm reloads its configuration and applies the changes to the kernel. Changes are applied in a way that avoids unnecessary disruptions; for example removing one LUN does not affect other LUNs. .Pp When exiting gracefully, the .Nm daemon removes LUNs it managed and forcibly disconnects all the clients. Otherwise - for example, when killed with SIGKILL - LUNs stay configured and clients remain connected. .Pp To perform administrative actions that apply to already connected sessions, such as forcing termination, use .Xr ctladm 8 . .Pp The following options are available: .Bl -tag -width ".Fl P Ar pidfile" .It Fl f Ar config-file Specifies the name of the configuration file. The default is .Pa /etc/ctl.conf . .It Fl d Debug mode. The server sends verbose debug output to standard error, and does not put itself in the background. The server will also not fork and will exit after processing one connection. This option is only intended for debugging the target. .El .Sh FILES .Bl -tag -width ".Pa /var/run/ctld.pid" -compact .It Pa /etc/ctl.conf The configuration file for .Nm . The file format and configuration options are described in .Xr ctl.conf 5 . .It Pa /var/run/ctld.pid The default location of the .Nm PID file. .El .Sh EXIT STATUS The .Nm utility exits 0 on success, and >0 if an error occurs. .Sh SEE ALSO .Xr ctl 4 , .Xr ctl.conf 5 , -.Xr ctladm 8 +.Xr ctladm 8 , +.Xr ctlstat 8 .Sh HISTORY The .Nm command appeared in .Fx 10.0 . .Sh AUTHORS The .Nm was developed by .An Edward Tomasz Napierala Aq Mt trasz@FreeBSD.org under sponsorship from the FreeBSD Foundation. Index: head/usr.sbin/iostat/iostat.8 =================================================================== --- head/usr.sbin/iostat/iostat.8 (revision 283284) +++ head/usr.sbin/iostat/iostat.8 (revision 283285) @@ -1,515 +1,516 @@ .\" .\" Copyright (c) 1997 Kenneth D. Merry. .\" 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. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, 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 DAMAGE. .\" .\" $FreeBSD$ .\" .\" Copyright (c) 1985, 1991, 1993 .\" The Regents of the University of California. 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. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, 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 DAMAGE. .\" .\" @(#)iostat.8 8.1 (Berkeley) 6/6/93 .\" -.Dd December 15, 2012 +.Dd May 22, 2015 .Dt IOSTAT 8 .Os .Sh NAME .Nm iostat .Nd report .Tn I/O statistics .Sh SYNOPSIS .Nm .Op Fl CdhIKoTxz?\& .Op Fl c Ar count .Op Fl M Ar core .Op Fl n Ar devs .Op Fl N Ar system .Oo .Fl t .Sm off .Ar type , if , pass .Sm on .Oc .Op Fl w Ar wait .Op Ar drives .Sh DESCRIPTION The .Nm utility displays kernel .Tn I/O statistics on terminal, device and cpu operations. The first statistics that are printed are averaged over the system uptime. To get information about the current activity, a suitable wait time should be specified, so that the subsequent sets of printed statistics will be averaged over that time. .Pp The options are as follows: .Bl -tag -width flag .It Fl c Repeat the display .Ar count times. If no repeat .Ar count is specified, the default depends on whether .Fl w is specified. With .Fl w the default repeat count is infinity, otherwise it is 1. .It Fl C Display CPU statistics. This is on by default, unless .Fl d or .Fl x is specified. .It Fl d Display only device statistics. If this flag is turned on, only device statistics will be displayed, unless .Fl C or .Fl T is also specified to enable the display of CPU or TTY statistics. .It Fl h Put .Nm in .Sq top mode. In this mode, .Nm will show devices in order from highest to lowest bytes per measurement cycle. .It Fl I Display total statistics for a given time period, rather than average statistics for each second during that time period. .It Fl K In the blocks transferred display (-o), display block count in kilobytes rather then the device native block size. .It Fl M Extract values associated with the name list from the specified core instead of the default .Dq Pa /dev/kmem . .It Fl n Display up to .Ar devs number of devices. The .Nm utility will display fewer devices if there are not .Ar devs devices present. .It Fl N Extract the name list from the specified system instead of the default .Dq Pa /boot/kernel/kernel . .It Fl o Display old-style .Nm device statistics. Sectors per second, transfers per second, and milliseconds per seek are displayed. If .Fl I is specified, total blocks/sectors, total transfers, and milliseconds per seek are displayed. .It Fl t Specify which types of devices to display. There are three different categories of devices: .Pp .Bl -tag -width indent -compact .It device type: .Bl -tag -width 9n -compact .It da Direct Access devices .It sa Sequential Access devices .It printer Printers .It proc Processor devices .It worm Write Once Read Multiple devices .It cd CD devices .It scanner Scanner devices .It optical Optical Memory devices .It changer Medium Changer devices .It comm Communication devices .It array Storage Array devices .It enclosure Enclosure Services devices .It floppy Floppy devices .El .Pp .It interface: .Bl -tag -width 9n -compact .It IDE Integrated Drive Electronics devices .It SCSI Small Computer System Interface devices .It other Any other device interface .El .Pp .It passthrough: .Bl -tag -width 9n -compact .It pass Passthrough devices .El .El .Pp The user must specify at least one device type, and may specify at most one device type from each category. Multiple device types in a single device type statement must be separated by commas. .Pp Any number of .Fl t arguments may be specified on the command line. All .Fl t arguments are ORed together to form a matching expression against which all devices in the system are compared. Any device that fully matches any .Fl t argument will be included in the .Nm output, up to the number of devices that can be displayed in 80 columns, or the maximum number of devices specified by the user. .It Fl T Display TTY statistics. This is on by default, unless .Fl d or .Fl x is specified. .It Fl w Pause .Ar wait seconds between each display. If no .Ar wait interval is specified, the default is 1 second. .Pp The .Nm command will accept and honor a non-integer number of seconds. Note that the interval only has millisecond granularity. Finer values will be truncated. E.g., .Dq Li -w1.0001 is the same as .Dq Li -w1.000 . The interval will also suffer from modifications to .Va kern.hz so your mileage may vary. .It Fl x Show extended disk statistics. Each disk is displayed on a line of its own with all available statistics. If this flag is turned on, only disk statistics will be displayed, unless .Fl C or .Fl T is also specified to enable the display of CPU or TTY statistics. .It Fl z If .Fl x is specified, omit lines for devices with no activity. .It Fl ?\& Display a usage statement and exit. .El .Pp The .Nm utility displays its information in the following format: .Bl -tag -width flag .It tty .Bl -tag -width indent -compact .It tin characters read from terminals .It tout characters written to terminals .El .It devices Device operations. The header of the field is the device name and unit number. The .Nm utility will display as many devices as will fit in a standard 80 column screen, or the maximum number of devices in the system, whichever is smaller. If .Fl n is specified on the command line, .Nm will display the smaller of the requested number of devices, and the maximum number of devices in the system. To force .Nm to display specific drives, their names may be supplied on the command line. The .Nm utility will not display more devices than will fit in an 80 column screen, unless the .Fl n argument is given on the command line to specify a maximum number of devices to display. If fewer devices are specified on the command line than will fit in an 80 column screen, .Nm will show only the specified devices. .Pp The standard .Nm device display shows the following statistics: .Pp .Bl -tag -width indent -compact .It KB/t kilobytes per transfer .It tps transfers per second .It MB/s megabytes per second .El .Pp The standard .Nm device display, with the .Fl I flag specified, shows the following statistics: .Pp .Bl -tag -width indent -compact .It KB/t kilobytes per transfer .It xfrs total number of transfers .It MB total number of megabytes transferred .El .Pp The extended .Nm device display, with the .Fl x flag specified, shows the following statistics: .Pp .Bl -tag -width indent -compact .It r/s read operations per second .It w/s write operations per second .It kr/s kilobytes read per second .It kw/s kilobytes write per second .It qlen transactions queue length .It svc_t average duration of transactions, in milliseconds .It %b % of time the device had one or more outstanding transactions .El .Pp The extended .Nm device display, with the .Fl x and .Fl I flags specified, shows the following statistics: .Pp .Bl -tag -width indent -compact .It r/i read operations per time period .It w/i write operations per time period .It kr/i kilobytes read per time period .It kw/i kilobytes write per time period .It qlen transactions queue length .It tsvc_t/i total duration of transactions per time period, in seconds .It sb/i total time the device had one or more outstanding transactions per time period, in seconds .El .Pp The old-style .Nm display (using .Fl o ) shows the following statistics: .Pp .Bl -tag -width indent -compact .It sps sectors transferred per second .It tps transfers per second .It msps average milliseconds per transaction .El .Pp The old-style .Nm display, with the .Fl I flag specified, shows the following statistics: .Pp .Bl -tag -width indent -compact .It blk total blocks/sectors transferred .It xfr total transfers .It msps average milliseconds per transaction .El .It cpu .Bl -tag -width indent -compact .It \&us % of cpu time in user mode .It \&ni % of cpu time in user mode running niced processes .It \&sy % of cpu time in system mode .It \&in % of cpu time in interrupt mode .It \&id % of cpu time in idle mode .El .El .Sh FILES .Bl -tag -width /boot/kernel/kernel -compact .It Pa /boot/kernel/kernel Default kernel namelist. .It Pa /dev/kmem Default memory file. .El .Sh EXAMPLES .Dl iostat -w 1 da0 da1 cd0 .Pp Display statistics for the first two Direct Access devices and the first CDROM device every second ad infinitum. .Pp .Dl iostat -c 2 .Pp Display the statistics for the first four devices in the system twice, with a one second display interval. .Pp .Dl iostat -t da -t cd -w 1 .Pp Display statistics for all CDROM and Direct Access devices every second ad infinitum. .Pp .Dl iostat -t da,scsi,pass -t cd,scsi,pass .Pp Display statistics once for all SCSI passthrough devices that provide access to either Direct Access or CDROM devices. .Pp .Dl iostat -h -n 8 -w 1 .Pp Display up to 8 devices with the most I/O every second ad infinitum. .Pp .Dl iostat -dh -t da -w 1 .Pp Omit the TTY and CPU displays, show devices in order of performance and show only Direct Access devices every second ad infinitum. .Pp .Dl iostat -Iw 3 .Pp Display total statistics every three seconds ad infinitum. .Pp .Dl iostat -odICTw 2 -c 9 .Pp Display total statistics using the old-style output format 9 times, with a two second interval between each measurement/display. The .Fl d flag generally disables the TTY and CPU displays, but since the .Fl T and .Fl C flags are given, the TTY and CPU displays will be displayed. .Sh SEE ALSO .Xr fstat 1 , .Xr netstat 1 , .Xr nfsstat 1 , .Xr ps 1 , .Xr systat 1 , .Xr devstat 3 , +.Xr ctlstat 8 , .Xr gstat 8 , .Xr pstat 8 , .Xr vmstat 8 .Pp The sections starting with ``Interpreting system activity'' in .%T "Installing and Operating 4.3BSD" . .Sh HISTORY This version of .Nm first appeared in .Fx 3.0 . .Sh AUTHORS .An Kenneth Merry Aq Mt ken@FreeBSD.org .Sh BUGS The use of .Nm as a debugging tool for crash dumps is probably limited because there is currently no way to get statistics that only cover the time immediately before the crash.