Majordomo Documentation

This is the README for majordomo version 1.92. This is an interim release while majordomo 2.0 is being designed and coded.

This readme is structured as follows:

What's New

Installation

Using Majordomo

Other Documentation

Mailing Lists/Support

Conclusion



WHAT'S NEW

There are a number of new features in majordomo and its associated commands.

With Majordomo

The changes in majordomo are:

Return to index


With resend

Most of resend's options can be controlled remotely using a configuration file including:
A number of features have been added to resend that are also able to be controlled remotely.

Return to index


With digest

Brent Chapman's digest program has been integrated with majordomo. As with the rest of the programs, the config file can be used to set all of its parameters including: In addition to the above, the config file version allows arbitrary headers to be added to the outgoing digest.

Return to index


Contributions

The following contributions are all pretty much use at your own risk, in some cases they have actually been tested by multiple people and found to work nicely, in other cases they haven't been tested at all. So as they say on TV, your milage may vary.

We have three different types of archive programs:

  1. A simple hack by John Rouillard that uses the RAND MH mail system to handle splitting articles into separate files. (archive_mh.pl)
  2. One written by Brent Chapman that handles daily, monthly and yearly archives as well as splitting current archive files into yearly, monthly, or daily archives. (archive2.pl) This will become the standard version that will be integrated into a future version of majordomo.
  3. One written by Alan Millar that produces Listserv style archives. (archive.pl)
Three accessory scripts
  1. digest.send A simple shell script by Paul Pomes that can be run out of cron to send digests.
  2. logsumary.pl which summarizes majordomo logs written by Paul Close.
  3. makeindex.pl which provides CONTENTS and INDEX files for a directory of archives. Written by Paul Close.
Patches to majordomo which are usefull, but arrived too late to be tested and included as part of majordomo proper. Use at your own risk.
digest.diff by Paul Close.
Here are my changes to digest which support config file settings for specifying the digest size in lines and/or the maximum age of the oldest article, in days. Also support a new flag, -p (for "push"), intended for use by cron jobs. It checks to see if a digest should be sent, and sends it if it should (pretty well because an article is too old, but you could use this to send all the time).

mod_addr.diff by Arnold de Leon
The enclosed diffs allows a moderator to specified. resend will bounce mail to the moderator instead of owner-listname.

Line numbers may vary since I have other changes in my copy. Thanks to rouilj@terminus.cs.umb.edu for the pointers on what changes needed to be made.

Return to index


INSTALLATION

General Installation Instructions

The system should have its own uid and gid to run under ("majordom" is used on GreatCircle.COM). You need to edit the Makefile to set up the environment and directories used by the "wrapper" program. The "wrapper" program needs to be installed setuid to daemon and setgid to the special group. If you're in that group and the directories used by majordomo are writable by that group (they must be), you can do all the majordomo management functions (creating new lists, etc.) without having to "su". You can create and use a uid other than "daemon" if you want, but if you do, that uid needs to be a "trusted" user as far as Sendmail is concerned (i.e., the user name needs to appear on a "T" line in your sendmail.cf file).

If you're running something POSIX-compliant (including System V and BSDI, but not SunOS 4.x), you'll need to change the Makefile as documented in it, to make "wrapper" program work. Under POSIX, wrapper must be setuid "root", even if the programs will be running as something other than "root" (i.e., "daemon"), or it won't work. The symptom of this is that Perl starts bitching about security violations and "unsafe usages".

