Majordomo address:	# majordomo@columbia.edu
Majordomo-Owner address:# majordomo-owner@columbia.edu
List Name:		# ListName
Is resend used:		# yes
Is the list archived:   # no
List posting address:	# ListName@columbia.edu
List request address:	# ListName-request@columbia.edu
List password:		# whatever

[ if there is a digest... ]
Digest list name:	# ListName-digest
Digest list password:	# whatever

Your mailing list has been established.  It is being served by an automated
mailing list manager that responds to commands emailed to the "Majordomo
address" listed above.  

This message has all the details of how to manage your list remotely using
Majordomo.  A copy of this message is also kept on the web under
http://www.columbia.edu/acis/email/group/majordomo .  You can get help by
sending mail to majordomo-owner@columbia.edu.

Your list-owner password is shown above.  Keep track of this; you'll need
it later.  Instructions for changing your password are below.

As soon as possible, please issue a "newinfo" command for your list (see
below) to create the file that someone will receive when they join or ask
about your list.  A very short info file has been created by default, which
says:
   ListName is a new list and does not yet have an information file.
   The list owner will be making one shortly.

You can issue a "who" command for your list to see who's already on your
list.  You may or may not already be subscribed to your own list.

================
The Gory Details
================

Your mailing list is managed by an automated mailing list management
program called Majordomo.  Majordomo should free you from dealing with most
of the administrivia usually associated with running mailing lists (adding
users, dropping users, etc.).

To submit something to your list, you (or anybody else) should simply
mail it to the list posting address shown at the top of this file,
ListName@columbia.edu .

To be added to your list, a user simply sends a message to majordomo.
There are two ways to do it:

address--    To: ListName-request@columbia.edu
message--    subscribe

 OR

address--    To: majordomo@columbia.edu
message--    subscribe ListName

Majordomo understands several commands, and is not limited to a single
command per message (it will process commands until reaching end-of-message
or the command "end").  The command "help" will tell you about all the
other commands.

Actually, it won't tell you about _all_ the other commands that Majordomo
understands.  There are several commands there for use by list owners such
as yourself, which are not advertised to the public.  All of these commands
are password-protected on a list-by-list basis, but anyone with a valid
list/password combination can invoke these commands.  This is not exactly
high-tech security, but it's more intended to keep annoyance to a minimum
than to be foolproof.

The "documented" commands which Majordomo understands and which are for
everyone to use are:

    subscribe <list> [<address>]
    unsubscribe <list> [<address>]
    which [<address>]
    who <list>
    info <list>
    index <list>
    get <list>
    lists
    help
    end

You can get detailed explanations of all of these by asking for "help" from
Majordomo (send a message containing just the word "help" as the message
text to majordomo@columbia.edu).

The "undocumented" commands for use by list owners are:

    approve <passwd> {subscribe|unsubscribe} <list> [<address>]
	This is so that you can approve subscription or unsubscription
	actions that need approval by the list owner.  Note that this
	is just a standard "subscribe" or "unsubscribe" command prefixed
	with "approve <password>" (where you substitute the password for
	your list, which is listed above, for "<password>").

    passwd <list> <old_passwd> <new_passwd>
	This is so you can change the password for your list, if you desire.

    newinfo <list> <password>
	This is so that you can replace the information file that people
	get when they do "info <list>" or "subscribe <list>".  It reads
	everything after the "newinfo" command to end-of-message or the
	word "EOF" on a line by itself as the new info for the list.

    config <list> <password>
        Retrieves a self-documenting configuration file for
        the list <list>.  The <password> can be the password
        contained in the file <list>.passwd or the
        admin_password in the configuration file.

    newconfig <list> <password>
   	Validates and installs a new configuration file.  It reads
	everything after the "newconfig" command to end-of-message or
	the word "EOF" on a line by itself as the new info for the
	list.  The config file is expected to be a complete config
	file as returned by "config".  Incremental changing of the
	config file is not yet supported.  As soon as the config file
	is validated and installed its settings are available for
	use. This is useful to remember if you have multiple commands
	in your mail message since they will be subject to the
	settings of the new config file.  If there is an error in the
	config file (incorrect value...), the config file will not be
	accepted and the error message identifying the problem line(s)
	will be returned to the sender.  Note that only the error
	messages are returned to the sender not the entire config
	file, so it would be a good idea to keep a copy of your
	outgoing email message.


    writeconfig <list> <password> 
        Write a new config file in standard form. Writeconfig forces a
	rewrite of the config file with all comments and default
	values in place. It is useful to use after an upgrade of
	majordomo since it will add the new keywords for people to
	change. It also updates the documentation in the file if that
	has changed.

    mkdigest <digest list name> <password>
	Generate a digest.


