#############################################################################
#
#     This Cplant(TM) source code is the property of Sandia National
#     Laboratories.
#
#     This Cplant(TM) source code is copyrighted by Sandia National
#     Laboratories.
#
#     The redistribution of this Cplant(TM) source code is subject to the
#     terms of the GNU Lesser General Public License
#     (see cit/LGPL or http://www.gnu.org/licenses/lgpl.html)
#
#     Cplant(TM) Copyright 1998, 1999, 2000, 2001, 2002, 2003, 2004, 2005, 2006 
#     Sandia Corporation. 
#     Under the terms of Contract DE-AC04-94AL85000, there is a non-exclusive
#     license for use of this work by or on behalf of the US Government.
#     Export of this program may require a license from the United States
#     Government.
#
#############################################################################


DDN 
-----------------------------------
This documents provides an introduction to the capabilities for using
CIT to manage DDN Controllers. There are two basic sections to the
document. The first section covers the basics of getting started,
creating a database, and interacting with that database using CIT. The
second section describes some of the specifics of the ddn commands.


Getting Started: Create a Database
-----------------------------------
You have probably just received a tarball containing a set of
directories files and are wondering what to do next? 

Presuming that you have already executed configure; make; make install
from the top-level directory of your unpacked tarball. If not, consult
the README in the top-level directory of your tarball. 

Afterwards, the first thing you will need to do is set up a database
(persistent storage) that contains an accurate representation of your 
DDN hardware. This database will store information about your system, 
including things such as the type of hardware, networking interfaces, 
etc. CIT uses the information contained in this database to interact
with your actual hardware, so it's important that it reflects the
actual setup of your system.

This distribution includes an example database configuration script,
entitled configure-ddn-using-input.pl, which reads in a
comma-separated-value file and creates a working database. We also
provide the example input file, example_ddn_config_input for this
configuration script.  You can modify this input file to reflect your
actual hardware or if you are interested in setting up the database
yourself, consult the ACME-TUTORIAL and configuration script,
configure-ACME-library-style.pl.

To set up an initial database using the example script and input, simply
execute configure-ddn-using-input.pl, and the script will create your
database (cluster.db) under the config directory relative to 
your installation. 

Browsing the Database 
------------------------------------------
Once you have created your database, you can use the 'lookup' command
to retrieve the top-level group of equipment.

# lookup equipment

If you execute this command with the example database, you will see
the following output:

========= "equipment"
$VAR1 = bless( {
    'bag' => {
        'rack2' => 'rack2',
        'rack1' => 'rack1' 
            }, 
     'name' => 'equipment'
   }, 'Collection' );
$VAR1;

This display indicates that your top-level group (equipment) contains 
two racks (rack1 and rack2). To determine what is in those racks, you
can execute the 'lookup' command on one of the racks.

# lookup rack1

========= "rack1"
$VAR1 = bless( {
                'bag' => {
                    'BLK-C1-U-2' => 'BLK-C1-U-2',
                    'BLK-C1-U-1' => 'BLK-C1-U-1' 
                        },
                'name' => 'rack1'
               }, 'Collection' );
$VAR1;

This output indicates that rack1 contains two pieces of hardware,
BLK-C1-U1 and BLK-C1-U2. Up until this point, you have been looking at
collections (or logical groupings) of hardware. Now, you are looking
at the representation of hardware itself.

Another way to browse through collections of equipment is with the
collection_mgr tools (abbreviated cm). The following command displays
all the available collections in the current database:

# cm --find
collection_mgr --find
DDN
all_controllers
equipment
rack1
rack2

You can continue to drill down through the collections until you hit
the actual objects. The collection_manager tool will only work on
collections.

# cm BLK-C1-U-2
collection_mgr BLK-C1-U-2
Collection object is required.

To display the characteristics of an object, you can invoke either the
device_mgr (dm) or the lookup command. The dm will display all the
characteristics (attributes) of a particular piece of hardware.

# dm BLK-C1-U-2
    console => 192.168.0.2
    console_port => 23
    interface => 0
        address => 192.168.0.2
        boot_if => 1
        hostname => BLK-C1-U-2
        is_primary => 1
        net_mask => 255.255.255.0
        nic => 0
        isa => Device::Storage::Controller::DDN::S2A_8500
        name => BLK-C1-U-2
        priv_user => admin
        user => user
        user_password => password

You can change attributes of an object using the dm command, for
example if the IP address of a Controller should change.

# dm BLK-C1-U-1 --set -i 0 --address 192.168.0.1

