Chapter 3  Installation

3.1  compatibilitySBUS Controller Compatibility

3.2  hardware installationHardware Installation Procedure

GNOME:

1. From the login screen right click the "Options" button.
2. On the popup menu select System -> Halt.
3. Click "Yes" when the verification box appears

KDE:

1. From the login screen right click shutdown.
2. On the popup menu select shutdown by right clicking its radio button.
3. Click OK

XDM:

1. login as root
2. Left click on the desktop to bring up the pop-up menu
3. select "New Shell"
4. When the shell opens type "halt" at the prompt and press return

Console Login (systems without X windows):

1. Login as root
2. Type "halt"

All Systems:

SPARCstation 4, 5, 10, 20 & UltraSPARC Systems:

1. Remove the top cover on the CPU enclosure. On a SPARCstation 10, this is done by loosening the captive screw at the top right corner of the back of the CPU enclosure, then tilting the top of the enclosure forward while using a Phillips screwdriver to press the plastic tab on the top left corner.
2. Decide which SBUS slot you will use. Any slot will do. Remove the filler panel for that slot by removing the two screws and rectangular washers that hold it in.
3. Remove the SBUS retainer (commonly called the handle) by pressing outward on one leg of the retainer while pulling it out of the hole in the printed circuit board.
4. Insert the board into the SBUS slot you have chosen. To insert the board, first engage the top of the 5070 RAIDium backpanel into the backpanel of the CPU enclosure, then rotate the board into a level position and mate the SBUS connectors. Make sure that the SBUS connectors are completely engaged.
5. Snap the nylon board retainers inside the SPARCstation over the 5070 RAIDium board to secure it inside the system.
6. Secure the 5070 RAIDium SBUS backpanel to the system by replacing the rectangular washers and screws that held the original filler panel in place.
7. Replace the top cover by first mating the plastic hooks on the front of the cover to the chassis, then rotating the cover down over the unit until the plastic tab in back snaps into place. Tighten the captive screw on the upper right corner.

Ultra Enterprise Servers, SPARCserver 1000 & 2000 Systems, SPARCserver 6XO MP Series:

1. Remove the two Allen screws that secure the CPU board to the card cage. These are located at each end of the CPU board backpanel.
2. Remove the CPU board from the enclosure and place it on a static-free surface.
3. Decide which SBUS slot you will use. Any slot will do. Remove the filler panel for that slot by removing the two screws and rectangular washers that hold it in. Save these screws and washers.
4. Remove the SBUS retainer (commonly called the handle) by pressing outward on one leg of the retainer while pulling it out of the hole in the printed circuit board.
5. Insert the board into the SBUS slot you have chosen. To insert the board, first engage the top of the 5070 RAIDium backpanel into the backpanel of the CPU enclosure, then rotate the board into a level position and mate the SBUS connectors. Make sure that the SBUS connectors are completely engaged.
6. Secure the 5070 RAIDium board to the CPU board with the nylon screws and standoffs provided on the CPU board. The standoffs may have to be moved so that they match the holes used by the SBUS retainer, as the standoffs are used in different holes for an MBus module. Replace the screws and rectangular washers that originally held the filler panel in place, securing the 5070 RAIDium SBus backpanel to the system enclosure.
7. Re-insert the CPU board into the CPU enclosure and re-install the Allen-head retaining screws that secure the CPU board.

All Systems:

1. Mate the external cable adapter box to the 5070 RAIDium and gently tighten the two screws that extend through the cable adapter box.
2. Connect the three cables from your SCSI devices to the three 68-pin SCSI-3 connectors on the Antares 5070 RAIDium. The three SCSI cables must always be reconnected in the same order after a RAID set has been established, so you should clearly mark the cables and disk enclosures for future disassembly and reassembly.
3. Configure the attached SCSI devices to use SCSI target IDs other than 7, as that is taken by the 5070 RAIDium itself. Configuring the target number is done differently on various devices. Consult the manufacturer's installation instructions to determine the method appropriate for your device.
4. As you are likely to be installing multiple SCSI devices, make sure that all SCSI buses are properly terminated. This means a terminator is installed only at each end of each SCSI bus daisy chain.

Verifying the Hardware Installation:

3.2.1  Serial Terminal

3.2.2  Hard Drive Plant

• Remember, you generally get what you pay for. I strongly recommend paying the extra money for better (i.e. more reliable) hardware especially if you are setting up a RAID for a mission critical project. For example, consider purchasing drive cabinets with redundant hot-swappable power supplies, etc.
• You will also want a UPS for your host system and drive cabinets. Remember, RAID levels 3 and 5 protect you from data loss due to drive failure NOT power failure.
• The drive cabinet you select should have hot swappable drive bays, these cost more but are definitely worth it when you need to add/change drives.
• Make sure the cabinet(s) have adequate cooling when fully loaded with drives.
• Keep your SCSI cables (internal and external) as short as possible
• Mark the drives/cabinet(s) in such a way that you will be able to reconnect them to the controller in their original configuration. Once the RAID is configured you cannot re-organize you drives without re-configuring the RAID (and subsequently erasing the data stored on it).
• Keep in mind that although it is physically possible to connect/configure up to 6 drives per channel, performance will sharply decrease for RAIDs with more than three drives per channel. This is due to the 25 MHz bandwidth limitation of the SBUS. Therefore, if read/write performance is an issue go with a small number of large drives. If you need a really large RAID (~ 1 terabyte) then you will have no other choice but to load the channels to capacity and pay the performance penalty. NOTE: if you are serving files over a 10/100 Base T network you may not notice the performance decrease since the network is usually the bottleneck not the SBUS.

3.3  5070 Onboard Configuration

• "RaidRunner" is the name given to the the 5070 controller board.
• "Husky" is the name given to the shell which produces the ":raid;" command prompt. It is a command language interpreter that executes commands read from the standard input or from a file. Husky is a scaled down model of Unix's Bourne shell (sh). One major difference is that husky has no concept of current working directory. For more information on the husky shell and command prompt see the "Advanced Topics" section
• The "host port" is the SCSI ID assigned to the controller card itself. This is usually ID 7.
• A "backend" is a drive attached to the controller on a given channel.
• A "rank" is a collection of all the backends from each channel with the same SCSI ID
  (i.e. rank 0 would consist of all the drives with SCSI ID 0 on each channel)