Configuring Your List
=====================

You should retrieve the configuration file for your list. To do this, send
an email message to the majordomo address listed at the top of this form.
The contents of this message should be:

	config <list> <List password>

Where <list> <List password> are given at the top of the form. You will
receive a config file that can be used to change the operation of your
list. If the information at the top of this form shows that resend is being
used, you want to configure the majordomo and resend subsystems. Otherwise
you only have to configure those items that are associated with the
majordomo system.

The configuration file is meant to be self documenting. Once you have
completed all of the changes to the config file, You should use the
newconfig command (described above) to put a new configuration file in
place.

If you have a digest version of your list, you should retrieve the config
file for the digest as well using:

	config <Digest List Name> <Digest list password>

and configure the parameters for the digest and majordomo subsystems.


Regular Expressions (in the configuration file) 
-------------------

For some of the configuration options, a rudimentary knowledge of perl
style regular expressions will help you run Majordomo through its tricks.
A regular expression is a concise way of expressing a pattern in a series
of characters.  Letters and numbers stand for themselves, but the other
characters are mostly symbolic and need a \ in front of them to mean
themselves.  Here are some very useful ones for Majordomo:

  \@    the @ character (which obviously is common in email addresses!)
  .     any one character
  \.    the . character (a period)
  ^     the beginning of the string (or line), so
	/^a/    letter "a" at the beginning of the string
  $     the end of the string (or line), so
        /a$/    letter "a" at the end of the string
  *     the previous character, zero or more times, so
        /a*/    letter "a" any number of times, or not at all
	/.*/    any characters any number of times, or nothing
  +     the previous character, one or more times, so
        /a+/    letter "a" any number of times, but at least once
	/.+/    any characters any number of times, but at least one character

Example 1.
        /cs\.umb\.edu/
        read:	  "cs", a period, "umb", a period, "edu"
	matches:  cs.umb.edu
        	  foo.cs.umb.edu
		  user@foo.cs.umb.edu
		  users%foo.cs.umb.edu@greatcircle.com

Example 2.
	/rouilj\@.*cs\.umb\.edu/
	read:	  "rouilj@", anything or nothing, "cs" etc as example 1
	matches:  rouilj@cs.umb.edu
		  rouilj@terminus.cs.umb.edu
		  arouilj@terminus.cs.umb.edu@greatcircle.com

Example 3.
	/^rouilj\@cs\.umb\.edu$/
	read:	  beginning of line, like example 1, end of line
	matches:  rouilj@cs.umb.edu
	This will not match a string that has "rouilj@cs.umb.edu" between
	other text-- it will have to start at "rou" and end at "edu".

Example 4.
        /.*/
	read:	  anything
	This matches absolutely any string including a null string.

To be on the safe side put a \ in front of any characters in the regular
expressions that are not numbers or letters.  Even use \/ to put the /
character itself into a regular expression.  You might want to check
for something like "/CO=US" in an address, like this:
        /\/CO\=US/


Approval
========

When Majordomo requests your approval for something, it sends you a message
that includes a template of the approval message; if you concur, you simply
need to replace "PASSWORD" in the template with your list password, and
send the template line back to Majordomo.