The -i 0 flags signify that you are setting attributes for the first
interface. As another example, suppose you change the user's password
to a particular controller. You should then update the database to
reflect the new information.

# dm BLK-C2-U-2 --set --user_password blah

You can also add or remove objects to a collection and even create a 
new collection. For example, suppose that you want to indicate that 
a pair of controllers is offline. First, create a new collection.

# cm --new offline
collection_mgr --new offline
Adding new object named offline

Add the controllers to the new collection. 

# cm --add BLK-C2-U-1 offline
collection_mgr --add BLK-C2-U-1 offline
Adding object named BLK-C2-U-1 to collection offline
BLK-C2-U-1

# cm --add BLK-C2-U-2 offline
collection_mgr --add BLK-C2-U-2 offline
Adding object named BLK-C2-U-2 to collection offline
BLK-C2-U-2
BLK-C2-U-1

Now when you look up the offline collection, you'll see the names
of the equipment that you added. 

# cm offline
collection_mgr offline
BLK-C2-U-2
BLK-C2-U-1

You can also delete a collection for example if these controllers 
go back online. 

# cm --destroy offline
collection_mgr --destroy offline
Destroying object named offline
Deleting "offline" from database

Remember that this removes the collection from the database, not the
objects that the collection contains. The controllers themselves
still exist in the database.

DDN commands 
------------------------------------------

Now that you've had a basic introduction to some of the generic CIT
tools, this section describes some of the commands specific to DDN
controllers. These commands are a direct abstraction of the DDN 
command line without having to log into a controller to accomplish the
task. Note that since these commands require actual interaction with
the DDN, for these commands to work, your database must accurately
reflect your hardware. In other words, the example database won't work
on your system. 

The ddn commands typically consist of 'ddn' followed by a flag which
indicates the command you want to execute and the name of the object
that you want to execute the command on. The object can either be a
collection or a ddn object. For example, the VERSION command will
print out the version information for a DDN. 

# ddn --version BLK-C2-U-2
BLK-C2-U-2:VERSION:


    DataDirect Networks Silicon Storage Appliance Model 8500
    Firmware Version: 5.12

    Firmware date: Dec 22 2004, 15:54:33
    IEEE ULA Number: 00030546
    Bootrom Version: 1.08
    Platform: S2A 8500

You can leverage the collections to obtain information for both
controllers at once.

# ddn --version rack1
BLK-C1-U-1: VERSION


    DataDirect Networks Silicon Storage Appliance Model 8500
    Firmware Version: 5.12

    Firmware date: Dec 22 2004, 15:54:33
    IEEE ULA Number: 00030546
    Bootrom Version: 1.08
    Platform: S2A 8500


BLK-C1-U-2: VERSION


    DataDirect Networks Silicon Storage Appliance Model 8500
    Firmware Version: 5.12

    Firmware date: Dec 22 2004, 15:54:33
    IEEE ULA Number: 00030546
    Bootrom Version: 1.08
    Platform: S2A 8500

The check_version command will grab the information from the real
device and check it against the information that is contained in the
database.

# ddn --check_version BLK-C1-U-1
BLK-C1-U-1: bootrom DB value => "" and Device value => "1.08" differ
BLK-C1-U-1: firmware DB value => "" and Device value => "5.12" differ
BLK-C1-U-1: ula DB value => "" and Device value => "00030546" differ
BLK-C1-U-1: platform DB value => "" and Device value => "S2A 8500" differ

This output tells us that the information we have in the database does
not match the actual device, for example, if the firmware has been
upgraded since we created the database.

We can synchronize the database with the actual device information
using the --sync_version command. 

# ddn --sync_version BLK-C1-U-1
BLK-C1-U-1: bootrom DB value => "" and Device value => "1.08" differ
Syncing....
BLK-C1-U-1: firmware DB value => "" and Device value => "5.12" differ
Syncing....
BLK-C1-U-1: ula DB value => "" and Device value => "00030546" differ
Syncing....
BLK-C1-U-1: platform DB value => "" and Device value => "S2A 8500" differ
Syncing....

Now when we check the version, the command returns nothing, which
indicates that the database and the equipment match. 

# ddn --sync_version BLK-C1-U-1

The FAULTS command is a part of the ddn cli and has likewise been
abstracted.

# ddn --faults BLK-C1-U-1
FAULTS: BLK-C1-U-1

       Current System Faults
    -----------------------------

   Disk 6B is failed and replaced by spare 6S.


        --- Faults detected! ---