To install majordomo:

  1. choose and/or create a uid and gid for this to run under

  2. create appropriate directories ($homedir and $listdir), with appropriate user, group, and permissions (775)

  3. edit the "Makefile" to set W_BIN and the environment for "wrapper"; don't forget to make the changes for POSIX, if necessary

  4. compile and install the perl code and man pages. ("make", then "make install")

  5. As root install the wrapper ("make install-wrapper")

  6. install your majordomo.cf file (probably in /etc, or at least symlinked into /etc otherwise external programs such as medit won't work.)

  7. add the majordomo-related aliases to your /etc/aliases file

Return to index


The Majordomo Configuration File

Majordomo depends on a .cf file, as specified by the MAJORDOMO_CF envariable, or the -C command line flag; it defaults to /etc/majordomo.cf if neither of those are set. The .cf file is "eval"ed into majordomo (so it needs to be valid PERL), and sets several things:
    
    $whereami		What machine am I on?
    $whoami		Who do users send requests to me as?
    $whoami_owner	Who is the owner of the above, for problems?
    $homedir		Where can I find my extra .pl files?
    $listdir		Where are the mailing lists?
    $digest_work_dir	Where does digest do its work?
    $log		Where do I write my log?
    $mailer		What program and args do I use to send mail?
    $filedir		Where should I look for files for "get" and "index"?
    $filedir_suffix	What suffix should I use for the file directory?
    $index_command	What command should I use for "index" requests?

If the following are set, Majordomo uses FTPMAIL to handle "get" and "index" requests, rather than processing those requests itself. FTPMAIL will use the $filedir and $filedir_suffix settings to determine where to look for the files on the host specified by $ftpmail_location.

    $ftpmail_address	What FTPMAIL server should I send requests to?
    $ftpmail_location	What host should FTPMAIL look for my files on?
See the "sample.cf" file for examples.

Return to index


Aliases Needed for majordomo proper

Majordomo depends on several aliases in the /etc/aliases file (see the file "sample.aliases" for a couple of templates):
    majordomo: "|/path/to/majordomo/wrapper majordomo"
    owner-majordomo: brent
    majordomo-owner: brent
Note, the program name (majordomo) must not be a full path name. Majordomo must reside in the directory specified by W_BIN in the makefile. (Brent used to suggest using "listserv", but doesn't any more; Majordomo is not compatible with BITNET LISTSERV, and calling it "listserv" confuses people).

Return to index


Customizing the default PER LIST config values

Per list config files are created automatically on demand. The default values are taken from the %known_keys (associative) array in config_parse.pl. The array is indexed by keyword.

You may want to look at section 2.3 "The per list config files" before continuing on to get a better feel for what these parameters do. If you want to change the defaults, change the values assigned to each keyword. There is some documentation in the config_parse.pl file. The config_parse.pl file is also a man page describing the programatic interface to the config file parser and some other details about the config file parser.

Paul Pomes p-pomes@uiuc.edu suggests the following as replacements for the message_fronter and message_footer default values. I haven't tested them, but they may be useful:

'message_fronter',      '#! local($TEMP) = $list;
      if ( $list =~ /-digest$/ ) {
           $TEMP =~ s/-digest$//;
          "In this issue:\n\n\t_SUBJECTS_\n\nSee the end of the digest for information on subscribing to the $TEMP\nor $TEMP-digest mailing lists.\n";
      } else {
          "";
      }',
'message_footer',      '#! local($TEMP) = $list;
      if ( $list =~ /-digest$/ ) {
           $TEMP =~ s/-digest$//;
          "To subscribe to $TEMP-digest, send the command:\n\n\t
	 subscribe $TEMP-digest\n\nin the body of a message to \"Majordomo@
	 Majordomo.cso.uiuc.edu\".  If you want\nto subscribe something
	 other than the account the mail is coming from,\nsuch as a local
	 redistribution list, then append that address to the\n\"subscribe\"
	 command; for example, to subscribe \"local-$TEMP\":\n\n\tsubscribe
	 $TEMP-digest local-$TEMP@your.domain.net\n\nA non-digest
	 (direct mail) version of this list is also available;
	 to\nsubscribe to that instead, replace all instances of
	 \"$TEMP-digest\"\nin the commands above with \"$TEMP\".";
                                    } else {
                                        "";
                                    }',
Note that the strings are all one line long. I have wrapped and broken them here for ease of viewing.

Return to index


Perl version

Majordomo has been tested with perl 4.019, however perl version 4.036 is recommended. Perl versions earlier than 4.019 are not expected to work. If you experience problems when using an earlier version of perl (one prior to 4.036), upgrade to the newest version.

Return to index


Common Problems

Make sure that majordomo, resend, and digest are executable and in the directory specified as W_BIN in the makefile.

Make sure that perl is installed in /usr/local/bin/perl, or change the path to perl in the programs.

If you get complaints about being unable to find "ctime.pl", then either your version of perl is too old, or is not installed properly. "ctime.pl" is a library file that comes with all versions of perl recent enough to use with Majordomo.

If you get complaints about "insecure usage" from "wrapper", then you're probably invoking it incorrectly. The first argument to "wrapper" should be the simple filename of the program in the W_BIN directory (defined in the Makefile) that you want to run. You should NOT specify the full path name to the program; as a security measure, to keep people from being able to run anything they want with the setuid/setgid permissions of "wrapper" "wrapper" will ONLY run programs from the W_BIN directory. If what "wrapper" is told to run contains a "/", it assumes somebody is trying to make it run something from somewhere else, and complains about "insecure usage". For example, the right way to use wrapper is in something like this:

	majordomo: "|/usr/local/majordomo/wrapper majordomo"
The WRONG way is
"|/usr/local/majordomo/wrapper /usr/local/majordomo/majordomo"

Make sure you've got all the permissions right. In particular, you need to watch for permissions of DIRECTORIES files are in, as well as permissions on the files themselves. Almost any time Majordomo tries to read a file, and every time it tries to write one, it tries to create a lock file in the same directory as the file. If it can't create that lock file for any reason (because the directory permissions won't allow it, or because a lock already exists for that file), Majordomo waits 1 second and then tries again; it keeps trying for 10 minutes. If Majordomo isn't working for you, and takes some multiple of 10 minutes to fail, you've almost certainly got a permission problem; check the Majordomo log file. If there's nothing in the log file, then you've got a permission problem with the log file and/or the directory it's in.

Return to index


Using Majordomo

List names must be of the form "[a-z0-9_-]+" (in other words, letters, digits, underbars, or dashes only). The list of names is stored in the $listdir directory, in a file of the same name as the list.

Return to index


Creating A List for Majordomo

To create a list:
  1. create an empty file called <list-name> in $listdir, mode 664.

  2. create a file called "<list-name>.passwd" in $listdir, mode 664, with the "approve" password for the list in it. [optional; the config file will allow setting of passwords]

  3. create a file called "<list-name>.info" in $listdir, mode 664, with the initial introductory info for the list in it.

  4. create the appropriate entries for the list in /etc/aliases.

  5. optionally, create an archive directory for the list, in the location specified by the $filedir and $filedir_suffix variables.

  6. optionally, create a digest work (incoming) directory for the list, in the $digest_work_dir/<list-name>. you must create an archive directory for the digest list as well as a work directory.

  7. make sure everything is owned by user majordomo, group majordomo, and writable by both owner and group (i.e., mode 664 for files and mode 775 for directories).

Return to index


Setting Up Aliases File

Each list also requires several aliases (note that these are minimal aliases; for a real mailing list, you'll probably want to distribute messages to the list through a program that rewrites the headers appropriately, which is what "resend" does):
    test: :include:/tools/majordomo/Lists/test
    owner-test: brent
    test-request: "|/tools/majordomo/wrapper request-answer test"
    test-approval: brent
A more complete set of aliases that provides digestification, archiving, and header manipulation would look like:
    test:"|/tools/majordomo/wrapper resend -l test -h cs.umb.edu test-outgoing"
    test-digest:test

    # I put the digest and archive programs on the outgoing list so that
    # messages bounced by resend don't end up in the digest or archive
    # unless I send them through resend explicitly. 
    test-outgoing::include:/usr/local/Lists/test,
     "| /tools/majordomo/wrapper digest -r -C -l test-digest test-digest-outgoing",
     "| /tools/majordomo/wrapper archive2.pl -a  -m
	-f /usr/local/mail/archive/test/test.archive"
    # archive produces a monthly archive with the -m flag.

    test-digest-outgoing::include:/usr/local/Lists/test-digest

    owner-test:rouilj
    owner-test-outgoing:owner-test
    # note that the "-digest" and "-digest-outgoing" suffixes
    # are required to allow the majordomo mkdigest command, and the
    # config code to work properly.
    owner-test-digest:owner-test
    owner-test-digest-outgoing:owner-test

    test-request: "|/tools/majordomo/wrapper request-answer test"
    test-digest-request: "|/tools/majordomo/wrapper request-answer test-digest"

    test-approval:rouilj
    test-digest-approval:test-approval

With version 1.92, you can also run majordomo at the -request address, and it will handle requests such as:

without requiring the user to supply a list name. To do this set up an alias similar to:
    test-request: "|/tools/majordomo/wrapper majordomo -l test"
Where the argument to -l is the name of the list.

Hopefully in a future release of majordomo archive2.pl will be integrated into majordomo so that the frequency of archive rollover (daily, monthly, yearly) will be controllable via the config file mechanism. If you wish to use archive2 in the current release, you MUST move it from the Tools subdirectory into the top level majordomo directory.

More examples of alias setups can be found in the file sample.aliases.

Return to index


Error Messages

MAJORDOMO ABORT
This error occurs anytime some anomaly occurs during the majordomo run. It causes majordomo to send an error message to the majordomo owner, and exit immediately. No further commands in the input message are processed. Mail is sent to the originator of the message that caused the abort consisting of the output from all command in the message that had succeeded before the abort. The types of errors that cause an abort are shown below.

Hostile Address
somebody submitted an address that had characters not usually found in valid internet email addresses. These characters are the forward slash "/" and the vertical bar "|". These characters can be used to try to write files on the majordomo host or execute programs on that host. The check is done in valid_addr in the file majordomo.pl.

This check does cause problems for X.400 addresses since they have "/" delimited components. If anybody has any bright ideas about how to differentiate between a filename attempt, and a valid X.400 address, Majordomo-workers would like to hear from you.

Can't open/append/read
for some reason majordomo can't open/append/read a to a file that it was supposed to be able to access. Usually this is caused by improper permissions.

chmod(, link(
the corresponding chmod or link operation failed when it shouldn't have. Usually this is caused by improper permissions.

Can't invoke
the program majordomo wanted to invoke to send mail couldn't be invoked. This error is usually only seen when you are tracing the smtp connection using /usr/ucb/Mail -v.

Can't connect to sendmail
for some reason the attempt to run sendmail in the function resend_sendmail in the resend program failed.

unknown mailer error 5
This can be caused by a number of things all

Return to index


The per list config files

The file <listname>.passwd contains the "approve" password for the list. Is is not really required with the config file, but it does serve as a nice back door if the configuration file is trashed.

The file <list-name>.info contains the "info" text for the list, which is sent in response to "info" and successful "subscribe" commands. In a future version of majordomo, the option will be provided to keep the info in the config file rather than using an external file. However, the external file is useful if you are serving up the info information by some means other than majordomo (e.g. gopher, finger, ftp).

The master config file (called <listname>.config) is created as needed. If you want to force generation of a config file, you can request it using the "config list PASSWD" command using the default passwd "<list>.admin" if there is no <list>.passwd file. A lists, or "info <list>" command will also cause the config files to be created. The default values, and how to change them are described in section 1 of this document (Customizing the default PER LIST config values).

The config file is meant to be self-documenting. A representative file is included below. Note that it has both digest and resend parameters in it, so the person configuring the file needs to know whether the list is being handled by digest (e.g. test-digest), or resend (e.g. test), or neither.

# The configuration file for a majordomo mailing list.
# Comments start with the first # on a line, and continue to the end
# of the line. There is no way to escape the # character. The file
# uses either a key = value for simple (i.e. a single) values, or uses
# a here document
#     key << END 
#     value 1
#     value 2
#     [ more values 1 per line]
#     END 
# for installing multiple values in array types. Note that the here
# document delimiter (END in the example above) must be the same at the end
# of the list of entries as it is after the << characters.
# Within a here document, the # sign is NOT a comment character.
# A blank line is allowed only as the last line in the here document.
#
# The values can have multiple forms:
#
#	absolute_dir -- A root anchored (i.e begins with a /) directory 
#	absolute_file -- A root anchored (i.e begins with a /) file 
#	bool -- choose from: yes, no, y, n
#	enum -- One of a list of possible values
#	integer -- an integer (string made up of the digits 0-9,
#		   no decimal point)
#	float -- a floating point number with decimal point.
#	regexp -- A perl style regular expression with
# 		  leading and trailing /'s.
#	restrict_post -- a series of space or : separated file names in which
#                        to look up the senders address
#	            (restrict-post should go away to be replaced by an
#		     array of files)
#	string -- any text up until a \n stripped of
#		  leading and trailing whitespace
#	word -- any text with no embedded whitespace
#
# A blank value is also accepted, and will undefine the corresponding keyword.
# The character Control-A may not be used in the file.
#
# A trailing _array on any of the above types means that that keyword
# will allow more than one value.
#
# Within a here document for a string_array, the '-' sign takes on a special
# significance.
#
#     To embed a blank line in the here document, put a '-' as the first
#       and ONLY character on the line.
#
#     To preserve whitespace at the beginning of a line, put a - on the
#       line before the whitespace to be preserved
#
#     To put a literal '-' at the beginning of a line, double it.
#
#
# The default if the keyword is not supplied is given in ()'s while the 
# type of value is given in [], the subsystem the keyword is used in is
# listed in <>'s. (undef) as default value means that the keyword is not
# defined or used.


	# admin_passwd       [word] (test.admin) <majordomo>
	# (Default is specified in the file <listname>.passwd) The password
	# for handling administrative tasks on the list.
admin_passwd      =   test.admin

	# administrivia      [bool] (yes) <resend>
	# Look for administrative requests (e.g. subscribe/unsubscribe) and
	# forward them to the list maintainer instead of the list.
administrivia     =   yes

	# advertise          [regexp_array] (undef) <majordomo>
	# If the requestor email address matches one of these regexps, then
	# the list will be listed in the output of a lists command. Failure to
	# match any regexp excludes the list from the output. The regexps
	# under noadvertise overide these regexps.
advertise         <<  END

END

	# approve_passwd     [word] (test.pass) <resend>
	# Password to be used in the approved header to allow posting to
	# moderated list, or to bypass resend checks.
approve_passwd    =   test.pass

	# archive_dir        [absolute_dir] (undef) <majordomo>
	# The directory where the mailing list archive is kept. This item does
	# not currently work. Leave it blank.
archive_dir       =

	# comments           [string_array] (undef) <config>
	# Comment string that will be retained across config file rewrites.
comments          <<  END

END

	# date_info          [bool] (yes) <majordomo>
	# Put the last updated date for the info file at the top of the info
	# file rather than having it appended with an info command. This is
	# useful if the file is being looked at by some means other than
	# majordomo (e.g. finger).
date_info         =   yes

	# debug              [bool] (no) <resend>
	# Don't actually forward message, just go though the motions.
debug             =   no

	# description        [string] (undef) <majordomo>
	# Used as description for mailing list when replying to the lists
	# command. There is no quoting mechanism, and there is only room for
	# 50 or so characters.
description       =

	# digest_archive     [absolute_dir] (undef) <digest>
	# The directory where the digest archive is kept. This item does not
	# currently work. Leave it blank.
digest_archive    =

	# digest_issue       [integer] (1) <digest>
	# The issue number of the next issue
digest_issue      =   1

	# digest_name        [string] (test) <digest>
	# The subject line for the digest. This string has the volume  and
	# issue appended to it.
digest_name       =   test

	# digest_rm_footer   [word] (undef) <digest>
	# The value is the name of the list that applies the header and
	# footers to the messages that are received by digest. This allows the
	# list supplied headers and footers to be stripped before the messages
	# are included in the digest. This keyword is currently non operative.
digest_rm_footer  =

	# digest_rm_fronter  [word] (undef) <digest>
	# Works just like digest_rm_footer, except it removes the front
	# material. Just like digest_rm_footer, it is also non-operative.
digest_rm_fronter =

	# digest_volume      [integer] (1) <digest>
	# The current volume number
digest_volume     =   1

	# digest_work_dir    [absolute_dir] (undef) <digest>
	# The directory used as scratch space for digest. Don't  change this
	# unless you know what you are doing
digest_work_dir   =

	# maxlength          [integer] (40000) <resend,digest>
	# The maximum size of an unapproved message in characters. When used
	# with digest, a new digest will be automatically generated if the
	# size of the digest exceeds this number of characters.
maxlength         =   40000

	# message_footer     [string_array] (undef) <resend,digest>
	# Text to be appended at the end of all messages posted to the list.
	# The text is expanded before being used. The following expansion
	# tokens are defined: $LIST - the name of the current list, $SENDER -
	# the sender as taken from the from line, $VERSION, the version of
	# majordomo. If used in a digest, no expansion tokens are provided
message_footer    <<  END

END

	# message_fronter    [string_array] (undef) <resend,digest>
	# Text to be prepended to the beginning of all messages posted to the
	# list. The text is expanded before being used. The following
	# expansion tokens are defined: $LIST - the name of the current list,
	# $SENDER - the sender as taken from the from line, $VERSION, the
	# version of majordomo. If used in a digest, only the expansion token
	# _SUBJECTS_ is available, and it expands to the list of message
	# subjects in the digest
message_fronter   <<  END

END

	# message_headers    [string_array] (undef) <resend,digest>
	# These headers will be appended to the headers of the posted message.
	# The text is expanded before being used. The following expansion
	# tokens are defined: $LIST - the name of the current list, $SENDER -
	# the sender as taken from the from line, $VERSION, the version of
	# majordomo.
message_headers   <<  END

END

	# moderate           [bool] (no) <resend>
	# If yes, all postings to the list  must be approved by the moderator.
moderate          =   no

	# mungedomain        [bool] (no) <majordomo>
	# If set to yes, a different method is used to determine a matching
	# address.  When set to yes, addresses of the form user@dom.ain.com
	# are considered equivalent to addresses of the form user@ain.com.
	# This allows a user to subscribe to a list using the domain address
	# rather than the address assigned to a particular machine in the
	# domain. This keyword affects the interpretation of addresses for
	# subscribe, unsubscribe, and all private options.
mungedomain       =   no

	# noadvertise        [regexp_array] (undef) <majordomo>
	# If the requestor name matches one of these regexps, then the list
	# will not be listed in the output of a lists command. Noadvertise
	# overrides advertise.
noadvertise       <<  END

END

	# precedence         [word] (bulk) <resend,digest>
	# Put a precedence header with value <value> into the outgoing
	# message.
precedence        =   bulk

	# private_get        [bool] (yes) <majordomo>
	# If set to yes, then the requestor must be on the mailing list in
	# order to get files.
private_get       =   yes

	# private_index      [bool] (no) <majordomo>
	# If set to yes, then the requestor must be on the mailing list in
	# order to get a file index.
private_index     =   no

	# private_info       [bool] (no) <majordomo>
	# If set to yes, then the requestor must be on the mailing list to use
	# the info <list> command.
private_info      =   no

	# private_which      [bool] (no) <majordomo>
	# If set to yes, then the requestor must  be on the mailing list in
	# order to get which info from that list.
private_which     =   no

	# private_who        [bool] (no) <majordomo>
	# If set to yes, then the requestor must  be on mailing the list in
	# order to use the who command.
private_who       =   no

	# purge_received     [bool] (no) <resend>
	# Remove all received lines before resending the message.
purge_received    =   no

	# reply_to           [word] () <resend,digest>
	# Put a reply-to header with value <value> into the outgoing message.
	# If the token $SENDER is used, then the address of the sender is used
	# as the value of the reply-to header. This is the value of the reply-
	# to header for digest lists.
reply_to          =

	# resend_host        [word] (undef) <resend>
	# The host name that is appended to all address strings specified for
	# resend.
resend_host       =

	# restrict_post      [restrict_post] (undef) <resend>
	# If defined only address listed in one of the files (colon or space
	# separated) can post to the mailing list. This is less useful than it
	# seems it should be since there is no way to create these files if
	# you do not have access to the machine running resend. This mechanism
	# will be replaced in a future version of majordomo/resend.
restrict_post     =

	# sender             [word] (owner-test) <majordomo,resend,digest>
	# The envelope and sender address for the resent mail. This string has
	# "@" and the value of resend_host appended to it to make a complete
	# address. For majordomo, it provides the sender address for the
	# welcome mail message generated as part of the subscribe command.
sender            =   owner-test

	# strip              [bool] (yes) <majordomo>
	# When adding address to the list, strip off all comments etc, and put
	# just the raw address in the list file.  In addition to the keyword,
	# if the file <listname>.strip exists, it is the same as specifying a
	# yes value. That yes value is overridden by the value of this
	# keyword.
strip             =   yes

	# subject_prefix     [word] (undef) <resend>
	# This word will be prefixed to the subject line, if it is not already
	# in the subject. The text is expanded before being used. The
	# following expansion tokens are defined: $LIST - the name of the
	# current list, $SENDER - the sender as taken from the from line,
	# $VERSION, the version of majordomo.
subject_prefix    =

	# subscribe_policy   [enum] (open) <majordomo> /open;closed;auto/
	# One of 3 possible values: open, closed, auto.  Open allows people to
	# subscribe themselves to the list. Auto allows anybody to subscribe
	# anybody to the list without maintainer approval. The existence of
	# the file <listname>.auto is the same as specifying the value auto.
	# Closed requires maintainer approval for all subscribe requests to
	# the list. In addition to the keyword, if the file <listname>.closed
	# exists, it is the same as specifying the value closed. The value of
	# this keyword overrides the value supplied by any existent files.
subscribe_policy  =   auto
# END of CONFIG FILE

Return to index


Using Digest and Archive

There are three archive programs available. The one that will be integrated with a future version of majordomo is called archive2.pl, and is in the contrib subdirectory. The comments at the top of the file should explain its use.

The digest program was written by Brent Chapman. The config file conversion was done by John Rouillard. If you are using digest with the config file conversion, the command line should look like:

  digest -r -C -l test-digest test-digest-outgoing
where -r means that it is getting a single article on standard input. -C means that we are using the config file change code. -l is the name of the list. It is used to read the correct config file. The last argument on the command line is the real distribution alias that the digest will be sent to. This mimics the command line structure of resend.

All digest lists should end in '-digest'. This allows the config file code to change the default values for digest lists as opposed to regular lists. Also, the outgoing channel for a digest list, must end in digest-outgoing. This allows the majordomo "mkdigest" command to work.

To use digest you must create the archive dir and the incoming directory. The archive directory is created using $filedir/<digest-name>.$filedir_suffix. $filedir and $filedir_suffix are defined in the majordomo.cf file. <digest-name> is something like sample-digest. You should also create the incoming directory as well. Its name is obtained by using $digest_work_dir/<digest-name>, where $digest_work_dir is defined in majordomo.cf and <digest-name> is the same as in the archive directory.

In the digest subdirectory are standard config files if you wish to use digest without using the rest of the majordomo system. If you choose to use digest as a stand-alone program PLEASE be sure to change the values in the file:

	 digest/firewalls-digest.cf
to avoid causing problems for the real firewalls-digest.

Return to index


Other Programs

The "bounce-remind" script should be run out of cron using a line similar to:

	10 2 * * *  /tools/majordomo/wrappers/bblisa/wrapper bounce-remind
This sends mail to all of the people on the bounces list to warn them that they are no longer on the lists they thought they were on.

The "medit" program is used to hand edit the mailing list files, but it locks the files first so that majordomo won't touch them while you are editing them. You may need to edit this program and change the location of the majordomo.cf file if the majordomo.cf file is not accessible as /etc/majordomo.cf).

The "new-list" is used when starting a new list. Often there is a flood of mail when a list starts up. If you wish to allow a grace period for people to subscribe before actually putting the list "on-line", the new-list script can be put at the list address, and it will notify people that the list is not yet open for business.

The "request-answer" program attached to the "-request" address for the list sends back a recording telling folks how to use the Majordomo address for their requests, or how to contact a human if they really need to. You can use majordomo with the -l option to sit at the -request address instead of using request-answer if you like.

The "approve" program is intended to be used by a mailing list administrator to approve messages send by majordomo or resend.

The "bounce" program removes an address from an active majordomo list, and subscribes it to the bounces list. This is used when mail to the address starts bouncing.

Return to index


Tricks

This section has a few tricks when using majordomo and resend.
How do I maintain the -I file for resend?
The easiest way is to create a pseudo list in majordomo. The file that contains this list if the file name used for the -I flag to resend. For example the filename "<listname>-can_post" can be created in the majordomo mailing lists directory. This list should be unadvertized and closed. Don't bother creating any sendmail aliases for it. This allows people to be added to or removed from the list using majordomo commands.

How can I have more than one moderator/owner for a list?
Again majordomo is your friend. Create a mailing list called "<listname>-owner". Again create it nonadvertised and closed. Set up the appropriate aliases for the list:
	owner-listname::include:/usr/local/Lists/<listname>-owner
	listname-owner:owner-listname
	owner-owner-listname: owner-majordomo
and you are done.

When using the lists command and the noadvertise pattern /.*/ the list is still listed. Why?
This is a feature. If you are subscribed to the list, the list is always shown since it doesn't make any sense to not show it since you already know it is there by virtue of being subscribed to it.

If you wish to disable this feature, you must edit the majordomo script itself. Remove the statement around line 890 that reads:

		$result	 = &is_list_member($reply_to, $listdir, $list)
			if ! $result;

Return to index


Other Documentation

There is quite a bit of documentation in the Doc subdirectory.

Documentation for your list-managers

The file Doc/list-owner-info contains some information for your list owners. It can be sent to them and should be enough information to get them started using majordomo.

The original majordomo paper

The file Doc/majordomo.lisa6.ps is the original paper introducing majordomo. Please note that it is useful for getting a feel for majordomo, but it should not be used as an installation document since some of the examples (including how to invoke majordomo) are incorrect.

The FAQ

The file Doc/FAQ has been compiled from the questions asked on the majordomo-users list. The FAQ was originally compiled by Vincent D. Skahan, and is being maintained by David Barr.

Manual pages

In the Doc/man directory are some man pages for majordomo and approve. If anybody writes up man pages for resend, bounce and digest, please send them to majordomo-workers@greatcircle.com, and majordomo-docs@greatcircle.com.

Other README's

The file resend.README documents most of the command line flags available in resend. Additional featues are available only via the config file code. If you are using resend with the config file code, it is recommended that you only use the -l and -h flags, and the name of the outgoing list. The list name for the -l flag should be all lower case the same as the filename that houses the lists members.

The config file that is discussed in resend.README, and is specified with -C, has no releationship to the perl list config file code, and should not be used.

The file digest/README discusses how to use digest in a standalone capability, and should be ignored if you are using digest in the scope of an entire majordomo system.

Doc/README has some info on the documentation directory.

Miscelleanous Comments

On the majordomo-users mailing list, BEBO@slac.stanford.edu asked a number of questions that were answered by Dave Sill <de5@de5.CTD.ORNL.GOV>. I reproduce the answers here with updates for the config file code.
> BEBO
] David Sill

>1) What steps are required to set up a list where:
>       * only the owners can subscribe new folks
>       * only the owners can send messages to the list
]
]Create listname.closed in the list directory.  Alias incoming list
]submissions to go through "resend" with the -A and -a options.

Rather than use listname.closed, set 

	subscribe_policy = closed

The -A flag is handed by setting:

	moderate = yes

and the -a <password> flag is handled using the

	approve_passwd = <some password>
	
>2) What steps are required to set up a list where:
>       * only the owners can subscribe new folks
>       * any subscribers can send to the list

]Same as above, except leave of the -A and -a options.

