tw_cli(8) - 3ware Storage Controller Management Command Line Interface.
tw_cli Interactive Mode tw_cli -f file Process from a file tw_cli command Process single command (batch mode)
tw_cli(8) is a Command Line Interface Storage Management Software for 3Ware ATA RAID Controller(s). It provides controller, logical unit and drive management. tw_cli can be used in both interactive and batch mode, providing higher level API (Application Programming Interface) functionalities.
As a way of synchronizing terminologies, logical units (aka units) are block devices presented to operating systems. A logical unit can be a one-tier, two-tier, or three-tier arrangement. JBOD, spare, and single logical units are examples of one-tier units. RAID-1 and RAID-5 are examples of two-tier units and as such will have sub-units. RAID-10 and RAID-50 are examples of three-tier units and as such will have sub-sub-units. A controller has one or many ports (typically 4, 8, 12). Each port is connected to zero or one disk drive.
The functionality provided by tw_cli(8) can be divided into the following categories:
------------------------------------------------------------
Info commands are read-only operations showing various values of controllers, units and drives.
Typical output looks like:
3ware CLI> info
Ctl Model Ports Drives Units NotOpt RRate VRate --------------------------------------------------------------------- c0 7500-12 12 8 3 1 2 - c1 9506S-12 12 6 1 0 3 5
Indicating that Controller 0 is a 7500 model with 12 Ports, with 8 Drives detected (attached), total of 1 Units, with one unit in a NotOpt (Not Optimal) state, RRate (Rebuild Rate) of 2, VRate (Verify Rate) of '-' (Not Applicable). Not Optimal refers to any state except OK and VERIFYING. Other states include INITIALIZING, REBUILDING, DEGRADED, MIGRATING, and INOPERABLE.
The Unit summary section lists all present units specifying their Unit Number, Unit type (such RAID 5), Status, usable capacity in Giga (or Tera) Bytes, number of blocks and unit status such as OK, VERIFYING, INITIALIZING, etc. %Compl reports percent completion of REBUILDING or VERIFYING units.
The Port summary section lists all present ports specifying the port number, disk status, unit affiliation, size (in human readable and blocks of 512 bytes), and disk vendor assigned serial number.
Additional attributes about controllers, units, ports and disks can be obtained by querying for them explicitly. See other info sub-commands below.
Typical output looks like:
3ware CLI> info c0 Unit UnitType Status %Cmpl Stripe Size(GB) Cache AVerify OvrECC ------------------------------------------------------------------------------------ u0 RAID-1 OK - - 149.05 ON OFF OFF u1 RAID-5 OK - 64k 298.22 ON OFF OFF u2 SPARE OK - - 149.05 ON OFF - Port Status Unit Size Blocks Serial --------------------------------------------------------------- p0 OK u0 149.05 GB 312581808 3JS0TF14 p1 OK u0 149.05 GB 312581808 3JS0TETZ p2 OK u1 149.05 GB 312581808 3JS0VG85 p3 OK u1 149.05 GB 312581808 3JS0VGCY p4 OK u1 149.05 GB 312581808 3JS0VGGQ p5 OK u2 149.05 GB 312581808 3JS0VH1P p6 OK - 149.05 GB 312581808 3JS0TF0P p7 OK - 149.05 GB 312581808 3JS0VF43 p8 OK - 149.05 GB 312581808 3JS0VG8D p9 NOT-PRESENT - - - - p10 NOT-PRESENT - - - - p11 NOT-PRESENT - - - -
Example:
3ware CLI> info c0 driver /c0 Driver Version = 1.02.00.036
Example:
3ware CLI> info c0 model /c0 Model = 7500-12
Example:
3ware CLI> info c0 firmware /c0 Firmware Version = FGXX 2.01.00.025
Example:
3ware CLI> info c0 bios /c0 BIOS Version = BG9X 2.01.00.026
Example:
3ware CLI> info c0 monitor /c0 Monitor Version = BLDR 1.00.00.008
Example:
3ware CLI> info c0 serial /c0 Serial Number = F12705A3240009
Example:
3ware CLI> info c0 pcb /c0 PCB Version = Rev3
Example:
3ware CLI> info c0 pchip /c0 PCHIP Version = 1.30-33
Example:
3ware CLI> info c0 achip /c0 ACHIP Version = 3.20
Example:
3ware CLI> info c0 numports /c0 Number of Ports = 12
Example:
3ware CLI> info c0 numunits /c0 Number of Units = 1
disk(s) will not be detected unless
I/O is performed against the disk. See info cid pid smart for a workaround.
Example:
3ware CLI> info c0 numdrives /c0 Number of Drives = 5
Example:
3ware CLI> info c0 unitstatus
Unit UnitType Status %Cmpl Size Blocks --------------------------------------------------------------- u0 RAID-1 OK - 149.00 GB 312480256 u1 RAID-5 OK - 298.00 GB 624960512 u2 SPARE OK - 149.04 GB 312562352
Example:
3ware CLI> info c0 allunitstatus Total Units = 2 NotOptimal Units = 0
Example:
3ware CLI> info c0 drivestatus
Port Status Unit Size Blocks Serial --------------------------------------------------------------- p0 OK u0 149.05 GB 312581808 3JS0TF14 p1 OK u0 149.05 GB 312581808 3JS0TETZ p2 OK u1 149.05 GB 312581808 3JS0VG85 p3 OK u1 149.05 GB 312581808 3JS0VGCY p4 OK u1 149.05 GB 312581808 3JS0VGGQ p5 OK u2 149.05 GB 312581808 3JS0VH1P p6 OK - 149.05 GB 312581808 3JS0TF0P p7 OK - 149.05 GB 312581808 3JS0VF43 p8 OK - 149.05 GB 312581808 3JS0VG8D p9 NOT-PRESENT - - - - p10 NOT-PRESENT - - - - p11 NOT-PRESENT - - - -
Example:
3ware CLI> info c0 u5
Unit UnitType Status %Cmpl Port Stripe Size(GB) Blocks ---------------------------------------------------------------------- u0 RAID-50 OK - - 64K 596.05 1249921024 u0-0 RAID-5 OK - - 64K - - u0-0-0 DISK OK - p0 - 149.10 312481280 u0-0-1 DISK OK - p2 - 149.10 312481280 u0-0-2 DISK OK - p3 - 149.10 312481280 u0-1 RAID-5 OK - - 64K - - u0-1-0 DISK OK - p4 - 149.10 312481280 u0-1-1 DISK OK - p5 - 149.10 312481280 u0-1-2 DISK OK - p6 - 149.10 312481280
Example:
3ware CLI> info c0 u5 status /c0/u5 status = DEGRADED
Example:
3ware CLI> info c0 u5 rebuildstatus /c0/u5 is not rebuilding, its current state is OK
Example:
3ware CLI> info c0 u5 verifystatus /c0/u5 is not verifying, its current state is OK
Example:
3ware CLI> info c0 u5 initializestatus /c0/u5 is not initializing, its current state is OK
Example:
3ware CLI> info c0 p5 Port Status Unit Size Blocks Serial --------------------------------------------------------------- p5 OK u5 149.05 GB 312581808 WD-WMACK1406498
The above report indicate that port 5 of controller 0 is attached to one Western Digital disk with status OK participating in unit 5.
Example:
3ware CLI> info c0 p5 status /c0/p5 Status = OK
Example:
3ware CLI> info c0 p5 model /c0/p5 Model = WDC WD1600BB-00DAA0
Example:
3ware CLI> info c0 p5 serial /c0/p5 Serial = WD-WMACK1406498
Example:
3ware CLI> info c0 p5 firmware /c0/p5 Firmware Version = 65.13G65
Example:
3ware CLI> info c0 p5 capacity 149.05 GB (312581808)
Example:
3ware CLI> info c0 p5 smart
10 00 01 0B 00 C8 C8 00 00 00 00 00 00 00 03 07 00 9A 96 BC 14 00 00 00 00 00 04 32 00 64 64 7A 00 00 00 00 00 00 05 33 00 C8 C8 00 00 00 00 00 ... 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 2C
Note that at this writing, we are not decoding the SMART data. Also note that if the disk attatched to the specified port is not present or there are cabling problems reaching the disk, CLI will return successful but the SMART data is all zeros. This could be one way of detecting whether a disk is present or not.
Example:
tw_cli info c0 diag > diag.txt
Sub-commands under this category allow you to create and mutate objects and their attributes such as creating and deleting logical units, rebuilding, flushing, etc. These commands are read/write operations and should be used with care.
Use of the keyword ``maint'' is now optional. That is ``maint rescan c0'' is the same as ``rescan c0''.
If no controller is specified, all controllers will be rescanned. One or many controllers can be specified. noscan is used to not inform the OS of the unit discovery. Default is to inform the OS.
Example:
3ware CLI> maint rescan Rescanning controller /c0 for units and drives ...Done. Rescanning controller /c1 for units and drives ...Done.
Since this command is by far the richest command, it deserves more details.
cid is the controller name as in c0, c1, etc.
RaidType consists of letter ``r'' followed by RAID or logical unit type as in raid0, raid1, raid5, raid10, raid50, single, spare, and jbod. For example ``rraid50''. The following table illustrates supported types and controller models.
Model | R0 | R1 | R5 | R10 | JBOD | Spare | R50 | Single | ------+----+----+----+-----+------+-------+-----+--------+ 7K/8K | Y | Y | Y | Y | Y | Y | N | N | ------+----+----+----+-----+------+-------+-----+--------+ 9K | Y | Y | Y | Y | Y | Y | Y | Y |
PidList consists of letter ``p'' followed by a list of ports (disks) to be used in the construction of the specified unit type. One or more ports can be specified. Multiple ports can be specified using ``:'' or ``-'' as port index separators. A dash indicates a range and can be mixed with ``:''. For example p0:1:2-5:9:12 indicates port 0, 1, 2 thru 5 (inclusive), 9 and 12.
Stripe consists of letter ``k'' followed by the stripe size to be used. The following table illustrates the supported and applicable stripes on unit types and controller models. Stripe size units are in K (kilo bytes).
Model | R0 | R1 | R5 | R10 | JBOD | Spare | R50 | Single |
------+------+-----+-----+------+------+-------+-----+--------+
7K/8K | 64 | N/A | 64 | 64 | N/A | N/A | N/S | N/S |
| 128 | | | 128 | | | | |
| 256 | | | 256 | | | | |
| 512 | | | 512 | | | | |
| 1024 | | | 1024 | | | | |
------+------+-----+-----+------+------+-------+-----+--------+
9K | 16 | N/A | 16 | 16 | N/A | N/A | 16 | N/A |
| 64 | | 64 | 64 | | | 64 | |
| 256 | | 256 | 256 | | | 256 | |
------+------+-----+-----+------+------+-------+-----+--------+
DskGrp consists of letter ``g'' followed by the number of disks per group for a RAID-50 type. Recall that a RAID-50 is a multi-tier array. At the most bottom layer, N number of disks per group are used to form the RAID-5 layer. These RAID-5 arrays are then integrated into a RAID-0. This option allows you to specify the number of disks in the RAID-5 level. Valid values are 3, 4, 5 and 6.
Note that a sufficient number of disks are required for a given pattern or disk group. For example, given 6 disks, specifying 3 will create two RAID-5. However given 12 disks, specifying 3 will create four RAID-5 under the RAID-0 level. Given 6 disks and grouping of 6 is not allowed, as you'll basically be creating a RAID-5.
The default gDskGrp varies based on number of disks. For 6 & 9 disks, default is g3. For 8 disks, default is g4. For 10 disks, default is g5 and for 12 disks, default is g4. Case of 12 disks could be grouped with g3, g4, or g6. g4 was set by default as it provides best net capacity and performance.
noscan switch instructs CLI not to notify OS of creation of the new unit. By default CLI will inform the OS. One application of this feature is to avoid the OS from creating block special devices such as /dev/sdb and /dev/sdc as some implementations might create naming fragmentation and creating a moving target.
nocache switch instructs CLI disable the write cache on the newly create unit. Enabling write cache increases performance at the cost of high-availability.
autoverify switch enables the autoverify attribute on the unit that is to be created. For more details on this feature, refer to Set Commands section of this document. This feature is not supported on model 7000/8000. On model 9000, JBOD autoverify attribute is not persistent (does not survive reboots).
ignoreECC switch enables the ignoreECC/OverwriteECC attribute on the unit that is to be created. For more details on this feature, refer to Set Commands section of this document. The following table illustrates the supported Model-UnitType. This table only applies to setting this feature at unit creation time. Generally ignoreECC applies to redundant units.
Model | R0 | R1 | R5 | R10 | JBOD | Spare | R50 | Single | ------+----+----+----+-----+------+-------+-----+--------+ 7K/8K | N | N | N | N | N | N | N | N | ------+----+----+----+-----+------+-------+-----+--------+ 9K | N | Y | Y | Y | N | N | Y | N |
Note that the port (disk) to be used to rebuild a unit, must be a SPARE or configured disk.
at(1) or user supplied programs.
See also Sched Commands.
Model | R-0 | R-1 | R-5 | R-10 | R-50 | Single | JBOD | Spare | ------+-----+-----+-----+------+------+--------+------+-------+ 7K/8K | No | Yes | Yes | Yes | N/A | N/A | No | No | ------+-----+-----+-----+------+------+--------+------+-------+ 9K | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | ------+-----+-----+-----+------+------+--------+------+-------+
Note that if subsequent to this command, one enables the background verify task to follow the scheduled slots, then this on-demand task will be ignored.
disk(s) and clear the in-transaction
bit.
Typical application of this feature is when an application is using a given unit in raw mode (such as databases) and user would like to shutdown the host (Including UPS post failure automations). This command can then expedite the process by instructing the controller to finish pending requests, clear DCB's in-transaction flag as we are going down.
Note that block devices (cooked devices) do not require this and clients of block devices (such as Filesystem) will send such requests via ASPI SRB_SHUTDOWN_REQUEST.
This command only applies to Windows operating system. This command was previously known as 'shutdown'.
Model 9000 supports background tasks. Background tasks include ``rebuild'', ``verify'', or ``selftest'' activities. For each activity, up to 7 tasks can be registered, known as slot 0 through 6. Each activity can be managed by this command including adding, removing, enabling and disabling a task. Background tasks have slot id, category (rebuild, verify, selftest), start-day-time and duration attributes.
rebuild activity attempts to (re)synchronize all members of redundant units such as RAID-1, RAID-10, RAID-5 and RAID-50. Rebuild can be started manually or automatically if a spare has been defined. Scheduled rebuilds will take place during the scheduled window AND if enabled.
verify activity attempts to verify all units based on their unit type. Verifying RAID-1 involves checking that both drives contain the exact data. On RAID-5, the parity information is used to verify data integrity. RAID-10 and 50 are composite types and follow their respective array types. On 9000 series, non redundant units such as RAID-0, JBOD, single, and spare, are also verified (by reading and reporting un-readable sectors).
selftest activity provides two types of selftests; UDMA (Ultra Direct Memory Access) and SMART (Self Monitoring Analysis and Reporting). UDMA selftest entails checking the current ATA bus speed (between controller and attached disk), which could have been throttled down during previous operations and increase the speed for best performance (usually one level higher). Possible speeds include 33, 66, 100 and 133 Mhz (at this writing). Note that UDMA selftest is not applicable (or required) with SATA drives.
SMART activity instructs the controller to check certain SMART supported thresholds by the disk vendor.
$ tw_cli sched rebuild c1
Rebuild Schedule for Controller /c1 ======================================================== Slot Day Hour Duration Status -------------------------------------------------------- 0 Mon 2:00pm 10 hr(s) disabled 1 Thu 7:00pm 18 hr(s) disabled 2 - - - - 3 - - - - 4 - - - - 5 Mon 1:00am 4 hr(s) disabled 6 Sun 12:00am 1 hr(s) disabled
Status ``disabled'' indicates that the controller will not use the tabled schedules.
For example:
$ tw_cli sched rebuild c1 add d0 h16 t3
Will add a rebuild background task to be executed on Sundays at 4:00 PM for a duration of 3 hours.
For example:
$ tw_cli sched rebuild c1 remove 2
Will remove rebuild background task in slot 2.
Warning: If all timeslots are removed, be sure to also disable the schedule. Otherwise the applicable background task will never occur.
$ tw_cli sched verify c1
Verify Schedule for Controller /c1 ======================================================== Slot Day Hour Duration Status -------------------------------------------------------- 0 Mon 2:00am 4 hr(s) disabled 1 - - - - 2 Tue 12:00am 24 hr(s) disabled 3 Wed 12:00am 24 hr(s) disabled 4 Thu 12:00am 24 hr(s) disabled 5 Fri 12:00am 24 hr(s) disabled 6 Sat 12:00am 24 hr(s) disabled
Status indicates that the controller will not use the tabled schedules.
For example:
$ tw_cli sched verify c1 add d0 h16 t3
Will add a verify background task to be executed on Sundays at 4:00 PM for a duration of 3 hours.
For example:
$ tw_cli sched verify c1 remove 3
Will remove rebuild background task in slot 3.
Warning: If all timeslots are removed, be sure to also disable the schedule. Otherwise the applicable background task will never occur.
$ tw_cli sched selftest c1
Selftest Schedule for Controller /c1 ======================================================== Slot Day Hour UDMA SMART -------------------------------------------------------- 0 Sun 12:00am enabled enabled 1 Mon 12:00am enabled enabled 2 Tue 12:00am enabled enabled 3 Wed 12:00am enabled enabled 4 Thu 12:00am enabled enabled 5 Fri 12:00am enabled enabled 6 Sat 12:00am enabled enabled
For example:
$ tw_cli sched selftest c1 add d0 h16
Will add a selftest background task to be executed on Sundays at 4:00 PM.
For example:
$ tw_cli sched selftest c1 remove 3
Will remove rebuild background task in slot 3.
Warning: If all timeslots are removed, be sure to also disable the schedule. Otherwise the applicable background task will never occur.
For example:
$ tw_cli sched selftest c1 enable s0
Will enable UDMA selftest on controller c0.
For example:
$ tw_cli sched selftest c1 disable s1
Will disable SMART selftest on controller c0.
Asynchronous events are originated by firmware and captured by their respective device drivers. These events are kept in a finite queue inside the kernel, awaiting extraction by user space programs such as CLI and/or 3DMPlus. These events reflect warning, debugging and/or informative messages for end user.
Alarms generated on 7000/8000 models do not have dates, as such you'll see a '-' (read not-applicable) in ``Date'' column. Also on 7000/8000 models, the alarm message, contain the severity as well, hence the ``Severity'' column is showing a '-' as well.
Typical output looks like:
tw_cli> alarms
Ctl Date Severity Message -------------------------------------------------- c0 - - ERROR: Unit degraded: Unit #0 c1 [Fri Nov 28 04:26:31 2003] ERROR (0x04:0x0002): Degraded unit detected: unit=0, port=2 c1 [Fri Nov 28 06:13:54 2003] INFO (0x04:0x000B): Rebuild started: unit=0 c1 [Fri Nov 28 06:30:35 2003] INFO (0x04:0x003B): Background rebuild paused: unit=0 c1 [Fri Nov 28 06:33:00 2003] ERROR (0x04:0x0002): Degraded unit detected: unit=0, port=0 c1 [Fri Nov 28 06:33:04 2003] ERROR (0x04:0x0002): Degraded unit detected: unit=0, port=4 c1 [Fri Nov 28 06:33:46 2003] INFO (0x04:0x000B): Rebuild started: unit=0 c1 [Fri Nov 28 06:37:58 2003] INFO (0x04:0x000B): Rebuild started: unit=0 c1 [Fri Nov 28 07:51:34 2003] INFO (0x04:0x0005): Background rebuild done: unit=0 c1 [Fri Nov 28 07:59:43 2003] INFO (0x04:0x0005): Background rebuild done: unit=0 c1 [Mon Dec 1 02:26:12 2003] ERROR (0x04:0x0002): Degraded unit detected: unit=0, port=3
These commands allow you to view and/or set certain controller and unit specific parameters as described below.
Model | R-0 | R-1 | R-5 | R-10 | R-50 | Single | JBOD | Spare | ------+-----+-----+-----+------+------+--------+------+-------+ 7K/8K | Yes | Yes | Yes | Yes | N/A | N/A | Yes | No | ------+-----+-----+-----+------+------+--------+------+-------+ 9K | Yes | Yes | Yes | Yes | Yes | Yes | Yes | No | ------+-----+-----+-----+------+------+--------+------+-------+
This command set provides brief on-line help.
3ware CLI> help Copyright (c) 2003 3ware, Inc. All rights reserved. 3ware CLI (version 2.00.00.042)
List of Commands ------------------------------------------- info - displays information about the controller alarms - displays or deletes the list of AENs set - displays or modifies controller settings maint - performs maintenance operations on a controller sched - Sets the schedule for a controller (9000 controllers only) quit - exits the CLI
Type help <command> to get more details about a particular command.
While informative messages are written to standard output, error messages are written to standard error. On success, 0 is returned. On failure 1 is returned.
tw_cli(8) reporting has changed (hopefully for better). The intent has been to
provide a consistent tabular reporting so that relevant and important information
(such as info) are made available as fast as possible. For example, firmware,
PCB, PCHIP and similar information have been removed from the info summary report,
as this type of information is not frequently needed.
The new style also accommodates automation much better by providing consistent columns with or without values so that it could be easily parsed. The intent is to make CLI yet another API (to approach it).
However to accommodate current automations around tw_cli and to ease the migration, the old behavior can still be requested by setting TW_CLI_STYLE environment variable to OLD as follows:
If Bash, then "export TW_CLI_STYLE=OLD" If csh, then "setenv TW_CLI_STYLE OLD" if Windows, then "set TW_CLI_STYLE=OLD"
This backward compatibility window, will be communicated by official 3Ware representatives.
TW_CLI_STYLE setting this variable to OLD, will provide the old reporting style.
Medi Montaseri, support@3ware.com
3Ware CLI User Guide 3Ware User Guide 3Ware Installation Guide http://www.3ware.com