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@<your-host-name> with listmanager commands in the message
body. Again, "help" is a good place to start.
NOT RUNNING AS ROOT
===================
[contributed by Gregory Shapiro <gshapiro@gshapiro.net>]
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.