home *** CD-ROM | disk | FTP | other *** search
/ Usenet 1994 January / usenetsourcesnewsgroupsinfomagicjanuary1994.iso / sources / misc / volume30 / mserv-3.0 / part02 / INSTALL < prev    next >
Encoding:
Text File  |  1992-06-19  |  12.4 KB  |  355 lines
  1. @(#)@ INSTALL    3.14 - INSTALL
  2.  
  3. Installation
  4. ============
  5.  
  6.  1. Preparation
  7.  
  8.     As distributed, perl is expected to reside in /usr/local/bin.  You
  9.     can change this in the Makefile if your perl resides somewhere
  10.     else.
  11.  
  12.     The mail server needs a user id to own the programs, and a place
  13.     where the programs and files can be stored.
  14.     Pre-configured values are "mserv" and "/usr/local/lib/mserv"
  15.     respectively. We'll call the library LIBDIR in this document.
  16.     LIBDIR could be the HOME directory of the mail server owner, but it
  17.     need not.
  18.     If you prefer a different value for LIBDIR, change the appropriate
  19.     line in the Makefile.
  20.     The name of the mail server owner can be changed in step 2, as
  21.     described below.
  22.  
  23.     Since all messages sent by the mail server are sent under the
  24.     server owner uid, its full name (the GCOS or comment field in
  25.     /etc/passwd) should be descriptive.
  26.  
  27.     The mail server owner does not need any privileges, except for
  28.     read access to the archives, and read/write access to LIBDIR.
  29.  
  30.     Do not use the root account for server owner!
  31.  
  32.  2. Configure and build
  33.  
  34.     Tailor "mserv_config.pl" to reflect your specific needs. It has
  35.     extensive descriptions for configuration variables and values.
  36.     Do not forget to tailor the Makefile also, if needed.
  37.  
  38.     It may be a good habit to generate differences using the 'diff'
  39.     program so you can apply your modifications to a new version of
  40.     the mail server software easily.
  41.  
  42.     Issue "make" to prepare the programs. 
  43.  
  44.     If you select the index file feature, you need GNU find / locate.
  45.     As of GNU find version 3.6, you can use the locate program 'as is'.
  46.     For version 3.5, change GNUFIND in the Makefile to designate where
  47.     your GNU find sourcetree is, and issue "make ixlookup".
  48.     This will build a customized version of GNU locate, called
  49.     "ixlookup".
  50.  
  51.     Issue "make listener" to generate and compile the listener
  52.     program. This command uses mserv_config.pl (from the current
  53.     directory) to determine how to build the listener program.
  54.  
  55.  3. Installation
  56.  
  57.     Now "su mserv" and execute "make install".
  58.  
  59.     This will install all programs and files in LIBDIR.
  60.     It will not install programs ixlookup and listener, since they
  61.     need special treatment.
  62.  
  63.     If you select the index file feature, issue "make install-ixlookup"
  64.     if you need the customized version of GNU locate 3.5. 
  65.     Note that whoever creates the index files, must have write access
  66.     to the location the index files are stored.
  67.  
  68.     If you configured the listener to use the setruid/setrgid system
  69.     calls, you need to "su mserv" before executing "make
  70.     install-listener".
  71.  
  72.     If you do not have setruid/setrgid, the program must be installed
  73.     setuid root.  In this case, you have to "su root" before doing
  74.     "make install-listener".  Look at the source of the listener.c
  75.     program to verify it will not harm your system security.
  76.  
  77.  4. Adding aliases
  78.  
  79.     Create a suitable alias in /usr/lib/aliases (or wherever your
  80.     aliases are kept):
  81.  
  82.       mail-server : "|LIBDIR/listener"
  83.  
  84.     To get rid of bounced mail, the mail server fakes "bit-bucket" as
  85.     its return address. To avoid bounced mails filling your
  86.     filesystems, add another alias:
  87.  
  88.       bit-bucket: /dev/null
  89.  
  90.  5. Verification of the installation
  91.  
  92.     All the following steps should be executed under the mail server
  93.     owner!
  94.  
  95.     * Run program LIBDIR/chkconfig. It shows most of the
  96.       configuration values, and verifies the existence of files and
  97.       programs.
  98.  
  99.       You may need to run the perl tool "h2ph" to supply system
  100.       include files needed for locking.
  101.  
  102.     * Verify your locking strategy. Execute
  103.      
  104.         % perl -s testlock.pl -test1 &
  105.      
  106.       It should say "Got the lock -- waiting ...".
  107.       Now execute
  108.      
  109.         % perl -s testlock.pl -test2 &
  110.      
  111.       It should say "Good. Could not lock -- waiting ...".
  112.       Now kill the first process. The second process should print "ret = 1" 
  113.       and exit.
  114.  
  115.     * Verify the working of the "dorequest" program:
  116.  
  117.         % LIBDIR/dorequest <youraddress> <arealfile>
  118.  
  119.       You should receive mail(s) containing the indicated file.
  120.       NOTE: If your site is running sendmail, the mail(s) are queued
  121.       for delivery. They can take some time before they arrive,
  122.       depoending on how often the sendmail queue is run.
  123.       You may want to inspect the sendmail queue to see if your
  124.       mail(s) are in it.
  125.  
  126.       If no mail(s) arrive, try
  127.  
  128.         % LIBDIR/dorequest -debug <youraddress> <arealfile>
  129.  
  130.       and see what happens.
  131.  
  132.     * Execute the "process" script by hand:
  133.  
  134.         % LIBDIR/process
  135.         From bla
  136.         From: <youraddress>
  137.  
  138.         test
  139.         send HELP
  140.         end
  141.  
  142.       (The program should terminate after processing the "end"
  143.       command). 
  144.       Now you should receive a mail (from yourself!) telling that your
  145.       request has been processed.
  146.       NOTE: If your site is running sendmail, and sendmail is
  147.       configured to use 'queued' delivery, the mail(s) are not
  148.       delivered immediately.
  149.       You may want to inspect the sendmail queue to see if your
  150.       mail is in it, or run the queue by hand.
  151.  
  152.       In case of trouble: run LIBDIR/process with "-debug" to find out
  153.       what happens.
  154.  
  155.     * Execute the "process" script again with the same input, but
  156.       leave out the line "test".
  157.  
  158.       Again you should receive a mail (from yourself!) telling that your
  159.       request has been processed. It should also tell you that your
  160.       request has been queued.
  161.  
  162.       If you configured $auto_runrequest, program "dorequest" will be
  163.       run to handle your request. You should receive a mail with the
  164.       requested file.
  165.  
  166.       In case of trouble: run LIBDIR/process with "-debug" to find out
  167.       what happens. This will prevent "dorequest" from being invoked,
  168.       so you can study the contents of LIBDIR/queue.
  169.  
  170.     * Execute the "listener" program with the same input.
  171.  
  172.       Again you should receive a mail message.
  173.  
  174.       If you configured $auto_runrequest, program "dorequest" will be
  175.       run to handle your request. You should receive a mail with the
  176.       requested file.
  177.  
  178.     * As another user, run the "listener" program with the same input.
  179.  
  180.       Again you should receive a mail, still originating from the
  181.       mail server owner.
  182.  
  183.     * Still going strong? Now, as another user, send a mail message to
  184.       your mail server:
  185.  
  186.       % mail mail-server
  187.       send foo bar INDEX
  188.       end
  189.       ^D
  190.  
  191.       (Mail programs usually do not terminate after reading the "end"
  192.       line. Issue Control-D or whatever you local EndOfFile setting is). 
  193.       
  194.       You will receive a return mail, indicating which archive entries
  195.       were found, and how they would be transmitted.
  196.  
  197.     * If you did not configure $auto_runrequest, change back to the
  198.       mail server user, and inspect LIBDIR/queue to see that your
  199.       request is in it.
  200.       Run LIBDIR/dorequest without arguments; the selected file should
  201.       be sent to you by email.
  202.  
  203.     If you receive the requests, your mail server is fully
  204.     operational! 
  205.  
  206.  6. If you don't want to keep of log of transactions, remove the file
  207.     "LIBDIR/logfile" that was created by the Makefile.
  208.  
  209.  7. As a service: place the files "HELP" and "unpack.pl" in one of
  210.     your archives. The Makefile prepares PUBDIR (defaults to
  211.     LIBDIR/pub) for this purpose.
  212.  
  213.     Also, supply shar-files with the btoa/atob handling
  214.     programs, uudecode/uuencode, and compress/uncompress.
  215.  
  216.     The contents of file LIBDIR/mserv.notes is prepended to every
  217.     reply the mail server sends. This file can be used to supply a
  218.     daily message about the server, new entries, etc.
  219.  
  220.     The contents of file LIBDIR/mserv.hints is appended to every reply
  221.     the mail server sends.
  222.  
  223.     Make sure your archives have a decent copy of Dumas uud/uue and
  224.     xxencode/xxdecode if you intent to support these.
  225.     Likewise, zoo, zip, etc.
  226.  
  227.     Also, provide a file "INDEX" that more or less describes what is
  228.     in your archives. People are going to ask for it.
  229.  
  230.     Since people usually don't read the documentation, link "help" to
  231.     "HELP", "index" to "INDEX", "atob.shar" to "btoa.shar", etc.
  232.  
  233.  8. Install crontab entries for the mail server processes. A sample
  234.     crontab is included in the distribution as CRONTAB.sample.
  235.  
  236.     30 0,2,4,6,18,20,22 * * * LIBDIR/do_runq
  237.     0 3 * * * LIBDIR/makeindex
  238.     0 7 * * * LIBDIR/do_report -errors -since .errrun
  239.     10 7 * * 7 LIBDIR/do_report -full -collect
  240.  
  241.     The above example runs the mail server queue every two hours,
  242.     except during working hours. Once a day any mail server errors are
  243.     reported, once a week the logfile data is accumulated and a usage
  244.     report is generated.
  245.  
  246.     CHECK AND MODIFY THESE SCRIPTS SINCE THEY WILL PROBABLY NOT
  247.     DO WHAT YOU WANT!
  248.  
  249.     Every night a three o'clock new index files are generated. You may
  250.     leave this line out if you do not use index files.
  251.  
  252.     If you configured auto_runrequest in mserv_common.pl, there is no
  253.     need to run the queue that often; once or twice a day will be
  254.     sufficient.
  255.  
  256. Interaction of programs
  257. =======================
  258.  
  259. An email message directed to the mail server will be passed to program
  260. `listener'. This program disguises itself as the mail server owner and
  261. executes `process'.
  262.  
  263. `process' parses the mail message, and extracts commands. Requests are
  264. looked up, and --if viable-- written to the mail server queue.
  265.  
  266. Some other time, `dorequest' will be run, either automatically from
  267. `process' or via cron. This program will lock the queue and read all
  268. entries from it. It will also read any pending entries in queue~. Then
  269. it will empty the queue and release it.  Next, it will handle all
  270. entries it has read. Before handling a request, all in-core entries
  271. are written to file queue~ just in case the system goes down.
  272. Upon completion of a request, a logfile entry is written and the
  273. request is removed from memory. Upon sucessful completion of
  274. `dorequest' the file queue~ will be removed.
  275.  
  276. Each queue entry takes one record from the queue file, with space
  277. separated files as follows:
  278.  
  279.   type        M for email, U for UUCP transfer, MP for packed email,
  280.         UP for packed UUCP.
  281.   recipient    the reply address used
  282.   destination    (type M* only): email address
  283.   host!path    (type U* only) UUCP host and path
  284.   notify    (type U* only) UUCP notification user
  285.   request    the request
  286.   file        the name of the file
  287.   encoding    (type M* only) encoding (B = btoa, U = uuencode, X = xxencode,
  288.             D = Dumas' uue)
  289.   limit        max size (in Kb) per chunk
  290.   parts        comma-separated parts list.
  291.  
  292. Logging
  293. =======
  294.  
  295. If you select logging, all transfers that are sent are logged in the
  296. logfile. Each record has a number of (space separated) fields as
  297. follows:
  298.  
  299.   date        e.g. 920501
  300.   time        e.g. 15:22
  301.   type        M for email, U for UUCP transfer
  302.   destination    email address, or host!notify for UUCP transfers
  303.   request    the name of the requested file
  304.   Xnn/mm    X = encoding (B = btoa, U = uuencode, X = xxencode,
  305.             D = Dumas' uue)
  306.             Note: no encoding is specfied for UUCP transfers.
  307.           nn/mm = part nn of mm parts
  308.   size        the size of the transfer
  309.  
  310. The programs report.pl and do_report.pl can be used to generate
  311. reports from the logfile.
  312.  
  313. Errors are logged with type `F'. The remainder of the record contains
  314. the error message. 
  315. If an error is detected due to a user request, the queue entry for
  316. this request is entered in the logfile with type `Q'.
  317. If the failure is temporary, the queue entry can be extracted from the
  318. logfile and added to the queue (or better: queue~) file.
  319.  
  320. do_report.pl can also be used to cleanup the logfile.
  321.  
  322. Design and Maintenance of the Archives
  323. ======================================
  324.  
  325. The mail server software can handle multiple archive directories.
  326. Every directory specified in @libdirs is treated equal.
  327.  
  328. Please consider the following points:
  329.  
  330.  - Hidden files (filenames starting with `.') and files that are not
  331.    readable to `mserv' cannot be retrieved. They might show in the
  332.    index, however.
  333.  
  334.  - If a file occurs multiple (e.g. "INDEX" in more than one archive
  335.    directory) the first occurrence is retrieved.
  336.  
  337.  - If a directory occurs multiple it can not be retrieved.
  338.  
  339.  - For best results: name archives similar to "foo-XXX.tar.Z", where
  340.    XXX is a version number, e.g. emacs-18.58.tar.Z or xdvi-12.zoo.
  341.    This will aid people in finding the right version for a specific
  342.    archive entry.
  343.  
  344. Please share your experiences and programs.
  345.  
  346. Good Luck!
  347.  
  348.     Johan Vromans
  349.     Multihouse Research
  350.     Doesburgweg 7
  351.     2803 PL  Gouda
  352.     The Netherlands
  353.     Phone: +31 1820 62911
  354.     E-mail: jv@mh.nl
  355.