Installing RIB (Repository In a Box)

For questions/comments about this document contact
rib@nhse.org.  Also, see http://www.nhse.org/RIB/ for any notes
or announcements.

NOTE : If you are upgrading from a previous version of RIB then
please see the file INSTALL.UPDATE for instructions.

------------------------------------------------
| Basic system requirements for installing RIB |
------------------------------------------------
UNIX machine with root access (root access is only required
                               during installation)
an HTTP/1.0 compliant http server (RIB was designed using
                                   NCSA 1.5.2)
perl version 5.003 or higher
Basic unix utilities (make, gcc, install, etc.)
Approximately 100 megabytes of free disk space
  (typical installation)

----------------
| Introduction |
----------------

The installation of RIB involves three stages:
    1.) Installing Isearch
    2.) Installing and/or configuring HTTP server
    3.) Installing RIB software

The steps should be followed in the order listed above.  It is
recommended that you browse over the entire document before
beginning the installation.  In addition, if the machine on which
you are planning to install RIB is administered by a fellow
staff member, then they should probably take a look at this
document before the installation.  They might want to handle 
some parts of the installation for you.

       ----------------------
1.     | Installing Isearch |
       ----------------------

Isearch is the search engine used by RIB.  It enables RIB to
build searchable indexes which are used for searching its html
software catalogs.  Installation of Isearch is actually optional
but is highly recommended.  If you choose not to install
Isearch then you are sacrificing much of the functionality
of RIB.

