NorthStar IP Address Tracking System
============================================================================

Welcome to the INSTALL file.  This file will hopefully guide you through
the install of the NorthStar system.

The installation process is broken down into 5 sections.  These sections are:
 
Section 1. Downloading and Unpacking the software
Section 2. Configuring the NorthStar system
Section 3. Preparing the PostgreSQL Database server
Section 4. Preparing the Apache HTTP server
Section 5. Final Installation Notes.

---------------------------------------------------------------------------
Section 1 - Downloading and Unpacking the software 
---------------------------------------------------------------------------

First you need to pick and installation directory for the NorthStar system.
The directory that NorthStar is installed into needs to be able to execute 
CGI programs and has to be contained in directory capable of doing HTTP 
authentication.

For this file were are going to use the directory "/home/www" as
the directory to install NorthStar under.

Now that you have picked an installation directory you need to obtain a
copy of the current release of NorthStar.  The current release can be
found at:
   
        http://www.brownkid.net/NorthStar/dist/

After downloading the file execute the following commands to unpack the
archive:

        cd /home/www
        gzip -dc /path/to/NorthStar-1.0.tar.gz | tar -xvf -

You should now have the NorthStar files installed and we can move to
configuring the software.

---------------------------------------------------------------------------
Section 2 - Configuring the NorthStar system
---------------------------------------------------------------------------

Now that the files for the NorthStar system are installed we need to configure
the basic variables to get the system up and running.  To do this use
your favorite editor and open the NorthStar.cgi file located in the NorthStar
installation directory you picked in Section 1.  The NorthStar.cgi file contains
instructions for configuring the different variables.


---------------------------------------------------------------------------
Section 3 - Preparing the PostgreSQL Database server 
---------------------------------------------------------------------------

We will now configure your PostgreSQL Database server with the database
structure needed to run the NorthStar system.  This section assumes you
have PostgreSQL installed and running, have a working knowledge of the 
PostgreSQL database system, and also have permission to create a new user
and database.  

Provided that you meet all the above conditions you can create the initial 
database structure by using the SQL command file named NorthStar.sql.  
This file is located in the NorthStar installation directory you picked in 
Section 1. 

To create the database users and structure execute the following command:

        /opt/postgres/bin/psql template1 < NorthStar.sql

Additionally you probably want to create entries in pg_hba.conf to reference
your host and assign a password for database access.  If a password is assigned
be sure to put the password in the NorthStar.cgi file.


---------------------------------------------------------------------------
Section 4 - Preparing the Apache HTTP server
---------------------------------------------------------------------------

OK, hopefully database setup was not too hard so let's get to the HTTP server
setup.  I assume that you are familier with Apache and have access to the server
configuration.  

Add the following section to your main Apache config file (httpd.conf):

<Directory /home/www/NorthStar>
 Options ExecCGI
 AuthName "NorthStar"
 AuthType Basic
 AuthUserFile /path/to/northstar.passwd
 require valid-user
</Directory>

Ok, now you need to create the northstar.passwd file to be used to authenticate
users to the NorthStar system.  NorthStar currently depends on HTTP 
Authentication but will soon have it's own authentication mechanism in place.
To create the password file execute the command:

	/path/to/htpasswd -c /path/to/northstar.passwd admin

Enter a password for the admin user.  To create additional users execute the
command:

        /path/to/htpasswd /path/to/northstar.passwd <username>

Finally, restart your Apache server using:

	/path/to/apachectl restart

And your done!

---------------------------------------------------------------------------
Section 5 - Final Installation Notes
---------------------------------------------------------------------------

Adding additional users to the NorthStar system:

 To add an additional user to the NorthStar system it is currently required
 to use a command-line SQL utility like psql to add the user to the users 
 table.  The following SQL would add the user "bob" to the system:

 INSERT INTO users (username, passwd, realname, perm_addnet, perm_updnet,
 perm_delnet, perm_addaddr, perm_updaddr, perm_deladdr, perm_adddev,
 perm_upddev, perm_deldev, perm_adduser, perm_upduser, perm_deluser,
 perm_addowner, perm_updowner, perm_delowner, perm_addloc, perm_updloc,
 perm_delloc) VALUES ('bob','UNUSED','Bob User','t','t','t','t','t','t',
 't','t','t','t','t','t','t','t','t','t','t','t');

 The values for the perm_* fields are either 't' or 'f'.  Each permission
 should be set so that the user does not get priviledges they are not
 supposed to.  Be sure to change the above SQL as it will add a user with
 all permissions enabled.

