Instructions for installing req-1.2 or upgrading from an earlier release.

Overview:
 1. Basic Explanation
 2. Pre-Configure
 3. Decisions - the defs file.
 4. Install it to test it.
 5. Install it for real.
 6. Install any interfaces.
 7. Learn how to use it.
 8. Get on the update mailing list if you care.


1. Explanation
--------------
Read the file docs/blurb.  It explains at a relatively high level how
the system works - enough so that you can make decisions about how to
install it.


2. Pre-Configure
----------------
You need to build a file called "defs" at the root of distribution.
It's used configuration of the whole system.

If you've never built req before, type:
  ./configure

If you have built it, and wish to use your old defs file, type:
  ./configure <old-defs-file>

If you need to specify where perl is, you can do this:
  ./configure -p /path/to/perl


3. Decisions
------------
There are quite a few configuration options that you can set by editing
the values in the "defs" file, and that's what you should do now.

The variables are explained fully in the defs file.  You might want to 
look at the example defs file (the one we use) which is named "defs.ccs".

To people UPGRADING - there are NEW variables in the defs file which
you will probably want to configure.  Make sure you look it over.

One decision that you'll make will affect how you install the rest of
the package:  whether or not to install the request system such that
your mail system has a local copy.

Essentially, the issue is this: when mail is sent your mailing list, 
that mail is processed by a perl script, which may or may not update
files in the request queue.  If the perl script or the request system
are installed on a different machine than the mail server, and if you
are using some network file system like NFS (sigh), then your mail 
server can hang if it tries to access the remote file system while 
the remote server is down.  This is bad.

If you'd like to avoid this problem, and have the request mail handled
if the mail server is up, regardless of other servers, then you should
install the request system on the mail server.  This includes installing
the request programs and the request spool on the server.  It also 
includes having perl installed on the mail server.

If you choose to do this, then you will need to export the request
spool (i.e. the files which make up the requests) from the mail server
to the other machines where you want to run the request system, so that
those machines can find them.  Sorry, at this point in the process,
there's no way to share the files other than a shared file system.

So, choose a strategy:
  1) forget reliability and just install it somewhere
  2) install req on the mail server and nowhere else
     (requiring that you login to the mail server to run it)
  3) install req on the mail server and export it to the network
  4) install req on the mail server, another copy of the programs
     on the network, and share the request spool.

Based on your choice, you can fill in the values for the directories
in the "defs" file.

If you would like to see what the paths in your defs file will look
like when fully expanded, run:
  ./extract defs > /tmp/defs.out
And then read '/tmp/defs.out'.  You don't have to do this, but it might
help make more sense out of the insanity towards the end of the defs
file.


4. Test it
----------
Having now edited the defs file, you should install a test case to see
how it works.  (You don't want mail sent to your list to die if there's
some problem.)

  A.  Pick a test alias.   'test' may be good, if it's not being used.

  B.  Update the 'defs' file to use 'test' as the alias name, and
      'test-dist' as the recipient's alias.

  C.  Create the login that it will run as.
       - Make sure the password is unusable.  "*" works well.
       - The shell probably should be usable so that the cronjob will
         work.

  D.  Create the group that you mentioned as REQUEST_GROUP, and put
      anyone in it who should have access to the request system.  
      (Probably the same people as are on the list.)

  E.  Put a mail alias in for the test alias, and an alias in for the 
      distribution:
            test:           |"/ccs/adm/test/etc/req-mailgate"
            test-dist:      remy, django, dave, bdowling    
      You may need to run 'newaliases' or something else... this is
      system dependent.  Make sure you put in the real path to your
      mailgate.
      
  F.  In the top of the distribution directory (the directory containing
      the "defs" file):
         make all
      This should build all the programs.

  G.  As whomever has the permissions to create the directories you've
      chosen as the installation directories:
         make directories

  H.  As root, or as the user you picked for the request system:
         make install
      This requires root because it makes some programs setuid.

  I.  Put in the currentnum file.

      When you're installing req (not the test version) DON'T DO THIS if 
      you've already installed req before and want to keep the current 
      req number at what it is. (And you do want that.)  Instead, copy 
      in the old currentnum file, or point a link at it, or something
      similar.

      Still as root:
         make numbers
      This installs the currentnum file.  

  J.  As whomever you like:
         make install-man