The requests for approval that Majordomo generates all start with "APPROVE"
in the "Subject:" line.

You aren't limited to approving only things to Majordomo requests approval
for.  You can approve any "subscribe" or "unsubscribe" request, regardless
of whether Majordomo has requested this approval, with an "approve"
command.  Thus, you can subscribe or unsubscribe people from your list
without them having to send anything to Majordomo; just send a message to
majordomo@columbia.edu with either of these commands in the message text:

approve PASSWORD subscribe LIST ADDRESS
approve PASSWORD unsubscribe LIST ADDRESS


Bounced Messages
================

Majordomo may bounce certain messages that people attempt to post to your
mailing list.  These messages may be bounced because they appear to be
administrative requests (i.e., someone mailed a request to subscribe or
unsubscribe to the posting address rather than to Majordomo or to the
-request address), because they are too long, or for any of a number of
other reasons.  Majordomo takes the presence of certain keywords in the
subject line or first lines of a message to mean they are administrative
requests, including "subscribe" and "help"... look out for this if you
can't figure out why something bounced.

Majordomo will forward these messages to you in another message whose
subject line begins with the word "BOUNCE"; the subject line will also
indicate the name of the list the message was bounced from (in case you
manage more than one list) and the reason the message was bounced.

If you decide that the message is OK for the list, then you can make
Majordomo post it by sending the message back to the ListName@columbia.edu
address with a special first line that looks like:

Approved: approve_password

Note the details: capital "A", small "pproved", then a colon and a space,
and then the password.  Be sure this is the very first line of the message.

The original headers of the message should then follow on the very next
line with NO BLANK LINE between the Approved line and the first line of 
original headers.  Your mail software may normally insert a blank line or
lines with wording like "-- Forwarded Message --" or "----" before the
forwarded message-- get rid of those lines.


Moderation
==========

Moderating a list means you, the list owner, read every message first and
post only the ones you approve.  

(Actually you could also be piping them through a procmail script in your
account that catches mail sent to the list address, and checks for something
you define that needs to be in the message ... if you are ambitious.)


Making a list moderated
-----------------------

To put moderation into effect, first get the config file by sending mail to
majordomo@columbia.edu with the message

   config ListName password

using the list password.  You need to edit this file and send a complete
copy of the file back to majordomo with the changes.  The message you send
back has to be start with the command

   newconfig ListName password

followed by the complete config file.
The variables to change are:

   approve_passwd    =   whatever
   moderate          =   yes

The approve_passwd could be the same as the list password, but if you make
it different you can share moderation without sharing access to the rest of
Majordomo's commands.  To undo this, set moderate = no.
   
Now, all messages sent to the list without an Approved: line will be
bounced to you, just as described above.

Sending a message to a moderated list
-------------------------------------

Majordomo checks the first paragraph of the message.  If the first
line contains:

  Approved: approve_password

with the correct password, Majordomo considers this message approved
and will send it to the list.  If there are more header lines in the
first paragraph, they will be used in the message sent by Majordomo.

If you, the moderator, are sending a new message to the list, make
sure there is a blank line under the Approved line.

If you, the moderator, are forwarding someone else's message, the usual
method is to make sure there is NO blank line under the Approved line,
so that the original sender's header lines are used.  Your mail software
may insert blanks or lines with wording like "-- Forwarded message --";
get rid of those.  It should look something like:

  Approved: approve_password
  Date: Tue, 9 Jun 1998 18:49:37 -0400 (EDT)
  From: Firstname Lastname <somesubscriber@columbia.edu>
  To: listname@columbia.edu
  Subject: A Vital Message

  This is the first line of text

You will have trouble with mail software that inserts ">" before forwarded
material, or forwards as MIME enclosures.  A partial workaround is to type
in minimal headers by hand, at least the From: and Subject: headers.  A
future version of Majordomo will handle this better.


Restricting Posting
===================

