home *** CD-ROM | disk | FTP | other *** search
/ NetNews Usenet Archive 1993 #1 / NN_1993_1.iso / spool / comp / sources / misc / 4234 < prev    next >
Encoding:
Text File  |  1993-01-06  |  59.7 KB  |  1,467 lines

  1. Newsgroups: comp.sources.misc
  2. Path: sparky!kent
  3. From: jv@squirrel.mh.nl (Johan Vromans)
  4. Subject: v34i092:  mserv - Squirrel Mail Server Software, version 3.1, Part01/06
  5. Message-ID: <csm-v34i092=mserv.214515@sparky.IMD.Sterling.COM>
  6. Followup-To: comp.sources.d
  7. X-Md4-Signature: 5647340cf8757daf64d577eb8f52762a
  8. Sender: kent@sparky.imd.sterling.com (Kent Landfield)
  9. Organization: Sterling Software
  10. Date: Thu, 7 Jan 1993 03:46:09 GMT
  11. Approved: kent@sparky.imd.sterling.com
  12. Lines: 1453
  13.  
  14. Submitted-by: jv@squirrel.mh.nl (Johan Vromans)
  15. Posting-number: Volume 34, Issue 92
  16. Archive-name: mserv/part01
  17. Environment: Perl
  18. Supersedes: mserv-3.0: Volume 30, Issue 46-49
  19.  
  20.     Announcing: Squirrel Mail Server Software, version 3.1
  21.     ======================================================
  22.  
  23.  For the user:
  24.  -------------
  25. The Squirrel Mail Server is a mail response program. You can send
  26. email to it, and it will try to react sensible to your message.
  27.  
  28. Main purpose of the mail server is to obtain files from a local
  29. archive or FTP servers. It is also possible to search for files and to
  30. generate directory listings. A powerful index mechanism obsoletes the
  31. need to transfer huge "ls-lR" files.
  32.  
  33. While looking for files, the server knows about commonly used
  34. extensions to filenames (e.g. ".tar.Z" in "foo.tar.Z") and pseudo-
  35. standard version numbering (e.g. "gcc-2.1.tar.Z").  It is quite well
  36. possible that a simple request for "emacs" will actually transmit the
  37. file "gnu/emacs-18/dist/emacs-18.59.tar.Z".
  38.  
  39. Delivery of information can take place via email or UUCP or both.
  40. Files are compressed if possible, encoded if necessary, and split into
  41. pieces if needed. If a transfer fails, it it always possible to
  42. request retransmission of the failed parts only.
  43.  
  44.  For the implementor:
  45.  --------------------
  46. All written in perl, hence portable and easily maintainable.  Code is
  47. readable; useful, plentiful comments. Very extentable and easily
  48. modified. Easy to install. Over 2000 lines of documentation.
  49.  
  50. Archives can be split over a number of directories or file systems.
  51.  
  52. Requests are queued and processed by a separate daemon process (e.g.
  53. from cron) to cut down on the system load. Moreover, the implementor
  54. can control when the queue is being run.
  55.  
  56. All transfers are logged. Maintenance procedures include a reporting
  57. tool.
  58.  
  59. Files retrieved via FTP are kept on local store for some time, so
  60. subsequent requests can be honoured from the cache.
  61.  
  62.  Requirements:
  63.  -------------
  64. Perl 4.0 patchlevel 35 or later.
  65. NOTE that perl 4.0 pl35 contains a bug that can be fixed by an
  66. (unofficial) patch obtainable from the NLUUG mail server -- see below.
  67.  
  68. GNU find 3.6 or later (only if you want to exploit the index
  69. features).
  70.  
  71. A decent mail system that can deliver mail to a process (sendmail,
  72. smail3, or smail2.5 w/ mods).
  73.  
  74. Common tools like compress, zoo, zip, uuencode etc.
  75.  
  76.  How to get it:
  77.  --------------
  78. Send a mail message to <mail-server@nluug.nl> with contents
  79.  
  80.     begin
  81.     send mserv-3.1.tar.Z
  82.     send XPatch-4.035.tar.Z
  83.     end
  84.  
  85. The latter file contains some unofficial patches to perl 4.0
  86. patchlevel 35.
  87.  
  88. Also available are nicely formatted PostScript versions of the 
  89. User Guide and Installation Guide:
  90.  
  91.     send usrguide.ps.Z
  92.     send mservmgr.ps.Z
  93.  
  94. The Squirrel Mail Server Software is 
  95.  
  96.     Copyright 1988,1992,1993 Johan Vromans.
  97.  
  98. It is distributed under the terms of the GNU Public Licence.
  99.  
  100. For more information: Johan Vromans <jv@mh.nl> .
  101. ----------------------------------------------------------
  102. #! /bin/sh
  103. # This is a shell archive.  Remove anything before this line, then feed it
  104. # into a shell via "sh file" or similar.  To overwrite existing files,
  105. # type "sh file -c".
  106. # Contents:  mserv-3.1 mserv-3.1/INSTALL mserv-3.1/dateconv.pl
  107. # Wrapped by kent@sparky on Wed Jan  6 21:39:45 1993
  108. PATH=/bin:/usr/bin:/usr/ucb:/usr/local/bin:/usr/lbin ; export PATH
  109. echo If this archive is complete, you will see the following message:
  110. echo '          "shar: End of archive 1 (of 6)."'
  111. if test ! -d 'mserv-3.1' ; then
  112.     echo shar: Creating directory \"'mserv-3.1'\"
  113.     mkdir 'mserv-3.1'
  114. fi
  115. if test -f 'mserv-3.1/INSTALL' -a "${1}" != "-c" ; then 
  116.   echo shar: Will not clobber existing file \"'mserv-3.1/INSTALL'\"
  117. else
  118.   echo shar: Extracting \"'mserv-3.1/INSTALL'\" \(52619 characters\)
  119.   sed "s/^X//" >'mserv-3.1/INSTALL' <<'END_OF_FILE'
  120. XAuthor:     Johan Vromans 
  121. XCmpny:      SQS 
  122. XCompany:    Squirrel Software 
  123. XDept.:      Public Domain 
  124. XProject:    Squirrel Mail Server 
  125. XTitle:      Squirrel Mail Server
  126. X            Installation and Maintenance 
  127. XVersion:    V3.01 
  128. X----------------------------------------
  129. X
  130. X1.    INTRODUCTION 
  131. X
  132. X1.1   The Mail Server 
  133. X
  134. X      The mail server is a mail response program. This means that you 
  135. X      can send it an email message, and the program will read this 
  136. X      message, extracts commands from it, and execute these commands if 
  137. X      no errors were encountered. 
  138. X
  139. X      The main purpose of the mail server is to handle requests for 
  140. X      files in archives. By sending a request for a file, the mail 
  141. X      server will look it up and send the requested file to the 
  142. X      originator of the request, either via email or via UUCP. 
  143. X
  144. X      When files are transferred via email, binary files (e.g. 
  145. X      compressed archives) are encoded using one of several popular 
  146. X      encoding schemes. Big files are split into pieces to avoid mailer 
  147. X      limits and transmission failures due to communication problems. 
  148. X
  149. X      The algoritms of the mail server are designed to satisfy user 
  150. X      requests as much as possible, without taking the risk that 
  151. X      unwanted information is sent. 
  152. X
  153. X1.2   Mail Server Basics 
  154. X
  155. X      The Squirrel Mail Server Software consists of a set of perl 
  156. X      programs, data files and a small wrapper program. The installation 
  157. X      procedure prepares these files, and stores them at a specific 
  158. X      location on disk, hereafter named LIBDIR. LIBDIR and the files it 
  159. X      contains should be owned by the so called 'mail server owner'. 
  160. X
  161. X      The mail server itself is driven via an email alias entry in the 
  162. X      file '/usr/lib/aliases' (or whatever your system uses). 
  163. X
  164. X      Default values are 'mserv' for the mail server owner, 
  165. X      'mail-server' for the mail alias, and '/usr/local/lib/mserv' for 
  166. X      LIBDIR. Al these (and more) can be configured for a particular 
  167. X      installation. 
  168. X
  169. X2.    PRINCIPLES OF OPERATION 
  170. X
  171. X      The main functions of the mail server are executed by the programs 
  172. X      'process' and 'dorequest'. 
  173. X
  174. X      A third program 'listener' is usually used as a wrapper around 
  175. X      'process'. This little C-program disguises itself as the mail 
  176. X      server owner and executes 'process'. 
  177. X
  178. X      The program 'process' reads an incoming email message, scans the 
  179. X      mail headers and examines the message body for mail server 
  180. X      commands. Valid server commands are stored internally until the 
  181. X      whole message has been read. If any errors were found, a short 
  182. X      help message is sent back to the sender of the message, and the 
  183. X      program quits. 
  184. X
  185. X      If desired, messages originating from a pre-defined list of users 
  186. X      may be rejected without notice. The standard configuration defines 
  187. X      @black_list to a list of system accounts, e.g. 'root', 'news', 
  188. X      'daemon' etc. 
  189. X
  190. X      If all commands appear valid, 'process' enters the second phase. 
  191. X      The commands are executed one by one. If files are requested 
  192. X      (which is normally the case) the files are looked up in the mail 
  193. X      server archives, using one or more search techniques discussed 
  194. X      below. If the file has been located, it is queued for delivery in 
  195. X      the mail server queue file. 
  196. X
  197. X      If files are requested from remote FTP servers, a connection to 
  198. X      the server is made and the files are transferred to local storage. 
  199. X      The local copy of the file is then entered in the mail server 
  200. X      queue for delivery. 
  201. X
  202. X      Finally, the program generates a report and sends it to the sender 
  203. X      of the message. This report contains (a.o.) details about the FTP 
  204. X      activities, and a list of files that are queued for delivery. 
  205. X
  206. X      At this point 'process' is complete and exits. 
  207. X
  208. X      Some other time, program 'dorequest' will be run, either 
  209. X      automatically from 'process' or via cron. This program handles the 
  210. X      actual delivery of files. It is also responsible for packing 
  211. X      directories and removing temporary files. 
  212. X
  213. X      For delivery via electronic mail, the requested file is (usually) 
  214. X      encoded to protect binary information from text-based mail 
  215. X      programs. The encoded file is chopped into parts (chunks) of a 
  216. X      specific maximum size, to not exceed mailer limits. The parts are 
  217. X      then passed to the mail program for delivery. If only some parts 
  218. X      need to be delivered, only these parts are passed to the mail 
  219. X      program. 
  220. X
  221. X      For delivery via UUCP there is no need to encode, so the actual 
  222. X      input file is passed, in pieces if necessary, to the delivery 
  223. X      program 'uucp'. 
  224. X
  225. X      An entry is made in the mail server logfile for each (partial) 
  226. X      delivery. 
  227. X
  228. X2.1   Format of the queue file 
  229. X
  230. X      Each queue entry takes one record from the queue file, with tab 
  231. X      separated items as follows: 
  232. X
  233. X         type           'M' or 'm' for email delivery,
  234. X                        'U' or 'u' for UUCP transfer,
  235. X                        'MP' for packed email,
  236. X                        'UP' for packed UUCP.
  237. X                        If the 'm' or 'u' is used instead of 'M' or
  238. X                        'U', the file is removed after being handled.
  239. X         recipient      the reply address used
  240. X         destination    email address (for email), or host!path for UUCP
  241. X                        transfers.
  242. X         notify         UUCP notification user
  243. X         request        the request
  244. X         file           the real name of the real file
  245. X         encoding       Encoding:
  246. X                        'B' = btoa, 'U' = uuencode, 'X' = xxencode,
  247. X                        'D' = Dumas' uue
  248. X                        If a 'Z' is appended, the file will be compressed
  249. X                        before being transferred.
  250. X         limit          max size (in Kb) per chunk
  251. X         parts          comma-separated parts list.
  252. X
  253. X2.2   Format of the logfile 
  254. X
  255. X      If you select logging, all transfers that are sent are logged in 
  256. X      the logfile. Each record has a number of (space separated) fields 
  257. X      as follows: 
  258. X
  259. X         date           e.g. 920501
  260. X         time           e.g. 15:22
  261. X         type           'M' for email, 'U' for UUCP transfer
  262. X         destination    email address, or host!notify for UUCP transfers
  263. X         request        the name of the requested file
  264. X         Xnn/mm         X = encoding;
  265. X                        nn/mm = part nn of mm parts
  266. X         size           the size of the transfer
  267. X
  268. X      Errors are logged with type 'F'. The remainder of the record 
  269. X      contains the text of the error message. 
  270. X
  271. X      If an error is detected due to a user request, the queue entry for 
  272. X      this request is entered in the logfile with type 'Q'. If the 
  273. X      failure is temporary, the queue entry can be extracted from the 
  274. X      logfile and added to the queue (or better: queue~) file. 
  275. X
  276. X      The support programs programs 'report.pl' and 'do_report.pl' can 
  277. X      be used to generate reports from the logfile. 
  278. X
  279. X3.    IMPLEMENTATION DETAILS 
  280. X
  281. X      Program 'process' uses the package 'rfc822' to read the incoming 
  282. X      mail message. This package supports reading header and body of the 
  283. X      message, and analyzing RFC822 compliant message headers. 
  284. X
  285. X      One of the functions of the package is to extract the send 
  286. X      information from the 'From', 'Sender' and 'Reply-To' headers. 
  287. X
  288. X      The commands are parsed by subroutine 'command_loop'. The command 
  289. X      handling is table driven, %cmd_tbl contains, for each of the 
  290. X      command verbs, the name of the subroutine to be called to parse 
  291. X      the command. 
  292. X
  293. X      Upon completion subroutine 'index_loop' (required from file 
  294. X      pr_doindex.pl) is called to handle index requests stored 
  295. X      internally in @indexq. 
  296. X
  297. X      Then subroutine 'search_loop' is called to handle search requests 
  298. X      stored in @searchq. 
  299. X
  300. X      If needed, subroutine 'do_work' (required from file pr_dowork.pl) 
  301. X      is called to handle the commands stored internally in @workq. This 
  302. X      will probably result in transfer requests being stored in @queueq. 
  303. X
  304. X      Processing @workq is table driven, just like the command loop. 
  305. X      Therefore is it very easy to add your own commands (and execution 
  306. X      code) to the mail server program without having to modify the 
  307. X      source code. See chapter "Advanced Techniques" for more 
  308. X      information. 
  309. X
  310. X      If @queueq contains transfer requests, these requests are reported 
  311. X      and stored in the queue file for processing by program 
  312. X      'dorequest'. 
  313. X
  314. X      Finally, a help message is generated on demand, or if syntactic 
  315. X      errors were detected by 'command_loop'. 
  316. X
  317. X3.1   Archive file lookup 
  318. X
  319. X      One of the advantages of the Squirrel Mail Server is the 
  320. X      possibility to spread the archives over a number of file trees. 
  321. X      Another advantage is the ability to search for files in the 
  322. X      archives, using file- and directory searches and index lookup. 
  323. X      While searching, a number of known extensions are appended to the 
  324. X      filename so that a request for 'foo' might result in finding 
  325. X      'foo.Z' or 'foo.tar'. 
  326. X
  327. X      The general principle of searching is: 
  328. X
  329. X      -- Use file lookup;
  330. X      -- if not found; use directory search;
  331. X      -- if still not found: search the index;
  332. X      -- unsuccessfull, or multiple possibilities were found,
  333. X         try automatic packing;
  334. X      -- if still unsuccessfull, try automatic compression.
  335. X
  336. X      When a SEARCH command is issued, all alternatives are tried and a 
  337. X      list of possibilities is returned. 
  338. X
  339. X3.1.1 File search strategy 
  340. X
  341. X      This strategy is rather straightforward: for each of the archive 
  342. X      directories, try to locate the requested file by appending the 
  343. X      known extensions. E.g. when looking for 'file': 
  344. X
  345. X            dir1/file
  346. X            dir1/file.tar
  347. X            dir1/file.tar.Z
  348. X            ...
  349. X            dir2/file
  350. X            dir2/file.tar
  351. X            ... etc ...
  352. X
  353. X      If an exact match is found, the search within the directory is 
  354. X      terminated. This way it is possible to locate 'foo' even if 
  355. X      'foo.tar' also exists. 
  356. X
  357. X3.1.2 Directory search strategy 
  358. X
  359. X      The directory search extends the file search. The code is located 
  360. X      in file 'pr_dsearch.pl'. 
  361. X
  362. X      It reads the directories that are specified in @libdirs, and 
  363. X      searches them for entries that correspond to certain patterns. In 
  364. X      general, it looks for filenames that start with the search 
  365. X      argument, optionally followed by something that can be interpreted 
  366. X      as a version number. If such a filename is found, and it 
  367. X      corresponds to a directory, the search recurses to this directory. 
  368. X      If not, the known extensions are tried. 
  369. X
  370. X      E.g. when looking for 'file': 
  371. X
  372. X            dir1/file-2.3.tar.Z              <-- found
  373. X            dir1/file/                       <-- recurse
  374. X            dir1/file/file-2.3.tar.Z         <-- found
  375. X            dir1/file-2.3/                   <-- recurse
  376. X            dir1/file-2.3/file.tar.Z         <-- found
  377. X            dir1/file-2.3/file-2.3.tar.Z     <-- found
  378. X            ...
  379. X
  380. X      This process is repeated for every directory in @libdirs. 
  381. X
  382. X3.1.3 Index search strategy 
  383. X
  384. X      The final (and most powerful) search strategy uses a list of 
  385. X      filenames, and searches for every occurrence of the search 
  386. X      argument. The code is located in file 'pr_isearch.pl'. 
  387. X
  388. X      The index strategy is based on the GNU 'locate' program. This 
  389. X      program provides an extreme fast searching method in a compressed 
  390. X      list of files. 
  391. X
  392. X      When searching the index, the search argument is turned into a 
  393. X      regular expression pattern and passed to the 'locate' program. The 
  394. X      output of this program is further analyzed to find filenames using 
  395. X      the same method as described above (version numbers and known 
  396. X      extensions). 
  397. X
  398. X      For efficiency, the 'locate' database contains the file date and 
  399. X      size, so no other lookups are needed. 
  400. X
  401. X      It is possible to have an index file per archive directory 
  402. X      (default situation), or one single index file that contains 
  403. X      information for all archive directories. 
  404. X
  405. X      The index information is maintained by the program 'makeindex'. 
  406. X      This program uses GNU 'find' to traverse the archive directories, 
  407. X      and GNU 'locate' tools to create the index files. 
  408. X
  409. X3.1.4 Automatic Packing 
  410. X
  411. X      This section only applies if $auto_packing and $packing_limit have 
  412. X      been set in the configuration file. 
  413. X
  414. X      If the user requests for 'file.XXX', where XXX is a known packing 
  415. X      extension ('zip', 'zoo', 'tar' or 'tar.Z'), and this file does not 
  416. X      exist, automatic packing is tried. 
  417. X
  418. X      The packing extension is removed from the filename. If the 
  419. X      resultant name points to a directory it is handled as if the 
  420. X      request were preceeded with a PACK command. See also the section 
  421. X      on Packing, below. 
  422. X
  423. X      No search strategies will be used when locating this directory. 
  424. X
  425. X3.1.5 Automatic Compression 
  426. X
  427. X      This section only applies if $auto_compress and $compress have 
  428. X      been set in the configuration file. 
  429. X
  430. X      If the user requests for a file 'foo.Z', which does not exist, but 
  431. X      a file 'foo' exists in the archives, this file is queued for 
  432. X      delivery. Before transfer, it will be compressed. 
  433. X
  434. X      The strategies file search, directory search and index search will 
  435. X      be used when locating this file. Normally, no known extensions are 
  436. X      tried. By setting $auto_compress to a value greater than 1 in the 
  437. X      config file, known extensions will be tried, so that a request for 
  438. X      'file.Z' may result in 'file.shar.Z' (or 'file.zoo.Z'). 
  439. X
  440. X3.2   FTP file lookup 
  441. X
  442. X      The Squirrel Mail Server uses a cached FTP lookup mechanism. The 
  443. X      code is located in file 'pr_ftp.pl'. 
  444. X
  445. X      When a request for a file to be retrieved via FTP is handled, the 
  446. X      mail server performs the following steps. 
  447. X
  448. X      1. A connection is made to the FTP host. 
  449. X
  450. X      2. A directory request (LIST command) is used to retrieve 
  451. X         information about the file that is being requested. 
  452. X
  453. X      3. The file is looked up in the FTP cache. If the file exists in 
  454. X         the cache, the file modification date and size are compared to 
  455. X         the FTP information from the FTP host. 
  456. X
  457. X      4. If the file is not in the cache, or if the info does not match, 
  458. X         the file is retrieved from the FTP host and placed in the 
  459. X         cache. 
  460. X
  461. X      5. The file in the cache is queued for delivery. 
  462. X
  463. X      This caching strategy is based on the assumption that, when a 
  464. X      piece of interesting software is made available via anonymous FTP 
  465. X      and announced on the net, several requests for this file will be 
  466. X      made within a short period of time. 
  467. X
  468. X      Special precautions are taken to prevent problems when the cache 
  469. X      does not exists, or is write-protected, etc. In this case, the 
  470. X      file is retrieved to temporary storage and transferred from there. 
  471. X
  472. X      The filenames for the cache are generated by reversing the 
  473. X      dot-separated parts of the FTP host name, and prepending these (as 
  474. X      directories) to the file name, e.g. 
  475. X
  476. X            prep.ai.mit.edu:/pub/gnu/emacs-18.59.tar.Z
  477. X
  478. X      is stored in the cache as 
  479. X
  480. X            edu/mit/ai/prep/gnu/emacs-18.59.tar.Z
  481. X
  482. X      A leading directory "pub" is removed from the resultant filename. 
  483. X      The host info is transformed to all lowercase; the filename is 
  484. X      not. 
  485. X
  486. X      NOTE:  VMS style filenames are recognized and transformed. The
  487. X             resultant filename is lowcased.
  488. X             VMS directory info is not handled yet.
  489. X
  490. X3.3   Directory listings 
  491. X
  492. X      Directory listings are obtained from the server using a local 
  493. X      "ls -l" command or an FTP "LIST" command, the return info is 
  494. X      stored in a temporary file. If the size of this file does not 
  495. X      exceed a specific limit ($fb_limit) it is included in the output. 
  496. X      Otherwise it is queued for delivery. 
  497. X
  498. X3.4   Archie commands 
  499. X
  500. X      Archie commands are handled by executing the 'archie' program. The 
  501. X      output is stored in a temporary file. If the size of this file 
  502. X      does not exceed a specific limit ($fb_limit) it is included in the 
  503. X      output. Otherwise it is queued for delivery. 
  504. X
  505. X3.5   Packing 
  506. X
  507. X      With packing, it is possible to gather the contents of a directory 
  508. X      into a single file, which is then queued for transfer. Before 
  509. X      doing so, the size of the resultant file is calculated. If the 
  510. X      size exceeds a specific limit ($packing_limit) the request is 
  511. X      rejected, to prevent accidental (or not accidental) retrieval of 
  512. X      too much information. 
  513. X
  514. X      The name of the directory is stored in the queue file, the actual 
  515. X      packing and delivery is handled by the 'dorequest' program. 
  516. X
  517. X3.6   The delivery process 
  518. X
  519. X      Upon completion of 'process' all files to be transferred are 
  520. X      stored somewhere on disk, and their names and destinations are in 
  521. X      the queue file. 
  522. X
  523. X      The delivery is handled by program 'dorequest'. It can be run 
  524. X      automatically from 'process', from 'cron' or manually. 
  525. X
  526. X      Upon invokation, it ensures that there is only one instance of the 
  527. X      program running. Then it locks the mail server queue, reads it 
  528. X      into internal storage, writes it out to a special backup version 
  529. X      on disk, empties the queue on disk and releases it. The queue file 
  530. X      is not simply removed, since other instances of 'process' may 
  531. X      already be waiting to store new entries in the queue file. 
  532. X      (Actually, 'dorequest' picks up an existing backup on disk first, 
  533. X      since that file results from a previous run of 'dorequest' that 
  534. X      was not properly finished, most likely due to a system crash.) The 
  535. X      backup file is hereafter referred to with 'queue~', since its name 
  536. X      is dereived from the name of the queue file by appending a tilde. 
  537. X
  538. X      Next, the program starts to handle the entries that were in the 
  539. X      queue. First the internal copy of the queue is written to the 
  540. X      queue~ file. Then an entry is taken from the internal queue, to be 
  541. X      handled. This way, if the system crashes during a 'dorequest' run, 
  542. X      no requests will get lost. 
  543. X
  544. X      If the request needs packing, the contents of the directory are 
  545. X      stored into a single file, which is then queued for transfer. 
  546. X
  547. X      The following packing methods are supported by the mail server, 
  548. X      although they need not be present in each implementation. 
  549. X
  550. X      *  (Compressed) tar 
  551. X
  552. X         The contents of the directory are gathered into a tar-file, 
  553. X         which is then compressed. If the public domain program 'pdtar' 
  554. X         is available, it is ised to handle the packing and compressing. 
  555. X         Otherwise the output of 'tar' is piped to 'compress'. 
  556. X
  557. X      *  Zoo 
  558. X
  559. X         The popular 'zoo' program is used, in combination with 'find', 
  560. X         to gather the information. 
  561. X
  562. X      *  Zip 
  563. X
  564. X         The INFO-ZIP standard 'zip' program is used to handle the 
  565. X         request. 
  566. X
  567. X      If the requested file must be compressed, this is handled now. The 
  568. X      file is compressed into a temporary file which is further 
  569. X      processed. If the file to be transferred was a temporary file, it 
  570. X      is removed. The (freshly created) temporary file is marked for 
  571. X      deletion so it will be removed upon completion of this request. 
  572. X
  573. X      For delivery via electronic mail, the requested file is (usually) 
  574. X      encoded to protect binary information from text-based mail 
  575. X      programs. The encoded file is chopped into parts (chunks) of a 
  576. X      specific maximum size, to not exceed mailer limits. The parts are 
  577. X      then passed to the mail program for delivery. If only some parts 
  578. X      need to be delivered, only these parts are passed to the mail 
  579. X      program. To reduce system load, the 'dorequest' program sleeps a 
  580. X      bit between parts so the mail delivery can take place. 
  581. X
  582. X      For delivery via UUCP there is no need to encode, so the actual 
  583. X      input file is passed, in pieces if necessary, to the delivery 
  584. X      program 'uucp'. 
  585. X
  586. X      An entry is made in the mail server logfile for each (partial) 
  587. X      delivery. 
  588. X
  589. X      Finally, if the file to be transferred was a temporary file, it is 
  590. X      removed and processing continues with the next entry in the queue. 
  591. X
  592. X      Upon completion, the backup of the queue file (queue~) on disk 
  593. X      will be removed. 
  594. X
  595. X4.    SUPPORT PROGRAMS 
  596. X
  597. X4.1   Generating the index files 
  598. X
  599. X      The program 'makeindex', as its name suggests, maintains the index 
  600. X      information. It is based on the 'updatedb' program that comes with 
  601. X      GNU find. 
  602. X
  603. X      The program should be run from cron, as often as needed to keep 
  604. X      the index file synchronized with the actual contents of the 
  605. X      archives. Usually once per day (night) is sufficient. 
  606. X
  607. X      Sometimes it is not appropriate to include all information in the 
  608. X      index file, e.g. a specific sub-tree might contain your local news 
  609. X      spool which is not to be retrieved via the mail server. You can 
  610. X      set @libprunes in the configuration file to a regular expression 
  611. X      pattern to exclude certain directories from being traversed. Note 
  612. X      that this pattern is implicitly anchored, i.e. it behaves as if it 
  613. X      were placed between '^' and '$'. @libprunes, if used, should 
  614. X      contain a pattern for each of the directories in @libdirs, in the 
  615. X      same order. 
  616. X
  617. X4.2   Analyzing the log file 
  618. X
  619. X      The support programs programs 'report' and 'do_report' can be used 
  620. X      to generate reports from the logfile. 
  621. X
  622. X      'do_report' is a wrapper around 'report', and will usually be the 
  623. X      only program used. 
  624. X
  625. X      When run, 'do_report' gathers logfile information about transfers 
  626. X      and errors. Both reports are mailed to the mail server owner by 
  627. X      default. You can specify other recipients on the command line. 
  628. X
  629. X      You can specify a cutoff date and time for error reporting by 
  630. X      supplying the name of a file that is timestamped after the 
  631. X      previous error report. The 'do_report' program normally updates 
  632. X      the timestamp of this file, so errors are reported only once. 
  633. X
  634. X      A typical usage report looks like: 
  635. X
  636. X            Mail Server Report for July 1992 -- by Package                           Page 1
  637. X            
  638. X                                                                     1111111111222222222233
  639. X            Package                              Type Total 1234567890123456789012345678901
  640. X            -------------------------------------------------------------------------------
  641. X            /usr/local/lib/mserv/pub/README         M     1                   S
  642. X            /usr/local/lib/mserv/pub/mserv.tar.Z    M     2                   S
  643. X            TOTAL                                         4                   S
  644. X
  645. X      'Type' will be 'M' for mail transfers, and 'U' for UUCP transfers. 
  646. X      'Total' denoted the number of times a file has been requested. The 
  647. X      rest of the information shows on what days requests have been 
  648. X      issued. In the above example, all requests were issued on July 19 
  649. X      (a Sunday). 
  650. X
  651. X      Likewise, a list will be generated containing the users that have 
  652. X      requested files. 
  653. X
  654. X      Program 'do_report' can also be used to cleanup the logfile. If 
  655. X      this function is selected, the logfile is renamed to a '.o' 
  656. X      extension (e.g. 'logfile.o'), and appended to a file with a '.cum' 
  657. X      extension (e.g. 'logfile.cum'). It is possible to compress the 
  658. X      accumulating logfile, in this case the program will uncompress is 
  659. X      before appending the new information, and compress it afterwards. 
  660. X
  661. X      Command line options for 'do_report' are: 
  662. X
  663. X                -config XX   use alternate config file
  664. X                -usage       generate usage report
  665. X                -ftp         show files in FTP cache
  666. X                -full        generate report for usage, errors and ftp
  667. X                -ftpclean    cleanup old files in FTP cache (implies -ftp)
  668. X                -ftpkeep NN  number of days a file is to be kept in the FTP cache
  669. X                -since FILE  only error messages newer than FILE
  670. X                             (FILE date will be updated upon successful completion)
  671. X                -noupdate    do not update FILE date
  672. X                -collect     collect and cleanup logfile data
  673. X                -help        this message
  674. X                -trace       show commands
  675. X                -ident       print identification
  676. X            
  677. X            Default action is to generate a usage report, and to mail it to the
  678. X            recipients.
  679. X
  680. X4.3   The FTP cache 
  681. X
  682. X      Program 'do_report' can also be used to report the contents of the 
  683. X      FTP cache, and to exipre it. 
  684. X
  685. X      A typical report, generated with "do_report -ftp", will look like: 
  686. X
  687. X            Files in FTP cache /usr/local/lib/mserv/pub
  688. X            
  689. X              Timestamp     Age* Size  Filename (* means: file has been removed)
  690. X            --------------  ---  ----  ------------------------------------
  691. X            92/12/05 02:24   5   142K  com/foo/ftp/crack-4.1.tar.Z
  692. X            92/12/01 12:34   9*    2K  com/foo/ftp/pasta/INDEX
  693. X
  694. X      'Timestamp' indicates the last modification time of the file as 
  695. X      dereived from the FTP server. 'Age' is the last access date of the 
  696. X      file in the cache, in days. The cache expiry time is set in the 
  697. X      configuration file, but can be overridden with a command line 
  698. X      option. By using the last access date for expiry, the file will be 
  699. X      considered 'new' each time it is accessed. An '*' after the file 
  700. X      age means that this file has exceeded the expiry time and has been 
  701. X      removed from the cache. 
  702. X
  703. X5.    INSTALLING THE SQUIRREL MAIL SERVER SOFTWARE 
  704. X
  705. X5.1   Preparation 
  706. X
  707. X      As distributed, perl is expected to reside in /usr/local/bin. You 
  708. X      can change this in the Makefile if your perl resides somewhere 
  709. X      else. 
  710. X
  711. X      The mail server needs a user id to own the programs, and a place 
  712. X      where the programs and files can be stored. Pre-configured values 
  713. X      are "mserv" and "/usr/local/lib/mserv" respectively. We'll call 
  714. X      the library LIBDIR in this document. LIBDIR could be the HOME 
  715. X      directory of the mail server owner, but it need not. If you prefer 
  716. X      a different value for LIBDIR, change the appropriate line in the 
  717. X      Makefile. The name of the mail server owner can be changed in step 
  718. X      2, as described below. 
  719. X
  720. X      Since all messages sent by the mail server are sent under the 
  721. X      server owner uid, its full name (the GCOS or comment field in 
  722. X      /etc/passwd) should be descriptive. 
  723. X
  724. X      The mail server owner does not need any privileges, except for 
  725. X      read access to the archives, and read/write access to LIBDIR. 
  726. X
  727. X      Do not use the root account for server owner! 
  728. X
  729. X5.2   Configure and build 
  730. X
  731. X      Tailor 'ms_config.pl' to reflect your specific needs. It has 
  732. X      extensive descriptions for configuration variables and values. Do 
  733. X      not forget to tailor the Makefile also, if needed. 
  734. X
  735. X      It may be a good habit to generate differences using the 'diff' 
  736. X      program so you can apply your modifications to a new version of 
  737. X      the mail server software easily. 
  738. X
  739. X      Issue "make" to prepare the programs. 
  740. X
  741. X      If you select the index file feature, you need GNU find / locate. 
  742. X      As of GNU find version 3.6, you can use the locate program 'as 
  743. X      is'. For version 3.5, change GNUFIND in the Makefile to designate 
  744. X      where your GNU find sourcetree is, and issue "make ixlookup". This 
  745. X      will build a customized version of GNU locate, called 'ixlookup'. 
  746. X
  747. X      Issue "make listener" to generate and compile the listener 
  748. X      program. This command uses ms_config.pl (from the current 
  749. X      directory) to determine how to build the listener program. 
  750. X
  751. X5.3   Verify the configuration 
  752. X
  753. X      You can now verify the configuration with the 'chkconfig' program. 
  754. X
  755. X      You may need to run the perl tool 'h2ph' to supply system include 
  756. X      files needed for locking and socket IO. Pay attention to the lines 
  757. X      that got a "Not found" remark. Since the software has not been 
  758. X      installed yet, some of these remarks must be considered normal. 
  759. X
  760. X            % perl chkconfig.pl -current
  761. X            Squirrel Mail Server Software V3.01 [chkconfig 1.30]
  762. X            MSERVLIB = (not set, but that's OK)
  763. X            Program library: /usr/local/lib/mserv/src [OK]
  764. X            
  765. X            Server owner: mserv, uid = 50, gid = 8, "Squirrel Mail Server"
  766. X            Bcc user: mserv, uid = 50, gid = 8, "Squirrel Mail Server"
  767. X            
  768. X            The 'listener' program will use the setruid system call
  769. X              It will change identity to compiled-in uid 50
  770. X              (setenv will be used to set USER, LOGNAME and HOME)
  771. X            The 'listener' program is not installed correctly!
  772. X              It should be installed setuid mserv
  773. X            
  774. X            Replies will be sent using "/usr/lib/sendmail" [OK]
  775. X            Preset mail headers:
  776. X              From: PRONTO Mail Server <bit-bucket@mh.nl>
  777. X              X-Server: Squirrel Mail Server Software V3.01 [chkconfig 1.30]
  778. X              X-Info: Send mail to <postmaster@mh.nl>
  779. X            
  780. X            Mail messages from the following users will be rejected:
  781. X              root uucp mailer MAILER-DAEMON news daemon demon deliver sendmail
  782. X            
  783. X            Transfer strategies:
  784. X              email: "/usr/lib/sendmail -odq" [OK]
  785. X                     wait 30 seconds between chunks
  786. X                     limits: 64K (default), 10K (min), 1024K (max)
  787. X              uucp : "/usr/bin/uucp -ga" [OK]
  788. X                     check host names using "/usr/bin/uuname" [OK]
  789. X                     limits: 256K (default), 10K (min), 2048K (max)
  790. X                     uucp transfer is preferred, if possible
  791. X            
  792. X            Search strategies: File Directory Index
  793. X            
  794. X            Archives:
  795. X              /usr/local/src [OK]
  796. X              /beethoven/arch [OK]
  797. X              /albinoni/arch [OK]
  798. X              /usr/local/lib/mserv/src/pub [*** Not found ***]
  799. X            
  800. X            Indexfiles:
  801. X              /usr/local/src/ix.codes [Not found, but that's OK]
  802. X              /beethoven/arch/ix.codes [Not found, but that's OK]
  803. X              /albinoni/arch/ix.codes [Not found, but that's OK]
  804. X              /usr/local/lib/mserv/src/pub/ix.codes [Not found, but that's OK]
  805. X            Limit per index request: 200 lines.
  806. X            
  807. X            Index tools:
  808. X              gfind      /usr/local/bin/gfind [OK]
  809. X              ixlookup   /usr/local/bin/locate [OK]
  810. X              locatelib  /usr/local/lib/locate [OK]
  811. X            
  812. X            Server files:
  813. X              queue      /usr/local/lib/mserv/src/queue [OK]
  814. X              logfile    /usr/local/lib/mserv/src/logfile [Not found, but that's OK]
  815. X              lockfile   /usr/local/lib/mserv/src/lockfile [OK]
  816. X              notes      /usr/local/lib/mserv/src/mserv.notes [OK]
  817. X              hints      /usr/local/lib/mserv/src/mserv.hints [OK]
  818. X            
  819. X            Locking with fcntl(2).
  820. X            Use the 'testlock' program to verify the locking! (See INSTALL)
  821. X            
  822. X            Default encoding is B (btoa)
  823. X            Encoders:
  824. X              btoa       /usr/local/bin/btoa [OK]
  825. X              uuencode   /usr/bin/uuencode [OK]
  826. X              uue        /usr/local/bin/uue [OK]
  827. X              xxencode   /usr/local/bin/xxencode [Not found, but that's OK]
  828. X            
  829. X            Tools:
  830. X              dir: "/bin/ls -lL" [OK]
  831. X              archie: "/usr/local/bin/archie" [OK]
  832. X              extensions: /usr/local/lib/mserv/src/userdefs.pl [OK]
  833. X              feedback limit = 8K
  834. X            
  835. X            Support for FTP is included.
  836. X              Limited to uucp only.
  837. X              Cache dir = /usr/local/lib/mserv/src/ftp [*** Not found ***]
  838. X              Files are kept for 8 days in the cache.
  839. X            
  840. X            Support for packing is included.
  841. X              Packing limit = 4100 blocks.
  842. X              Dusk usage obtained using "/bin/du" [OK]
  843. X              File list obtained using "/usr/local/bin/gfind" [OK]
  844. X              Methods: tar [OK] zip [OK] zoo [OK]
  845. X              Compress/Tar using "/usr/local/bin/pdtar" [OK]
  846. X              Automatic packing of directories is allowed.
  847. X            
  848. X            Working storage: /usr/tmp [OK]
  849. X            
  850. X            The queue will automatically be run upon completion of process.
  851. X            The mail server will be niced with 10.
  852. X
  853. X5.4   Installation 
  854. X
  855. X      Now "su mserv" and execute "make install". 
  856. X
  857. X      This will install all programs and files in LIBDIR. It will not 
  858. X      install programs ixlookup and listener, since they need special 
  859. X      treatment. 
  860. X
  861. X      If you select the index file feature, issue "make 
  862. X      install-ixlookup" if you need the customized version of GNU locate 
  863. X      3.5. Note that whoever creates the index files, must have write 
  864. X      access to the location the index files are stored. 
  865. X
  866. X      If you configured the listener to use the setruid/setrgid system 
  867. X      calls, you need to "su mserv" before executing "make 
  868. X      install-listener". 
  869. X
  870. X      If you do not have setruid/setrgid, the program must be installed 
  871. X      setuid root. In this case, you have to "su root" before doing 
  872. X      "make install-listener". Look at the source of the listener.c 
  873. X      program to verify it will not harm your system security. 
  874. X
  875. X      Cd to the LIBDIR directory, and run 'chkconfig' again. Make sure 
  876. X      that all settings have the expected values. 
  877. X
  878. X5.5   Testing interactively 
  879. X
  880. X      Run LIBDIR/listener als follows: 
  881. X
  882. X            % ~mserv/listener -noqueue
  883. X
  884. X      Is should display a friendly banner: 
  885. X
  886. X            Mail Server (Squirrel Mail Server Software V3.01) ready.
  887. X            Local time is Thu Dec 24 20:33:06 1992.
  888. X            Enter HELP for a list of commands.
  889. X            
  890. X            Command>
  891. X
  892. X      Type "mail foo", followed by a RETURN: 
  893. X
  894. X            Command> mail foo
  895. X            Command: mail foo
  896. X            => Transfer via email to "foo"
  897. X
  898. X      Try "send HELP", followed by a RETURN: 
  899. X
  900. X            Command> send HELP
  901. X            Command: send HELP
  902. X            => Send: HELP
  903. X            Request results:
  904. X            
  905. X              Request                   Size  Enc  Limit  Status
  906. X              -----------------------  -----  ---  -----  ------
  907. X              HELP                       19K   A     64K  Tested OK
  908. X            
  909. X            Encoding A means: not encoded (plain file).
  910. X            
  911. X            The requests with status "Queued" will be sent as soon as
  912. X            the load of the server system permits, usually within 24 hours.
  913. X
  914. X      At this point, the basic functions of the mail server are working. 
  915. X      You can issue SEND and SEARCH commands for files in your archives, 
  916. X      and verify that the server can find them. 
  917. X
  918. X      Terminate this little session with the END command. 
  919. X
  920. X5.6   Adding aliases 
  921. X
  922. X      Create a suitable alias in /usr/lib/aliases (or wherever your 
  923. X      aliases are kept): 
  924. X
  925. X            mail-server : "|LIBDIR/listener"
  926. X
  927. X      To get rid of bounced mail, the mail server fakes 'bit-bucket' as 
  928. X      its return address. To avoid bounced mails filling your 
  929. X      filesystems, add another alias: 
  930. X
  931. X            bit-bucket: /dev/null
  932. X
  933. X5.7   Verification of the installation 
  934. X
  935. X      All the following steps should be executed under the mail server 
  936. X      owner! 
  937. X
  938. X      *  Verify your locking strategy. Execute 
  939. X
  940. X            % perl -s testlock.pl -test1 &
  941. X
  942. X         It should say "Got the lock -- waiting ...". Now execute 
  943. X
  944. X            % perl -s testlock.pl -test2 &
  945. X
  946. X         It should say "Good. Could not lock -- waiting ...". Now kill 
  947. X         the first process. The second process should print "ret = 1" 
  948. X         and exit. 
  949. X
  950. X      *  Verify the working of the 'dorequest' program: 
  951. X
  952. X            % LIBDIR/dorequest <youraddress> <arealfile>
  953. X
  954. X         You should receive mail(s) containing the indicated file. NOTE: 
  955. X         If your site is running sendmail, the mail(s) are queued for 
  956. X         delivery. They can take some time before they arrive, depending 
  957. X         on how often the sendmail queue is run. You may want to inspect 
  958. X         the sendmail queue to see if your mail(s) are in it. 
  959. X
  960. X         If no mail(s) arrive, try 
  961. X
  962. X            % LIBDIR/dorequest -debug <youraddress> <arealfile>
  963. X
  964. X         and see what happens. 
  965. X
  966. X      *  Create a text file containing the following lines: 
  967. X
  968. X            From bla
  969. X            From: <youraddress>
  970. X            
  971. X            test
  972. X            send HELP
  973. X            end
  974. X
  975. X         Now execute the 'process' script by hand: 
  976. X
  977. X            % LIBDIR/process < text-file
  978. X
  979. X         (The program should terminate after processing the 'end' 
  980. X         command). Now you should receive a mail (from yourself!) 
  981. X         telling you that your request has been processed. 
  982. X
  983. X         NOTE: If your site is running sendmail, and sendmail is 
  984. X         configured to use 'queued' delivery, the mail(s) are not 
  985. X         delivered immediately. You may want to inspect the sendmail 
  986. X         queue to see if your mail is in it, or run the queue by hand. 
  987. X
  988. X         In case of trouble: run LIBDIR/process with "-debug" to find 
  989. X         out what happens. 
  990. X
  991. X      *  Execute the 'process' script again with the same input, but 
  992. X         remove the line "test" from the text file. 
  993. X
  994. X         Again you should receive a mail (from yourself!) telling that 
  995. X         your request has been processed. It should also tell you that 
  996. X         your request has been queued. 
  997. X
  998. X         If you configured $auto_runrequest, program 'dorequest' will be 
  999. X         run to handle your request. You should receive a mail with the 
  1000. X         requested file. 
  1001. X
  1002. X         In case of trouble: run LIBDIR/process with "-debug" to find 
  1003. X         out what happens. This will prevent 'dorequest' from being 
  1004. X         invoked, so you can study the contents of LIBDIR/queue. 
  1005. X
  1006. X      *  Execute the 'listener' program with the same input. 
  1007. X
  1008. X         Again you should receive a mail message, but this time it 
  1009. X         should be from the mail server owner. 
  1010. X
  1011. X         If you configured $auto_runrequest, program 'dorequest' will be 
  1012. X         run to handle your request. You should receive a mail with the 
  1013. X         requested file. 
  1014. X
  1015. X      *  As another user, run the 'listener' program with the same 
  1016. X         input. 
  1017. X
  1018. X         Again you should receive a mail, still originating from the 
  1019. X         mail server owner. 
  1020. X
  1021. X      *  Still going strong? Now, as another user, send a mail message 
  1022. X         to your mail server: 
  1023. X
  1024. X            % mail mail-server
  1025. X            send foo bar INDEX
  1026. X            end
  1027. X            ^D
  1028. X
  1029. X         (Mail programs usually do not terminate after reading the 'end' 
  1030. X         line. Issue Control-D or whatever you local EndOfFile setting 
  1031. X         is). 
  1032. X
  1033. X         You will receive a return mail, indicating which archive 
  1034. X         entries were found, and how they would be transmitted. 
  1035. X
  1036. X      *  If you did not configure $auto_runrequest, change back to the 
  1037. X         mail server user, and inspect LIBDIR/queue to see that your 
  1038. X         request is in it. 
  1039. X
  1040. X         Run LIBDIR/dorequest without arguments; the selected file 
  1041. X         should be sent to you by email or UUCP. 
  1042. X
  1043. X      If you receive the requests, your mail server is fully 
  1044. X      operational! 
  1045. X
  1046. X      Likewise, you can test the correct functioning of delivery via 
  1047. X      UUCP. 
  1048. X
  1049. X5.8   The logfile 
  1050. X
  1051. X      If you don't want to keep of log of transactions, remove the file 
  1052. X      LIBDIR/logfile that was created by the Makefile. 
  1053. X
  1054. X      NOTE: This is strongly discouraged, since it will also disable the 
  1055. X      delivery of error messages. 
  1056. X
  1057. X5.9   Helpfiles and other goodies 
  1058. X
  1059. X      As a service: place the files 'HELP' and 'unpack.pl' in one of 
  1060. X      your archives. The Makefile prepares PUBDIR (defaults to 
  1061. X      LIBDIR/pub) for this purpose. 
  1062. X
  1063. X      Also, supply shar-files with the btoa/atob handling programs, 
  1064. X      uudecode/uuencode, and compress/uncompress. 
  1065. X
  1066. X      The contents of file LIBDIR/mserv.notes is prepended to every 
  1067. X      reply the mail server sends. This file can be used to supply a 
  1068. X      daily message about the server, new entries, etc. 
  1069. X
  1070. X      The contents of file LIBDIR/mserv.hints is appended to every reply 
  1071. X      the mail server sends. 
  1072. X
  1073. X      Make sure your archives have a decent copy of Dumas uud/uue and 
  1074. X      xxencode/xxdecode if you intent to support these. Likewise, zoo, 
  1075. X      zip, etc. 
  1076. X
  1077. X      Also, provide a file 'INDEX' that more or less describes what is 
  1078. X      in your archives. People are going to ask for it. 
  1079. X
  1080. X      Since people usually don't read the documentation, link 'help' to 
  1081. X      'HELP', 'index' to 'INDEX', 'atob.shar' to 'btoa.shar', etc. 
  1082. X
  1083. X5.10  Daemon processes 
  1084. X
  1085. X      Install crontab entries for the mail server processes. A sample 
  1086. X      crontab is included in the distribution as CRONTAB.sample. 
  1087. X
  1088. X            30 0,2,4,6,18,20,22 * * * LIBDIR/do_runq
  1089. X            0 3 * * * LIBDIR/makeindex
  1090. X            0 7 * * * LIBDIR/do_report -errors -since .errrun
  1091. X            10 7 * * 7 LIBDIR/do_report -full -collect -ftp -ftpclean
  1092. X
  1093. X      The above example runs the mail server queue every two hours, 
  1094. X      except during working hours. Once a day any mail server errors are 
  1095. X      reported, once a week the logfile data is accumulated and a usage 
  1096. X      report is generated. The FTP cache is reported and cleaned. 
  1097. X
  1098. X      CHECK AND MODIFY THESE SCRIPTS SINCE THEY WILL PROBABLY NOT DO 
  1099. X      WHAT YOU WANT! 
  1100. X
  1101. X      Every night a three o'clock new index files are generated. You may 
  1102. X      leave this line out if you do not use index files. 
  1103. X
  1104. X      If you configured $auto_runrequest in 'ms_common.pl', there is no 
  1105. X      need to run the queue that often; once or twice a day will be 
  1106. X      sufficient. 
  1107. X
  1108. X5.11  Let Me Know 
  1109. X
  1110. X      If you have implemented the mail server on your system, please let 
  1111. X      me <jv@mh.nl> know so I can collect information about the 
  1112. X      implementations. Also let me (and the net!) know what kind of 
  1113. X      archives you are offering. 
  1114. X
  1115. X      And protect your and mine freedom to write programs: join the 
  1116. X      League for Programming Freedom. 
  1117. X
  1118. X            League for Programming Freedom
  1119. X            1 Kendall Square #143
  1120. X            P.O.Box 9171
  1121. X            Cambridge, Massachusetts 02139
  1122. X            E-mail: league@prep.ai.mit.edu
  1123. X
  1124. X6.    ADVANCED TECHNIQUES 
  1125. X
  1126. X6.1   Extending the Mail Server command set 
  1127. X
  1128. X      Both the command parsing and execution are implemented using 
  1129. X      dispatch tables to subroutines. As a result, it is very easy to 
  1130. X      extend the Mail Server command set. 
  1131. X
  1132. X      In the configuration file, $cmd_extend can be defined to the name 
  1133. X      of a (perl) file to load extensions. 
  1134. X
  1135. X      Mail Server extensions can be implemented as follows: 
  1136. X
  1137. X      1. Write a subroutine to parse the command. See 'pr_parse.pl' for 
  1138. X         lots of examples. Any work should be pushed on the @workq. 
  1139. X
  1140. X      2. Add a command verb to $cmd_tbl, pointing to this routine. The 
  1141. X         command verb must be in ALL UPPERCASE. 
  1142. X
  1143. X      3. Write a subroutine to execute the command. See 'pr_dowork.pl' 
  1144. X         for lots of examples. 
  1145. X
  1146. X      4. Add a command verb to $exe_tbl, pointing to this routine. Since 
  1147. X         the Mail Server uses uppercase letters for this purpose, please 
  1148. X         use a lowercase letter or verb. 
  1149. X
  1150. X      5. Provide a short help message for the HELP command. 
  1151. X
  1152. X      As an example, the following code adds the 'REPORT' command to the 
  1153. X      Mail Server. 
  1154. X
  1155. X            sub cmd_report {                         # step 1.
  1156. X                # Check syntax.
  1157. X                # $cmd is the command verb, upcased.
  1158. X                # @cmd has the remainder of the command.
  1159. X                return &errmsg ("Usage: $cmd") unless @cmd == 0;
  1160. X            
  1161. X                # Push exe command on work queue.
  1162. X                push (@workq, &zp ('r'));
  1163. X            
  1164. X                # Feedback.
  1165. X                print STDOUT ("=> Okay\n");
  1166. X                1;
  1167. X            }
  1168. X            
  1169. X            $cmd_tbl{'REPORT'} = 'cmd_report';       # step 2.
  1170. X            
  1171. X            sub exe_report {                         # step 4.
  1172. X                &do_unix ("$libdir/report -usage");
  1173. X                1;
  1174. X            }
  1175. X            
  1176. X            $exe_tbl{'r'} = 'exe_report';            # step 4.
  1177. X            
  1178. X            &add_help ('REPORT',                     # step 5.
  1179. X                'Generate a mail server usage report.');
  1180. X
  1181. X      The source distribution contains a number of extension examples, 
  1182. X      look for the files ud_sample*.pl. 
  1183. X
  1184. X      NOTE:  Extending the Mail Server command set is not supported
  1185. X             and is not garanteed to work in future releases.
  1186. X             However, when implemented as described above, the impact
  1187. X             of a new release will probably be small.
  1188. X
  1189. X6.2   Setting up multiple servers 
  1190. X
  1191. X      You can set up multiple servers sharing the same software. All 
  1192. X      mail server programs support the command line option "-config" to 
  1193. X      specify an alternate configuration file for the program. This file 
  1194. X      can be used to select different archive directories. Depending on 
  1195. X      your needs, you can share the logfile, lockfile and queuefile. 
  1196. X      However, If you wish to share the queuefile, you *NEED* to share 
  1197. X      the lockfile also. 
  1198. X
  1199. X      You can have multiple mail aliases, e.g.: 
  1200. X
  1201. X            mail-server : "|LIBDIR/listener"
  1202. X            debug-server: "|LIBDIR/listener -trace"
  1203. X            info-server : "|LIBDIR/listener -config LIBDIR/info_config.pl"
  1204. X
  1205. X      All I/O to queue and logfile is done while locking the file, so it 
  1206. X      is not possible to get file corruption. The lockfile is used to 
  1207. X      prevent multiple invokations of the delivery program, 'dorequest'. 
  1208. X      But if you configure a common queue, you need to configure a 
  1209. X      common lockfile too. 
  1210. X
  1211. X      The delivery program will deliver requests that are entered in the 
  1212. X      queue. Who is going to receive what is totally determined by the 
  1213. X      'process' program. So it is perfectly safe to have a single queue 
  1214. X      for several flavours of the mail server. Once the information is 
  1215. X      in the queue, it doesn't matter what program is going to deliver 
  1216. X      it. 
  1217. X
  1218. X      NOTE: You need to build the listener program version 3.1 or later. 
  1219. X
  1220. X6.3   Setting up de Mail Server for Interactive Use 
  1221. X
  1222. X      If the program 'process' (or 'listener') is invoked with its input 
  1223. X      to a terminal, it enters interactive mode. Commands can be typed 
  1224. X      in and are executed immediately. Errors are not considered fatal. 
  1225. X      Alternatively, interactive mode can be forced with the 
  1226. X      "-interactive" command line option, and prohibited with "-noi". 
  1227. X
  1228. X      In interactive mode, the program displays a sign-on message, 
  1229. X      followed by the contents of the $notesfile. However, if a file 
  1230. X      exists with the name of the $notesfile followed by 'i', this file 
  1231. X      is used instead. This way you can have different messages for 
  1232. X      interactive and non-interactive use. 
  1233. X
  1234. X      In interactive mode, the $hintsfile, normally included at the end 
  1235. X      of the feedback message, will be appended to the output of the 
  1236. X      HELP command. If a file exists with the name of the $hintsfile 
  1237. X      followed by 'i', this file is used instead. 
  1238. X
  1239. X6.3.1 Via login 
  1240. X
  1241. X      Add a login name to your system to be used for this purpose. 
  1242. X      Supply a dummy HOME directory (e.g. /tmp), and specify 
  1243. X      LIBDIR/listener for login shell. 
  1244. X
  1245. X6.3.2 Via inetd 
  1246. X
  1247. X      Choose a port to be used for this service, e.g. 2000. Add this 
  1248. X      port to /etc/services: 
  1249. X
  1250. X            mserv   2000/tcp
  1251. X
  1252. X      Add the following line to the inet configuration file (usually 
  1253. X      /etc/inetd.conf): 
  1254. X
  1255. X            mserv    stream tcp nowait LIBDIR/listener listener -i0
  1256. X
  1257. X      Depending on your system, you may have to insert a user-id after 
  1258. X      'nowait'. Use whatever is appropriate. The listener program will 
  1259. X      set UID anyway. 
  1260. X
  1261. X      The command line option "-i0" forces interactive mode, and 
  1262. X      attaches standard output and error to standard input (file 
  1263. X      descriptor 0). 
  1264. X
  1265. X7.    DESIGN AND MAINTENANCE OF THE ARCHIVES 
  1266. X
  1267. X      The mail server software can handle multiple archive directories. 
  1268. X      Every directory specified in @libdirs is treated equal. 
  1269. X
  1270. X      Please consider the following points: 
  1271. X
  1272. X      *  Hidden files (filenames starting with '.') and files that are 
  1273. X         not readable to 'mserv' cannot be retrieved. They might show in 
  1274. X         the index, however. 
  1275. X
  1276. X      *  If a file occurs multiple (e.g. 'INDEX') in more than one 
  1277. X         archive directory, the first occurrence is retrieved. 
  1278. X
  1279. X      *  If a directory occurs multiple it can not be retrieved. 
  1280. X
  1281. X      *  For best results: name archives similar to 'foo-XXX.tar.Z', 
  1282. X         where XXX is a version number, e.g. emacs-18.58.tar.Z or 
  1283. X         xdvi-12.zoo. This will aid people in finding the right version 
  1284. X         for a specific archive entry. 
  1285. X
  1286. X8.    THE MAIL SERVER DISTRIBUTION 
  1287. X
  1288. X      This section lists the files in the mail server distribution, with 
  1289. X      a short explanation. Note that lots of functions are contained in 
  1290. X      separate files. These files are only loaded if needed, cutting 
  1291. X      down on the system resources. 
  1292. X
  1293. X      README           A short introduction.
  1294. X      ChangeLog        A log of changes. Relevant for developers only.
  1295. X      INSTALL          The ASCII version of this document.
  1296. X      ms_config.pl     Configuration file.
  1297. X      ms_common.pl     Common information for the mail server constituents.
  1298. X      process.pl       Perl script to parse mail messages, and to
  1299. X                       enqueue the requests.
  1300. X      pr_*.pl          Demand loadable modules for process.pl
  1301. X      pr_doindex.pl    Index lookup (for INDEX command).
  1302. X      pr_dowork.pl     Looking up files.
  1303. X      pr_dsearch.pl    Directory searching (for SEND commands).
  1304. X      pr_ftp.pl        FTP operations.
  1305. X      pr_help.pl       HELP message.
  1306. X      pr_isearch.pl    Index searching (for SEND commands).
  1307. X      pr_parse.pl      Command parsing
  1308. X      rfc822.pl        A package to process rfc822 based messages.
  1309. X      ftp.pl           Modified version of Alan R. Martello's package
  1310. X                       to deal with FTP.
  1311. X      chat2.pl         Modified version of Randal Schwartz' chat2.
  1312. X      dateconv.pl      Date conversions.
  1313. X      dorequest.pl     Perl script to encode and split the files, and sent
  1314. X                       them to the requester.
  1315. X      dr_*.pl          Demand loadable modules for dorequest.pl
  1316. X      dr_mail.pl       Sending files via email.
  1317. X      dr_uucp.pl       Sending files via UUCP.
  1318. X      dr_pack.pl       Packing directories before sending.
  1319. X      ms_lock.pl       Portable file locking package
  1320. X      unpack.pl        Perl script to unpack a concatenated series of parts.
  1321. X      HELP             The ASCII version of the user guide.
  1322. X      mlistener.pl     Generator for a simple wrapper around "process.pl"
  1323. X                       to enable setuid processing.
  1324. X      makeindex.pl     A simple script to aid in maintaining an index
  1325. X                       of archive entries.
  1326. X      chkconfig.pl     A tool to feed back on the configuration file.
  1327. X      testlock.pl      A tool to test the locking package.
  1328. X      report.pl        A tool to generate usage and error reports.
  1329. X      do_report.pl     A script to use report.pl
  1330. X      do_runq.sh       A shell script to run the mail server queue from cron.
  1331. X      CRONTAB.sample   A sample cron tab for the mail server.
  1332. X      mserv.notes      
  1333. X      mserv.hints      
  1334. X      mserv.hintsi     Sample files.
  1335. X      ud_*.pl          Sample Mail Server extensions.
  1336. X      ud_sample1.pl    'REPORT' command.
  1337. X      ud_sample2.pl    'SEND CONFIG' command.
  1338. X      ixlookup.patch   Patch to GNU find 3.5 'locate.c' to create
  1339. X                       the index lookup program.
  1340. X      Makefile         To install the package.
  1341. X      patchlevel.h     Patch version check.
  1342. X      MANIFEST         List of files.
  1343. X
  1344. X      Not included but also available are nicely formatted PostScript 
  1345. X      versions of the User Guide and Installation Guide. To obtain them, 
  1346. X      send a mail message to <mail-server@nluug.nl> with contents: 
  1347. X
  1348. X            begin
  1349. X            send usrguide.ps.Z
  1350. X            send mservmgr.ps.Z
  1351. X            end
  1352. END_OF_FILE
  1353.   if test 52619 -ne `wc -c <'mserv-3.1/INSTALL'`; then
  1354.     echo shar: \"'mserv-3.1/INSTALL'\" unpacked with wrong size!
  1355.   fi
  1356.   # end of 'mserv-3.1/INSTALL'
  1357. fi
  1358. if test -f 'mserv-3.1/dateconv.pl' -a "${1}" != "-c" ; then 
  1359.   echo shar: Will not clobber existing file \"'mserv-3.1/dateconv.pl'\"
  1360. else
  1361.   echo shar: Extracting \"'mserv-3.1/dateconv.pl'\" \(1794 characters\)
  1362.   sed "s/^X//" >'mserv-3.1/dateconv.pl' <<'END_OF_FILE'
  1363. X# dateconv.pl -- date/time conmversions.
  1364. X# SCCS Status     : @(#)@ dateconv.pl    1.2
  1365. X# Last Modified By: Johan Vromans
  1366. X# Last Modified On: Sat Dec  5 01:32:31 1992
  1367. X# Update Count    : 1
  1368. X# Status          : OK
  1369. X
  1370. X# Convert a date into a time.
  1371. X
  1372. Xsub lstime_to_standard
  1373. X{
  1374. X    local( $ls ) = @_;
  1375. X
  1376. X    return &time_to_standard( &lstime_to_time( $ls ) );
  1377. X}
  1378. X
  1379. Xpackage dateconv;
  1380. X
  1381. Xrequire 'timelocal.pl';
  1382. X
  1383. X@months = ( "zero", "Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec" );
  1384. X
  1385. X$month_num{ "Jan" } = 0;
  1386. X$month_num{ "Feb" } = 1;
  1387. X$month_num{ "Mar" } = 2;
  1388. X$month_num{ "Apr" } = 3;
  1389. X$month_num{ "May" } = 4;
  1390. X$month_num{ "Jun" } = 5;
  1391. X$month_num{ "Jul" } = 6;
  1392. X$month_num{ "Aug" } = 7;
  1393. X$month_num{ "Sep" } = 8;
  1394. X$month_num{ "Oct" } = 9;
  1395. X$month_num{ "Nov" } = 10;
  1396. X$month_num{ "Dec" } = 11;
  1397. X
  1398. X( $mn, $yr ) = (localtime)[ 4, 5 ];
  1399. X
  1400. X# Convert an 'ls' type date string into a time
  1401. Xsub main'lstime_to_time
  1402. X{
  1403. X    package dateconv;
  1404. X
  1405. X    local( $date ) = @_;
  1406. X
  1407. X    local( $mon, $day, $hours, $mins, $month, $year );
  1408. X
  1409. X    if( $date =~ /^(\w\w\w)\s+(\d+)\s+((\d\d\d\d)|((\d+):(\d+)))$/ ){
  1410. X        ($mon, $day, $year, $hours, $mins) = ($1, $2, $4, $6, $7);
  1411. X#print "(mon $mon, day $day, year $year, hours $hours, mins $mins)\n";
  1412. X    }
  1413. X    else {
  1414. X        printf STDERR "invalid date $date\n";
  1415. X        return time;
  1416. X    }
  1417. X    
  1418. X    $month = $month_num{ $mon };
  1419. X
  1420. X    if( $year !~ /\d\d\d\d/ ){
  1421. X        $year = $yr;
  1422. X        $year-- if( $month > $mn );
  1423. X    }
  1424. X    if( $year > 1900 ){
  1425. X        $year -= 1900;
  1426. X    }
  1427. X     
  1428. X#print " &timegm( 0, $mins, $hours, $day, $month, $year );\n";
  1429. X    return &timegm( 0, $mins, $hours, $day, $month, $year );
  1430. X}
  1431. X
  1432. Xsub main'time_to_standard
  1433. X{
  1434. X    package dateconv;
  1435. X
  1436. X    local( $time ) = @_;
  1437. X
  1438. X    local( $sec,$min,$hour,$mday,$mon,$year,$wday,$yday,$isdst ) =
  1439. X         gmtime( $time );
  1440. X    return sprintf( "%2d $months[ $mon + 1 ] %2d %02d:%02d", $mday, $year, $hour, $min );
  1441. X}
  1442. X
  1443. X1;
  1444. END_OF_FILE
  1445.   if test 1794 -ne `wc -c <'mserv-3.1/dateconv.pl'`; then
  1446.     echo shar: \"'mserv-3.1/dateconv.pl'\" unpacked with wrong size!
  1447.   fi
  1448.   # end of 'mserv-3.1/dateconv.pl'
  1449. fi
  1450. echo shar: End of archive 1 \(of 6\).
  1451. cp /dev/null ark1isdone
  1452. MISSING=""
  1453. for I in 1 2 3 4 5 6 ; do
  1454.     if test ! -f ark${I}isdone ; then
  1455.     MISSING="${MISSING} ${I}"
  1456.     fi
  1457. done
  1458. if test "${MISSING}" = "" ; then
  1459.     echo You have unpacked all 6 archives.
  1460.     rm -f ark[1-9]isdone
  1461. else
  1462.     echo You still must unpack the following archives:
  1463.     echo "        " ${MISSING}
  1464. fi
  1465. exit 0
  1466. exit 0 # Just in case...
  1467.