Simply set 

	moderate = no

The approval password can still be used to approve message bounced
due to length restrictions or administrivia checks.

Return to index


Mailing Lists/Support

There are four mailing lists at GreatCircle.COM, To subscribe to any of the lists above, send an appropriate "subscribe" command to "Majordomo@GreatCircle.COM".

Also at greatcircle.com is the list-managers mailing list. General topics on managing lists including, what email headers should be rewritten, list policies, how to handle problems with users at sites, issues with the size of lists etc. Questions that pertain to operating majordomo DO NOT belong on this list. Use majordomo-users instead.

Return to index


Conclusion

Attributions

Majordomo and digest were originally written by Brent Chapman, however he doesn't have the time currently to do more development on it. The config file code and majordomo 1.92 modifications were done by John Rouillard. The FAQ was compiled by Vincent D. Skahan and is currently being maintained by David Barr <barr@pop.psu.edu>.

In addition to those above, I would like to thank the following people who shaped the current release of majordomo:

To anybody I left off the attributions list, my apologies. Let me know that I left you off, and I will make sure that you get mention in a future release.

Return to index


Future Directions

The next planned release will be majordomo 2.0. The specification document has been written for it, and is is in the process of being written. The intent with 2.0 is to have a defined programmers interface that allows people to develop portable modules that can be added into majordomo to provide additional functionality. If you think of majordomo as a stripped down car, and the addin modules as extra options that you can "buy", then you have the right idea. 1.92 is being released to test the config file code, and because some of the resend and majordomo features seem to be needed by people on the majordomo-users list.