An easier alternative to moderation is to restrict who can post to the
list, which can be done with the restrict_post configuration variable.  The
variable requires a file listing the people who can post.

To restrict posting to subscribers, get the config file and change this:

  restrict_post = listname
  munge_domain = yes

using the real name of your list for "listname".  You don't have to set
munge_domain to yes, but it is a good idea.  munge_domain tells Majordomo
to allow variation on the hostnames, so for example the addresses
foo@alpha.uni.edu and foo@beta.uni.edu are accepted as being the same
as subscriber foo@uni.edu, which is normally what you want.  


Archiving
=========

Archiving has to be set or unset by the system administrators reached at
majordomo-owner@columbia.edu.  It is not the default but must be requested.
Here is what can be done.

Archive files can be split by years, months, or days.  This means all mail
to the list for one of those periods of time will be collected into one
archive file.  People who want to get archived mail will need to get one
such file as a unit.

We are running an indexer program nightly.  It produces two index files
that subscribers can get: CONTENTS lists what subject lines are in each
archive file; TOPICS lists what archive files contain each subject.

Subscribers use the "get" command to see files in the archives.  Examples:
  get ListName CONTENTS            # gets the CONTENTS file
  get ListName ListName.9507       # gets the July 1995 archive file

Access to archives is controlled by the get_access variable in the config
file.  The value "list" means they must be subscribers to get archived
files.

Subscribers can also get a list of filenames and dates in the archive by
sending an "index" command.  Example:
  index ListName

This is controlled by the config file variable index_access similarly.

Notes on archiving.

 -  It's possible for the archive to contain files besides the indexes
    and the archive files of messages.  However, majordomo offers no
    method for you to put them there.  In an unusual case you can ask 
    majordomo-owner to put a file there for you.  

 -  Archiving could be accomplished by directing a copy of messages to
    some other place besides the majordomo archive.  Ask, if you have
    something in mind.

 -  The only check on requests for archives is to compare the From line
    address against the subscriber list (and that is done only if 
    get_access is set to "list" in the list's config file).  A forged
    From line would make a request pass, but Majordomo would send the
    results only to the subscriber who appeared to have sent the request.


Digesting
=========

A digest version of a list is a way to reduce the number of messages sent
from Majordomo to subscribers.  Normally, each message to the list is
remailed to all the subscribers, but with a digest, several messages are
collected into a batch and then sent together as one message.  This does
not reduce the total size too much, although there are fewer mail header
lines-- the main purpose is to reduce the number of separate messages.
This actually helps the mail systems at both ends, and may help subscribers
reduce clutter in their mailboxes.

A Majordomo digest is actually a separate mailing list.  The digest of
ListName would normally be called ListName-digest.

People subscribe independently to ListName and ListName-digest.  Very
likely no one would want to be on both lists.  To change between ListName
and ListName-digest, a subscriber needs to unsubscribe from one list and
subscribe to the other.  This can be done with one message to
majordomo@columbia.edu with two command lines in it, e.g.:
  unsubscribe ListName
  subscribe ListName-digest

Remember that ListName-digest will have its own information file and
configuration file.  Change them, if you want to, when you change the same
files for ListName.

Majordomo will send a digest automatically when the size of the digest
exceeds the size given as max_length in the configuration file of the
digest list.  The default max_length is 40 K.  You can change this.

- Irregular digest  

  Just leave the max_length as 40 K, or change it to the value you want.  A
  digest will go out whenever enough mail accumulates.

- Scheduled digest

  Postmaster runs a job to send digests out each night.  To do this, ask
  postmaster to add your list to the job, and then set the max_length to 
  a high value so that it is not normally reached in a day.  It is still
  worthwhile to check size, so that an "extra" will be sent based on
  size if you have a lot of traffic in one day.

- Digest on demand

  At any time, you can send the mkdigest command to Majordomo.
  Just send mail to majordomo@columbia.edu with the message:
    mkdigest ListName-digest password

---------------------------------------------------------------------------
10 June 1998