listmanager -- A mailing list manager Copyright (c) 1994-2001, Murray S. Kucherawy (msk@blackops.org) $Id: INSTALL,v 1.10 2001/02/22 09:22:01 msk Exp $ DISCLAIMER: The author of the software assumes absolutely no liability for damage or loss resulting from installation or use of this software, however caused. The author is also disclaimed from responsibilities of warranty for the software's proper operation. Use at your own risk. Listmanager was designed originally under Digital UNIX v3.2C. It is now primarily developed and maintained on OpenBSD v2.5, although ports are also produced for Linux, FreeBSD and Solaris as well as a few others. COMPILATION INSTRUCTIONS ======================== Source code is proprietary and is thus not (yet) available to the public. Please don't ask about it if you don't already have it. Compile using the traditional "./configure" method provided with most GNU packages. Options of interest: --with-readline[=DIR] Instructs the build to try to include support for GNU's readline library. DIR is assumed to be /usr/local if it's not explicitly specified. The directory must contain lib/libreadline.a and include/readline/readline.h, etc. --with-aliases=DIR Identifies the directory containing the sendmail aliases table, if different from the current sendmail default which is /etc/mail. --with-db=DIR Identifies the location of the Berkeley DB installation, if different from the default of /usr/local/BerkeleyDB. Berkeley DB must be compiled with the --enable-compat185 option. --localstatedir=DIR Specifies the location of the top of the local machine's local data directory. Dynamic information useful only to the local installation goes here (e.g. data files). Defaults to /usr/local/var. Listmanager will install its data in DIR/listmanager. --datadir=DIR Specifies the location of the top of the local machine's shared data directory. Static information useful on any architecture goes here (e.g. help files). Defaults to /usr/local/share. Listmanager will install its data in DIR/listmanager. The build procedure is thus: % ./configure [options] % make % make install to install the binary % make install-man to install the man page % make install-dirs to create the directory structure and install help files Follow the steps under EDITING ALIASES (further below) and SETTING UP CRON JOBS (even further below), and you're done. INSTALLATION INSTRUCTIONS ========================= Grab the latest binary for your operating system from http://www.listmanager.org. While you're there, grab the "responses" tarball and the "help" tarball and the man page. Install the binary in /usr/local/bin (or wherever you like), and make it owned by root and in group daemon, and mode 4510. Install the man page in /usr/local/man/man8. Below are the instructions for creating the directories listmanager needs to run. You can override all of these locations in the configuration file and choose your own, if you wish. However, these instructions assume the defaults. Listmanager looks for its configuration file (mandatory) in /usr/local/var/listmanager/listmanager.cf and, failing that, in /etc/listmanager.cf. You should create a configuration file in the latter location which describes your alternative directory structure. See the man page for information about the configuration file. Create the following directories: /usr/local/var/listmanager /usr/local/var/listmanager/archives /usr/local/var/listmanager/backup /usr/local/var/listmanager/db /usr/local/var/listmanager/files /usr/local/var/listmanager/lists /usr/local/var/listmanager/responses /usr/local/var/listmanager/storage /usr/local/share/listmanager /usr/local/share/listmanager/help They should all be owned by root and in group daemon. For security reasons, /usr/local/var/listmanager should be mode 0750. Unpack the help tarball into /usr/local/share/listmanager/help. Unpack the responses tarball into /usr/local/var/listmanager/responses. Create empty configuration and ignore files in /usr/local/var/listmanager/listmanager.cf and /usr/local/var/listmanager/ignore. RUNNING AS ROOT =============== The phrase "Listmanager runs as root all the time" bothers a lot of people so this will soon be untrue. What will probably happen instead is that listmanager will require its own account, and that account will own all files associated with the operation of the service. The trick is getting sendmail to trust files owned by that user and not complain about them, so it may be necessary to provide information about further sendmail configuration issues at installation time. PER-OS BUILD NOTES ================== SOLARIS: o You must include /usr/ccs/bin in your path to get some important binaries needed, such as "ar". EDITING ALIASES =============== At some appropriate point in your sendmail aliases table, add: listmanager: "|/usr/local/bin/listmanager -p" At the end of your aliases table, add this: ----- 8< -- snip -- 8< ----- # Listmanager additions #% #% ----- 8< -- snip -- 8< ----- Listmanager will insert all of the aliases it requires in between the two "#%" markers each time it rebuilds the aliases table. You also need to define "listmanager-admin" as an alias to which people can direct requests for help when something goes wrong. Listmanager will use this address in error reports. It can be modified by the values in the configuration file; see the man page for more information. SETTING UP CRON JOBS ==================== The final step in the installation is to add three jobs to cron so that sendmail and listmanager control and data files are updated regularly. The three crontab entries you need to add are: 00-44,46-59 * * * * /usr/local/bin/listmanager -d 45 * * * * /usr/local/bin/listmanager -m 0 6 * * * /usr/local/bin/listmanager -R The first job does a digest check every minute, which makes the digest schedule feature work. You should arrange that this is run every minute except during the minute that the second job is run, since the functions of the second job are a superset of the functions of the first. If this creates a lot of load on your machine (e.g. if you have a lot of lists), you can still get accurate performance by running it every five minutes. The second job should be run with reasonable frequency (an hour seems to be perfect). It takes the list databases and turns them into actual mailing lists, which sendmail expands when a submission arrives. The more frequently you run this, the faster things like external database changes actually take effect. It's a little on the I/O intensive side, so don't run it too often. The third job actually rebuilds your aliases file, adding or removing lists that have been added or removed since the last rebuild. It looks for the "#%" markers and replaces everything between them with a fresh set of aliases for your lists. Listmanager isn't yet intelligent enough to know when this isn't necessary (i.e. when no lists have been added or removed since the last rebuild). Very large aliases files (8000+ records or so) take a long time to rebuild and can jam up a system where lots of jobs are waiting to do lookups on the aliases database, which is why this function isn't performed with every update. Once a day seems fine for my scenario; people seem to be able to tolerate the idea that a list created on day "n" won't actually be available until day "n+1". THAT'S IT ========= Listmanager should now be installed and functioning. To access listmanager from the shell (the administrator mode), type "listmanager". You'll get an "lm>" prompt. Type commands at the prompt and away you go. "help" is a good place to start. To access listmanager via e-mail (what most people do), send mail to listmanager@ with listmanager commands in the message body. Again, "help" is a good place to start. NOT RUNNING AS ROOT =================== [contributed by Gregory Shapiro ] It is possible to run listmanager without making it set-user-id root. The instructions below assume the sendmail's default user is mailnull and default group is mailnull. By default, sendmail will use mailnull if that account exists. So you should have an /etc/passwd entry such as: mailnull:*:666:666:Sendmail Default User:/var/spool/mqueue:/sbin/nologin and an /etc/group entry such as: mailnull:*:666: Back to the listmanager instructions: 1. Create a new account for listmanager. For example, in /etc/passwd: listmgr:*:777:777:List Manager:/var/listmanager:/sbin/nologin and in /etc/group: listmgr:*:777: 2. Make /usr/local/sbin/listmanager owned by listmgr and group mailnull with mode 4710: -r-s--x--- 1 listmgr mailnull 639623 Feb 9 21:11 listmanager 3. Make /usr/local/etc/listmanager.cf world readable: -rw-r--r-- 1 root wheel 483 Feb 12 22:16 listmanager.cf 4. Configure listmanager to use /var/listmanager/aliases instead of /etc/mail/aliases and /var/listmanager/tmp for a temp directory: aliases /var/listmanager/aliases homedir /var/listmanager tempdir /var/listmanager/tmp 5. Make /var/listmanager permissions match the following: mkdir -p /var/listmanager/{archives,backup,db,files,lists,responses,storage,tmp} chown -R listmgr:listmgr /var/listmanager chmod -R o-rx /var/listmanager chmod o+x /var/listmanager{,/lists} chmod o+r /var/listmanager/lists/* (create /var/listmanager/aliases as instructed elsewhere) chmod 0644 /var/listmanager/aliases 6. Configure sendmail to trust listmanager for rebuilding the aliases database: define(`ALIAS_FILE', `/etc/mail/aliases, /var/listmanager/aliases') define(`confTRUSTED_USERS', `listmgr') 7. Install the new sendmail.cf, restart sendmail, and start testing. TROUBLESHOOTING =============== (1) Sendmail bounces submissions with "Permission denied" errors. When sendmail tries to read a list for distribution, it usually (depending on configuration) relinquishes its superuser access and operates as some other user, usually "daemon". As such, the files which contain the lists of subscribers must be readable by sendmail once it changes from being "root" to "daemon". You should be able to do this without compromising the privacy of the lists. To find out what your sendmail will change to in order to run listmanager, look for a line that starts "Ou" (for version 5 or earlier configurations) or "O DefaultUser" (for version 6 and up configurations). Similarly, for the group ID, look for "Og" (for earlier configurations) or note the second value of the "DefaultUser" parameter, if defined (for newer configurations). As long as sendmail can execute listmanager, and as long as sendmail can read the lists it produces, things will work properly. (2) I get "in-core dbopen(): No such file or directory" errors. [reported by blh@nol.net] Listmanager sometimes creates temporary databases, part of which are in memory and part of which are on disk. When trying to create the on-disk portion, the database library used by listmanager will check for the existence of an environment variable called TMPDIR, which specifies which directory to use for creating temporary files. If this variable is not set, /tmp is used. If this variable is set and points to a directory that does not exist, the error above is produced. The solution is to unset the variable, or set it to a directory to which you have write and execute access. MAILING LIST ============ There's a mailing list where listmanager bugs, features, concerns, questions, answers, and panic from confused list owners are discussed. The list is listowners@blackops.org. Oddly enough, it's controlled by the most recent production version of listmanager, so you subscribe by sending subscribe listowners to listmanager@blackops.org. You really should subscribe to this, because I don't post update announcements or anything like that to any other public place yet.