-*- Text -*-

For some brief instructions on getting a list started, see
README.QUICKSTART.

If you are upgrading an existing Majordomo 2 (Mj2) installation, always
read README.UPGRADE for instructions on dealing with inter-version
changes.

If you are upgrading an existing Majordomo 1 installation, see
README.CONVERSION.

For specific instructions on using Mj2 with various MTAs (Mail
Transfer Agents) see README.SENDMAIL, README.QMAIL, README.EXIM, or
README.POSTFIX.  (If instructions for your MTA are not available, please
assist us in writing the documentation for it.)

See README.DIRECTORIES if you'd like to know the complete layout of a
running Mj2 system. 

See README.INTERNALS and README.CALLING for some information about the
design of the Mj2 software.

See README.QUEUEING for an explanation of how Mj2 processes incoming
e-mail messages.

See README.DEBUGGING for some tips on diagnosing problems. 

Nearly all Majordomo 1.94.4 functionality is supported (including
archives and digests).  There is still much work to be done, and bugs
remain to be found.  See the TODO document for a list of features that
have not yet been implemented.


Similarities with Version 1.94.x
--------------------------------
A major design goal of Majordomo 2 is to provide something that looks
exactly like Majordomo 1.94.4 to the users.  All existing instructions for
end users of Majordomo-managed lists should still be applicable, excepting
places where changes in previous behavior were required to fix bugs or plug
security holes.  (Note that the changes in the confirmation process both
fix bugs and improve security and also make things much easier on the
users.)

The situation is much the same for list owners, but the approval and config
procedures have changed.  There is some backwards compatibility here,
though, and more may be forthcoming.  There are, of course, many more
variables that can be set.


Differences from Version 1.94.x
-------------------------------
Everything has changed.  Majordomo 1 was flea-bitten, full of warnings
and didn't have a hope of running under -w, use strict, or taint checks.
Jason found it simpler to write it all anew than to try to fix the old
code and make it do what I wanted.  He tried for a long time,
half-rewriting it at least twice.

Mj2 communicates with an MTA using the standard SMTP protocol; there is
no reliance on being able to call something that looks like Sendmail.
It can also speak the protocol used by qmail-queue to inject mail
directly.

Majordomo keeps a database of subscribers, and so can keep lots of extra
state information.  Because of this, digests can be incorporated into the
main list, along with vacation mode and other improvements.

Majordomo has a completely different file layout, with one directory per
virtual domain containing one directory per list.

The interfaces are completely separate from the core.  There are interfaces
for email, shell, and WWW access.

The other changes are too many to list.  See the extensive help
documents for more information about the current features of Mj2.


The Perl Interpreter
--------------------
You need a complete and proper Perl installation in order to run Majordomo.
Some vendors ship Perl but do not configure it correctly.  Majordomo will
try to detect trouble during the installation process but it will not
do anything to fix it.

Mj2 requires Perl 5.004_01 or later to run.  This is due to bugs in
5.004, and the fact that lesser versions are both lacking in features
and security.  Most of the testing is done using Perl 5.5.2, 5.6.1, and
5.8.1.

Currently a Perl built with threading support will fail to run Mj2 code
properly due to bugs in the Perl threading support (which is in a
development state).  Please use only non-threaded builds for the time
being.


Perl Modules
------------
Mj2 requires that numerous other Perl modules be install on your system.
All of the Perl modules are available from CPAN, the Comprehensive Perl
Archive Network.  The easiest way to install a new module is to use the
CPAN module.  This module is included with most recent versions of Perl.
For example, to install the Date::Format module, run the following shell
command:

  perl -MCPAN -e 'CPAN::Shell->install("Date::Format")'

(In most cases, it is necessary to run this command as root.)  

During the installation process, if some of the required modules are
missing, you will be given a list of commands to execute to install the
missing modules.

If the CPAN module is not installed at your site, you can search it
at the following location:
  <URL:http://search.cpan.org/>


The following modules are optional:

Time::HiRes 
  Installing this module will cause activity and debugging logs to
  record with higher precision the amount of time taken by a command or
  subroutine (e.g., 2.393 seconds instead of 2.000 seconds).

Term::ReadLine::Perl or Term::ReadLine::Gnu
  Either of these modules will give the mj_shell program extra
  features when you use it interactively (see below).

Text::Reflow
  When an HTML or enriched-text message part is changed into plain text,
  Mj2 will use this module to format the text attractively.  Otherwise,
  it will use a simpler and cruder algorithm.

DB_File
  The DB_File module will allow Majordomo to store its data in Berkeley
  DB databases.  Berkeley DB databases are much faster than the plain
  text databases that Majordomo also supports.  To use this module,
  it must be installed before you configure and install Mj2.

DBI
DBD::Pg
DBD::mysql
  In addition to plain text and Berkeley DB databases, Mj2 has
  experimental support for PostgreSQL and MySQL databases.  Use at your
  own risk.  To use this module, it must be installed before you configure
  and install Mj2.

Mail::DMARC
  Used to implement DMARC checks.  If not installed, the dmarc_action,
  dmarc_modes and dmarc_timeout list options have no effect.

