Installing the Rover Toolkit

This document details the installation process for the alpha release of the Rover toolkit. There are three sections:

1. System Requirements. These are the requirements for installing and using the Rover toolkit.
2. Obtaining the Source Code. These are the options for obtaining the source code for the Rover toolkit.
3. Step-by-Step Instructions. These are the step-by-step instructions for installing the Rover toolkit.

The forked Rover server should be compatible with most web servers and has been tested with NCSA's and Apache's httpd servers. Please inform the Rover developers of any incompatibilities.

Software Requirements

1. Tcl/Tk. The toolkit requires Tcl versions 7.3 through 7.6 and Tk version 3.6 through 4.2. No support is provided for any other Tcl/Tk versions.
   

   Note: If the client machine's operating system supports shared libraries (e.g., Linux), you will need Tcl and Tk shared libraries. To reduce transmission time, cache size, and memory usage, Rover client applications may be compiled with dynamic linking on those operating systems that support it. The toolkit libraries are always statically linked.

2. WWW LineMode browser. To compile the Rover client and server toolkits and client applications, you will need a copy of the WWW LineMode browser. A precompiled, gzip-compressed Linux binary is available here. Download the link as the file www_3.0pre2.gz (or as www_3.0pre2, if your browser automatically uncompresses files), uncompress it in the /usr/local/bin directory, and make a link from the binary to www.

3. tar and GNU gunzip or GNU gtar (sometimes called tar). Rover source code is stored as gzip-compressed tar archive files.

4. GNU gcc compiler. Some of the files may not compile with other compilers. Note that you may have to set the CC environment variable to make your system default to the gcc compiler (i.e., setenv CC gcc).

5. GNU gdbm. Server RDO log management uses the gdbm library.
   • If gdbm.h is not in a standard location (e.g., /usr/include, /usr/local/include, or /usr/include/gdbm), set the environment variable gdbminc point to the correct location (i.e., setenv gdbminc /usr/local/gdbm-1.73/include)
   • If the GDBM library file (libgdbm.a, libgdbm.so, or libgdbm.so.*) is not in a standard location (e.g., /usr/lib or /usr/local/lib), set the environment variable gdbmlib point to the correct location (i.e., setenv gdbmlib /usr/local/gdbm-1.73/lib)

This section lists the locations of the source code for the toolkit. The Rover toolkit source code and documentation is covered by a copyright notice. Please read the notice before downloading the code.

The developer installation process requires login access or remote NFS mount access to the Rover source CVS repository. If you do not have such access, you should follow the user instructions.

User Installation

The source code is stored as gzip-compressed tar archive files. Download the code from the following URLs:

1. Rover documentation
2. Rover server RDOs and libraries
3. Rover server source code
4. Rover access manager and client applications
5. Rover common code

Developer Installation