Now, ONLY IF you're installing a separate system on the mail server.

  K.  Build the programs for the mail server:
         make mail-all
      This will make programs with different paths in the mail/ directory.
       
  L.  On the mail server, as root, do:
         make mail-directories

  M.  On the mail server, as root do:
         make mail-install

  N.  Make sure that you export the request spool from the mail server, if
      that's part of your plan.

You're done with the install.  If some part doesn't work out because of
strange permissions or such, do a 'make -n <target>' to see what would
have happened, and then do it by hand.  This may be necessary under
certain shared directory conditions.  Sigh.

Now test it.  Send mail to 'test'.  If it bounces, there's a problem.
Run 'q'.  It should show a request (probably number 1) in the queue.
Run 'req -show 1'.  You should see the message.  At this point, play
around with the system.  Read the manual pages.


5. Install it for real
----------------------

   A. Edit the 'defs' file so that it says the name of the real 
      mailing list that you want to filter into the request system.

   B. Update the aliases file to have the real aliases.
       
   C. make clean

   D. Follow all the instructions in number 3, starting at F.  (make all)


6. Drop in the cron job
-----------------------
Arrange with cron to run the "req-daily" script that should be in the 
etc/ directory of the install tree.  The req-daily script runs 
glimpseindex on the active and resolved queues to allow easy indexing.

This should be run as the user who owns the request system.  You could 
put in a crontab entry for this user, or from root's crontab or daily 
script, you could do:
    su request -c req-daily

(Substitute the appropriate user name and path name.)

This should be done on the machine where the requests will be stored.


7. Install any interfaces
-------------------------
If you're installing any of the interfaces for the request system,
install them now.  See instructions in their directories for details.

The two interfaces we use are:
  tkreq: for X
  request-queue-mode: for emacs

These are also up for ftp on ftp.ccs.neu.edu:/pub/sysadmin.  Put them
in the interfaces/ directory and go for it from there.


8. Customize
------------
The autoreply message should probably be customized to your site.  We've
provided one in that was probably installed as req-autoreply, but the
messages (hours, and so on) will probably not be appropriate to your
installation.

You should modify that program (or write your own) to do as you see fit.


9. You're done
--------------
Things you might want to read:
   docs/changes   - Changes made in recent releases
   docs/intro     - An intro to using it.
   docs/use       - Suggestions on how to use the request system.
   docs/wish.list - The current list of requested features and comments
                    about them.
   The manual pages also contain quite a lot of detail.
 
Also, ftp.ccs.neu.edu:/pub/sysadmin/usenix.ps.gz is a paper that was
presented at Usenix's LISA VIII on req and how we use it.  


10. Updates & Discussions
-------------------------
If you want to be notified of new releases or bug fixes, send mail to
majordomo@ccs.neu.edu, with this in the *body* of your mail:
  subscribe req-announce

If you want to get involved in discussions about req, you're welcome
to join the req working mailing list.  Send mail to majordomo@ccs.neu.edu
with this in the body of your mail:
  subscribe req

The address of the discussion list is 'req@ccs.neu.edu'.


Otherwise
---------
If you run into trouble, check out the code and the manual pages.  If that
still doesn't work, send mail to "req@ccs.neu.edu" with lots of 
description of what's going wrong.

Please be aware that those of us developing req have full-time++ jobs that
have a lot to do with using req but nothing to do with developing it...
while we take bug reports and feature requests seriously, we simply can't
make any promises about support for any of this.