Notice the above command reports a fault. For a large system, instead
of reporting the faults for each device, we would rather just obtain a
list of the controllers that have faults. Therefore, when we execute the
check_faults command on a collection, which then returns a list of the
controllers with faults. 

# ddn --faults rack1 
BLK-C1-U-1

This command affirms what we noticed above, that BLK-C1-U-1 has a fault. 

Another direct abstraction is the DISK command, which reports a list
of the disks for a particular controller.

# ddn --disk BLK-C1-U-1
DISKS: BLK-C1-L-1

                                Disks Installed

               Vendor   Product ID      Mbytes  Rev   Serial Number
-------------------------------------------------------------------------------
    Disk   1A  SEAGATE  ST373307FC      70007   0006  3HZ9410N
    Disk   1B  SEAGATE  ST373307FC      70007   0006  3HZ7JHFX
    Disk   1C  SEAGATE  ST373307FC      70007   0006  3HZ6A11P
... 
    Disk   8H  SEAGATE ST373307FC       70007   0006  3HZ7MAPN
    Disk   8P  SEAGATE ST373307FC       70007   0006  3HZ7NTXV
    Disk   8S  SEAGATE ST373307FC       70007   0006  3HZ77SD2

    Found: 79 SEAGATE ST373307FC 70007 0006
    Found:  1 SEAGATE ST373207FC 70007 XR32 

            FW Enclosure Version Information 

    SES devices     Enclosure Version   Controller Version 

Information not available (available for SA2016/4016 enclosures only)
     

If we want out database to reflect the acutal disks associated with a
particular controller, we can use the populate_disks command, which
retrieves the information from a controller and adds it to the
database.

# ddn --populate_disks BLK-C1-U-1

Now when we retrieve a list of collections, we note the addition of
two new groups, BLK-C1-U-1.disks and disks, which were automatically
added when we executed the populate_disks command. 

# cm --find
collection_mgr --find
DDN
all_controllers
BLK-C1-U-1.disks
disks
equipment
rack1
rack2

The disks group contains a list of all the disks on the system, whose
name is the unique serial number of the disk. For example, if we
access this collection, we'll see a list of serial numbers. 

cm disks
collection_mgr disks
3HZ76L8F
3HZ9410N
3HZ7KX3C
3HZ7GRKB
.
. ...
.
3HZ7NNZR
3HZ7JH60
3HZ7NJ8F
3HZ7NDHZ
3HZ7MZPG

The other group, BLK-C1-U-1.disks, contains a list of the disks that
are associated with a particular controller. The name is
<controllername.disks>. Instead of just a serial number, this
representation provides an 'alias' to the real object in the format
<controller>.<tier><channel>, which is a more useful (to humans) way
of representing the disk in a controller. 

# cm BLK-C1-U-1.disks
collection_mgr BLK-C1-U-1.disks
BLK-C1-U-1.5G
BLK-C1-U-1.7S
BLK-C1-U-1.5H
BLK-C1-U-1.6F
BLK-C1-U-1.7G
BLK-C1-U-1.4H
BLK-C1-U-1.7E
BLK-C1-U-1.2H
.
.
.

If we look at one of these objects using the device manager, we note
that it is an alias to another object.

# dm BLK-C1-U-1.5G
     isa => Alias
     name => BLK-C1-U-1.5G
     target => 3HZ7K7HC

This output indicates that BLK-C1-U-1.5G "isa" or "is an" Alias to the
target 3HZ7K7HC, the actual disk object in the database.

If we then execute the same command on the actual disk object, we
obtain a list of attributes for that disk. 

# dm 3HZ7K7HC 
     isa => Device::Storage::Disk::SEAGATE::ST373307FC
     name => 3HZ7K7HC
     rev => 0006
     serial_number => 3HZ7K7HC
     size => 70007

We can obtain a list of attributes for a group of disks if we execute
the device_mgr command on a collection and specify the --all flag.

# dm --rev disks --all
3HZ6A11P
     rev => 0006

3HZ76L8F
    rev => 0006

3HZ778P3
    rev => 0006
...

This output returns the revision (rev) attribute for all of the
objects in the disk collection. Suppose you would like the information
in a more compressed format, then excute the same command with the
--flat flag.

# dm --rev disks --all --flat
3HZ6A11P --rev 0006
3HZ76L8F --rev 0006
3HZ778P3 --rev 0006
....    

This represents a summary of some of the basic ddn commands and the
different ways that CIT has of abstracting and representing data. To
obtain more information on a particular command, simply execute ddn
with the --help flag.

# ddn --help