.TH LISTMANAGER 8 .SH NAME .B listmanager - a mailing list maintenance package .SH SYNOPSIS .B listmanager [-dDmRv] [-c commands] [-C config] [-f name] [-p [sender]] [-P list] [-s list] [-S list] .SH DESCRIPTION .B listmanager is a package that efficiently maintains mailing lists. It can interact with list owners and subscribers via an e-mail interface, and system administrators can use the command line interface to set up configuration locally. The package was designed to be used with .B sendmail(8) but can probably work comfortably with other mail packages that accept (or at least tolerate) a similar set of command line options. .SH OPTIONS .TP .I -c commands executes the specified listmanager commands without going into interactive mode; if more than one command is specified, the list must be enclosed in quotes and commands must be separated by semicolons, e.g. "select testlist; show" .TP .I -C config sets the pathname of the first configuration file to .I config (see the FILES and CONFIGURATION sections) .TP .I -d runs a digest check on the mailing lists, sending any digests which are ready for sending because of exceeded limits or the list's digest schedule .TP .I -D enables debugging features, most notably the ability to bypass listmanager's "disabled" feature; not for use by anyone other than the author, and its results can be unpredictable and may change between versions; more instances of .I -D on the command line imply more debugging output .TP .I -f name sets the "full name" of the invoking user to .I name; this is generally used only by .B sendmail to pass in a full name when processing submissions or commands .TP .I -m runs maintenance on the mailing lists, which involves updating the list files that .B sendmail uses to distribute mail, rolling archives, and various other housekeeping chores; also implies the .I -d option .TP .I -p [sender] processes commands; .I sender is the optional address of the originator of the mail, which .B sendmail may pass in as an argument (sendmail is good at determining the originator's mail address, as it understands various comment and addressing styles, but listmanager will do this on its own if sendmail doesn't provide it) .TP .I -P list requests that listmanager preprocess all of standard input in order to determine what the contents of the message are and react appropriately; this is used when a list owner has requested that listmanager attempt to detect and filter commands sent to the "-request" address, or bounced mail from mailer daemons; mail that can be identified is handled automatically, and other mail is routed to the list owners for manual intervention .TP .I -R rebuilds the aliases table, adding, updating or removing entries to support lists that have been created, deleted or modified; this is normally invoked at least daily by .B cron(8) .TP .I -s list processes submissions; .I list is the list to which the submission was directed .TP .I -S list similar to -P, except this is used when the inbound mail might be a legitimate submission to the list; mail which can't be identified as commands or as a bounce is sent out to the list as a submission .TP .I -v verbose mode; produces some more detailed output to show what .B listmanager is up to; more instances of .I -v on the command line imply more verbose output .SH CONFIGURATION The configuration file consists of lines of text which are either comments (lines beginning with '#', which are ignored), blank lines (lines which are zero-length or contain only whitespace, which are also ignored) or parameter-value pairs. Unrecognized parameters are ignored. The parameter and its value must be separated by at least one whitespace character. Booleans accept values of "1", "on", "y", "yes", "t" and "true" to mean the positive, and "0", "off", "n", "no", "f" and "false" to mean the negative. The special parameter .I homedir identifies a directory from which other paths are based, unless an explicit path is specified (i.e. something starting with "/"). Any path parameter can use "~" as its first character, a la .I csh(1), to indicate a home directory path (e.g. "~root/foo" is a directory off of the home directory of "root" called "foo"). Simply "~" by itself will be interpolated as the home directory of the user executing .B listmanager. Below, if the default value is relative to the value of .I homedir, that will be indicated by the string .I HOMEDIR/path. The parameters recognized, and their respective meanings and defaults, are: .TP .I adminmail The address on the local machine to which errors are redirected and users are advised to direct inquiries about miscellaneous problems. Default is "listmanager-admin". .TP .I aliases The location of the mail aliases file. Default is .I HOMEDIR/aliases. .TP .I archdir The directory where list archives are maintained. Default is .I HOMEDIR/archives. .TP .I auxdir The directory where auxilliary list files are maintained, such as headers, footers, welcome messages, digests, etc. Default is .I HOMEDIR/files. .TP .I backupdir The directory where list rebuild scripts are written by the .I config command, used when rebuilding a list's configuration after removing the database file. Default is .I HOMEDIR/backup. .TP .I bodytag When the CGI generates a page as a result of some form being posted, this is used as the "body" HTML tag, so that the local system administrator can customize colours and so forth. The default is simply "". .TP .I cgipath Specifies the location of the listmanager CGI to be used for the web interface. This string is appended to "http://" to complete the URL to be referenced, and should give the local host's name and the path to the listmanager binary in an authorized CGI directory. There is no default, so if the web interface is to be made available, this .I must be set. .TP .I cmdpcnt Defines the percentage of a message body which should be commands for automatic processing to take effect; that is, if a list is marked "filtered" and a message is sent either to the list or the "-request" address, listmanager will preprocess the message and scan its contents, and if at least this percentage of the non-blank lines in the message body start with listmanager commands, the entire message is parsed as if it was mailed to listmanager directly. This is useful for picking up misdirected "unsubscribe" messages and so forth. Values over 1 are divided by 100 to render the value a floating point number between 0 and 1, so values of "80" and "0.80" are equivalent. The default is .I 80. .TP .I compress Path to a binary that can provide standard file compression service. Default is .I /usr/bin/compress. .TP .I configfile Continues configuration by using the named configuration file instead of the current one. Any subsequent parameter-value pairs in the current file are ignored, and processing begins in the new file. This allows chaining of configuration files where a partial configuration is distributed to many machines. The first configuration file read is defined by the .I -C command line parameter (or the default of .I /usr/local/etc/listmanager/options). The absence of a configuration file, be it the first or a subsequent file, does not produce an error, and the last value set for each parameter (or corresponding defaults) are used. .TP .I confirmdb The location of the database where subscription confirmation requests are stored. Default is .I HOMEDIR/confirm.db. .TP .I dbdir The directory which contains the databases for all active lists. Default is .I HOMEDIR/db. .TP .I debugdir The directory into which debugging information is placed. This is really only useful to the author and shouldn't be set otherwise. Default is .I HOMEDIR/DEBUG. .TP .I disabled The location of a file whose presence implies that .B listmanager is presently disabled and should instruct .B sendmail to queue mail-based requests and list submissions for later processing. The command line is always available whether or not this file is present. Default is .I HOMEDIR/disabled. .TP .I executable The full path name to the listmanager executable, used when generating aliases table entries. Default is .I /usr/local/bin/listmanager. .TP .I gzip Path to GNU's "gzip" binary. Default is .I /usr/local/bin/gzip. .TP .I helpdir The directory containing help files. Default is .I HOMEDIR/help. .TP .I homedir The base directory for operation of .B listmanager. This string specified here is used to replace HOMEDIR in any of the default values, and is used as the root of all relative paths provided in other path values. The default is .I /usr/local/etc/listmanager. .TP .I htmlfooter A file containing HTML code to place at the end of CGI output. If this is defined and the file exists, it must contain at least a and tag, as .B listmanager will not provide such. There is no default. If this value is not defined, or refers to a nonexistent file, listmanager's bland internal default is used (i.e. the string ""). Note that two interpolations are available; any instance of "%t" in the file will be replaced by the title .B listmanager wants to use for the CGI output, and "%b" will be replaced by the value of the .I bodytag configuration parameter. You may omit either or both to use your own values. .TP .I htmlheader A file containing HTML code to place at the top of CGI output. At the time this file would be used, .B listmanager has output a Content-type: header, an tag and a tag. The header file should therefore contain at a minimum header information followed by , and a tag. The same interpolations described under .I htmlfooter are available here as well. .TP .I ignore The location of a file containing mail addresses (with "*" wildcards allowed) which .B listmanager should silently ignore. In the case of submissions, if either the address shown in the "From:" or "To:" header matches an address in this file, listmanager drops the submission and exits. Default is .I HOMEDIR/ignore. .TP .I listdir The directory where address lists are placed for use by .B sendmail when distributing mailings. Each list produces four files: the list itself, a list of people who handle errors, a list of people who receive the digested form of the list, and a list of people who receive information requests about the list (for a list called "blah", the lists would be called "blah", "blah-errors", "blah-digest", and "blah-request"). Default is .I HOMEDIR/lists. .TP .I listname Adjusts the rules that decide what .B listmanager considers to be a valid list name when lists are created or renamed. Automatically, zero-length names, names containing characters other than alphanumerics and the hyphen ("-"), and names matching existing aliases or userids are considered invalid. These additional checks may be applied at the discretion of the system administrator. The value of this parameter is a string of zero or more letters in any order, each with a specific meaning: .I - rejects list names that start or end with a hyphen character, and names in which two or more hyphens are adjacent; .I 9 rejects list names whose length is less than nine characters, which is intended to prevent a list from consuming a possible UNIX userid; .I a rejects list names that do not start with a letter. The default is to use only the built-in tests. .TP .I lockdir The directory into which .B listmanager places lock files, used to prevent two instances of .B listmanager from accessing a database at the same time. Default is .I HOMEDIR/lockfiles. Note that this value is not used on systems with Berkeley-style file locking via .I flock(2), as lockfile locking is needed on those systems with completely stupid SysV .I fcntl(2) style file locking. .TP .I logopts Logging options. This is a set of zero or more characters which request certain additional syslogging by listmanager, usually intended for debugging and detecting installation problems. The recognized characters are: .B c causes listmanager to syslog the startup of the command line interface, and who it was that did so, indicating discrepancies between real and effective uids and gids; .B C causes listmanager to syslog commands issued via the command line interface; .B M causes listmanager to syslog commands issued via the mail interface; .B u causes listmanager to syslog the startup of the e-mail interface for handling submissions or commands, and what local user it was that did so, indicating discrepancies between real and effective uids and gids. Unrecognized characters are ignored. The default is the null string, implying no additional logging. .TP .I masquerade The domain/host name that .B listmanager should use in place of the local machine's hostname on outgoing mail. Default is none, which means use the local host's fully qualified hostname is used. .TP .I maxunrec Limits the number of unrecognized commands .B listmanager will accept via the mail interface before aborting processing and ignoring the rest of the message. This prevents unwieldy replies to misdirected or strangely encoded messages. The default is 5. This value only applies to messages sent directly to .B listmanager and not via a list's "request" address. .TP .I newaliases The UNIX command used to rebuild the aliases hash table after .B listmanager updates the text form of the aliases table. Default is .I /usr/local/bin/sendmail -bi. .TP .I pipelist The location of the authorized pipes list file. See the PIPES section for the format of this file. Default is .I HOMEDIR/pipelist. .TP .I queueflush The format of a command that causes pending mail to a list to be flushed. The string "%s" may appear once in the string provided which will be replaced by the list to be flushed. Default is .I /usr/local/bin/sendmail -qS%s -v. .TP .I responsedir The directory into which you should place templates for mandatory response files. See the help file "Responses" for more information. Default is .I HOMEDIR/responses. .TP .I sendmail The location and parameters of .B sendmail(8) or other mail transport agent which accepts a full mail message on standard input. This should also contain any command line options that cause that program to not treat a dot (".") on its own line as the end of input. Default is .I /usr/local/bin/sendmail -oiTrue. .TP .I storagedir The directory under which storage space for lists is created. Default is .I HOMEDIR/storage. .TP .I subtimeout A boolean, indicating whether or not submissions that attempt to access a list currently locked by another process should wait indefinitely for the lock to become available, or should time out and try again later. Default is "false", meaning the submission should wait indefinitely for the list to become unlocked. .TP .I syslog Specifies which syslog facility should be used by listmanager; any facility which is defined on the local machine can be selected. Default is "local4" for various historical reasons. .TP .I tempdir The directory where incoming messages are cached while they are checked against a list's size limitations, if set. Default is .I /var/tmp. This should be set to a directory on a filesystem which is pretty much guaranteed to have a good amount of disk space available, since many messages might be cached at once. .TP .I templates The directory where files containing lists of commands for use during list creation are stored. Default is .I HOMEDIR/templates. .TP .I umask Sets the process umask for file creation. The default is 022. .TP .I uuencode Path to a binary that can provide standard uuencoding service. Default is .I /usr/bin/uuencode. .TP .I webacl If defined, specifies an access control list to govern what clients may request creation of lists and perform administrative list functions via the web interface. If not defined, access is not restricted based on the client's origin. .TP .I webcreate Controls what can be done when requesting list creation via the web interface. The value of this parameter is a string of zero or more letters in any order, each with a specific meaning: .I d causes any created lists to have the "disabled" flag set (see the help files), meaning the list may not be adjusted or modified in any way until an administrator removes that flag, thereby approving the list's existence; .I n causes mail to be sent to the administrator whenever a list is created; .I y permits creation of lists via the web interface, and the absence of this character therefore blocks such creations. The default is the null string which, since it doesn't contain .I y denies the ability to create lists via the web interface. .SH COMMANDS There are many commands which .B listmanager understands, via both the command line interface and the mail interface. These are too numerous and too volatile to make keeping this section of the man page easily accomplished. Thus, from either interface, use the "help" command to get information about the current set of commands, list flags, member flags, and other topics to guide you and others through the operation and features of .B listmanager. .SH PIPES .B listmanager supports the idea of importing a list of subscribers to a list from an external program. In the interests of convenience and security, this is controlled by a file called the "pipelist" whose location is determined by the "pipelist" configuration parameter (see the CONFIGURATION section above). The file allows list owners to select a command to be run by using an alias, or a simple word describing a program's invocation which can be more complex. It also allows system administrators to arrange to run these external programs as some other user, if .B listmanager is running as the superuser already. The format of the file is: alias list user regexp command ...where .I alias is the simple word by which this external command is referenced; .I list is the name of a list which may reference this external command, or "*" if any list should be allowed to do so; .I user is the userid .B listmanager should try to become when executing this external command, or "-" if no change in userid should take place (this should always be "-" if listmanager doesn't run as the superuser); .I regexp is an .B egrep(1) style regular expression that should be used to select lines of output from the pipe, i.e. only those lines that match will be added as list subscribers; if pattern matching is desired, the regular expression must start and end with a slash ("/") character; if no pattern matching is desired (i.e. all lines should be added to the list), this field should simply be "-"; and .I command is the command to be executed when this alias is referenced; the entire command string must appear here, and if it contains options or spaces, enclose the command in quotes; standard search rules apply so explicit paths are not necessary (but are recommended). For example: oracle-query * - /@/ "/usr/local/bin/oracle-query -d" creates an alias called "oracle-query" which can be referenced by any list. It runs as the same user as the listmanager program. Only lines containing "@" are considered, and the program to be executed is "/usr/local/bin/oracle-query -d". all-users local-announce nobody - /usr/local/bin/parsepwd creates an alias called "all-users" which can be referenced only by the "local-announce" list. When called, it runs as "nobody" rather than the superuser. All lines output by the external program are considered valid addresses for subscription, and the external program to be run is /usr/local/bin/parsepwd. .SH FILES .TP .I /usr/local/etc/listmanager/options default location of the configuration file .SH AUTHOR Murray S. Kucherawy (msk@blackops.org) .SH COPYRIGHT Copyright (c) 1994-2001, Murray S. Kucherawy .SH AVAILABILITY The latest binaries, help files, release notes, instructions and this man page are available for download from http://www.listmanager.org. Binaries exist for Linux v2.2.20, BSD/OS v4.0, FreeBSD 3.5, OpenBSD v2.5 (both Sparc and i386 versions), and Solaris v2.6 and v2.7. Source is currently considered proprietary and is thus not yet available. .SH NOTES Thanks to the subscribers of listowners@blackops.org for being my guinea pigs so far. I hope using listmanager has been as fun for you as it has been for me to develop it. Compiler environments other than my own were provided by Matt Kucherawy of Rassilon Networking Corporation (BSD/OS 4.0). Gregory Neil Shapiro of Retsiger (FreeBSD 4.2), Jan Beisser of Caustic Dot Org (FreeBSD 3.5), Darren McKeeman of Gothic.Net Internet Services (Solaris 2.6), Joe Abley (OpenBSD 2.5 Sparc), and Matt Westervelt of uber-gawth productions (Linux). MIME support provided by David Collier-Brown (davecb@sietec.com) using his publicly-available source code. .SH BUGS Report bugs to listowners@blackops.org. .SH SEE ALSO dbopen(3), sendmail(8)