Isearch was developed at the Center for Network Information
Discovery and Retrieval (CNIDR) and is freely available.  There
are precompiled isearch binaries for IRIX, Linux, OSF1, SunOS,
and Solaris at the Isearch Web site
(http://www.cnidr.org/ir/isearch.html).  If you prefer compiling
Isearch yourself then you can get the Isearch source code at the
Isearch web site.  The Isearch source code is also included in
this RIB package (named Isearch-1.14.tar.gz).  Note that you
will need g++ and the g++ libs (both available at
ftp://prep.ai.mit.edu/pub/gnu/) to compile the isearch source
code.

Use the installation instructions contained in the Isearch
package.  While you are installing Isearch, be sure to remember
the directory where you chose to install it as well as the
directory where you chose to install its cgi-bin programs.
You will need the names of those two directories later when
you install the RIB software.

If you have problems installing Isearch, you can proceed
with the rest of the installation of RIB.  If at a later time
you are able to successfully install Isearch onto your system
then you can reconfigure RIB to add the support for searching.
See the "Installing the RIB software" section below for
details on how to reconfigure your RIB installation.


         ------------------------------------------------
2.0      | Installing and/or Configuring an HTTP server |
         ------------------------------------------------

RIB should be installed on a machine which also runs an HTTP
server because it uses cgi-scripts to handle its flow of data.
It is not necessary for a dedicated HTTP server to be devoted to
RIB; if you have a machine which already has an HTTP server
installed, you can use that machine.

RIB was developed and tested using NCSA httpd 1.5.2
(http://hoohoo.ncsa.uiuc.edu/), and we recommend this HTTP
server to those who are still shopping for one. Another good
server to use is the Apache server (http://www.apache.org/).
Both of these HTTP servers are free to the public.

If you expect security to be a major concern with the
repositories that you set up using RIB, you might want to
consider using a server such as the Netscape HTTP server
(http://home.netscape.com/). Unlike the two servers previously
mentioned, it is not free, but it supports X.509 certificates
which can provide an added layer of access controls to the
repositories you create. (Apache can support X.509 certificates
as well but it can be quite tedious to set up.)

!!!!!!!!!!!!!!!!!!!!! READ THIS PART !!!!!!!!!!!!!!!!!!!!!!!!!!
Whether security is important to you or not, you should
DEFINITELY read appendix B which discusses how to set up access
control for your RIB installation.  If you neglect to set
up access control for your RIB then ANYONE who
can contact your machine with a web browser can control your RIB
software.  You're not ready to actually implement the access
control yet because RIB has not been installed.  However,
you should consult the appendix before making your RIB
installation active.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

At this point you should go ahead and install an HTTP
server on your machine if necessary.  When you've got the
server up and running, you'll be ready to proceed with the
rest of the installation.

Although the RIB software will not actually be installed until
the next stage of this installation, you need to decide where
you plan to install RIB so that you can configure your HTTP
server.  The recommended location to install the RIB software is
'/usr/local/rib'.  The rest of this section will assume that it
has been installed at that location.  If you choose to install
it elsewhere then just substitute the name of that directory
wherever you see '/usr/local/rib'.  Whatever the case, be sure
to remember whatever location you choose at this point to
install RIB because you will need that information in the next
stage of the RIB installation.

The first modification you need to make to your HTTP server will
map the url 'http://your.machine.name/rib/cgi-bin/' to the
directory '/usr/local/rib/cgi-bin/' and will allow cgi-scripts
to be run within that directory.  If you are using NCSA httpd or
Apache httpd then you will need to add a ScriptAlias directive
to conf/srm.conf that looks like :

  ScriptAlias /rib/cgi-bin/ /usr/local/rib/cgi-bin/

The second modification to your HTTP server will map the url
'http://your.machine.name/rib/' to '/usr/local/rib'.  If you're
using NCSA httpd or Apache httpd then you will need to add
another line to your conf/srm.conf that looks like :

  Alias /rib/ /usr/local/rib/

Different servers have different ways for specifying these
mappings.  You've already seen how to modify the NCSA and Apache
HTTP servers.  If you're using Netscape or some other commercial
HTTP server, chances are good you'll need to add the
mappings using some type of WWW browser interface to the
server's controls.  Consult your HTTP server's documentation
for details.

Note
-----

Depending on what HTTP server you're using, the order in which
you add the url mappings to your server might be important.
Using NCSA httpd, for example, we had to add the ScriptAlias
directive to the configuration file BEFORE (i.e. earlier in the
file) the Alias directive in order for the cgi-scripts to be
executed properly.  If you see a perl script in your browser the
first time you try to use RIB then you need to make sure that
your server recognizes /usr/local/rib/cgi-bin as a cgi-script
directory.


           -------------------------------
3.0        | Installing the RIB software |
           -------------------------------

It would be a good idea for you to visit the RIB home page at
this point so that you can check for any timely news about RIB
(new versions, patches, etc).  Point your WWW browser at
http://www.nhse.org/RIB/ to view the RIB home page.

perl
-----
The RIB requires that perl version 5.003 or higher is installed
on your machine.  If you are not sure what version of perl is
installed on your machine then try typing 'perl -v'.  If perl
is installed and the perl binary is in your path then the output
should look something like :

>  This is perl, version 5.003 with EMBED
>          built under sunos
>          + suidperl security patch
>  
>  Copyright 1987-1996, Larry Wall
>  
>  Perl may be copied only under the terms of either the Artistic
>  License or the GNU General Public License, which may be found in
>  the Perl 5.0 source kit.

If your version of perl is less than 5.003 then you can either
download the newest version of perl from
http://www.perl.com/perl/info/software.html or from the RIB home
page (http://www.nhse.org/RIB/).  You should install perl as
root and (if possible) accept the default locations during the
install.

perl modules
------------
After making sure that perl version 5.003 or higher is installed
you are ready to install the perl modules used by RIB.  The modules
required by RIB should be installed in the following order :

  IO-1.14 (newer versions of perl already have this module intalled)
  MD5-1.7
  Data-Dumper-2.07
  libnet-1.05
  libwww-perl-5.08

For your convenience, each of these modules is included in the
RIB distribution.  If you prefer, however, you can obtain the
modules directly from the Comprehensive Perl Archive Network
(CPAN) at http://www.perl.org/CPAN/CPAN.html.  In addition, the
perl modules are available from the RIB home page at
http://www.nhse.org/RIB/. Each perl module contains a README or
INSTALL file which provides instructions on how to install it.

Since the development of RIB began, some of the perl modules that
it uses have matured to a later version (libnet and libwww have,
for example).  We have not tested thoroughly test RIB with the
new versions of these modules, but have reason to believe that
RIB should work just fine with these newer modules.  If you would 
like to retrieve the newer versions of these modules from CPAN
(or already have them installed on your target system) then we
encourage you to do so.  Feel free to contact us at rib@nhse.org
if you have any problems.

The basic steps are :
  1.) uncompress and untar
  2.) perl Makefile.pl
  3.) make
  4.) make test
  5.) make install (as root)

See Appendix A for an example session of installing a perl
module.  Some of the perl modules (e.g. libnet) will ask
you for some information about your machine.  You should
check with your local techie person if you're not sure
about how to answer any of these questions.

If you have problems installing any of the perl modules,
you should contact the author(s) of the module or
send mail to rib@nhse.org for assistance.

rib perl module
--------------------

Included in your RIB distribution file is a perl module
called rib-xxx (where xxx is the version number).

Most of the modules used by RIB are "standard" modules which are
distributed by CPAN.  However, the rib perl module was
written specifically for RIB and therefore is not available at
CPAN.  The steps for installing this module are much like 
the steps taken to install any of the other modules.  However,
during the 'perl Makefile.PL' stage you will be asked several
questions about your Isearch and HTTP configurations.  If you've
followed this INSTALL document sequentially to this point,
you'll already know how to answer those questions.  If you
haven't then you should read the sections above before
installing this particular module so that you'll be prepared to
answer the questions.

Once you've got the rib tar file extracted you should do
a 'perl Makefile.PL'.  This step should be done as root.  Don't
be alarmed if the program reports that it can't find the
versions of some of the modules.  If you've successfully
installed each of the modules in the previous subsection, you're
fine.

At this point you will be asked several questions about how you
want RIB to be installed :

>  Enter the absolute path to the directory where rib will
>  be installed: [/usr/local/rib]

Enter the directory where you decided you install RIB.
Just press 'enter' to accept the default (/usr/local/rib)

>  Enter the URL for RIB: []

This will be the url that your HTTP server maps to your
RIB installation.  If the name of your machine is
  jughead.micropot.com
then you would enter http://jughead.micropot.com/rib at
this point.

>  Would you like your repositories searchable via Isearch? [yes]

If Isearch is installed on your system (see section titled
'Installing Isearch' for details) then press enter to accept the
default answer ('yes').  If Isearch is not installed then type
'no' and press enter.

>  Enter the absolute path to the directory where the Iindex binary
>  is installed:

This is the location where you chose to install Isearch.
In the Isearch Makefile this directory is called 'INSTALL'.

>  Enter the absolute path to the directory where the
>  isrch_srch and isrch_fetch binaries are installed: [] 

isrch_srch and isrch_fetch are two of the cgi binaries that are
included in the Isearch distribution. 
In the Isearch Makefile the directory that these two binaries
are installed into is called 'CGI_DIR'.

>  Enter the username that your web server runs under: [nobody] 

Most HTTP (web) servers run under the username 'nobody' by
default.  If your HTTP server runs under a different username
then you should specify that here.  Otherwise, just press
'enter' to accept the default value 'nobody'.
If you're not sure what username that your HTTP server runs
under, check your HTTP server documentation.

At this point a Makefile will be created that you can use to
install the RIB perl module.  Like before, to install the module
you will type 'make', and then 'make test'.

Finally, you need to type 'make install_rib' to complete the
installation.  Note that unlike the other perl modules that
you've installed, you do not need to type 'make install'.  This
is because 'make install_rib' should take the place of this
command.

You are now ready to start using RIB on your machine.
You can access it by pointing your web browser at the
url http://your.machine.name/rib/cgi-bin/admin/RIB.pl

Reconfiguring RIB
-----------------
If at some point in the future you need to reconfigure RIB, you
can follow the instructions in the previous subsection titled
"rib perl module" to reinstall the RIB software.
You will need to reconfigure RIB if you change where
any of the RIB software is installed or if you change the RIB
url mappings in your HTTP server.  In addition, if you want to
add/remove RIB's support of the Isearch software, you can
do this by reconfiguring RIB.

Upgrading from a previous version of RIB
----------------------------------------

Please see the file INSTALL.UPDATE


------------------------------------------------------------
| Appendix A:  example session of installing a perl module |
------------------------------------------------------------
 [ blank lines are inserted into the session for clarity ]

% ls
Data-Dumper-2.07.tar.gz

% gunzip -c Data-Dumper-2.07.tar.gz | tar tf -
Data-Dumper-2.07/
Data-Dumper-2.07/Dumper.html
Data-Dumper-2.07/t/
Data-Dumper-2.07/t/dumper.t
Data-Dumper-2.07/MANIFEST.NOXSUB
Data-Dumper-2.07/Dumper.pm.NOXSUB
Data-Dumper-2.07/Dumper.xs
Data-Dumper-2.07/Todo
Data-Dumper-2.07/MANIFEST
Data-Dumper-2.07/Makefile.PL
Data-Dumper-2.07/Dumper.pm
Data-Dumper-2.07/Changes
Data-Dumper-2.07/flip
Data-Dumper-2.07/README

% gunzip -c Data-Dumper-2.07.tar.gz | tar xf -
% cd Data-Dumper-2.07/

% perl Makefile.PL
Checking if your kit is complete...
Looks good
Writing Makefile for Data::Dumper

% make
cp Dumper.pm ./blib/lib/Data/Dumper.pm
/bin/perl -I/usr/local/lib/perl5/sun4-sunos/5.003 -I/usr/local/lib/perl5 /usr/local/lib/perl5/ExtUtils/xsubpp  -typemap /usr/local/lib/perl5/ExtUtils/typemap Dumper.xs >Dumper.tc && mv Dumper.tc Dumper.c
cc -c  -I/usr/local/include -O     -DVERSION=\"2.07\"  -DXS_VERSION=\"2.07\" -pic -I/usr/local/lib/perl5/sun4-sunos/5.003/CORE  Dumper.c
Running Mkbootstrap for Data::Dumper ()
chmod 644 Dumper.bs
LD_RUN_PATH="" ld -o blib/arch/auto/Data/Dumper/Dumper.so -assert nodefinitions -L/usr/local/lib Dumper.o     
chmod 755 blib/arch/auto/Data/Dumper/Dumper.so
cp Dumper.bs ./blib/arch/auto/Data/Dumper/Dumper.bs
chmod 644 blib/arch/auto/Data/Dumper/Dumper.bs
Manifying ./blib/man3/Data::Dumper.3

% make test
PERL_DL_NONLAZY=1 /bin/perl -I./blib/arch -I./blib/lib -I/usr/local/lib/perl5/sun4-sunos/5.003 -I/usr/local/lib/perl5 -e 'use Test::Harness qw(&runtests $verbose); $verbose=0; runtests @ARGV;' t/*.t
t/dumper............ok
All tests successful.
Files=1,  Tests=120,  2 secs ( 2.13 cusr  0.25 csys =  2.38 cpu)

% whoami
root
% make install
Installing /usr/local/lib/perl5/site_perl/sun4-sunos/./auto/Data/Dumper/Dumper.bs
Installing /usr/local/lib/perl5/site_perl/sun4-sunos/./auto/Data/Dumper/Dumper.so
Installing /usr/local/lib/perl5/site_perl/./Data/Dumper.pm
Installing /usr/local/lib/perl5/man/man3/./Data::Dumper.3
Writing /usr/local/lib/perl5/site_perl/sun4-sunos/auto/Data/Dumper/.packlist
Appending installation info to /usr/local/lib/perl5/sun4-sunos/5.003/perllocal.pod




----------------------------------------------------
| Appendix B :  Configuring Access Control for RIB |
----------------------------------------------------

No access controls are enforced by your RIB software by
default.  Instead, access control for your RIB is activated by
enabling the access control mechanisms of your http server.  The
actual mechanisms for access control vary depending on what http
server you are using, but as long as your http server allows
access control based on directory name you should be able
configure your RIB to meet fairly rigid security requirements.
As a bare minimum, if your http server supports what is called
'Basic HTTP Authentication' then you will be able to achieve a
moderate level of security.  However, if your http server
supports features such as SSL (secure sockets layer) or X.509
certificates then you can achieve much higher levels of
security.  Consult your http server documentation for
information on what security features it supports and how to
enable and configure those features.  If you are still
'shopping' for an http server then an excellent choice is the
Netscape Enterprise Server (footnote: http://home.netscape.com).

It will probably be the case that you will need to ask your
system administrator to configure your http server's access
controls.  Depending on the security policies of the target
machine, this might involve editing your http server's
configuration files or could perhaps require copying a special
file (called '.htaccess' by some http servers) into the access
controlled directories.  Whatever the case, you should carefully
read this section and plan the access control scheme for your
RIB so that your system administrator can integrate the access
controls with as few interruptions as possible.  In addition,
the lack of careful planning could compromise any sensitive
information controlled by your RIB.

Access control mechanisms can be divided into 2 main types :
authentication based on host name and authentication based on
username/passwd pairs.  When used together, these two types of
authentication provide a reasonable amount of access control for
the RIB while sacrificing little of its functionality and
scalability.  Using the combination of these two types of access
control, for example, you can specify that anyone who accesses
your RIB from a machine whose hostname ends with the suffix
'.goodguys.com' is allowed to browse your software catalog but
not allowed to administer your RIB.  You could require a
username/passwd combination in addition to any hostname
requirements in order to administer your RIB. [ footnote: If you
protect an area of your RIB with username/passwd authentication
then it is important to ensure that any people that need to
access that area use WWW browsers that are equipped to handle
username/passwd dialogue boxes.  Authentication based on
hostname is not handled by WWW browsers so it places no
requirements on them. ]

It is important to keep in mind that access limitations placed
on any directory are inherited by each of its subdirectories.
However, it may be the case that your http server allows a
subdiretory to override the access restrictions of its parent
directory without also inheriting the parent directory's access
restrictions.  For example, I might require accesses to a
directory named '/parentdir' to come from a host ending with
'.goodguys.com'.  Later I might want to add access controls to
subdirectory which is named '/parentdir/subdir1/subdir2'
requiring a certain username/passwd pair.  Now, depending on
what http server I use, it may not be the case that accesses to
'/parentdir/subdir1/subdir2' require the usernname/passwd pair
AND come from '.goodguys.com'.  If I want the combination of
these two access controls to apply then I may have to explicitly
configure '/parentdir/subdir1/subdir2' in this manner.  To
figure out if your HTTP server behaves in this manner then you
should either consult your HTTP documentation or construct a
small test.

What follows below is a listing of the directories in the RIB
that should be considered for access control.

top level RIB installation directory (RIB_DIR)
----------------------------------------------
A top level directory is created when RIB is installed which
contains the subdirectories 'help', 'conf', 'repositories',
'cgi-scripts', and 'cgi-bin'.  For future references we will
call this directory 'RIB_DIR'.  Restricting access to this top
level directory will restrict access to every aspect of your RIB
installation,  i.e. whatever access controls you specify for
this directory will be automatically carried over to any of its
subdirectories unless they are explicitly overridden.  If you
choose to restrict access to this directory then those
restrictions will control not only who can administrate your RIB
but also who can browse any of your software catalogs and who
can interoperate with your repositories.  Therefore, you should
carefully consider the implications of controlling access to
this directory before adding them.  If you do choose to enable
access control on this directory then it should be by hostname
rather than by username/passwd authentication if you plan on
interoperating with other repositories.  This is because the RIB
currently does not have the ability to retrieve metadata from a
foreign repository using username/passwd pairs.

RIB_DIR/cgi-bin/admin/
----------------------------------------------
This directory contains a script that is the entry point for
administrating all of your RIB repositories and for creating and
deleting repositories.  Restricting access to this directory
will control who can perform any administrative functions on any
of your repositories.  If access control is not very important
to you then you should at least retrict access to this directory
with a username/passwd pair.  It only takes a moment to type in
a username/passwd pair when you begin adminstrating your RIB
repositories, but it could take weeks (or be impossible) to
restore data in your RIB repositories that was deleted by
someone who has no business using the scripts in this
directory.


RIB_DIR/cgi-bin/admin/create_delete_repo
----------------------------------------------
This directory contains the scripts that create and delete
repositories.  Users with access permissions to this directory
can create a new repository in your RIB or delete one already
created.  This directory should be well protected with at least
a username/passwd pair because deleting a repository is such a
serious action (all data within the repository is lost).  If
feasible, this directory should also be protected by hostname
restriction.

RIB_DIR/cgi-bin/admin/repositories
---------------------------------------------
This directory contains the administrative scripts that are used
by each of the repositories created by your RIB.  Restricting
access to this directory will control who can do such
adminstrative tasks such as generating catalogs and adding
assets to any of your repositories.

RIB_DIR/repositories
---------------------------------------------
This directory contains the data for all of the repositories
that you create.  Restricting access to this directory will
restrict who can access any of the data that is associated with
any of your RIB's repositories.  This data includes all object
description files that are created or imported by your RIB as
well as repository-specific configuration files and software
catalogs.  If access controls are applied to this directory
then it should be by hostname rather than username/passwd authentication.
See the section above for RIB_DIR for more information on why.


-----------------------------------------------------------------

When you use your RIB to create a new repository certain
directories will be created that, depending on the information
you would like to catalog in that repository, may need access
control.  Applying access controls to these directories will
only limit who can access the resources of that new repository.
All other repositories made by your RIB will need to have their
own separate access controls if they are needed.  For future
reference let the name of the new repository be 'NEW_REPOSITORY'.
Below is a description of the directories created for a new repository
which you may want to apply access controls to.

RIB_DIR/repositories/NEW_REPOSITORY
---------------------------------------------
This directory contains the configuration file, software
catalog, object description files, and any uploaded software
files that are associated with the new repository.  Note that
access to the new repository already has the same restrictions
as its nearest parent directory whose access is restricted.
It's worth repeating that this directory contains the software
catalog for this repository.  Restricting access to this
directory limits who can browse the software catalog for this
repositoy.

RIB_DIR/cgi-bin/admin/repositories/NEW_REPOSITORY
---------------------------------------------
This directory contains the administrative scripts for this
repository.  It is strongly recommended that access to this
directory is restricted by a username/passwd pair.  Whoever has
permission to access this directory will have access to cgi
scripts that directly access (read and write to) the disk files
associated with NEW_REPOSITORY.  It's important to point out
that just because you don't advertise the url to this directory
doesn't mean that it won't ever turn up in someone's WWW search
or that someone with knowledge of how the RIB works couldn't
derive the url.
