#############################################################################
#
#     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 
#     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.
#
#############################################################################


In this document, $CIT_DIST refers to the CIToolkit source distribution
directory, usually /usr/local1/cit_dist/cit, or /var/tmp/cit.  Also,
$CHITS_HOME and $WEB_HOME refer to the web page root dir, from the operating
system and from the web browser respectively.

----------------------------------------------
HOWTO set up a CHITS server:

  1. Install required services and configure the web server:
        MySQL - must have access that allows creation of new DB's and users
        Apache - *See documentation below*
        Perl Modules - DBI, DBD-mysql

  2. Install the "base" and "site" modules as described in
     the main INSTALL document. (and any other modules you want)
        # cd $CIT_DIST
        # make base
        # make site

  3. Edit the top level Makefile (or chits/Makefile)
        Set CHITS_HOME to the dir from which the webserver will serve
        CHITS pages.  For example:
                CHITS_HOME:=/var/www/https/chits
        Set WEB_HOME to the path at which the above dir will be available
        on the web.  For example:
                WEB_HOME:=/chits

  4. Install the "chits" module:
        # make chits

  5. Test the install by browsing to:
        http://<hostname>/$WEB_HOME/
        You should see "Welcome to CHITS!" and a message that there are
        not any systems available to select.  If you do not get the welcom page,
	you may need to adjust permissions.  CHITS assumes that the web server
	will run as user 'apache' and group 'apache', but it can be changed
	in the Auth.pm file.

  6. Add authentication to CHITS (optional)
        This will restrict access to verious parts of CHITS, and allow
        for (automatic) tracking of who does what to each issue.
        *See the documentation below*

  7. Create additional CHITS instances for each system you wish to support.
        *See the documentation below*

  8. See the online help for more information on using CHITS.


----------------------------------------------
HOWTO prepare the Apache web server for CHITS:

  1. Basic modifications:
        a. Tell Apache that .cgi files are scripts to be executed in the
           CHITS_HOME directory.  Replace CHITS_HOME and CLUSTER_HOME below
           with whatever they are defined as in the CIT top-level Makefile.

                <Directory CHITS_HOME>
                    SetEnv CLUSTER_CONFIG CLUSTER_HOME/config
                    AllowOverride AuthConfig
                    Options ExecCGI
                    Order allow,deny
                    Allow from all
                </Directory>

                AddHandler cgi-script .cgi

        b. If mod_dir is part of your Apache install, you will want the
           DirectoryIndex line to contain "index.cgi".  For example:

                <IfModule mod_dir.c>
                    DirectoryIndex index.html index.htm index.shtml index.cgi
                </IfModule>

        c. CHITS assumes the standard name of ".htaccess" for AccessFileName:

                AccessFileName .htaccess

  2. Kerberos Authentication:
        Ensure that you have a kerberos module (and usually mod_ssl) installed
        and working with Apache.  There are several kerberos modules available
        and some may require different syntax in the .htaccess files.  Adjust
        these lines if necessary in all .htaccess files or in Auth.pm prior
        to running "chits_userconf --init" as described above.  The assumed
        syntax is:

                AuthType KerberosV5
                KrbAuthRealm your-realm-here

  3. Recommendations:
        If possible, use the mod_perl module with Apache.  It should make
        CHITS run a _lot_ faster.


----------------------------------------------
HOWTO add authentication to CHITS:

  1. Edit $CHITS_HOME/env_variables (eg. /var/www/https/chits/env_variables)
        Set AUTH_MODE to the authentication method you are using.
        If you are using "KERBEROS", set KERB_REALM to your auth server.
        If you are using "HTPASSWD", set HTPASSBIN to use the correct path
          to the htpasswd utility.

  2. Initialize security 
        # chits_userconf --init all

  3. Create a CHITS instance.  *See the documentation below*

  4. Once you have a CHITS instance created, set up a user with admin privs.
        # chits_userconf --system <sysname> --add <username> <last name> <first name>
        # chits_userconf --allow <username> all
        # chits_userconf --system <sysname> --list

        Some auth modes (HTPASSWD) require you to set a password:
        # chits_userconf --passwd <username> <password>

  5. Make CHITS_HOME writeable by the webserver:  If your apache process
     runs as the 'apache' or 'www' user, recursively change the ownership
     of CHITS_HOME to that user and make all directory permissions 775 under it.
     This will allow you to manage users through the web interface of CHITS.
        # chown -R <apache user>.<apache group> <CHITS_HOME>
        # chmod 775 <CHITS_HOME>
        # find <CHITS_HOME> -type d | xargs chmod 775


----------------------------------------------
HOWTO create a new CHITS instance:

  1. # chits_dbconf --create <sysname> --user <username> --pass <password>
        Where:
        <sysname> is the name of the system you are creating the instance for.
        <username> is a user on the MySQL database that has admin privliges.
        <password> is the password for the above user.  Leave it blank and you
          will be prompted (several times) for the password.

  2. Make the CIT configuration database for this system available.
        Usually this consists of copying the cluster.db file to
        $CIT_HOME/config/<sysname>.db.  However, if the original admin
        node and the web server are different architectures, the binary
        database file will be incompatible, so recreate the database.
        LDAP is also a viable option.

        If "lookup equipment --db <some connection string>" works then
        you should be all set to continue.

  3. Edit $CHITS_HOME/env_variables (eg. /var/www/https/chits/env_variables)
        Modify the "CONNECT_<sysname>" line according to the above step.

  4. Test the install by browsing to:
        http://<hostname>/$WEB_HOME/
        Select the system from the dropdown list and click "continue"
        Click "Admin" then "List Device Types".
        If you see a list of devices, then you are interfacing with the
          CIT device hierarchy correctly.
        Click "Up" then "Device Browser".
        If the dropdown list shows all the collections in the config db
          and if typing a device name and clicking lookup shows the object
          data for that device, then you are interfacing with the CIT
          configuration database correctly.

  5. Use the "Manage Users" admin utility to add any additional required users

  6. Use the "Manage Hardware Types" admin utility to make sure that all
     of your system hardware is listed.  If necessary, add additional
     hardware components as well.  (Plan out any additions carefully, the more
     consistent and complete you are, the easier it will be to track issues
     and generate reports later!)


----------------------------------------------
Important Notes:

- CHITS will work with any Java Script capable web browser, although it is recommended that you use a fairly recent one, as old versions such as Netscape 4.x have a few bugs.