• Each of the backends is identified by a three digit number where the first digit is the channel, the second the SCSI ID of the drive, and the third the LUN of the drive. The numbers are separated by a period. The identifier is prefixed with a "D" if it is a disk or "T" if it is a tape (e.g. D0.1.0). This scheme is referred to as <device_type_c.s.l> in the following documentation.
• A "RAID set" consists of given number of backends (there are certain requirements which I'll come to later)
• A "spare" is a drive which is unused until there is a failure in one of the RAID drives. At that time the damaged drive is automatically taken offline and replaced with the spare. The data is then reconstructed on the spare and the RAID resumes normal operation.
• Spares may either be "hot" or "warm" depending on user configuration. Hot spares are spun up when the RAID is started, which shortens the replacement time when a drive failure occurs. Warm spares are spun up when needed, which saves wear on the drive.

3.3.1  Main Screen Options

---

Figure 3.1: The main screen of the 5070 onboard configuration utility

---

• [Q]uit: Exit the main screen and return to the husky prompt.
• [R]aidSets: Enter the RaidSet configuration screen.
• [H]ostports Enter the Host Port configuration screen.
• [S]pares Enter the Spare Device configuration screen.
• [M]onitor Enter the SCSI Monitor configuration screen.
• [G]eneral Enter the General configuration/information screen.
• [P]robe Re-probe the device backends on the RaidRunner. As each backend is probed it's "name" (c.s.l format) is displayed in the bottom left corner of the screen.

3.3.2  [Q]uit

3.3.3  [R]aidSets:

---

Figure 3.2: The RAIDSet configuration screen.

---

• [Q]uit: Exit the Raid Set Configuration screen and return to the Main screen. If you have modified, deleted or added a raid set and have not installed the changes you will be asked to confirm this. If you select Yes to continue the exit, all changes made since the last install action will be discarded.
• [I]nst: This action installs (into the RaidRunner configuration area) any changes that may have been made to raid sets, be that deletion, addition or modification. If you exit prior to installing, all changes made since the last installation will be discarded. The installation process takes time. It is complete once the typed "i" character, is cleared from the menu line.
• [M]od: This action allows you to modify the displayed raid set. You will be prompted for each Raid Set attribute that can be changed. The prompt includes allowable options or formats required. If you don't wish to change a particular attribute, then press the RETURN or TAB key. The attributes you can change are the raid set name, I/O mode, status (Active to Inactive), bootmode, spares usage, backend zone table usage, IO size (if raid set has never been used - i.e. just added), cache size, I/O queues length, host interfaces and additional stargd arguments. If you wish to change a single attribute then use the RETURN or TAB key to skip all other options. The changed attribute will be re-displayed as soon as you press the RETURN key. When specifying cache size, you may suffix the number with 'm' or 'M' to indicate the number is in Megabytes or with 'k' or 'K' to indicate the number is in Kilobytes. Note you can only enter whole integer values. When specifying io size, you may suffix the number with 'k' or 'K' to indicate the number is in Kilobytes. When you enter data, it is checked for correctness and if incorrect, a message is displayed and all changes are discarded and you will have to start again. Remember you must install ([I]nst.) any changes.
• [A]dd: When this option is selected you will be prompted for various attributes of the new raid set. These attributes are the raid set name, the raid set type, the initial host interface the raid set is to appear on (in c.h.l format where c is the controller number, h is the host port (0, 1, 2 etc) and l is the SCSI LUN) and finally a list of backends. When backends are to be entered, the screen displays a list of available backends, each with a numeric index (commencing at 0). You select each backend by entering the index and once complete enter q for Quit. As each backend index is entered, it's backend name is displayed in a comma separated list. When you enter data, it is checked for correctness and if incorrect, a message is displayed and the addition will be ignored and you will have to start again. Once the backends are complete, the newly created raid set will be displayed on the screen with supplied and default attributes. You can then modify the raid set to change other attributes. Remember you must install ([I]nst.) any new raid sets.
• [D]elete: This action will delete the currently displayed raid set. If this raid set is Active, then you will not be allowed to delete it. You will have to make it Inactive (via the [M]od. option) then delete it. You will be prompted to confirm the deletion. Once you confirm the deletion, the screen will be cleared and the next raid set will be displayed, if configured. Remember you must install ([I]nst.) any changes.
• [F]irst, [L]ast, [N]ext and [P]rev allow you to scroll through the configured raid sets.

3.3.4  [H]ostports:

---

Figure 3.3: The host port configuration screen.

---

• [Q]uit: Exit the Host Port Configuration screen and return to the Main screen. If you have modified a host port SCSI ID assignment and have not installed the changes you will be asked to confirm this. If you select Yes to continue the exit, all changes made since the last install action will be discarded.
• [I]nstall: This action installs (into the RaidRunner configuration area) any changes that may have been made to host port SCSI ID assign­ ments. If you exit prior to installing, all changes made since the last installation will be discarded. The installation process takes time. It is complete once the typed "i" character, is cleared from the menu line.
• [M]odify: This action allows you to modify the host port SCSI ID assignments for each host port on each controller (if NO external host port SCSI ID switches). You will be prompted for the SCSI ID for each host port. You can enter either a SCSI ID (0 thru 15), the minus "-" character to clear the SCSI ID assignment or RETURN to SKIP. As you enter data, it is checked for correctness and if incorrect, a message will be printed although previously correctly entered data will be retained. Remember you must install ([I]nst.) any changes.

3.3.5  [S]pares:

---

Figure 3.4: The spare device configuration screen.

---

• [Q]uit: Exit the Spare Device Configuration screen and return to the Main screen. If you have modified, deleted or added a spare device and have not installed the changes you will be asked to confirm this. If you select Yes to continue the exit, all changes made since the last install action will be discarded.
• [I]nstall: This action installs (into the RaidRunner configuration area) any changes that may have been made to the spare devices, be that deletion, addition or modification. If you exit prior to installing, all changes made since the last installation will be discarded. The installation process takes time. It is complete once the typed "i" character, is cleared from the menu line.
• [M]odify: This action allows you to modify the unused spare devices. You will be prompted for each spare device attribute that can be changed. The prompt includes allowable options or formats required. If you don't wish to change a particular attribute, then press the RETURN key. The attributes you can change are the new size (in 512-byte blocks), the spin state (H or hot or W for Warm), and the controller allocation (A for any, 0 for controller 0, 1 for controller 1, etc). If you wish to change a single attribute of a spare device, then use the RETURN key to skip all other attributes for each spare device. The changed attribute will not be re-displayed until the last prompted attribute is entered (or skipped). When you enter data, it is checked for cor­ rectness and if incorrect, a message is dis­ played and all changes are discarded and you will have to start again. Remember you must install ([I]nstall) any changes.
• [A]dd: When adding a spare device, the list of available devices is displayed and you are required to type in the device name. Once entered, the spare is added with defaults which you can change, if required, via the [M]odify option. Remember you must install ([I]nstall) any changes.
• [D]elete: When deleting a spare device, the list of spare devices allowed to be deleted is displayed and you are required to type in the required device name. Once entered, the spare is deleted from the screen. Remember you must install ([I]nstall) any changes.

3.3.6  [M]onitor:

---

Figure 3.5: The SCSI monitor configuration screen.

---

• [Q]uit: Exit the SCSI Monitor Configuration screen and return to the Main screen. If you have made changes and have not installed them you will be asked to confirm this. If you select Yes to continue the exit, all changes made since the last install action will be discarded.
• [I]nstall: This action installs (into the RaidRunner configuration area) any changes that may have been made to SCSI Monitor configuration. If you exit prior to installing, all changes made since the last installation will be discarded. The installation process takes time. It is complete once the typed "i" character, is cleared from the menu line.
• [M]odify: This action allows you to modify the SCSI Monitor configuration. The cursor will be moved around the table, prompting you for input. If you do not want to change an attribute, enter RETURN to skip. If you want to delete a SCSI monitor then enter the minus "-" character when prompted for the controller number. If you want to use the default protocol list, then enter RETURN at the Protocol List prompt. As you enter data, it is checked for correctness and if incorrect, a message will be printed and any previously entered data is discarded. You will have to re-enter the data again. Remember you must install ([I]nstall) any changes.

3.3.7  [G]eneral:

---

Figure 3.6: The General Screen. The options accessible from here allow you to view information on the attached devices (SCSI hard drives and tape units), browse the system logs, and examine environment variables.

---

• [Q]uit: Exit the General screen and return to the Main screen.
• [D]evices: Enter the Device information screen (Figure 3.7). The Devices screen displays the name of all devices on the RaidRunner. The menu line allows one to Quit and return to the General screen or display information about the devices.

  ---

  

  
  

  Figure 3.7: The device information screen.

  
  

  ---

  • [Q]uit: Exit the Devices screen and return to the General screen.
  • Device information[I]nformation: The Device Information screen (Figure 3.8) displays information about each device (Figure ). You can scroll through the devices. For disks, information displayed includes, the device name, serial number, vendor name, product id, speed, version, sector size, sector count, total device size in MB, number of cylinders, heads and sectors per track and the zone/notch partitions. The menu line allows one the leave the Device Information screen or browse through devices.

    ---

    

    
    

    Figure 3.8: Example of the information displayed for a hard drive device.

    
    

    ---

    • [Q]uit: Exit the Device Information screen and return to the Devices screen.
    • [F]irst, [L]ast, [N]ext and [P]rev allow you to scroll through the devices and hence display their current data .
• System LogSys[L]og: Enter the System Logger Messages screen (Figure 3.9).

  ---

  

  
  

  Figure 3.9: The system logger messages screen. An example message is shown, there is one message per screen.

  
  

  ---

  • [Q]uit: Exit the System Logger Messages screen and return to the General screen.
  • [F]irst, [L]ast, [N]ext and [P]rev allow you to scroll through the system log.
• Environment variable configuration[E]nvironment: Enter the Global Environment Variable configuration screen (Figure 3.10). The Environment Variable Configuration screen dis­ plays all configured Global Environment Variables and provides a menu which allows you to Add, Delete, Modify and Install (changes) variables. Each variable name is displayed followed by an equals "=" and the value assigned to that variable enclosed in braces - "{" .. "}". The menu line allows you to Quit and return to the General screen or select further actions.

  ---

  

  
  

  Figure 3.10: The global environment variable configuration screen.

  
  

  ---

  • [Q]uit: Exit the Environment Variable Configuration screen and return to the General screen. If you have modified, deleted or added an environment variable and have not installed the changes you will be asked to confirm this. If you select Yes to continue the exit, all changes made since the last install action will be discarded.
  • [I]nst: This action installs (into the RaidRunner configuration area) any changes that may have been made to environment variables, be that deletion, addition or modification. If you exit prior to installing, all changes made since the last installation will be discarded. The installation process takes time. It is complete once the typed "i" character, is cleared from the menu line.
  • [M]od: This action allows you to modify an environment variable's value. You will be prompted for the name of the environment variable and then prompted for it's new value. If the environment variable entered is not found, a message will be printed and you will not be prompted for a new value. If you do not enter a new value, (i.e. just press RETURN) no change will be made. Remember you must install ([I]nstall) any changes.
  • [A]dd: When adding a new environment variable, you will be prompted for it's name and value. Providing the variable name is not already used and you enter a value, the new variable will be added and displayed. Remember you must install ([I]nstall) any changes.
  • [D]elete: When deleting an environment variable, you will be prompted for the variable name and if valid, the environment variable will be deleted. Remember you must install ([I]nstall) any changes.
• Throughput statistics (viewing)[S]tats: Enter the Statistics monitoring screen (Figure 3.11). The Statistics screen display various general and specific statistics about raid sets configured and running on the RaidRunner. The first section of the data area displays the current temperature in degrees Celsius and the current speed of fans in the RaidRunner. The next section of the data area displays various statistics about the named raid set. The statistics are - the current cache hit rate, the cumulative number of reads, read failures, writes and write failures for each backend of the raid set and finally the read and write throughput for each stargd process (indicated by it's process id) that front's the raid set. The menu line allows one the leave the Statistics screen or select further actions.

  ---

  

  
  

  Figure 3.11: The statistics monitoring screen

  
  

  ---

  • [Q]uit: Exit the Statistics screen and return to the General screen.
  • [F]irst, [L]ast, [N]ext and [P]rev allow you to scroll through the statistics.
  • [R]efresh: This option will get the statistics for the given raid set and re-display the current statistics on the screen.
  • [Z]ero: This option will zero the cumulative statistics for the currently displayed raid set.
  • [C]ontinuous: This option will start a back­ ground process that will update the statistics of the currently displayed raid set every 2 seconds. A loop counter is created and updated every 2 seconds also. To inter­ rupt this continuous mode of gathering statistics, just press any character. If you need to re-fresh the display, then press the refresh characters - <Control-l> or <Control-r>.

3.3.8  [P]robe

3.3.9  Example RAID Configuration Session

1. Configuring the Host Port(s)
2. Assigning Spares
3. Configuring the RAID set

• Level 0 : 2 backends
• Level 3 : 2 backends
• Level 5 : 3 backends

1. Power on the computer with the serial terminal connected to the RaidRunner's serial port.
2. When the husky ( :raid; ) prompt appears, Start the GUI by typing "agui" and pressing return.
3. When the main screen appears, select "H" for [H]ostport configuration
4. On some models of RaidRunner the host port in not configurable. If you have only a [Q]uit option here then there is nothing further to be done for the host port configuration, note the values and skip to step 6. If you have add/modify options then your host port is software configurable.
5. If there is no entry for a host port on this screen, add an entry with the parameters: controller=0, hostport=0 , SCSI ID=0. Don't forget to [I]nstall your changes. If there is already and entry present, note the values (they will be used in a later step).
6. From this point onward I will assume the following hardware configuration:
   1. There are 7 - 2.04 gig drives connected as follows:
      1. 2 drives on SCSI channel 0 with SCSI IDs 0 and 1 (backends 0.0.0, and 0.1.0, respectively).
      2. 3 drives on SCSI channel 1 with SCSI IDs 0 ,1 and 5 (backends 1.0.0, 1.1.0, and 1.5.0).
      3. 2 drives on SCSI channel 2 with SCSI IDs 0 and 1 (backends 2.0.0 and 2.1.0).
   2. Therefore:
      1. Rank 0 consists of backends 0.0.0, 1.0.0, 2.0.0
      2. Rank 1 consists of backends 0.1.0, 1.1.0, 2.1.0
      3. Rank 5 contains only the backend 1.5.0
   3. The RaidRunner is assigned to controller 0, hostport 0
7. Press Q to [Q]uit the hostports screen and return to the Main screen.
8. Press S to enter the [S]pares screen
9. Select A to [A]dd a new spare to the spares pool. A list of available backends will be displayed and you will be prompted for the following information:
   
   Enter the device name to add to spares - from above:
   
   enter
   
   D1.5.0
   
   
10. Select I to [I]nstall your changes
11. Select Q to [Q]uit the spares screen and return to the Main screen
12. Select R from the Main screen to enter the [R]aidsets screen.
13. Select A to [A]dd a new RAID set. You will be prompted for each of the RAID set parameters. The prompts and responses are given below.
    1. Enter the name of Raid Set: cim_homes (or whatever you want to call it).
    2. Raid set type [0,1,3,5]: 5
    3. Enter initial host interface - ctlr,hostport,scsilun: 0.0.0
       
       Now a list of the available backends will be displayed in the form:
       0 - D0.0.0 1 - D1.0.0 2 - D2.0.0 3 - D0.1.0 4 - D1.1.0 5 - D2.1.0
    4. Enter index from above - Q to Quit:
       1 press return
       2 press return
       3 press return
       4 press return
       5 press return
       Q
14. After pressing Q you will be returned to the Raid Sets screen. You should see the newly configured Raid set displayed in the data area (Figure 3.12).
15. Press I to [I]nstall the changes

    ---

    

    
    

    Figure 3.12: The RaidSets screen of the GUI showing the newly configured RAID 5

    
    

    ---

16. Press Q to exit the RaidSet screen and return to the the Main screen
17. Press Q to [Q]uit agui and exit to the husky prompt.
18. type "reboot" then press enter. This will reboot the RaidRunner (not the host machine.)
19. When the RaidRunner reboots it will prepare the drives for the newly configured RAID.
    NOTE: Depending on the size of the RAID this could take a few minutes to a few hours. For the above example it takes the 5070 approximately 10 - 20 minutes to stripe the RAID set.
20. Once you see the husky prompt again the RAID is ready for use. You can then proceed with the Linux configuration.

3.4  Linux Configuration

3.4.1  Existing Linux Installation

QLogic SCSI Driver

Device mappings

Partitioning

Installing a filesystem

Mounting

3.4.2  New Linux Installation

1. Configure the host port, RAID sets, and spares as outlined in "Onboard Configuration." Your computer must be on to perform this step since the 5070 is powered from the SBUS. It does not matter if the computer has an operating system installed at this point all we need is power to the controller card.
2. Begin the RedHat SparcLinux installation
3. The installation program will auto detect the 5070 controller and load the Qlogic driver
4. Your virtual RAID drives will appear as ordinary SCSI hard drives to be partitioned and formatted during the installation. NOTE: When using the graphical partitioning utility during the RedHat installation DO NOT designate any partition on the virtual drives as type RAID since they are already hardware managed virtual RAID drives. The RAID selection on the partitioning utilities screen is for setting up a software RAID.
   IMPORTANT NOTE: you may see a small SCSI drive ( usually ~128 MB) on the list of available drives. DO NOT select this drive for use. It is the SMON communication channel NOT a drive. If setup tries to use it it will hang the installer.
5. Thats it, the installation program takes care of everything else !!

3.5  Maintenance

3.5.1  spares, activatingActivating a spare

3.5.2  re-integrating repaired driveRe-integrating a repaired drive into the RAID (levels 3 and 5)

1. Start the text GUI
2. Look the list of backends for the RAID set(s).
3. Backends that have been marked faulty will have a (-) to the right of their ID ( e.g. D1.1.0- ).
4. If you set up spares the ID of the faulty backend will be followed by the ID of the spare that has replaced it ( e.g. D1.1.0-D1.5.0 ) .
5. Write down the ID(s) of the faulty backend(s) (NOT the spares).
6. Press Q to exit agui
7. At the husky prompt type:

   replace <name> <backend> 

   Where <name> is whatever you named the raid set and <backend> is the ID of the backend that is being re-integrated into the RAID. If a spare was in use it will be automatically returned to the spares pool. Be patient, reconstruction can take a few minutes minutes to several hours depending on the RAID level and the size. Fortunately, you can use the RAID as you normally would during this process.

3.6  Troubleshooting / Error Messages

3.6.1  Out of band temperature detected...

• Probable Cause: The 5070 SBUS card is not adequately cooled.
• Solution: Try to improve cooling inside the case. Clean dust from the fans, re-organize the cards so the raid card is closest to the fan, etc. On some of the "pizza box" sun cases (e.g. SPARC 20) you may need to add supplementary cooling fans especially if you have it loaded with cards.

3.6.2  ... failed ... cannot have more than 1 faulty backend.

• Cause: More than one backend in the RAID 3/4/5 has failed (i.e. there is no longer sufficient redundancy to enable the lost data to be reconstructed).
• Solution: You're hosed ... Sorry.
  If you did not assign spares when you configured you RAID 3/4/5 now may be a good time to re-consider the wisdom of that decision. Hopefully you have been making regular backups. Since now you will have to replace the defective drives, re-configure the RAID, and restore the data from a secondary source.

3.6.3  When booting I see: ... Sun disklabel: bad magic 0000 ... unknown partition table.

• Suspected Cause: Incorrect settings in the disk label set by fdisk (or whatever partitioning utility you used). This message seems to happen when you choose one of the preset disk labels rather than "Custom with autoprobed defaults."
• Solution: Since this error does not seem to effect the operation of the drive you can choose to do nothing and be ok. If you want to correct it you can try re-labeling the disk or re-partitioning the disk and choose "Custom with autoprobed defaults." If you are installing RedHat Linux from scratch the installer will get all of this right for you.

3.7  Bugs

3.8  Frequently Asked Questions

3.8.1  How do I reset/erase the onboard configuration?

3.8.2  How can I tell if a drive in my RAID has failed?

3.9  command referenceAdvanced Topics: 5070 Command Reference

3.9.1  autobootAUTOBOOT - script to automatically create all raid sets and scsi monitors

• SYNOPSIS: autoboot
• DESCRIPTION: autoboot is a husky script which is typically executed when a RaidRunner boots. The following steps are taken -
  1. Start all configured scsi monitor daemons (smon).
  2. Test to see if the total cache required by all the raid sets that are to boot is not more than 90% of available memory.
  3. Start all the scsi target daemons (stargd) and set each daemon's mode to "spinning-up" which enables it to respond to all non medium access commands from the host. This is done to allow hosts to gain knowledge about the RaidRunner's scsi targets as quickly as possible.
  4. Bind into the root (ram) filesystem all unused spare backend devices.
  5. Build all raid sets.
  6. If battery backed-up ram is present, check for any saved writes and restore them into the just built raid sets.
  7. Finally, set the state of all scsi target daemons to "spun-up" enabling hosts to fully access the raid set's behind them.

3.9.2  AUTOFAULT - script to automatically mark a backend faulty after a drive failure

• SYNOPSIS: autofault raidset
• DESCRIPTION: autofault is a husky script which is typically executed by a raid file system upon the failure of a backend of that raid set when that raid file system cannot use spare backends or has been configured not to use spare backends. After parsing it's arguments (command and environment) autofault issues a rconf command to mark a given backend as faulty.
• OPTIONS:
  • raidset: The bind point of the raid set whose backend failed.
  • $DRIVE_NUMBER: The index of the backend that failed. The first backend in a raid set is 0. This option is passed as an environment variable.
  • $BLOCK_SIZE: The raid set's io block size in bytes. (Ignored). This option is passed as an environment variable.
  • $QUEUE_LENGTH: The raid set's queue length. (Ignored). This option is passed as an environment variable.
• SEE ALSO: rconf

3.9.3  AUTOREPAIR - script to automatically allocate a spare and reconstruct a raid set

• SYNOPSIS: autorepair raidset size
• DESCRIPTION: autorepair is a husky script which is typically executed by either a raid type 1, 3 or 5 file system upon the failure of a backend of that raid set.
  
  After parsing it's arguments (command and environment) autorepair gets a spare device from the RaidRunner's spares spool. It then engages it in write-only mode and reads the complete raid device which reconstructs the data on the spare. The read is from the raid file system repair entrypoint. Reading from this entrypoint causes a read of a block immediately followed by a write of that block. The read/write sequence is atomic (i.e is not interruptible). Once the reconstruction has completed, a check is made to ensure the spare did not fail during reconstruction and if not, the access mode of the spare device is set to the access mode of the raid set. The process that reads the repair entrypoint is rebuild.
  
  This device reconstruction will take anywhere from 10 minutes to one and a half hours depending on both the size and speed of the backends and the amount of activity the host is generating.
  
  During device reconstruction, pairs of numbers will be printed indicating each 10% of data reconstructed. The pairs of numbers are separated by a slash character, the first number being the number of blocks reconstructed so far and the second being the number number of blocks to be reconstructed. Further status about the rebuild can be gained from running rebuild.
  
  When the spare is allocated both the number of spares currently used on the backend and the spare device name is printed. The number of spares on a backend is referred to the depth of spares on the backend. Thus prior to re-engaging the spare after a reconstruction a check can be made to see if the depth is the same. If it is not, then the spare reconstruction failed and reconstruction using another spare is underway (or no spares are available), and hence we don't re-engage the drive.
  
  
• OPTIONS:
  • raidset: The bind point of the raid set whose backend failed.
  • size : The size of the raid set in 512 byte blocks.
  • $DRIVE_NUMBER: The index of the backend that failed. The first backend in a raid set is 0. This option is passed as an environment variable.
  • $BLOCK_SIZE: The raid set's io block size in bytes. This option is passed as an environment variable.
  • $QUEUE_LENGTH: The raid set's queue length. This option is passed as an environment variable.
• SEE ALSO: rconf, rebuild

3.9.4  BIND - combine elements of the namespace

• SYNOPSIS: bind [-k] new old
• DESCRIPTION: Bind replaces the existing old file (or directory) with the new file (or directory). If the"-k" switch is given then new must be a kernel recognized device (file system). Section 7k of the manual pages documents the devices (sometimes called file systems) that can be bound using the "-k" switch.

3.9.5  BUZZER - get the state or turn on or off the buzzer

• SYNOPSIS: buzzer or buzzer on|off|mute
• DESCRIPTION: Buzzer will either print the state of the buzzer, turn on or off the buzzer or mute it. If no arguments are given then the state of the buzzer is printed, that is on or off will be printed if the buzzer is currently on or off respectively. If the buzzer has been muted, then you will be informed of this. If the buzzer has not been used since the RaidRunner has booted then the special state, unused, is printed. If the argument on is given the buzzer is turned on, if off, the buzzer is turned off. If the argument mute is given then the muted state of the buzzer is changed.
• SEE ALSO: warble, sos

3.9.6  CACHE - display information about and delete cache ranges

• SYNOPSIS: cache [-D moniker] [-I moniker] [-F] [-g moniker first|last] lastoffset
• DESCRIPTION: cache will print (to standard output) information about the given cache range, delete a given cache range, flush the cache or return the last offset of all cache ranges.
• OPTIONS
  • -F: Flush all cache buffers to their backends (typically raid sets).
  • -D moniker: Delete the cache range with moniker (name) moniker.
  • -I moniker: Invalidate the cache for the given cache range (moniker). This is only useful for debugging or elaborate benchmarks.
  • g moniker first|last: Print either the first or last block number of a cache range with moniker (name) moniker.
  • lastoffset: Print the last offset of all cache ranges. The last offset is the last block number of all cache ranges.

3.9.7  CACHEDUMP - Dump the contents of the write cache to battery backed-up ram

• SYNOPSIS: cachedump
• DESCRIPTION: cachedump causes all unwritten data in the RaidRunner's cache to be written out to the battery backed-up ram. No data will be written to battery backed-up ram if there is currently valid data already stored there. This command is typically executed when there is something wrong with the data (or it's organization) in battery backed-up ram and you need to re-initialize it. cachedump will always return a NULL status.
• SEE ALSO: showbat, cacherestore

3.9.8  CACHERESTORE - Load the cache with data from battery backed-up ram

• SYNOPSIS: cacherestore
• DESCRIPTION: cacherestore will check the RaidRunner's battery backed-up ram for any data it has stored as a result of a power failure. It will copy any data directly into the cache. This command is typically executed automatically at boot time and prior to the RaidRunner making it's data available to a host. Having successfully copied any data from battery backed-up ram into the cache, it flushes the cache and then re-initializes battery backed-up ram to indicate it holds no data. cacherestore will return a NULL status on success or 1 if an error occurred during the loading (with a message written to standard error).
• SEE ALSO: showbat

3.9.9  CAT - concatenate files and print on the standard output

• SYNOPSIS: cat [ file... ]
• DESCRIPTION: cat writes the contents of each given file, or standard input if none are given or when a file named `-' is given, to standard output. If the nominated file is a directory then the filenames contained in that directory are sent to standard out (one per line). More information on a file (e.g. its size) can be obtained by using stat. The script file ls uses cat and stat to produce directory listings.
• SEE ALSO echo, ls, stat

3.9.10  CMP - compare the contents of 2 files

• SYNOPSIS: cmp [-b blockSize] [-c count] [-e] [-x] file1 file2
• DESCRIPTION: cmp compares the contents of the 2 named files. If file1 is "-" then standard input is used for that file. If the files are the same length and contain the same val­ ues then nothing is written to standard output and the exit status NIL (i.e. true) is set. Where the 2 files dif­ fer, the first bytes that differ and the position are out­ put to standard out and the exit status is set to "differ" (i.e. false). The position is given by a block number (origin 0) followed by a byte offset within that block (origin 0). The optional "-b" switch allows the blockSize of each read operation to be set. The default blockSize is 512 (bytes). For big compares involving disks a relatively large blockSize may be useful (e.g. 64k). See suffix for allowable suffixes. The optional "-c" switch allows the count of blocks read to fixed. A value of 0 for count is interpreted as read to the end of file (EOF). To compare the first 64 Megabytes of 2 files the switches "-b 64k -c 1k" could be used. See suffix for allowable suffixes. The optional "-e" switch instructs ccmmpp to output to stan­ dard out (usually overwriting the same line) the count of blocks compared, each time a multiple of 100 is reached. The final block count is also output. The optional "-x" switch instructs ccmmpp to continue after a comparison error (but not a file error) and keep a count of blocks in error. If any errors are detected only the last one will be output when the command exits. If the "-e" switch is also given then the current count of blocks in error is output to the right of the multiple of 100 blocks compared. This command is designed to compare very large files. Two buffers of blockSize are allocated dynamically so their size is bounded by the amount of memory (i.e. RAM in the target) available at the time of command execution. The count could be up to 2G. The number of bytes compared is the product of blockSize and count (i.e. big enough).
• SEE ALSO: suffix

3.9.11  CONS - console device for Husky

• SYNOPSIS: bind -k cons bind_point
• DESCRIPTION: cons allows an interpreter (e.g. Husky) to route console input and output to an appropriate device. That console input and output is available at bind_point in the K9 namespace. The special file cons should always be available.
• EXAMPLES: Husky does the following in its initialization:
  
  bind -k cons /dev/cons
  
  On a Unix system this is equivalent to:
  
  bind -k unixfd /dev/cons
  
  On a DOS system this is equivalent to:
  
  bind -k doscon /dev/cons
  
  On target hardware using a SCN2681 chip this is equivalent to:
  
  bind -k scn2681 /dev/cons
  
  
• SEE ALSO: unixfd, doscon, scn2681

3.9.12  DD - copy a file (disk, etc)

• SYNOPSIS: dd [if=file] [of=file] [ibs=bytes] [obs=bytes] [bs=bytes] [skip=blocks] [seek=blocks] [count=blocks] [flags=verbose]
• DESCRIPTION: dd copies a file (from the standard input to the standard output, by default) with a user-selectable blocksize.
• OPTIONS
  • if=file Read from file instead of the standard input.
  • of=file, Write to file instead of the standard output.
  • ibs=bytes, Read given number of bytes at a time.
  • obs=bytes, Write given number of bytes at a time.
  • bs=bytes, Read and write given number of bytes at a time. Override ibs and obs.
  • skip=blocks, Skip ibs-sized blocks at start of input.
  • seek=blocks, By-pass obs-sized blocks at start of output.
  • count=blocks, Copy only ibs-sized input blocks.
  • flags=verbose, Print (to standard output) the number of blocks copied every ten percent of the copy. The output is of the form X/T where X is the number of blocks copied so far and T is the total number of blocks to copy. This option can only be used if both the count= and of= options are also given.
  The decimal numbers given to "ibs", "obs", "bs", "skip", "seek" and "count" must not be negative. These numbers can optionally have a suffix (see suffix). dd outputs to standard out in all cases. A successful copy of 8 (full) blocks would cause the following output:

  8+0 records in
  
  8+0 records out

  The number after the "+" is the number of fractional blocks (i.e. blocks that are less than the block size) involved. This number will usually be zero (and is otherwise when physical media with alignment requirements is involved).
  
  A write failure outputting the last block on the previous example would cause the following output:

  Write failed
  
  8+0 records in
  
  7+0 records out

• SEE ALSO: suffix

3.9.13  DEVSCMP - Compare a file's size against a given value

• SYNOPSIS: devscmp filename size
• DESCRIPTION: devscmp will find the size of the given file and compare it's size in 512-byte blocks to the given size (to be in 512-byte blocks). If the size of the file is less than the given value, then -1 is printed, if equal to then 0 is printed, and if the size of the given file is greater than the given size then 1 is printed. This routine is used in internal scripts to ensure that backends of raid sets are of an appropriate size.

3.9.14  DFORMAT- Perform formatting functions on a backend disk drive

• SYNOPSIS
  • dformat -p c.s.l -R bnum
  • dformat -p c.s.l -pdA|-pdP|-pdG
  • dformat -p c.s.l -S [-v] [-B firstbn]
  • dformat -p c.s.l -F
  • dformat -p c.s.l -D file
• DESCRIPTION: In it's first form dformat will either reassign a block on a nominated disk drive. via the SCSI-2 REASSIGN BLOCKS command. The second form will allow you to print out the current manufacturers defect list (-pdP), the grown defect list (-pdG) or both defect lists (-pdA). Each printed list is sorted with one defect per line in Physical Sector Format - Cylinder Number, Head Number and Defect Sector Number. The third form causes the drive to be scanned in a destructive write/read/compare manner. If a read or write or data comparison error occurs then an attempt is made to identify the bad sector(s). Typically the drive is scanned from block 0 to the last block on the drive. You can optionally give an alternative starting block number. The fourth form causes a low level format on the specified device. The fifth option allows you to download a device's microcode into the device.
• OPTIONS:
  • -R bnum: Specify a logical block number to reassign to the drive's grown defect list.
  • -pdA: Print both the manufacturer's and grown defect list.
  • \ -pdP: Print the manufacturer's defect list.
  • -pdG: Print the grown defect list.
  • -S: Perform a destructive scan of the disk reporting I/O errors.
  • -B firstbn: Specify the first logical block number to start a scan from.
  • -v: Turn on verbose mode - which prints the current block number being scanned.
  • -F: Issue a low-level SCSI format command to the given device. This will take some time.
  • -D file: Download into the specified device, the given file. The download is effected by a single SCSI Write-Buffer command in save microcode mode. This allows users to update a device's microcode. Use this command carefully as you could destroy the device by loading an incorrect file.
  • -p c.s.l: Identify the disk device by specifying it's channel, SCSI ID (rank) and SCSI LUN provided in the format "c.s.l"
• SEE ALSO: Product manual for disk drives used in your RAID.

3.9.15  DIAGS - script to run a diagnostic on a given device

• SYNOPSIS: diags disk -C count -L length -M io-mode -T io-type -D device
• DESCRIPTION: diags is a husky script which is used to run the randio diagnostic on a given device. When randio is executed, it is executed in verbose mode.
• OPTIONS:
  • disk: This is the device type of diagnostic we are to run.
  • -C count: Specify the number of times to execute the diagnostic.
  • -L length: Specify the "length" of the diagnostic to execute. This can be either short, medium or long and specified with the letter's s, m or l respectively. In the case of a disk, a short test will the first 10% of the device, a medium the first 50% and long the whole (100%) of the disk.
  • -M io-mode: Specify a destructive (read-write) or non-destructive (read-only) test. Use either read-write or read-only.
  • -T io-type: Specify a type of io - either sequential or random.
  • -D device: Specify the device to test.
• SEE ALSO: randio, scsihdfs

3.9.16  DPART - edit a scsihd disk partition table

• SYNOPSIS:
  • dpart -a|d|l|m -D file [-N name] [-F firstblock] [-L lastblock]
  • dpart -a -D file -N name -F firstblock -L lastblock
  • dpart -d -D file -N name
  • dpart -l -D file
  • dpart -m -D file -N name -F firstblock -L lastblock
• DESCRIPTION: Each scsihd device (typically a SCSI disk drive) can be divided up into eight logical partitions. By default when a scsihd device is bound into the RaidRunner's file system, it has four partitions, the whole device (raw), typically named bindpoint/raw, the partition file (bindpoint/partition), the RaidRunner backup configuration file (bindpoint/rconfig), and the "data" portion of the disk (bind- point/data) which represents the whole device less the backup configuration area and partition file. For more information, see scsihdfs. If other partitions are added, then they will appear as bindpoint/partitionname. dpart allows you to edit or list the partition table on a scsihd device (typically a disk).
• OPTIONS:
  • -a: Add a partition. When adding a partition, you need to specify the partition name (-N) and the partition range from the first block (-F) to the last block (-L).
  • -d: Delete a named (-N) partition.
  • -l: List all partitions.
  • -m: Modify an existing partition. You will need to specify the partition name (-N) and BOTH it's first (-F) and last (-L) blocknumbers even if you are just modifying the last block number.
  • -D file: Specify the partition file to be edited. Typically, this is the bindpoint/partition file.
  • -N name: Specify the partition name.
  • -F firstblock: Specify the first block number of the partition.
  • -L lastblock: Specify the last block number of the partition.
• SEE ALSO: scsihd

3.9.17  DUP - open file descriptor device

• SYNOPSIS: bind -k dup bind_point
• DESCRIPTION: The dup device makes a one level directory with an entry in that directory for every open file descriptor of the invoking K9 process. These directory "entries" are the numbers. Thus a typical process (script) binding a dup device would at least make these files in the namespace: "bind_point/0", "bind_point/1" and "bind_point/2". These would correspond to its open standard in, standard out and standard error file descriptors. A dup device allows other K9 processes to access the open file descriptors of the invoking process. To do this the other processes simply "open" the required dup device directory entry whose name (a number) corresponds to the required file descriptor.

3.9.18  ECHO - display a line of text

• SYNOPSIS: echo [string ...]
• DESCRIPTION: echo writes each given string to the standard output, with a space between them and a newline after the last one. Note that all the string arguments are written in a single write kernel call. The following backslash-escaped characters in the strings are converted as follows:
  
  \b backspace
  
  \c suppress trailing newline
  
  \f form feed
  
  \n new line
  
  \r carriage return
  
  \t horizontal tab
  
  \v vertical tab
  
  \\ backslash
  
  \nnn the character whose ASCII code is nnn (octal)
  
  
• SEE ALSO: cat

3.9.19  ENV- environment variables file system

• SYNOPSIS: bind -k env bind_point
• DESCRIPTION: env file system associates a one level directory with the bind_point in the K9 namespace. Each file name in that directory is the name of the environment variable while the contents of the file is that variable's current value. Conceptually each process sees their own copy of the env file system. This copy is either empty or inherited from this process's parent at spawn time (depending on the flags to spawn).

3.9.20  ENVIRON - RaidRunner Global environment variables - names and effects

• DESCRIPTION: The RaidRunner uses GLOBAL environment variables to control the functionality of automatic actions. GLOBAL environment variables are saved in the Raid configuration area so they retain their values between reboots/power downs. Certain RaidRunner internal run-time variables can also be set as a GLOBAL environment variables. See the internals manual entry for details. The table below describes those GLOBAL environment variables that are used by the RaidRunner in it's normal operation.
  • RebuildPri
    
    This variable, if set, controls the priority used when drive reconstruction occurs via the rebuild program. If the variable is not set then the default rebuild priority would be used. The variable is to be a comma separated list of raid set names and their associated rebuild priorities and sleep periods (colon separated). The form is
    
    Rname_1:Pri_1:Sleep_1,Rname_2:Pri_2:Sleep_2,...,Rname_N:Pri_N:Sleep_N
    
    where Pri_1 is to be the priority the rebuild program runs with when run on raid set Rname_1, Sleep_1 is the period, in milliseconds, to sleep between each rebuild action on the raid set, Pri_2 is to be the priority for raid set Rname_2, and so forth. For example, if the value of RebuildPri is
    
    R:5:30000
    
    then if a rebuild occurs (via replace, repair or autorepair) on raid set R then the rebuild will run with priority 5 (via the -p rebuild option) and will sleep 30000 milliseconds (30 seconds) between each rebuild action (specified via the -S rebuild option). The priority given must be valid for the rebuild program.
    
    
  • BackendRanks
    
    On certain RaidRunner's where multiple controllers may exist, you can restrict a controller's access to the backend ranks of devices available. For example, you may have 2 controllers and 4 ranks of backend devices. You can specify that the first controller can only access the first two ranks and the second controller, the second two ranks. This variable along with other associated commands allows you to set up this restriction. Additionally, you may only have a single controller RaidRunner which is in an enclosure with multiple ranks. By default the controller will attempt to probe for all devices on all ranks. If you have only populated the RaidRunner with say, half it's possible compliment of backend devices, then the RaidRunner will still probe for the other half. Setting this variable appropriately will prevent this un-needed (and on occasion time consuming) process. This variable takes the form
    
    controller_id:ranklist controller_id:ranklist ...
    
    where controller_id is the controller number (from 0 upwards) and ranklist is a comma list of backend ranks which the given controller will access. Note that the backend rank is the scsi-id of that rank. For example, on a 2 rank (rank 1 and 2 - i.e scsi id 1 for the first rank and scsi id 2 for the second), 1 controller
    
    This variable takes the form
    
    For example, on a 2 rank (rank 1 and 2 - i.e scsi id 1 for the first rank and scsi id 2 for the second), 1 controller RaidRunner where only the first rank has devices you could prevent the controller from attempting to access the (empty) second rank by setting BackendRanks to
    
    0:1
    
    Typically, you would not set this variable directly, but use supporting commands to set it. These commands are pranks and sranks. See these manual entries for details.
  
  
• RAIDn_reference_PBUFS
  
  Raid types 3, 4 and 5 all make use of memory for temporary parity buffers when they need to create parity data. This memory is in addition to that allocated to a raid set's cache. When a raid set is created, it will also create a default number of parity buffers (which are the same size is a raid set's iosize). Sometimes, if the iosize of the raid set is large there will not be enough memory to create this default number of parity buffers. To overcome this situation, you can set GLOBAL environment variables to over-ride the default number of parity buffers that all raid sets of a particular type or a specific raid set will use. You need to set these variables before you define the raid set via agui and if you delete them and not the raid set, then the effect raid sets may not boot and hence will not be accessible by a host. The variables are of the form RAIDn_reference_PBUFS where n is the raid type (3, 4 or 5), and reference is the raid set's name or the string 'Default' You use the reference of 'Default' to specify all raid sets of a particular type. For example, to over-ride the number of parity buffers for a raid 5 named

  : raid ; setenv RAID5_FRED_PBUFS 64

  To over-ride the number of parity buffers for ALL raid 3's (and set only 72 parity buffers) set

  : raid ; setenv RAID3_Default_PBUFS 128

  If you set a default for all raid sets of a particular type, but want ONE of them to be different then set up a variable for that particular raid set as it's value will over-ride the default. In the above example, where all Raid Type 3 will have 128 parity buffers, you could set the variable

  : raid ; setenv RAID3_Dbase_PBUFS 56 

  which will allow the raid 3 raid set named 'Dbase' to have 56 parity buffers, but all other raid 3's defined on the RaidRunner will have 128.
  
  
• SEE ALSO: setenv, printenv, rconf, rebuild, internals

3.9.21  EXEC - cause arguments to be executed in place of this shell

• SYNOPSIS: exec [ arg ... ]
• DESCRIPTION: exec causes the command specified by the first arg to be executed in place of this shell without creating a new process. Subsequent args are passed to the command specified by the first arg as its arguments. Shell redirection may appear and, if no other arguments are given, causes the shell input/output to be modified.

3.9.22  EXIT - exit a K9 process

• SYNOPSIS: exit [string]
• DESCRIPTION: exit has an optional string argument. If the optional argument is given the current K9 process is terminated with the given string as its exit value. (If the string has embedded spaces then the whole string should be a quoted_string). If no argument is given then the shell gets the string associated with the environment variable "status" and returns that string as the exit value. If the environment variable "status" is not found then the "true" exit status (i.e. NIL) is returned.
• SEE ALSO: true, K9exit

3.9.23  EXPR - evaluation of numeric expressions

• SYNOPSIS: expr numeric_expr ...
• DESCRIPTION: expr evaluates each numeric_expr command line argument as a separate numeric expression. Thus a single expression cannot contain unescaped whitespaces or needs to be placed in a quoted string (i.e. between "{" and "}"). Arithmetic is performed on signed integers (currently numbers in the range from -2,147,483,648 to 2,147,483,647). Successful calculations cause no output (to either standard out/error or environment variables). So each useful numeric_expr needs to include an assignment (or op-assignment). Each numeric_expr argument supplied is evaluated in the order given (i.e. left to right) until they all evaluate successfully (returning a true status). If evaluating a numeric_expr fails (usually due to a syntax error) then the expr command fails with "error" as the exit status and the error message is written to the environment variable "error".
• OPERATORS: The precedence of each operator is shown following the description in square brackets. "0" is the highest precedence. Within a single precedence group evaluation is left-to-right except for assignment operators which are right-to-left. Parentheses have higher precedence than all operators and can be used to change the default precedence shown below.
  
  UNARY OPERATORS
  
  +
  
  Does nothing to expression/number to the right.
  
  -
  
  negates expression/number to the right.
  
  !
  
  logically negate expression/number to the right.
  
  ~
  
  Bitwise negate expression/number to the right.
  
  BINARY ARITHMETIC OPERATORS
  
  *
  
  Multiply enclosing expressions [2]
  
  /
  
  Integer division of enclosing expressions
  
  %
  
  Modulus of enclosing expressions.
  
  +
  
  Add enclosing expressions
  
  -
  
  Subtract enclosing expressions.
  
  <<
  
  Shift left expression _left_ by number in right expression. Equivalent to: left * (2 ** right)
  
  >>
  
  Shift left expression _right_ by number in right expression. Equivalent to: left / (2 ** right)
  
  &
  
  Bitwise AND of enclosing expressions
  
  ^
  
  Bitwise exclusive OR of enclosing expressions. [8]
  
  |
  
  Bitwise OR of enclosing expressions. [9]
  
  BINARY LOGICAL OPERATORS
  
  These logical operators yield the number 1 for a true comparison and 0 for a false comparison. For logical ANDs and ORs their left and right expressions are assumed to be false if 0 otherwise true. Both logical ANDs and ORs evaluate both their left and right expressions in all case (cf. C's short-circuit action).
  
  <=
  
  true when left less than or equal to right. [5]
  
  >=
  
  true when left greater than or equal to right. [5]
  
  <
  
  true when left less than right. [5]
  
  >
  
  true when left greater than right. [5]
  
  ==
  
  true when left equal to right. [6]
  
  !=
  
  true when left not equal to right. [6]
  
  &&
  
  logical AND of enclosing expressions [10]
  
  ||
  
  logical OR of enclosing expressions [11]
  
  ASSIGNMENT OPERATORS
  
  In the following descriptions "n" is an environment variable while "r_exp" is an expression to the right. All assignment operators have the same precedence which is lower than all other operators. N.B. Multiple assignment operators group right-to-left (i.e. same as C language).
  
  =
  
  Assign right expression into environment variable on left.
  
  *=
  
  n *= r_exp is equivalent to: n = n * r_exp
  
  /=
  
  n /= r_exp is equivalent to: n = n / r_exp
  
  %=
  
  n %= r_exp is equivalent to: n = n % r_exp
  
  +=
  
  n += r_exp is equivalent to: n = n + r_exp
  
  -=
  
  n -= r_exp is equivalent to: n = n - r_exp
  
  <<=
  
  n <<= r_exp is equivalent to: n = n << r_exp
  
  >>=
  
  n >>= r_exp is equivalent to: n = n >> r_exp
  
  &=
  
  n &= r_exp is equivalent to: n = n & r_exp
  
  |=
  
  n |= r_exp is equivalent to: n = n | r_exp
  
  
• NUMBERS: All number are signed integers in the range stated in the description above. Numbers can be input in base 2 through to base 36. Base 10 is the default base. The default base can be overridden by:
  1. a leading "0" : implies octal or hexadecimal
  2. a number of the form _base_#_num_
  Numbers prefixed with "0" are interpreted as octal. Numbers prefixed with "0x" or "0X" are interpreted as hexadecimal. For numbers using the "#" notation the _base_ must be in the range 2 through to 36 inclusive. For bases greater then 10 the letters "a" through "z" are utilised for the extra "digits". Upper and lower case letters are acceptable. Any single digit that exceeds (or is equal to) the base is consider an error. Base 10 numbers only may have a suffix. See suffix for a list of valid suffixes. Also note that since expr uses signed integers then "1G" is the largest magnitude number that can be represented with the "Gigabyte" suffix (assuming 32 bit signed integers, -2G is invalid due to the order of evaluation).
  
  
• VARIABLES: The only symbolic variables allowed are K9 environment variables. Regardless of whether they are being read or written they should never appear preceded by a "$". Environment variables that didn't previous exist that appear as left argument of an assignment are created. When a non-existent environment variable is read then it is interpreted as the value 0.
• EXAMPLES: Some simple examples:

  expr {n = 1 + 2} # create n
  
  echo $n

  3

  expr {n*=2} # 3 * 2 result back into n
  
  echo $n

  6

  expr { k = n > 5 } # 6 > 5 is true so create k = 1
  
  echo $k

  1

• NOTE: expr is a Husky "built-in" command. See the "Note" section in "set" to see the implications.
• SEE ALSO: husky, set, suffix, test

3.9.24  FALSE - returns the K9 false status

• SYNOPSIS: false
• DESCRIPTION: false does nothing other than return a K9 false status. K9 processes return a pointer to a C string (null terminated array of characters) on termination. If that pointer is NULL then a true exit value is assumed while all other returned pointer values are interpreted as false (with the string being some explanation of what went wrong). This command returns a pointer to the string "false" as its return value.
• EXAMPLE: The following script fragment will print "got here" to standard out:
  
  if false then
  
  echo impossible
  
  else
  
  echo got here
  
  end
  
  
• SEE ALSO: true

3.9.25  FIFO - bi-directional fifo buffer of fixed size

• SYNOPSIS:
  • bind -k {fifo size} bind_point
  • cat bind_point
  • bind_point/data
  • bind_point/ctl
• DESCRIPTION: fifo file system associates a one level directory with the bind_point in the K9 namespace with a buffer size of size bytes. bind_point/data and bind_point/ctl are the data and control channels for the fifo. Data written to the bind_point/data file is available for reading from the same file in a first-in first-out basis. A write of x bytes to the bind_point/data file will either complete and and transfer all the data, or will transfer sufficient bytes until the fifo buffer is full then block until data is removed from the fifo buffer by reading. A read of x bytes from the bind_point/data file will transfer the lessor of the current amount of data in the fifo buffer or x bytes. A read from the bind_point/ctl will return the size of the fifo buffer and the current usage. The number of opens (# Opens) is the number of processes that currently have the bind_point/data file open.
• EXAMPLE

  > /buffer
  
  bind -k {fifo 2048} /buffer
  
  ls -l /buffer
  
  /buffer:
  
  /buffer/ctl                     fifo    2 0x00000001    1 0
  
  /buffer/data                    fifo    2 0x00000002    1 0
  
  cat /buffer/ctl
  
  Max: 2048 Cur: 0, # Opens: 0
  
  echo hello > /buffer/data
  
  cat /buffer/ctl
  
  Max: 2048 Cur: 6, # Opens: 0
  
  dd if=/buffer/data bs=512 count=1
  
  hello
  
  0+1 records in
  
  0+1 records out
  
  cat /buffer/ctl
  
  Max: 2048 Cur: 0, # Opens: 0

• SEE ALSO: pipe

3.9.26  GET - select one value from list

• SYNOPSIS: get number [ value ... ]
• DESCRIPTION: get uses the given number to select one value from the given list. Indexing is origin 0 (e.g. "get 0 aaa bb c" returns "aaa"). If the number is out of range for an index on the given list of values then nothing is returned.

3.9.27  GETIV - get the value an internal RaidRunner variable

• SYNOPSIS:
  • getiv
  • getiv name
• DESCRIPTION: getiv prints the current value of an internal RaidRunner variable or prints a list of all variables. When a variable name is given it's current value is printed. If no value is given the all available internal variables are listed.
• NOTES: As different models of RaidRunners have different internal variables see your RaidRunner's Hardware Reference manual for a list of variables together with the meaning of their values. These variables are run-time variables and hence revert to their default value whenever the RaidRunner is booted.
• SEE ALSO: setiv

3.9.28  HELP - print a list of commands and their synopses

• SYNOPSIS: help or ?
• DESCRIPTION: help or the question mark character - ?, will print a list of all commands available to the command interpreter. Along with each command, it's synopsis is printed.

3.9.29  HUSKY - shell for K9 kernel

• SYNOPSIS
  • husky [-c command] [ file [ arg ... ] ]
  • hs [-c command] [ file [ arg ... ] ]
• DESCRIPTION: husky and hs are synonyms. husky is a command language interpreter that executes commands read from the standard input or from a file. husky is a scaled down model of Unix's Bourne shell (sh). One major difference is that husky has no concept of current working directory. If the "-c" switch is present then the following command is interpreted by husky in a newly thrown shell nested in the current environment. This newly thrown shell exits back to the current environment when the command finishes. Otherwise if arguments are given the first one is assumed to be a file containing husky commands. Again a new shell is thrown to execute these commands. husky script files can access their command line arguments and the 2nd and subsequent arguments to husky (if present) are passed to the file for that purpose. If no arguments are given to husky then commands are read from standard in (and the shell is considered interactive).
• RETURN STATUS: husky places the K9 return status of a process (NIL if ok, otherwise a string explaining the error) in the file "/env/status"
  
  An example:

  dd if=/xx
  
  dd: could not open /xx
  
  cat /env/status
  
  open failed
  
  cat /env/status

  # empty because previous "cat" worked
  
  As the file "/env/status" is an environment variable the return status of a command is also available in the variable $status. The exit status of a pipeline is the exit status of the last command in the pipeline.
  
  
• SIGNALS If an interactive shell receives an interrupt signal (i.e. K9_SIGINT - usually a control-C on the console) then the shell exits. The "init" process will then start a new instance of the husky shell with all the previously running processes (with the exception of the just killed shell) still running. This allows the user to kill the process that caused the previous shell problems. Alternatively a process that is acci­ dentally run in foreground is effectively put in the background by sending an interrupt signal to the shell. Note that this is quite different to Unix shells which would forward the signal onto the foreground process.
• QUOTES, ESCAPING, STRING CONCATENATION, ETC: A quoted_string (as defined in the grammar) commences with a "{" and finishes with the matching "}". The term "matching" implies that all embedded "{" must have a corresponding embedded "}" before the final "}" is said to match the original "{". A quoted_string can be spread across several lines. No command line substitution occurs within quoted_strings. The character for escaping the following character is "\". If a "{" needs to be interpreted literally then it can be represented by "\{". If a string containing spaces (whitespaces) needs to be interpreted as a single token then space (whitespace) can be escaped (i.e. "\ "). If a "\" itself needs to be interpreted literally then it can be represented by "\\". The string concatenation character is "^". This is useful when a token such as "/d4" needs to built up by a script when "/d" is fixed and the "4" is derived from some variable:
  
  set n 4
  
  > /d^$n
  
  This example would create the file "/d4".
  
  The output of another husky command or script can be made available inline by starting the sequence with "`" and finishing it with a "'". For example:
  
  echo {ps output follows:
  
  } `ps'
  
  This prints the string "ps output follows:" followed on the next line by the current output from the command "ps". That output from "ps" would have its embedded newlines replaced by whitespaces.
  
  
• COMMAND LINE FILE REDIRECTION:
  • Redirection should appear after a command and its arguments in a line to be interpreted by husky. A special case is a line that just contains "> filename" which creates the filename with zero length if it didn't previously exist or truncates to zero length if it did.
  • Redirection of standard in to come from a file uses the token "<" with the filename appearing to its right. The default source of standard in is the console.
  • Redirection of standard out to go to a file uses the token ">" with the filename appearing to its right. The default destination of standard out is the console.
  • Redirection of standard error to go to a file uses the token ">[2]" with the filename appearing to its right. The default destination of standard error is the console.
  • Redirection of writes from within a command which uses a known file descriptor number (say "n") to go to a file uses the token ">[n]" with the filename appearing to its right.
  • Redirection of read from within a command which uses a known file descriptor number (say "n") to come from a file uses the token "<[n]" with the filename appearing to its right.
  • Redirection of reads and writes from within a command which uses a known file descriptor number (say "n") to a file uses the token "<>[n]" with the filename appearing to its right. In order to redirect both standard out and standard error to the one file the form " > filename >[2=1]" can be used. This sequence first redirects standard out (i.e. file descriptor 1) to filename and then redirects what is written to file descriptor 2 (i.e. standard error) to file descriptor 1 which is now associated with filename.
• ENVIRONMENT VARIABLES: Each process can access the name it was invoked by via the variable: "arg0" . The command line arguments (excluding the invocation name) can be accessed as a list in the variable: "argv" . The number of elements in the list "argv" is place in "argc". The get command is useful for fetching individual arguments from this list. The pid of the current process can be fetched from the variable: "pid". When a script launches a new process in the background then the child's pid can be accessed from the variable "child". The variable "ContollerId" is set to the RaidRunner controller number husky is running on. Environment variables are a separate "space" for each process. Depending on the way a process was created, its initial set of environment variables may be copied from its parent process at the "spawn" point.
• SEE ALSO: intro

3.9.30  HWCONF - print various hardware configuration details

• SYNOPSIS: hwconf [-D] [-M] [-I] [-d [-n]] [-f] [-h] [-i -p c.s.l] [-m] [-p c.s.l] [-s] [-S] [-t] [-T] [-P] [-W]
• DESCRIPTION: hwconf prints details about the RaidRunner hardware and devices attached.
• OPTIONS:
  • -h: Print the number of controllers, host interfaces per controller, the number of disk channels per controller, number of ranks of disks and the details memory (in bytes) on each controller. Four memory figures are printed, the first is the total memory in the controller, next is the amount of memory at boot time, next is the amount currently available and lastly is the largest available contiguous area of memory. This is the default option.
  • -f: Print the number of fans in the RaidRunner and then the speed for each fan in the system. The speeds values are in revolutions per minute (rpms). The fans in the system are labeled in your hardware specification sheet for your RaidRunner. The first speed printed from this command corresponds to fan number 0 on your specification sheet, the second is for fan 1, and so forth.
  • -d: Print out information on all the disk drives on the RaidRunner. For each disk on the RaidRunner, print out - the device name, in the format c.s.l where c is the channel, s is the SCSI ID (or rank) and l is the SCSI LUN of the device, the manufacturer's name (vendor id), the disk's model name (product id), the disk's version id, the disk serial number, the disk geometry - number of cylinders, heads and sectors, and the last block number on the disk and the block size in bytes. the disk revolution count per minute (rpm's), the number of notches/zones available on the drive (if any)
  • -n: Print out the disk drive notch/zone tables if available. This is a sub-option to the -d option. Not all disks appear to correctly report the notch/zone partition tables. For each notch/zone,
  • the following is printed: the zone number, the zone's starting cylinder, the zone's starting head, the zone's ending cylinder, the zone's ending head, the zone's starting logical block number, the zone's ending logical block number, the zone's number of sectors per track
  • -D: Print out the device names for all disk drives on the system.
  • -I: Initialize back-end NCR SCSI chips. This flag may be used in conjunction with any other option and will done first. It has an effect only the first call to hwconf that has not yet used a -d, -D or -I options, or on those chips that have not yet had a -p on the channel associated with that chip.
  • -m: Print out major flash and battery backed-up ram addresses (in hex). Additionally print out the size of the RaidRunner configuration area. Eight (8) addresses are printed in order RaidRunner configuration area start and end addresses (FLASH RAM), RaidRunner Husky Scripts area start and end addresses (FLASH RAM), RaidRunner Binary Image area start and end addresses (FLASH RAM), RaidRunner Battery Backed-up area start and end addresses. And the size of the RaidRunner configuration area (in bytes) is then printed.
  • -p c.s.l: Probe a single device specified by the given channel, SCSI ID (rank) and SCSI LUN provided in the format "c.s.l". The output of this command is the same as the "-d" option but just for the given device. If the device is not present then nothing will be output and the exit status of the command will be 1.
  • -i -p c.s.l: Re-initialize the SCSI device driver specified by the given channel, SCSI ID (rank) and SCSI LUN provided in the format "c.s.l". Typically this command is used when, on a running RaidRunner, a new drive is plugged in, and it will be used prior to the RaidRunner's next reboot.
  • -M: Set the boottime memory. This option is executed internally by the controller at boot time and has no function (or effect) executed at any other time.
  • -s: Print the 12 character serial number of the RaidRunner.
  • -S: Issue SCSI spin up commands to all backends as quickly as possible. This option is intended for use at power-on stage only.
  • -t: Probe the temperature monitor returning the internal temperature of the RaidRunner in degrees Celsius.
  • -T: Print the temperatures being recorded by the hardware monitoring daemon (hwmon).
  • -P: For both AC and DC power supplies, print the number of each present and the state of each supply. The state will be printed as ok or flt depending on whether the PSU is working or faulty.
  • -W: This option will wait until all possible backends have spun up. It is used in conjunction with
• NOTES : The order of printing the disk information is by SCSI ID (rank), by channel, by SCSI LUN.

3.9.31  HWMON - monitoring daemon for temperature, fans, PSUs.

• SYNOPSIS: hwmon [-t seconds] [-d]
• DESCRIPTION: hwmon is a hardware monitoring daemon. It periodically probes the status of certain elements of a RaidRunner and if an out-of-band occurrence happens, will cause the alarm to sound or light up fault leds as well as saving a message in the system log. Depending on the model of RaidRunner, the elements monitored are temperature, fans and power supplies. When an out-of-band occurrence is found, hwmon will reduce the time between probes to 5 seconds. If a buzzer is the alarm device, then the buzzer will turn on for 5 seconds then off for 5 seconds and repeat this cycle until the buzzer is muted or the occurrence is corrected.
  
  If the RaidRunner model supports a buzzer muting switch, then the buzzer will be muted if the switch is pressed during a cycle change as per the previous paragraph. When hwmon recognizes the mute switch it will beep twice.
  
  Certain out-of-band occurrences can be considered to be catastrophic, meaning if the occurrence remains uncorrected, the RaidRunner's hardware is likely to be damaged. Occurrences such as total fan failure and sustained high temperature along with total or partial fan failure are considered as catastrophic. hwmon has a means of automatically placing the RaidRunner into a "shutdown" or quiescent state where minimal power is consumed (and hence less heat is generated). This is done by the execution of the shutdown command after a period of time where catastrophic out-of-band occurrences are sustained. This process is enabled, via the AutoShutdownSecs internal variable. See the internals manual for use of this variable. hwmon can be prevented from starting at boot time by creating the global environment variable NoHwmon and setting any value to it. A warning message will be stored in the syslog.
  
  
• OPTIONS:
  • t seconds: Specify the number of seconds to wait between probes of the hardware elements. If this option is not specified, the default period is 300 seconds.
  • -d: Turn on debugging mode which can produce debugging output.
• SEE ALSO: hwconf, pstatus, syslogd, shutdown, internals

3.9.32  INTERNALS - Internal variables used by RaidRunner to change dynamics of running kernel

• DESCRIPTION: Certain run-time features of the RaidRunner can be manipulated by changing internal variables via the setiv command. The table below describes each changeable variable, it's effect, it's default value and range of values it can be set to. The variables below are run-time features of a RaidRunner and hence are always set to their default values when a RaidRunner boots. Certain variables can be stored as a global environment variable and will over-ride the defaults at boot time. If you create a global environment variable of that variable's name with an appropriate value, it's default value will be over-ridden the next time the RaidRunner is re-booted. Note, that the values of these variables ARE NOT CHECKED when set in the global environment variable tables and, if incorrectly set, will generate errors at boot until deleted or corrected. In the table below, any variable that can have a value stored as a global environment variable is marked with (GEnv)
• write_limit: This variable is the maximum number of 512-byte blocks the cache filesystem will buffer for writes. If this limit is reached all writes to the cache filesystem will be blocked until the cache filesystem has written out (to it's backend) enough blocks to reach a low water mark - write_low_tide. This variable cannot be changed if battery backed-up RAM is available as it is tied to the amount of battery backed-up RAM available. The value of this variable is calculated when the cache is initialized. It's value is dependant on whether battery backed-up RAM is installed in the RaidRunner. If installed, the number of blocks of data that can be saved into the battery backed-up RAM is calculated. If no battery backed-up RAM is present, it's value is set to 75% of the RaidRunner's memory (expressed in a count of 512 byte blocks) then adjusted to reflect the amount of cache requested by configured raid sets. When write_limit is changed then both write_high_tide and write_low_tide are automatically changed to there default values (a function of the value of write_limit).
• write_high_tide: This variable is a high water mark for the number of written-to 512-byte blocks in the cache. When the number of data blocks exceeds this value, to avoid the cache filesystem from blocking it's front end, the cache flushing mechanism continually flushes the cache buffer until the amount of unwritten (to the backend) cache buffers is below the low water mark (write_low_tide). This value defaults to 75% of write_limit. This variable can have values ranging from write_limit down to write_low_tide. It is recommended that this variable not be changed.
• write_low_tide: This variable is a low water mark for when the cache flushing mechanism is continually flushing data to it's backend. Once the number of written-to cache blocks yet to be flushed equals or is less than this value, the sustained flushing is stopped. This value defaults to 25% of write_limit. This variable can have values ranging from write_high_tide-1 down to zero (0). It is recommended that this variable not be changed.
• cache_nflush: This variable is the number of cache buffers (not 512-byte data blocks) that the cache flushing mechanism will attempt to write out in one flush cycle. Adjusting this value may improve performance on writes depending of the size of the cache buffers and type of disk drives used in the raid set backends. The default value is 128. It's value can range from 2 to 128.
• cache_nread: This variable is the number of cache buffers (not 512-byte data blocks) that the cache reading mechanism will attempt to read out in one read cycle. Adjusting this value may improve performance on reads depending of the size of the cache buffers and type of disk drives used in the raid set backends. The default value is 128. It's value can range from 2 to 128.
• cache_wlimit: This variable is the number of cache buffers (not 512-byte data blocks) that the cache flushing m