home *** CD-ROM | disk | FTP | other *** search
/ ftp.rootsweb.com / 2014.06.ftp.rootsweb.com.tar / ftp.rootsweb.com / smartlst.txt next >
Text File  |  1996-08-04  |  32KB  |  739 lines

  1.         SmartList mailinglist management
  2.         --------------------------------
  3.  
  4.     Copyright (c) 1993-1995, Stephen R. van den Berg, The Netherlands.
  5.                  <srb@cuci.nl>
  6.  
  7. NOTE: Run "flist -v" to find out more about your installed version of
  8.       SmartList.
  9.  
  10. Contents:
  11. ---------    1. Creating and removing mailinglists or archive servers
  12.         2. Remote maintenance of mailinglists
  13.         3. Customisation
  14.         3a.Digest processing
  15.         3b.Restricting subscriptions
  16.         3c.Restricting submissions
  17.         3d.Auto subscription on first submission
  18.         3e.Autosending files to new subscribers
  19.         3f.Moderated lists
  20.         3g.List of lists
  21.         3h.Positively discriminate certain daemons
  22.         3i.Default help text replies
  23.         3j.Unsubscribe assistance
  24.         3k.Exploding other (non-SmartList) lists
  25.         3l.Schematic overview of what goes on behind the scenes
  26.         4. The archive server
  27.         4a.Sending files to the archive server
  28.         4b.Restricting access to the archive server
  29.         5. The format of the dist file
  30.         6. Multigram and the thresholds in rc.init/rc.custom
  31.         7. Choplist & sendmail
  32.         8. FTP addresses & the SmartList mailinglist
  33.  
  34. $Id: Manual,v 1.49 1995/10/30 02:09:09 srb Exp $
  35.  
  36.  
  37. 1. Creating and removing mailinglists or archive servers
  38.    -----------------------------------------------------
  39.  
  40. Make sure that the .bin directory is in your PATH.  Now you can issue
  41. commands like:
  42.  
  43.     createlist testing
  44.     createlist testing joe@somewhere.edu
  45.     createlist -a testing joe@somewhere.edu
  46.     removelist testing
  47.  
  48. The first command creates a mailinglist with two useful addresses:
  49.  
  50.     testing
  51.     testing-request
  52.  
  53. The second command does the same, but it also specifies joe@somewhere.edu
  54. to be the responsible contact person for this list.
  55.  
  56. The third command does the same, except instead of creating a mailinglist,
  57. it creates an archive server.
  58.  
  59. The fourth command removes all traces of the "testing" mailinglist again.
  60.  
  61. There are four other convenience-utilities that can be used:
  62.     led    A wrapper around your editor, should be used when instead
  63.         of calling up your editor directly whenever editing a
  64.         SmartList managed file.     It automatically takes care
  65.         of proper locking and does attribute checks.
  66.     delink
  67.         It will unlink a file from its hardlinked counterpart(s)
  68.         (without deleting it).
  69.     showlink
  70.         It will display what groups of files are linked together.
  71.     donatelist
  72.         It will put a list under complete and exclusive control
  73.         of the maintainer (a local user).  See below.
  74.  
  75. If you are running several lists maintained by separate maintainers, you
  76. can give a maintainer complete and sole control over his or her own list
  77. without the need for them to have user list or group list rights.
  78. For this to work, you simply have to "donatelist the_maintainer his_list"
  79. the whole tree that contains his list to him (her).  Make sure that the
  80. group id of all necessary files in the tree are still group-writable by
  81. "list", because that's the access privilege the mailinglist will be running
  82. under.
  83.  
  84. The maintainer has to be careful to use an umask of 007 while editing in
  85. his mailinglist directory.  This allows the mailinglist-programs to function
  86. while still limiting access to all mailinglist files to *one* person only
  87. (the maintainer).
  88.  
  89.  
  90. 2. Remote maintenance of mailinglists
  91.    ----------------------------------
  92.  
  93. To facilitate remote maintenance of some mailinglists by their maintainers
  94. I have created the .bin/x_command script.  It parses mails sent to the
  95. -request address and can execute some administrative commands.
  96.  
  97. The mail should be sent to the -request address of a mailinglist and
  98. should contain a field in the header looking like this:
  99.  
  100. X-Command: joe@somewhere.edu password command
  101.  
  102. "command" can be anything of the following:
  103.  
  104.     subscribe mailaddress
  105.     unsubscribe mailaddress
  106.     checkdist mailaddress        To multigram-match mailaddress to
  107.                     the list (showing the eight best
  108.                     matches)
  109.     showdist            To list the distfile
  110.     showlog                To list the log
  111.     wipelog                To clear the log
  112.     help                To show this command summary
  113.     info                Ditto
  114.  
  115. The exact fieldname defaults to "X-Command", but can be customised to
  116. whatever you want.
  117.  
  118. The password defaults to "password", but can/should be changed.
  119.  
  120. The "joe@somewhere.edu" is always the mail address of the maintainer.  Note
  121. that this has to match what was specified on the command line of
  122. "createlist" when the list was created.
  123.  
  124. Note that the X-Command: field has to be part of the header, when it's
  125. in the body of the mail, it has no effect.
  126.  
  127. Anytime an X-Command: mail has been processed, the results will be
  128. mailed back to the maintainer of the list, and the X-Command: field
  129. will have been renamed to X-Processed:.
  130.  
  131. Although this remote-facility is convenient, some might argue that it
  132. presents a security hole.  Well, in order to make this hole as small as
  133. possible, you can keep the password secret.  Also, the exact mailaddress
  134. of the maintainer might not be publicly known.    You can simply change
  135. the X-Command field into something else like X-MyCommand.  Above all, since
  136. faking mail is a well known possibility it would be ridiculous to take
  137. more precautions than these.  Besides, if someone indeed manages to sneak in
  138. a bogus X-Command:, it will never go unnoticed since the mailing list
  139. maintainer (and only the maintainer) will always receive the X-Processed:
  140. mail.
  141.  
  142. For your convenience, a sample script "doxcommand" is present in the
  143. SmartList/examples directory.  It can be used to easily generate these
  144. X-Command mails.  Do remember to read-protect this script once the password
  145. has been changed.
  146.  
  147.  
  148. 3. Customisation
  149.    -------------
  150.  
  151. The mailinglists can be customised in several ways:
  152.  
  153. - For all the lists:
  154.     - Since all the lists initially share the same help.txt, subscribe.txt,
  155.       unsubscribe.txt, rc.init, rc.submit and rc.request files
  156.       (hardlinked), any change to them will affect all lists.
  157.     - Since all the lists have the .bin directory in their PATH, any
  158.       change to one of the Bourne shell scripts in there will affect
  159.       them all.
  160. - Per list:
  161.     - Every list directory contains an "rc.custom" rcfile which can
  162.       be edited to your hearts content to customise certain parameters
  163.       for this list only.
  164.     - Small local customisations can be realised by uncommenting one
  165.       or more of the RC_LOCAL_* assignments in rc.custom.
  166.       You then have to create the appropriate rc.local* file in which
  167.       you can put any commands you'd like (e.g. adding a general signature
  168.       or disclaimer to every outgoing submission).
  169.     - For graver customisation you can remove the hardlink (using
  170.       .bin/delink for example) to any of the files in a list directory and
  171.       provide that list with its own copy in order to edit that to taste.
  172.     - Since the current directory is in the PATH before the .bin
  173.       directory you can create per-list copies of any of the Bourne shell
  174.       scripts in .bin which can then be changed without affecting the
  175.       other lists.
  176. - Per group of lists:
  177.     - The same applies as when customising per list, but you should
  178.       then hardlink the appropriate files among the group of list
  179.       directories.
  180.  
  181. By default the scripts create and use hardlinks in various places.  You are
  182. completely free to change some or all into symbolic links instead (or
  183. substitute "ln" with "ln -s" in some scripts).
  184. Some editors have a habit of moving the file you were editing to a backup
  185. name and writing out a new copy in its place.  This can cause problems if
  186. the editor is unaware of the symbolic or hard links in place.  You should
  187. make sure that the editor is aware of the link and preserves it, even after
  188. the file has been edited (for people using emacs: try setting
  189. backup-by-copying-when-linked to true).
  190. By using the "led" script instead of calling your editor directly you
  191. will be timely warned of anything your editor broke.
  192.  
  193. If you are not using the remote-maintenance facility and you start editing
  194. or customising scripts/files by hand, then you should make sure that there
  195. doesn't arrive any mail to those lists that are affected by your changes.
  196. The best way to do this is by using the command "led" whenever you want
  197. to edit a SmartList governed file.  Led will take care of all the necessary
  198. locking for any file, led can also be used to edit non-SmartList files.
  199.  
  200. If you don't use "led" but still would like to put incoming mails on hold
  201. temporarily, then you can do this:
  202.  
  203. - for all the lists by creating the file:    .etc/rc.lock
  204. - only for one list by creating the file:    rc.lock
  205.   in the list directory of that list.
  206.  
  207. The .bin/flist command checks to see if these rc.lock files exist AND are
  208. not older than 17 minutes before delivering the mail.  So, if you create
  209. an rc.lock file, mails to that (or all) lists will stall for the next
  210. 17 minutes.  If you need more time, touch the file every so often.
  211. You should remove the rc.lock files again after finishing your editing.
  212.  
  213. If you would like to change the -dist alias (used to distribute the
  214. mail to the subscribers) into something less well known, go right ahead,
  215. but remember to change the corresponding assignment to listdist.  For
  216. completeness sake one should also correct the createlist and removelist
  217. scripts in that case.  If you are using choplist to expand the dist-file,
  218. then you don't even need a -dist alias at all.
  219.  
  220.  
  221. 3a.Digest processing
  222.    -----------------
  223.  
  224. You can configure a list to send out digests of accumulated submissions.
  225. In order to do so, simply uncomment the appropriate assignment to
  226. digest_flag in rc.init (if you want all lists to be digested) or rc.custom
  227. (if you only want this list to be digested).  Digests are then sent out
  228. every so often depending on size and age of the accumulated messages.
  229.  
  230. The conditions for sending out a digest are checked during the arrival
  231. of every submission.  If, however, traffic on the list sometimes is very low
  232. (i.e. less often than the maximum age of a digest) a digest could be laying
  233. around for longer than the specified maximum period (3 days by default).
  234.  
  235. In order to make sure that the digest gets sent out anyway, you should be
  236. running the .bin/cronlist program every so often.  The recommended
  237. procedure is to create a cron job (under the list account) that contains
  238. something like the following entry:
  239.  
  240. 0 6 * * * /home/slist/.bin/cronlist
  241.  
  242. The cronlist script can be customised to taste (maybe you'll need to
  243. adjust the setting of the PATH variable).
  244. Beware: call cronlist with an absolute or relative path, do not rely on
  245. PATH to find it for you (cronlist uses $0 to find the location of the
  246. lists it is responsible for).
  247.  
  248. By default, cronlist will run the flush_digests program.
  249. By using the above listed crontab entry, you will ensure that at six o'clock
  250. in the morning all the overdue digests will be sent out.
  251.  
  252. Flush_digests normally checks the age of the digest and does not send it
  253. out until it is overdue.  If you want to force flush_digests to send out
  254. a digest of a particular list, you can create the file ".digest.force" in
  255. that list's directory.    During the next run of flush_digests, it will
  256. remove .digest.force and push out the digest (if any) regardless of its age.
  257.  
  258. If you create a file named digest.admin in either the main directory of
  259. the digested list or in the archive/latest directory belonging to it, it
  260. will be picked up by the next flush_digests and included up front to the
  261. actual digest under the heading "Administrivia".
  262. The archive/latest/digest.admin file digested list will be automatically
  263. removed after the digest has been pushed out.
  264. The digest.admin file in the main directory of the digested list will not be
  265. removed and is included in every digest.
  266.  
  267. If you want to give your subscribers the choice of receiving digests or not.
  268. This is what you can do:
  269.  
  270.     Create two lists.  E.g. if your list would be called "thelist", then
  271.     you have the `real' list called "thelist" (created and used like
  272.     a regular list) and the `digested' list called "thelist-d".
  273.  
  274.     In the distfile of thelist you should include thelist-d as one of
  275.     the subscribers.  In the rc.custom file of thelist-d you should
  276.     edit the assignment to undigested_list to read
  277.     "undigested_list =    thelist@$domain".
  278.  
  279.     After you've done this, you're all set.     People that want digests
  280.     simply subscribe to thelist-d and people that don't, subscribe to
  281.     thelist.
  282.  
  283.  
  284. 3b.Restricting subscriptions
  285.    -------------------------
  286.  
  287. There are three ways in which you can restrict who can subscribe to a list:
  288. - You can put the addresses of unwanted subscribers on the so-called reject-
  289.   list (the `reject'-file).
  290. - You can create a program (e.g. a shell script) called "subscreen".  It must
  291.   be executable and will receive the mail address of the prospective subscriber
  292.   as the first argument.  If subscription for that address is allowed, the
  293.   program must return with exitcode zero.  If subscription is disallowed,
  294.   simply return with exitcode one.  A sample program is provided in the
  295.   examples directory.
  296. - You can completely disable automatic subscription by uncommenting the
  297.   appropriate "auto_subscribe" line in rc.custom.
  298. - You can completely disable automatic unsubscription by uncommenting the
  299.   appropriate "auto_unsubscribe" line in rc.custom.
  300.  
  301.  
  302. 3c.Restricting submissions
  303.    -----------------------
  304.  
  305. You can restrict submissions to people on the accept-list (the `accept'-file).
  306. Mail from anyone else will be passed on to the maintainer instead of being
  307. submitted.  To enable this you have to uncomment the appropriate
  308. "foreign_submit" line in rc.custom.  By default the accept file is hardlinked
  309. to the dist file (i.e. if submissions are restricted, only subscribers
  310. can do so).  If you want to allow only an even more select group, delink the
  311. accept file and edit it to taste.  If you'd like to have both the dynamic
  312. accept file and a static one, create a new file "accept2", it will be
  313. searched in addition to the regular accept file.
  314.  
  315. Beware that using an accept file is incompatible with having an owner- alias
  316. for this list (procmail administered lists do not need the owner- alias
  317. anyway, so if you've never heard of such a thing, ignore this warning).
  318.  
  319. If, in addition to notifying the maintainer you want an automated reply
  320. to be generated to the submitter which was not in the accept file, then you
  321. can accomplish this by simply creating an accept.txt file.  Its contents
  322. will (like the contents of the help.txt file) be returned to the submitter.
  323.  
  324. This feature is not the same as a moderated list, the two features can be
  325. used accumulatively.
  326.  
  327. On a related note, SmartList, by default, tries to identify administrative
  328. requests that got mailed to the submission address instead of the -request
  329. address and diverts them to the -request address.  If for some reason this
  330. is undesirable, you can uncomment the appropriate "divertcheck" variable
  331. assignment in rc.custom to disable this feature.
  332.  
  333.  
  334. 3d.Auto subscription on first submission
  335.    -------------------------------------
  336.  
  337. Instead of rejecting submissions by people not on the accept (dist) list,
  338. you can enable "force_subscribe".  This will cause people submitting
  339. mails to the list to be autosubscribed to the list if they were not in the
  340. dist file.
  341.  
  342.  
  343. 3e.Autosending files to new subscribers
  344.    ------------------------------------
  345.  
  346. You can create a file named "subscribe.files".    It can contain any
  347. number of archive-server commands.  The results (i.e. the files requested)
  348. will be sent to the new subscriber.
  349.  
  350.  
  351. 3f.Moderated lists
  352.    ---------------
  353.  
  354. First create a file named "moderators", it should contain the fully
  355. qualified mail addresses of all the moderators for this list (i.e. just
  356. local usernames are not sufficient, at least include an @host or host! ).
  357. Then uncomment the appropriate "moderated_flag" line in rc.custom.
  358.  
  359. From then on all mail that does not contain an
  360. "Approved: the_address_of_one_of_the_moderators" field is forwarded to
  361. all the moderators.
  362.  
  363. One of the moderators should then resend the mail to the list after adding
  364. an "Approved: his_own_address" field to the header (and possible editing
  365. the contents of the mail).  It will be no problem if several moderators
  366. resubmit the same submission concurrently, since the mailinglist will
  367. filter out duplicates anyway (i.e. only the first one will go out and
  368. be archived).
  369.  
  370.  
  371. 3g.List of lists
  372.    -------------
  373.  
  374. If you want people to be able to get an overview of which lists are
  375. publicly available at your site, you can have your listmaintainers create
  376. a file called "info.txt" in their respective list directory.  This info.txt
  377. file should contain a short description of the purpose and main topic of
  378. this particular list.
  379.  
  380. You can then setup a command like examples/gatherinfo in crontab to collect
  381. all these various info.txt files once a day.
  382.  
  383. The thus gathered info.txt files can be placed in a directory which can
  384. be accessed by a gopher or ftp server, or, you can put them into the
  385. archive directory of a procmail-managed mail-archive server (e.g. under
  386. the mail-alias "metalist").
  387.  
  388.  
  389. 3h.Positively discriminate certain daemons
  390.    ---------------------------------------
  391.  
  392. SmartList usually does not accept submissions or subscriptions from daemons.
  393. If you'd like to make an exception for some, you can do this by tuning
  394. the daemon_bias variable.  A sample template can be found in the rc.init
  395. file.  This variable can of course be set in the rc.init, rc.custom or
  396. rc.local files.     Instead of directly specifying a weight and a regexp, you
  397. can just specify a weight.  You'll then have to make sure that the variable
  398. is set only when mail from your special daemons arrives.
  399.  
  400. Beware that if you change this for a list that has a digested shadowlist,
  401. you change it for the digested version as well.
  402.  
  403.  
  404. 3i.Default help text replies
  405.    -------------------------
  406.  
  407. By uncommenting the appropriate "auto_help" line in the rc.custom file the
  408. list will respond to every undecipherable request message as if it requested
  409. help.  Messages that will still get through to the maintainer are those:
  410. - that seem to come from a daemon.
  411. - which look like a reply.
  412.  
  413. Depending on the typical audience you have on the list, enabling this might
  414. not be a good idea.
  415.  
  416.  
  417. 3j.Unsubscribe assistance
  418.    ----------------------
  419.  
  420. By uncommenting the appropriate "unsub_assist" line in the rc.custom file
  421. you can turn on the unsubscribe assistance.  If the someone is trying to
  422. unsubscribe from the list, but his mailaddress could not be found, he
  423. will receive back a number of multigram matches (determined by the value
  424. of unsub_assist) between his unsubscribe message and the dist file.
  425.  
  426. If you'd like to enable this feature, please keep the following points
  427. in mind:
  428. - People can get excerpts of the dist file this way.
  429. - Malevolent individuals might become encouraged to unsubscribe lots
  430.   of people from your list.  This will not go by unnoticed, of course.
  431.   It will be logged and the innocent subscribers will receive a copy
  432.   of the unsubscribe request they didn't send.    Nevertheless, it can cause
  433.   considerable inconvenience.
  434.  
  435.  
  436. 3k.Exploding other (non-SmartList) lists
  437.    -------------------------------------
  438.  
  439. A SmartList list can easily be used to function as a local exploder for
  440. a larger mailinglist.  The advantages over using a regular alias are
  441. threefold:
  442. - (Un)subscription is handled automatically.
  443. - Bounce messages go to the local exploder list (instead of the larger
  444.   mailinglist which really is not interested in your mail problems with
  445.   some local aliases).
  446. - Misdirected administrative requests are filtered out of the regular
  447.   submission channel.
  448.  
  449. If the larger mailinglist you are exploding locally is a SmartList list
  450. as well, then there are no special precautions to take at all.
  451. If the larger mailinglist is not managed by SmartList, misdirected
  452. administrative requests will be caught *and* handled by the local list;
  453. if this "handling" turns out to be a problem you can turn it off
  454. by uncommenting the appropriate "pass_diverts" variable in rc.custom
  455. (this will cause misdirected administrative requests to be caught but
  456. then passed on to the maintainer verbatim).
  457.  
  458.  
  459. 3m.Schematic overview of what goes on behind the scenes
  460.    ----------------------------------------------------
  461.  
  462. Suppose you have two entries in the aliases file, one for thelist@domain
  463. and one for thelist-request@domain.
  464.  
  465. Whenever mail arrives for either address, the following happens:
  466.     - flist is started suid root with thelist as its argument
  467.         - changes its current directory to that of the (internally
  468.           hardcoded) main list directory
  469.         - changes its uid and gid to that of the (internally
  470.           hardcoded) list account
  471.         - changes its current directory to that of thelist
  472.         - waits until both ../.etc/rc.lock and rc.lock are gone or
  473.           are old enough (17 minutes)
  474.  
  475. Then, if it was a regular submission to thelist@domain:
  476.     - flist execs procmail with rcfile rc.submit
  477.         - pulls in rc.init that sets up the defaults
  478.         - pulls in rc.custom that overrides some defaults (if any)
  479.         - checks the submission format
  480.             - if needed it now checks:
  481.                 - the accept list
  482.                 - the moderators list (Approved:)
  483.             - checks the msgid cache for duplicate submissions
  484.             - if needed does digest processing (and stop)
  485.         - archives the mail
  486.         - munges the header of the mail to taste
  487.         - fires off sendmail to send the mail to thelist-dist@domain
  488.     - If the mail was an administrative request, it does not get
  489.       passed on to the list, instead, procmail pulls in rc.request
  490.  
  491. But, if it was an administrative mail for thelist-request@domain:
  492.     - flist execs procmail with rcfile rc.request
  493.         - pulls in rc.init that sets up the defaults
  494.         - pulls in rc.custom that overrides some defaults (if any)
  495.         - performs the necessary actions, depending on the content
  496.         - if the content was undecipherable, it gets passed on to
  497.           the maintainer of thelist
  498.  
  499. If there are grave system failures during all this, the catch-all script
  500. rc.post will kick in and make sure that the mail is stashed away somewhere
  501. or forwarded to the maintainer, whatever works.     This to ensure that no
  502. mail gets lost.
  503.  
  504.  
  505. 4. The archive server
  506.    ------------------
  507.  
  508. All mail (except mail being forwarded from another mailinglist) sent to any
  509. of the lists is archived.  The archiving is fairly straightforward.
  510. E.g. if you have a list called "scuba", then all submissions are archived
  511. in scuba/archive/latest/.  The mails will be stored one-mail-per-file each.
  512. The files will be numbered.
  513.  
  514. Now, normally, only the last two mails will be kept around, the others
  515. are periodically removed.  This in order to keep down the archiving costs
  516. for people with limited diskspace.  To change the size of the archive-history
  517. edit the rc.custom file.  To get more sophisticated archiving, like grouping
  518. submissions monthly, you should either create a cron job or edit the
  519. .bin/arch_trunc file.
  520.  
  521. The archive server can be accessed per mailinglist by sending mail
  522. to the -request address with the following Subject:
  523.  
  524.     Subject: archive
  525.  
  526. The body of the mail or the rest of the subject line can then be
  527. filed with requests to the archive server.  It basically understands
  528. five commands:
  529.  
  530.     get file ...
  531.     ls directory ...
  532.     egrep case_insensitive_regular_expression file ...
  533.     maxfiles nnn
  534.     help
  535.  
  536. The archive server does a thorough check on the commands and the files
  537. that are requested.  This to ensure that it does not access any files
  538. outside the "scuba/archive" directory.    Any text-file that you put in
  539. the "scuba/archive" directory (or any of its subdirectories) can now be
  540. retrieved by the archive commands.
  541.  
  542. If a file requested via the archive server starts with a header that begins
  543. with `Content-Type:', then the file is sent out as is, without encapsulation.
  544. This allows you to prepare the files in special formats that are directly
  545. supported by the recipient's mailuser agent.  The leading Content-Type: and
  546. any immediately following fields will become part of the header.
  547.  
  548. All other files are MIME-encapsulated before transmission.  You should take
  549. a look at /home/slist/.bin/mimencap.local if you want to extend or
  550. customise the recognised file types.
  551.  
  552. The MIME-encapsulation is automatic and depends on the availability of the
  553. metamail package in the PATH defined in rc.init.  The programs from this
  554. package which need to be available are: mimencode and splitmail.
  555. If mimencode is not found on the PATH, the files will be sent out with a
  556. standard wrapper around them.
  557.  
  558. You can switch from MIME-encoding to uuencoding by applying the
  559. appropriate patch from .examples/uuencode.dif.
  560.  
  561. If you put links in the "scuba/archive" tree, you can allow the archive
  562. server to retrieve files from other parts of the filesystem.
  563.  
  564. The whole archive server can be found in the .bin/arch_retrieve script.
  565. The archive server can be extended with arbitrary commands via the
  566. examples/retrieve.local script that comes with the distribution.
  567.  
  568.  
  569. 4a.Sending files to the archive server
  570.    -----------------------------------
  571.  
  572. The archive server as installed with SmartList does not directly support
  573. the receipt and storage of files.
  574. What you can do is look in the at the rcfile script .examples/putfile.
  575. It provides you with all you'd need to receive and store files.
  576.  
  577.  
  578. 4b.Restricting access to the archive server
  579.    ----------------------------------------
  580.  
  581. You can restrict archive access to people on the accept-lists
  582. (the `accept' and `accept2'-file).  Mail from anyone else will be passed on
  583. to the maintainer instead of being passed to the archive server.  To enable
  584. this you have to uncomment the appropriate "restrict_archive" line in
  585. rc.custom.
  586.  
  587.  
  588. 5. The format of the dist file
  589.    ---------------------------
  590.  
  591. You do not need to know this, unless you edit the dist file by hand or want
  592. to incorporate an existing list of addresses.
  593.  
  594. In order to distribute incoming submissions the dist file is fed to sendmail
  595. with the regular :include: alias.  So the format of this file must
  596. be in accordance with what sendmail would expect.  In addition to that
  597. this file is searched and edited by multigram in order to find particular
  598. subscribers.  The format which multigram expects is a bit more rigid than
  599. what sendmail allows.
  600.  
  601. The following conditions apply:
  602. - One subscriber per line.
  603. - Empty lines are allowed.
  604. - The mail address of the subscriber must be the first word on the line.
  605. - Comments may follow the address (but separated from the address by
  606.   at least one whitespace character).
  607. - Everything preceding the line containing:
  608.     (Only addresses below this line can be automatically removed)
  609.   is write protected from changes by multigram (i.e. these addresses can
  610.   never be automatically/accidentally unsubscribed).
  611. - If the line:
  612.     (Only addresses below this line can be automatically removed)
  613.   is not present at all, automatic unsubscriptions to this list are impossible.
  614. - Whenever multigram automatically removes an address from the list, it
  615.   rewrites the dist file `in situ'.  This means that the dist file will be
  616.   contracted at that point, any excess slack at the end will be overwritten
  617.   by newlines (i.e. the dist file never shrinks, this because ANSI-C does not
  618.   provide a truncate() command of some kind).  I choose to write in situ in
  619.   order to avoid copying the dist file every time it changes (a real life
  620.   saver if the list grows too big).
  621. - Multigram always adds new subscribers on the line immediately following the
  622.   last filled entry in the dist file.
  623.  
  624. Some sample entries (the preferred format):
  625.     joe@some.where
  626.     joe@some.where (some comment)
  627.     joe@some.where (some comment) (some more comments)
  628.  
  629. Depreciated, but allowed:
  630.     <joe@some.where>
  631.     <joe@some.where> some comment
  632.     <joe@some.where> (some comment)
  633.  
  634. Not allowed by multigram (although sendmail doesn't mind):
  635.     (some comment) joe@some.where
  636.     some comment <joe@some.where>
  637.  
  638.  
  639. 6. Multigram and the thresholds in rc.init/rc.custom
  640.    -------------------------------------------------
  641.  
  642. The rc.init and rc.custom scripts define some threshold values:
  643.  
  644.     match_threshold, off_threshold, reject_threshold, submit_threshold.
  645.  
  646. These values are fed to multigram as a cut-off value with which to decide
  647. if a certain mail address is on a list.
  648. The higher the threshold, the better the match must be.     The thresholds
  649. have a scale from -16383 to 32766.  This means that, for instance a threshold
  650. of 30730 can be used to find only mailaddresses that are almost verbatim
  651. on the list.  A value of 24476 on the other hand allows for some error
  652. (like mailaddresses munged by gateways etc.) in finding matches to the
  653. list.
  654.  
  655. The values 30730 and 24476 are somewhat arbitrary values which seem
  656. to work well for the particular problems at hand.
  657.  
  658. To get a feeling for the values computed by multigram you can do
  659. the following test:
  660.  
  661.     Create a file with the same format as the distfile, fill it with
  662.     any number of addresses you like (e.g. you could take an existing
  663.     distfile).
  664.     Now make a copy of this `distfile' and alter some of the addresses
  665.     a bit (like omit one character, or add some gateway information,
  666.     switch two words, change it into an uucp address, etc.).
  667.     Next you should call up multigram with the following command line:
  668.  
  669.         multigram -l-16000 -b300 pseudo_distfile <altered_distfile
  670.  
  671.     Multigram will display up the 300 best matches it found after
  672.     crossreferencing altered_distfile and pseudo_distfile.
  673.     The output produced by multigram can be disected as follows:
  674.  
  675.         lineno. name1 goodness name2
  676.  
  677.     Lineno. and name1 refer to the line number in pseudo_distfile which
  678.     contains the mailaddress name1.     Goodness is the metric that
  679.     corresponds to the aforementioned threshold values, and name2 is
  680.     the matching mailaddress from altered_distfile (which is usually
  681.     the incoming mail).
  682.  
  683.     Once you get the hang of it you can play around a bit with the
  684.     entries in altered_distfile by mutilating them more and more in
  685.     order to see what multigram makes of it (try inserting some non-
  686.     existing addresses as well).
  687.  
  688.  
  689. 7. Choplist & sendmail
  690.    -------------------
  691.  
  692. There are two ways of distributing the message to the addresses listed
  693. in the dist file: either directly through sendmail and the :include:
  694. alias expansion, or indirectly, through choplist which does the
  695. expansion itself and calls up sendmail on suitable chunks.
  696.  
  697. By default, choplist takes care of the expansion, uncomment the appropriate
  698. alt_sendmail environment variable in rc.init to revert to standard sendmail
  699. expansion.
  700.  
  701. Choplist tries to make sure that even for big lists, the alias expansion
  702. goes as swiftly as possible and several sendmails will be delivering the
  703. mail to the subscribers concurrently.  The various limits that can be
  704. imposed on this process can be tuned in the rc.init file.
  705.  
  706. Most sendmails will do a worse job without choplist as a preprocessor.
  707.  
  708. A side effect of using choplist as a preprocessor is that there is no need for
  709. a -dist alias anymore.
  710.  
  711.  
  712. 8. FTP addresses & the SmartList mailinglist
  713.    -----------------------------------------
  714.  
  715. A recent version can be picked up at various comp.sources.misc archives.
  716. The latest version can be obtained directly from the ftp-archive at:
  717.  
  718.     ftp.informatik.rwth-aachen.de
  719.  
  720. as (g)zipped tar file:       /pub/packages/procmail/SmartList.tar.gz
  721. as compressed tar file:       /pub/packages/procmail/SmartList.tar.Z
  722.  
  723. There exists a dedicated mailinglist for SmartList users, send your
  724. subscription requests to:
  725.  
  726.         SmartList-request@informatik.rwth-aachen.de
  727.  
  728. For procmail related questions not specific to the SmartList package
  729. you can also write to the procmail mailinglist, send your subscription
  730. requests to:
  731.  
  732.         procmail-request@informatik.rwth-aachen.de
  733.  
  734. There is a readonly announcement list to stay informed about new versions
  735. and official patches of both procmail & SmartList, send your subscription
  736. requests to:
  737.  
  738.         procmail-announce-request@informatik.rwth-aachen.de
  739.