Before the next planned release, there may be other releases in the 1.9x series as bugs are found, and as additional functionality that is currently hinted at in the config file is added.

Bugs/Misfeatures/Todo

The following is a list of things that I want to address at some point. The items marked with a * imply that patches to implement the feature have been written, but it is too late in this cycle to apply the patch and test it. Hopefully some of these items will be fixed in majordomo 1.92.
  1. Resend only recognizes an Approved: header as the first line in the body. The approved header should be recognized if it is the first non-blank line in the body.

  2. Resend should have a separate moderater address to bounce email to

  3. Multiple privacy levels have to be provided. yes, no, password protected

  4. The number of reported hits from which should be tunable

  5. approve has to be extended to handle almost all commands

  6. new-list should be part of resend

  7. wrapper.c should use sysexits.h for its error codes

  8. auto lists should prevent the list from being subscribed to itself

  9. auto lists should make sure that listserv style addresses aren't used

  10. provide the ability to smash case of all incoming addresses under majordomo administrator control.

  11. ability to specify banned users whose posts are ignored.

  12. rework the advertise/noadvertise interface

  13. Look at supporting #included/#exploder lists for mail sublists.

  14. set up reply to be smart enough to break mail loops (using received: headers)

  15. should -h not be required by resend, or should resend_host keyword go away?

  16. config should return the input file if there is an error.

  17. digest needs to strip headers and footers from list info. Maybe there should be a back channel out of resend that doesn't do any body massaging.

  18. have resend/majordomo check to see if the last Received: line is a right hand sub/super string of the user's from address.

  19. fix help messages to remove syntax diagram info to stop address subscriptions like: subscribe list [user@site]

  20. Support auto digest creation based on number of lines, and age.

  21. Have resend log messages as it sends them through. Can be used to prevent mail loops as well as provide stats for later use.

  22. analyze code to make sure all areas that require locks are in place

  23. detect error condition (e.g. out of disk space) and deal with them better

  24. add code to support incremental config file changes.

  25. add ability to add arbitrary headers to message and check that the headers are in the proper form.

  26. add the ability to do load limiting of majordomo commands

  27. messages shouldn't be bounced as administrivia. They should be in a different class, and should be user settable.

  28. list always needs to have its archive directory present. Digest should be rewritten to place its outgoing digest into the incoming directory, and it should use archive to do archiving if need be.

Return to index


If you want to contribute

Join the majordomo-workers list mentioned above. If you have an idea, feel free to submit it to majordomo-workers.

If you are actually writing perl code:

If you are creating a stand alone utility (e.g. digest) make sure that it reads its non-user modifiable configuration information from the majordomo.cf file. As of this release, per list configuration should be done using the config file interface. To use the config file code you should use the program interface to the config file code to instantiate your config file parameters. Do not add your config keywords to the tables in config_parse.pl.

If you are making a modification to majordomo, retrieve the majordomo rewrite specification, and see what effect that will have on your modification. Majordomo 2.0 will look very different from the current majordomo. If the functionality is able to be done as an add on module, we would prefer to make the functionality available via that mechanism.

If you are making modifications to resend or digest, majordomo 2.0 is unlikely to require major changes, since only majordomo is likely to be heavily changed for release 2.0.

Return to index


$Header: /sources/cvsrepos/majordomo/README,v 1.22.2.1 1994/06/09 19:45:04 rouilj Exp $
Real/Time Majordomo Administration<owner-majordomo@bga.com>