ListManager Release 3 ********************* (C) Copyright 1995-1997 by hartmut Goebel. This program is 'Giftware'! $Id: ListManager.doc,v 1.4 1995/11/17 01:10:40 hartmut Exp $ Copyright and other legal stuff ******************************* Copyright ========= ListManager Release 3 and this documentation are (C) Copyright 1995-1997 by hartmut Goebel hartmut Goebel Aufseßplatz 5, 90459 Nürnberg, Germany By releasing this program as 'Giftware' I do not place any obligations on you except the ones mentioned below. If you like this program and use it frequently, I would like you to send me a gift of any kind which you think will do as a 'payment' for *ListManager*. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. No program, document, data file or source code from this software package, neither in whole nor in part, may be included or used in other software packages unless it is authorized by a written permission from the author. Permission is given to include this package into official release packages of UMS. ListManager Release 3 is based on ListManager.rexx, which is (C) Copyright 1993-1995 by Martin Horneffer, Kai Bolay and hartmut Goebel. No Warranty =========== There is no warranty for this software package. Although the author has tried to prevent errors, he can't guarantee that the software package described in this document is 100% reliable. You are therefore using this material at your own risk. The author cannot be made responsible for any damage which is caused by using this software package. Distribution ============ This software package is freely distributable. It may be put on any media which is used for the distribution of free software, like Public Domain disk collections, CDROMs, FTP servers or bulletin board systems. In order to ensure the integrity of this software package, distributors should use the original archive file ListManager.lha. The author cannot be made responsible if this software package has become unusable due to modifications of the archive contents or of the archive file itself. There is no limit on the costs of the distribution, e.g. for the media, like floppy disks, streamer tapes or compact disks, or the process of duplicating. Such limits have been proven to be harmful to the idea of freely distributable software, e.g. instead of reducing the price of the floppy disk below the limit, the software was simply removed from the master disk. Although the author does not impose any limit on the distribution of this software package, he would like to express his personal opinions on this matter: * This software package should be made available to everyone free of charge whenever it is possible. * If you have acquired this software package under normal conditions from a Public Domain dealer on a floppy disk at a price higher than 5DM or US $5, then you have definitely paid too much. Please don't support this improper profit making any longer and switch to a cheaper source as soon as possible. Usage Restrictions ================== No program, document, data file or source code from this software package, neither in whole nor in part, may be used on any machine which is used * for the research, development, construction, testing or production of weapons or other military applications. This also includes any machine which is used in the education for any of the above mentioned purposes. * by people who accept, support or use violence against other people, e.g. citizens from foreign countries. Indroduction ************ ListManager is a mailing list tool for the Universal Message System (UMS). It does not only ease handling of subscribed mailing lists (client mode) but also can serve them (server mode). In both cases ListManager works as an news-mail gateway, too. In client mode ListManager sorts mails from incoming mailing lists into local newsgroups (import mode) or sends postings in this newsgroups to the corresponding mailinglist (export mode). In server mode - well - ListManager serves mailing lists. In this case it sends all messages received to the subscribers of the mailing list, too. Messages are forwarded both from the lists mail account and the newsgroup corresponding to the mailing list. Starting with version 2, ListManager supports admins for every list. Admins will get some messages from ListManager and mails to the special list-admin alias. Most people will not need this, or only when they are away for a longer time. For details see Admins. Most people will use only client mode. Just skip the parts about server mode here in the docs :-) Requirements ============ ListManager Release 3 requires: * AmigaOS 2.04 (V37) or higher * UMS V11 (V11) or higher * ... nothing more IMPORTANT NOTE for users of V1.20/2.x: ====================================== 1. The term *owner* has been replaced by the more appropriate term *admin*. As a consequence the configuration variables `ListManager.Owner' and `ListManager..Owners' have been renamed to ListManager..Admins and ListManager..Admins respectively. UpdateLMConfig.rexx will do the renaming for you. 2. The format of ListManager.Mailinglists, ListManager..Status, ListManager..Users and ListManager..Admins has changed (see below). Use UpdateLMConfig.rexx for conversion. 3. Access check matches `name ' (without quotes). You have to change your ListManager..Access variables manualy. How does it work? ***************** Client Mode =========== * All incoming mails are scanned for REPLYNAME matching `Mailinglist '#?'' (case insensitive). These mails were put into the newsgroup `mailinglist.#?', where `#?' is substituted by the `#?' of the above pattern. E.g. `"Mailinglist 'blafasel'"' goes into newgroup `mailinglists.blafasel'. The prefix `mailinglist.' may be changed using ListManager.GroupPrefix. If a mailinglist does not set a REPLYNAME like this, you can use Klaus Melchior's programm SetFolder in order to correct the REPLYNAME. * The mailinglists name and address determined in the first step are added to the config variable, if not already present. The address is updated automaticaly from the REPLYADDR field if necessary. * For each known mailing list the corresponding newsgroup is scanned for new postings. These are forwarded to the mailinglist by sending it to the address found in the config variable. Server Mode =========== * Server mode implies client mode. * All mails to the ListManager deamon account are processed as control messages. This includes subscription, help and some more commands (see Commands). All outgoing mail messages will get the `junk' flag set, so you will not be bothered with them. Further they will be put into a folder named after ListManager_Server. * All mailing lists found in the config variable ListManager.Mailinglists to be served here are processed as follows: - All mails for the mailing list are forwarded to the subscribers. In this mode TONAME is tested instead of ReplyName (we are the list :-). - If a groupname is defined for this list (see ListManager..Group), the messages are also posted into the corresponding newsgroup. - All new postings in the corresponding newsgroup (if defined) are forwarded to the subscribers. - A trailer will be appended to each messages, which may be freely configured. If no trailer is specified, nothing will be appended. ListManager..Trailer. All outgoing mail messages will get the `junk' flag set and be put into the folder `'. * All mails to the list admin alias will be forwarded to the Admins. They will get the `junk' flag set and be put into the folder `-Admin'. Config Locking / Semaphore ========================== To avoid problems ListManager locks the configuration variable ListManager.Mailinglists. Thus this variable can not be changed while ListManager is running. It's obvious that changing other ListManager variables while ListManager is running is dangerous! Usage ***** ListManager can only be started from CLI/Shell, Workbench is not supported. Template: NAME=USER,PASSWORD,SERVER/K,LOOP/K,DEBUGLEVEL/N/K `NAME=USER' `PASSWORD' `SERVER' UMS standard command line options (defaults to `lists "" ""') `LOOP' Never quit ListManager just run it in a loop. After one loop is completed the supplied command is started. When this command returns an error (return value 10 or higher) looping is aborted. ListManager may also be aborted by CTRL-C. `DEBUGLEVEL' Messages with log level lower or equal this value are not only written to the UMS Logfile, but also to StdIO (default: 5). Known Server Commands ********************* These are the commands, ListManager understands: `HELP' Send the helpfile as seperate message. `ADD List/A,Name/K,Addr/K' `SUBSCRIBE List/A,Name/K,Addr/K' Subscribe somebody to a list. `REMOVE List/A,Name/K,Addr/K' `DELETE List/A,Name/K,Addr/K' `DEL List/A,Name/K,Addr/K' `UNSUBSCRIBE List/A,Name/K,Addr/K' Unsubscribe somebody from a list. `DESCRIPTION List/A' `DESC List/A' `INFO List/A' Send the list's description file as seperate message. `END' `STOP' `QUIT' Stop processing the mail `LISTS' `INDEX' List all served Mailinglists. `USERS List/A' `WHO List/A' List all users subscribed to a given list. `WHICH Name' List all lists, a given user has subscribed. `APPROVE Password/A,Command/A,Args/F' Special command for admins to pass the password to commands supporting access restrictions (see list below). Please note: this command is intentionally not in the user's helpfile. For detailed information, please refer to the example helpfile. Commands supporting access restrictions ======================================= The following commands support access restrictions via ListManager..Password or ListManager..Access: `Subscribe' (and synonyms) `Unsubscribe' (and synonyms) `Users' ... others to come Installation for Client Mode **************************** For using ListManager in client mode, you need ... ... One User, ... ================= For using ListManager, it's quite useful to have an extra user who gets all the mailinglists. The suggested name is `lists'. For security reasons restrict `Export', `WriteAccess' and `NetAccess' as far as possible. If you are not able to use an extra deamon user you must use the ListManager.NoDeamonAccount configuration. The only valid reason for not using an extra user is that you can only use exactly one email address, e.g. when using POP mail). ListManager.NoDeamonAccount invokes a lot of magic. It's very tricky. We propose the use of an extra user for this deamon stuff handling whenever possible. If you are subscribed to a Mailinglist which does not create a REPLYNAME in the form of `Mailinglist 'Listname'' please use Klaus Melchior's programm SetFolder in order to correct this. Mind the Exporters ------------------ Mind the `ReadAccess' pattern of all your exporters! If this is set up wrong, you will export the mailing list as newsgroup. This is especially important for confidental mailinglists. ... One Variable ================ ListManager will automatically add all incoming mailinglists into its config variable. For the case you got some postings to be exported to mailinglists not already present in the config variable, just add an entry. The lines will be parsed one by one using ReadArgs with template `Name,Addr'. ( ListManager.Mailinglists "Oberon-A oberon-a@wossname.apana.org.au\n" "AMOK amok-l@listserv.uni-stuttgart.de" ) If only using client operation further configuration is not nesseccary! Optionally you may set a variable: `ListManager.GroupPrefix' This variable defines the prefix listgroups in Intro. This will be postfixed with the `#?' part of the REPLYNAME's matching pattern `Mailinglist '#?''. E.g. if `ListManager.GroupPrefix' is `local.ml.' then `"Mailinglist 'blafasel'"' goes into newgroup `local.ml.blafasel'. Again: Mind the `ReadAccess' pattern of your exporters (see ClientMode). *optional, default: "mailinglist."* `ListManager.NoDeamonAccount' This is only useful if the ListManager runs on a real-user account. Set the contents of this variable to `Y' (or `y') to enable this option, anything else to disable. Please note: This is *not* suggested usage. Please use an extra (deamon) user whenever possible. If it isn't possible for you to use an extra user for mailinglist handling (because you are limited to a single mail address e.g. due to POP) ListManager uses a userflag instead of OLD to determine which messages from newsgroups must be exported. This flag is automatically reserved by using the config variable `flags.user'. Please check all other UMS tools which use userflags in order to avoid conflicts. If a tool does not support `flags.user' please notify the author! Installation for Server Mode **************************** Okay, this is for the guys willing to run a mailinglist. This may look a bit complicated but this is just do keep some nerds away ;-) First of all you need an alias for your Deamon, suggested names are `ListServ' or `request'. This may be the deamon user's name, but this is not suggested since you may use the same deamon account for other purposes (ListManager_Server). You also have to set the alias `postmaster' to your own account if you did not already. Users of the lists are instructed to send questions to this alias. Please note: When using ListManager.NoDeamonAccount it's not possible to run ListManager in server mode. Then you need a bunch of extra config variables for handling the server stuff: `ListManager.Server' This is the alias of the pseudo-user which handles all requests. All mails with this TONAME set are handled as control messages. The presence of this varibale is taken as indicator whether to run in server mode. Enter here the alias you just created. Suggested names are `ListServ' or `request'. It's not suggested to use the deamon user's name since you may use the same deamon account for other purposes, e.g. BugsManager. You may add several aliases, one per line, which will be checked. The first alias will be used when sending messages. This is very helpfull to get misspelled names, like `ListServer' instead of `ListServ'. Empty lines are ignored, but the first line *must not* be empty. The first alias given will be taken as FromName when ListManager sends out messages, like the help-file. This alias is also the name of the folder such messages will be put in. Please note: Do make this feature work as expected, all the names in this list should be aliases of the deamon user. `ListManager.HostName' The name of your host. In almost all cases this is identical to `rfc.domainname'. `ListManager.Admin' Alias for the *admin* of ListManager, this is the person to maintain setup, etc., usually the postmaster. This is used to generate the `Errors-To:'-Header, the footer and several other texts and message fields. *Optional, default: `postmaster'.* `ListManager.HelpFile' Filename (including path) of a file describing the usage of ListManger. Best to take the example helpfile included with the distribution. Change the e-mail addresses at the top and bottom of the text to suit your needs. *Optional but suggested.* `ListManager.Trailer' Format of the informational trailer to be appended to every served message. If no trailer is specified or the trailer is an empty string nothing will be be appended. *Optional but suggested.* The Info-Trailer ================ To each messages forwarded in server mode an information trailer will be appended. If no trailer is specified, nothing will be appended. The format of the trailer may be freely configured, the string may contain some special commands: `%a' If there are Admins defined for this list, the alias `-admin' will be put here, otherwise ListManager_Admin. `%h' Hostname, the contents of ListManager_HostName. `%n' the list name, e.g. `duerer-klatsch' `%v' the server alias `%c' center this line `%_' fill this line with undersores *Please note:* * The width used for `%x' and `%_' is the length of the longest line plus 2. * `%x' and `%_' are not designed to be used together in one line; so if you use them this way, you may get unexpected results. * `%x' and `%_' are only recognized within the first 32 trailer-lines. But you should restrict the trailer to a few lines anyway! The trailer should contain the name of the mailinglist, the address of the Admins and the address of the server (where to send requests). The format ListManager.Trailer ( "%_\n" "%cMailinglist '%n' Admin: <%a@%h>\n" "%cSend listserv-requests to <%v@%h>" ) will lead to a trailer like this: ___________________________________________________________ Mailinglist 'WRITE' Admin: Send listserv-requests to `ListManager.Reject.Address' Every subscriber's address is checked against this pattern. If it matches, the request will be rejected. This is thought to exclude domains from subscription which caused repeated problems. Please note: Only the address part will be checked. *Optional* `ListManager.Reject.Subject' NOT YET IMPLEMENTED! The subject of every message to be forwarded by ListManager is checked against this pattern. If it matches, the message is asumed to be a request and will not be forwared to the list. The sender of the message will get a note about this fact. *Optional but suggested.* Per-list configuration ********************** Now you have set up the ListServer but there are no mailing lists specified to be served. This is what has to be configurated for each mailinglist. First of all you need three more aliases for your (deamon) user. So if you are serving `testlist' the appropriate UMS user must have the aliases `testlist', `Mailinglist 'testlist'' and `testlist-Admin'. The last one is to reach the admins of the list (see below). `ListManager.Mailinglists' This variable is well known from client operation. Those lists without an address are run in server mode. Example (only 'My List' is served by the local system): ( ListManager.Mailinglists "Oberon-A oberon-a@wossname.apana.org.au\n" "\"My List\"\n" "AMOK amok-l@listserv.uni-stuttgart.de" ) The lines will be parsed one by one using ReadArgs with template `Name/A,Addr'. Add an appropriate entry the this variable. `ListManager..Alias' If a list is named `Testlist' ListManager automatically scans for mails to the names `Testlist' and `Mailinglist 'Testlist''. If you want ListManager to check an additional alias you can specify it here. *optional, default: none* `ListManager..Group' Name of the newsgroup corresponsing to the mailinglist. Suggested name is `mailinglist.'. If you ommit this variable ListManager does not gate the mails to any newsgroup. *optional, default: none* `ListManager..Descfile' Filename (including path) of a file containing a short description about this mailinglist. This text can be requested using the command `DESCRIPTION'. *optional, default: none* `ListManager..Status' This allows further configuration for the list. Just put in here the option keywords you want. Some synonyms have been added to avoid confusion :-) *optional, default: ""* Private MembersOnly Only subscribers can write to the list. Please note: Everybody can subscribe to a private list! Use ListManager..Password or ListManager..Access to make the list a 'closed' one. Moderated (not yet supported) Digest (not yet supported) `ListManager..Password' Generally everyone can subscribe to your Mailinglists just by sending a control message to Listmanager. You can restrict the use of some ApproveCommands setting a `Password' for the list to be used together with the APPROVE command: APPROVE will pass it on to the real commands to check it. If a password is set for this list, ListManager..Access is ignored! *optional, default: none* Please note: An empty password will not work! `ListManager..Access' Generally everyone can subscribe to your Mailinglists just by sending a control message to Listmanager. You can restrict the use of some ApproveCommands to certain users by setting `Access' to a pattern which must match the address of the user sending the control message. The address is tested using the format `name ' (without quotes). Matching is done via `UMSMatchPattern()', thus you can use UMS' multi-line pattern. If a ListManager..Password is set for this list, the access pattern is ignored! *optional, default: "#?"* `ListManager..Trailer' Format of the informational trailer to be appended to every served message. If no trailer is specified nothing will be be appended. *optional, default: ListManager.Trailer* `ListManager..Users' This will hold the names and addresses for the subscribers of the list, automatically maintained by ListManger. Example: ( ListManager.Testlist.Users "" ) The lines will be parsed one by one using ReadArgs() with template `Name,Addr'. And here's an example with some entries, just in case you need it: ( ListManager.Testlist.users "\"Joe User\" joe@site.sub.org\n" "\"Otto Normalverbraucher\" lists@verbrauch.in.de\n" ) The List Administrators *********************** For now list admins will only get all the mails send to `-Admin'. This alias will be put into the trailer if `%a' is used there. Future versions of ListManager may use admins for automatic reports, checking access rights and so on. If no admins are specified for a list, the alias defined in ListManager_Admin (which defaults to `postmaster') is the admin of the list. Thus most users of ListManager will not need this feature. But you may use this to delegate administration of a certain list to one or more persons. ListManager..Admins This will hold the names and addresses for the admins of the list. Format is the same as for ListManager..Password. *optional, default: ListManager.Admin* History And Future ****************** Important Changes ================= This lists only the important changes, since I don't want to bore you with things like "improofed error-handling" :-) * since V3.26 - fixed: some bugs in case NoDeamonAccount * since V3.24 - fixed: imported mails were not marked as read * since V1.20/2.x - Trailer may now be configured individually - completly re-written in Oberon-2 - CheckAccess now matches "name " - ListManager.Mailinglists, ..Users and ..Admins are now parsed through ReadArgs(). UpdateLMConfig.rexx converts this variables. - use ReadArgs() for .Status: this enables spelling names and more options (on the long run) - added synonym for .Status: Private=MembersOnly - new config var ListManager.GroupPrefix for changing group prefix for client mode - ListManager.Server may no hold several aliases, one per line - ListManager.MailingLists is now locked and used as a semaphore. - may securely be interupted by Ctrl-C - Loop will be aborted if loop-command returns ERROR (10) or higher. Todo -- not all is done yet =========================== * priority: high - support for requesting FAQ texts - support for sending several files when subscribing - generate reports following ReportGuide - fully integrate Matthias Scheler's MailServ: - reject test for subjects - local address check - ... * priority: medium - ListManager_Admins.doc - complete RFC-Headers, set Fido-Headers for Deamons. - Digest, Moderated * priority: low - better texts - complete Admins support (check pgp keys, more commands, etc.) - make lists maintainable by admins via mail - put all msg into an optional folder (should be easy to implement) --> Kai has been asked to send a patch. - approve tool Other useful tools ****************** SetFolder ========= SetFolder is a mighty tool written by Klaus Melior. SetFolder filters mails and sets the folder, as the name suggests. But further SetFolder may also set REPLYTO and REPLYNAME. Thus it can be used to make messages recognizable by ListManager. Here's an example configuration for SetFolder: ( SetFolder.Folder "AMOK-L Comments \"#?(To|Cc): #?amok-l@#?.uni-stuttgart.de#?\" \"Mailinglist 'AMOK',amok-l@listserv.uni-stuttgart.de\"\n" "Envoy-L ReplyAddr \"beta@iam.com\" \"Mailinglist 'Envoy',beta@iam.com\"" ) Acknowledgements **************** I would like to thank Martin Horneffer For writing UMS and ListServer.rexx, the ancestor of ListManager.rexx. Kai Bolay For ListClient.rexx, ListServer.rexx, ListManager.rexx and for many remarks. Thomas Wagner whom I have to thank always :-) and esp. for proof-reading the new documentation. Matthias Scheler for the source of his MailServ so I may integrate it's features into ListManager. Frank Bornemann