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.