The Rover source CVS repository uses CVS (http://www.loria.fr/~molli/cvs-index.html) for source code version control. You will need at least version 1.7 (available from ftp://prep.ai.mit.edu:/pub/gnu). A local quick start guide to CVS commands can be found on this page.

The CVS syntax for checking out modules is:
cvs checkout module names

Note: A CVS checkout will fail if the target directory already exists and is not a CVS directory. For example, if you checkout and build the server source code before checking out the server RDOs, the server RDO checkout will fail, since building the source code will create the cgi-bin/rover directory. Thus, it is important to carefully follow the installation and build order listed below.

The CVSROOT environment variable specifies the location of the primary CVS repository, currently pdos.lcs.mit.edu . The source repository supports three access methods: ssh, Kerberos rsh, and NFS access. The most desired access method ssh. NFS access is not recommended.

• ssh:
  1. Optional: Install the appropriate .shosts file on pdos. If you don't install the file, you will have to type your password each time you use a CVS command (not a bad idea, in general).
  2. Optional: Acquire and add the pdos public host key. The first time you use a CVS command, ssh will acquire the host key, however if you are paranoid about spoofing, you can acquire and add the host key manually.
  3. Set the CVS_RSH and CVSROOT environment variables:
     setenv CVS_RSH ssh
     setenv CVSROOT pdos.lcs.mit.edu:/home/am3/Rover/CVS
  For more information about ssh, see the ssh home page, http://www.cs.hut.fi/ssh/.
• Kerberos rsh:
  1. Acquire a ticket granting ticket from the LCS Kerberos server.
  2. Set the CVS_RSH and CVSROOT environment variables:
     setenv CVS_RSH KerberosRshCommand
     setenv CVSROOT pdos.lcs.mit.edu:/home/am3/Rover/CVS
  For more information about Kerberos, see the LCS Kerberos page, http://www.crs.lcs.mit.edu/kerberos.html.
• NFS: This is the least desirable option. NFS relies upon UDP and not all UDP implementations use UDP checksums. We have had problems with corruption of the repository when checking in changes over NFS. Do not use this alternative unless you are using a local Ethernet connection.
  1. Use NFS to mount the pdos's /u3 directory on the client's /home/am3 directory.
  2. Set the CVSROOT environment variable:
     setenv CVSROOT /home/am3/Rover/CVS

1. Rover documentation (Optional).
2. Rover server RDOs and libraries (Server).
3. Rover server source code (Server).
4. Rover access manager and client applications (Client).
5. Rover common code (Server and Client).

The server files are the files that are required to install a Rover server. The client files are the files that are required to install a Rover client.

Important Notes:

1. Follow the installation directions in the order that the components are listed.
2. Client applications may be built on the client architecture and then stored on the server.

1. Change into the the server's html directory:
   cd DocumentRoot
2. User:
   • Create a documentation directory:
     mkdir rover
     
   • Change into the directory and unpack the documentation tar file.
     cd rover; gtar xzvf DownloadDirectory/RoverDoc.tar.gz
     This will unpack the files containing the Rover toolkit documentation.
   Developer:
   • Type cvs checkout RoverDoc
     This will create a rover directory containing the Rover documentation.
   • Update the .htaccess file in the LCS-ONLY directory, if necessary.
     Note: Verify that the .htaccess file is correctly restricting access to the documentation to LCS machines. For example, try to access the documentation from Athena using lynx (use the add infoagents command to enable lynx)

1. Change into the server's cgi-bin directory:
   cd ScriptAlias
2. User:
   • Create and change into the Rover server RDO directory:
     mkdir rover; cd rover
   • Unpack the Rover server RDOs and libraries:
     gtar xzvf DownloadDirectory/RoverServerRDOLib.tar.gz
     This will unpack the RDOs and create a rover/lib directory containing the libraries.
   • Create (if it doesn't already exist) and change into the library directory:
     mkdir lib; cd lib
   Developer:
   • Type: cvs checkout Objects
     This will create a rover directory containing the Rover server RDOs.
   • Create the Rover library:
     mkdir rover/lib; cd rover/lib
   • Checkout copies of the exmh, rexmh, and Webcal script libraries and link the libraries into the directory:
     cvs checkout exmh1.6.1 Mail Webcal
     ln -s Mail/Implementation rexmh
     ln -s Webcal ical
3. Create links for Tcl and Tk scripts (where the init.tcl and tk.tcl scripts are located)):
   ln -s /usr/lib/tcl . ; ln -s /usr/lib/tk .
   Note: The scripts may be located in other directories (e.g., /usr/uns/lib) or under version names (e.g., /usr/lib/tcl7.5 or /usr/lib/tk4.1). In the latter case, you should create links from the versioned names to the names without versions (i.e., ln -s /usr/lib/tcl7.5 tcl).
4. If your Tcl/Tk scripts are not in standard locations (e.g., /usr/local/lib/tcl, /usr/lib/tcl, /usr/local/lib/tk, or /usr/lib/tk), set the environment variables tclscripts and tkscripts to point to the correct locations (i.e., setenv tclscripts /usr/lib/tcl7.5; setenv tkscripts /usr/lib/tk4.1)
5. Developer:
   • Configure Webcal:
     cd Webcal
     ./configure --without-roverlib
     Note: The Webcal library must be configured, as the configuration process generates system specific Tcl scripts from general templates.
   • Update the rexmh tclIndex file:
     cd ../rexmh; tclsh ./genIndex
     Note: If you are installing the Rover access manager and client applications, delete the rexmh directory and replace it with a link to the client applications' ClientDir/WWW/Mail directory:
     cd ScriptAlias/rover/lib; rm rexmh; ln -s ClientDir/WWW/Mail rexmh

1. Change into the directory above the server's cgi-bin directory:
   cd ScriptAlias/..
2. If it does not already exist, create a cgi-src directory. The directory may be different for other servers (e.g., Apache uses cgi-scripts for CGI source files).
   mkdir cgi-src; cd cgi-src
3. User:
   • Create and change into the Rover server source code directory:
     mkdir rover; cd rover
   • Unpack the Rover server source code:
     gtar xzvf DownloadDirectory/RoverServer.tar.gz
     
   Developer:
   • Type cvs checkout Sources
     This will create a rover directory containing the source code for the Rover server.
   • Change into the rover directory:
     cd rover
4. Follow the instructions for installing the Rover common code.
5. Set the server's unique identifier by creating the RoverServerID.h file:
   echo "ServerID = x;" > RoverServerID.h ,
   where x is an identifier that is unique to this server with respect to all other Rover servers. The variable ServerID is an unsigned integer, so you can choose a large random number for the server's ID.
6. Set the server's Access Control List (ACL) by creating the file, RoverACL.h. The file contains the usernames of the users that are allowed to use the server. The following is an example of the file's contents:

   PRIVATE char *RoverClientACL[] = {
     "adj",
     "candea",
     "dean",
     "josh",
     "kaashoek",
     NULL
   };
   

   The list must be terminated by a NULL entry.
7. Set the location of the server's RDOs, ScriptAlias/rover, by creating the file, RoverConfig.h. The file contains the possible locations of the server's RDOs. The following is an example of the file's contents:

   char *RoverRoot[]  = {
     "/usr/local/etc/httpd/cgi-bin/rover",
     "/u3/httpd/cgi-bin/rover",
     "/u1/httpd/cgi-bin/rover",
     "/home/httpd/cgi-bin/rover",
     ".",
     NULL
   };
   

   The list must be terminated by a NULL entry.
8. User:
   • Configure the server:
     ./configure
   Developer:
   • Configure the server:
     ./configure --with-Webcal --with-FullRover
     
9. Compile the server:
   make
10. If there are no compilation errors, then as root, install the executables:
    su; make install
11. To use the SMTP proxy for client-server communication, you need to add the following lines to your /etc/aliases file:

    webcache: |ScriptAlias/rover/rmcacheshell
    webserv: |ScriptAlias/rover/rmgateshell
    

    This method assumes that you are using sendmail for mail delivery. On some platforms, it may be necessary to execute newaliases to rebuild the aliases database.
12. To use the server in forked or standalone mode, follow the server usage instructions.

1. Change to the directory above where the client software will be installed:
   cd ClientDir
2. User:
   • Create and change into the client software directory:
     mkdir WWW; cd WWW
     
   • Unpack the Rover access manager and client applications:
     gtar xzvf DownloadDirectory/RoverAM.tar.gz
     
   Developer:
   • Type: cvs checkout WWW
     This will create a WWW directory containing the code for the Rover access manager and client applications.
   • Change into the client software directory:
     cd WWW
     
3. Install the Rover Common code:
   • For client and server installations, create a link to the server's common files:
     ln -s ScriptAlias/../cgi-src/rover/Common .
     ln -s ScriptAlias/../cgi-src/rover/zlib .
     Developer: ln -s ScriptAlias/rover/RoverFS .
     
   • For client-only installations, follow the instructions for installing the Rover common code.
4. Compile the access manager and client applications:
   ./BUILD
5. Create a ~/.rover-session-init default mappings file for Service to Server mappings in the access manager.
6. Copy the client executables from the build directory to the server and place them in the ScriptAlias/rover/binaries directory. Here is a sample list of the locations of the client executables when compiled and the desired target server directories:
   • WWW/Rover/arch/base.app --> ScriptAlias/rover/binaries/base-arch.app
   • WWW/Rover/arch/browse.app --> ScriptAlias/rover/binaries/browse-arch.app
   where arch is the name of the client machine architecture.
7. To start the Rover access manager and the chooser applications, follow these instructions.
   Note: The only build directory files needed on the client to run the Rover toolkit are the script file (WWW/rover) and the Rover access manager executable (WWW/LineMode/arch/www). All other build files may be deleted from the client to save disk space.
   

   ---

   Rover common code

   The Rover common code consists of directories containing the source code for the Zlib compression library and the common server and client code. For client and server or server-only installations the code should be installed in the server source code directory. For client-only installations, the should be installed in the client source code directory

   1. Change into the appropriate directory.
      • For client and server or server-only installations, change into the Rover Server directory:
        cd ScriptAlias/../cgi-src/rover
      • For client-only installations, change into the Rover Client directory:
        cd ClientDir/WWW
   2. User:
      • Unpack the common code:
        gtar xzvf DownloadDirectory/RoverCommon.tar.gz
        
      Developer:
      • Type cvs checkout zlib Common RoverFS
        This will create directories containing the source code for the Zlib compression library, the Common server and client code, and the RoverFS code.

   ---

   Last updated by $Author: adj $ on $Date: 1997/12/03 01:59:43 $.
   Copyright © 1995-1998 Anthony D. Joseph and Massachusetts Institute of Technology