SetUID Scripts
--------------
Majordomo 2 includes its own setuid wrapper generation, so setuid shell
scripts are not required.  (Some versions of Unix do not support them; Perl
can work around this on some Unices but it must be configured to do so.  If
needed, the wrappers are compiled using the information from the Perl
configuration, in particular the configured location of the system C
compiler.  If this information is incorrect, then the wrappers will not
build.  If the wrappers are not required, neither is a C compiler.  Note
that even if you have an MTA that does not require the Majordomo1 wrapper
there are still Majordomo 2 programs that need to be setuid, namely the
shell and web-confirm interfaces.  These are setuid majordomo only, not
setuid root.


Installation
------------
Much blood has been shed to make installation as painless as possible.
It's still painful because it's not finished.  Try to imagine how easy it
will be when it's finished.

To install:
  * Unpack (you did that if you're reading this).  Make certain that root is
    able to read all of the distribution files.  (This means that you
    cannot unpack the distribution with no global read permissions on a
    disk that root cannot manipulate, such as an NFS-mounted directory
    with no root privilege.)
 
  * Run the following shell command:
    perl Makefile.PL

Your system will be checked for prerequisite modules and such.  If any are
not found, you must install them before installation can continue.  Some
sample instructions that may work for many properly configured perl
installations are provided for missing modules.

You will be asked several questions related to your site, and several
questions for each virtual domain that you choose to support.

When the configuration process finishes, you will be asked to run 'make'
and 'make install'.  'make' will prepare the files for installation, and
can be done without special privileges.  'make install' must be done as
root, as it will need permission to make directories and change ownership
of files.

The final installation step is complex; Majordomo is used to configure
itself.  This can result in copious amounts of information so the
verbosity can be controlled.  By default Majordomo will completely
configure itself and will present to you a brief progress summary and
some important configuration steps, but you can request additional
information.  This works by specifying variables on the 'make install'
command line.  You can specify the following variables:

  QUIET   - show even less information
  VERBOSE - print everything that's happening
  
They are specified like this:

  make install VERBOSE=1

In addition, there are two other flags for use by developers:

  ASK  - ask questions about whether or not things should be done
  SKIP - skip all non-essential configuration steps, including
         the installation of configuration templates and regeneration
         of the list configuration and MTA alias files.

If you are making changes to the code or are frequently updating from CVS
and you want to skip parts of the installation process, you can use SKIP to
skip it all or ASK to have the process prompt you.  Also note that
MakeMaker understands the VERBINST flag to quiet its part of the
installation; you must set it to zero (i.e. 'make install VERBINST=0') to
use it.  Finally, you can get the quickest possible installation by
skipping the installation of the manual pages and any setup by using "make
pure_all" and "make pure_install VERBINST=0 SKIP=1" (the latter, of course,
as root).

Finally Majordomo 2 will be installed, and some configuration information
will be suggested.  Be aware that this configuration information may not be
correct for all sites; especially sites running virtual domains.  Virtual
domain users and users of other MTAs, please let us know how to configure
things for you.


Using a Response File
---------------------
You can prepare a response file that has the answer to each
configuration question.  This is currently very fragile as it is still
in the preliminary stages.  Any change in the questions will cause a
response file to break, so use this approach with caution.


Adding a New Domain
-------------------
It is possible to configure Majordomo after installation to support
additional virtual domains.  To do so, run the shell command

  make domain

(usually as the root user) in the top-level source directory.


Changing the Site Configuration
-------------------------------
It is also possible to change the sitewide configuration (such as the
site master password and queueing options) without reinstalling the
software.  To do so, run the shell command

  make siteconfig

(usually as the root user) in the top-level source directory.


Testing after Installation
--------------------------
After the software has been installed, it may be necessary to restart
your MTA software to recognizes Mj2's mail aliases.  To test the
server, send the following command:
  help overview
in the body of a message to the server address.  The overview document
that you receive from the server briefly introduces Mj2's extensive help
system.


Interacting with Majordomo
--------------------------
Majordomo should respond to commands which are e-mailed to the server
address.  As in Majordomo version 1, commands must be in the body of an
e-mail message.  See the "admin_commands" and "commands" help files
for more information.

New with Majordomo 2 is the shell interface; it can be used to interact
with the server via the command line.  This is in general much easier
for people with shell access to the computer where Mj2 is running.
Nearly everything that can be done from the email interface can be done
from the shell interface, along with a few other things like interactive
editing of configuration settings and documents.

The mj_shell program also works interactively; just run it without any
Majordomo commands and it will prompt you.  If the Term::ReadLine::Perl
or Term::ReadLine::Gnu module is installed on your system, mj_shell will
also support command completion for commands and list names, and command
history.   See the "mj_shell" help file for more information.

If you have chosen WWW support during the installation process, three
WWW interfaces will be available:  mj_wwwadm, mj_wwwusr, and mj_confirm.
See the "mj_wwwadm" help file for more information.


Reporting Problems
------------------
Please report bugs to [email protected] and CC a copy to
[email protected] (just in case).  Please be sure to include information on
what version of Majordomo 2 you're running (including the time you checked
it out of CVS if you did so), the version of Perl you're using and the OS
you're running.  We may also need to know the versions of any relevant
modules and the configuration options you chose.

To participate in the Majordomo 2 developers' mailing list, write to 
  [email protected]
and in the body of the message, put this command:
  sub mj2-dev

All Mj2-related questions and comments are welcome on mj2-dev, if they
are phrased politely.