Import ezmlm-idx 0.40

[ezmlm] / INSTALL.idx

$Id: INSTALL.idx,v 1.49 1999/12/24 20:12:57 lindberg Exp $
$Name: ezmlm-idx-040 $

Like any other piece of software (and information generally), ezmlm-idx
comes with NO WARRANTY.

This file is for installing ezmlm-idx for the first time on a system
that may have ezmlm-0.53. If you're already using ezmlm-idx, see
UPGRADE.idx instead.

Things you have to decide before starting:

   Common for ezmlm-0.53:
   Put the desired ezmlm bin path into conf-bin. Default "/usr/local/bin/ezmlm",
   but for e.g. rpm packages it's "/usr/bin". Adjust conf-man accordingly.
   For installations (e.g. Debian) where qmail is not in "/var/qmail", adjust
   conf-qmail.

   NOTE: If you follow the test instructions in INSTALL of ezmlm-0.53 after
   adding ezmlm-idx, step 6 will fail. Before this step, edit
   ~/testlist/editor and remove the ezmlm-reject line.

HOW TO BUILD, TEST, AND INSTALL:

 1. Expand the ezmlm-0.53.tar.gz archive. expand the ezmlm-idx-0.xx.tar.gz
   archive:
        % zcat ezmlm-0.53.tar.gz | tar -xvf
        % zcat ezmlm-idx-0.xx.tar.gz | tar -xvf

 2. Copy the contents of the archive to your ezmlm-0.53 directory.
        % mv ezmlm-idx-0.xx/* ezmlm-0.53/

 3. Patch the ezmlm-0.53 source:
        % cd ezmlm-0.53
        % patch < idx.patch

    If you patch utility failes with this, get GNU patch.
    [ezmlm-issubn, an enhanced version of ezmlm-issub is part of this package.
    The patch for the ezmlm-return bug is also part of this package.]

 4. If your 'crontab' binary does not live in '/usr/bin' edit 'conf-cron'
    now to reflect the correct path.

 5. RDBM Support.

    MySQL:
    If you want to compile ezmlm with MySQL support (http://www.tcx.se),
    edit sub_mysql/conf-sqlcc (include files) and mysql/conf-sqlld (libraries)
    to reflect your MySQL installation (see MySQL documentation). The files
    are preset for RedHat Linux-i386. On some systems, the ``-lnsl'' should
    be removed from conf-sqlld. The package has been tested with MySQL 3.22.

    (Programs compiled with MySQL support will work like
    their non-MySQL counterparts for lists that are not specifically
    set up to take advantage of MySQL support.) Do:
        % make mysql

    PostgresSQL:
    If you want to compile ezmlm with PostgreSQL support 
    (http://www.postgreSQL.org), edit sub_pgsql/conf-sqlcc (include files) 
    and pgsql/conf-sqlld (libraries) to reflect your PostgreSQL installation 
    (see PostgreSQL documentation). Do:
        % make pgsql

    Others:
    If you're familiar with C programming for the particular RDBMS, it will
    take you no more than a few hours to adapt the files in sub_mysql (see
    docs there). Create a new sub_????, tar and gzip it and send it to
    lindberg#@id.wustl.edu for inclusion into the package.

 6. Compile the programs and man pages:
       % make clean
       % make; make man

 7. To use a language other than US English as the default for list texts:
       % make ISO

    where ``iso'' is the ISO language designation. Currently supported
    are: cz, da, de, en_US, fr, jp, pl, pt_BR, sv. NOTE: A normal ``make'' sets
    up the en_US version (as before). ezmlmrc files for your language
    may be available via ftp://id.wustl.edu/pub/patches/ezmlmrc. If not,
    please feel free to contribute one (translate ezmlmrc.en_US, but leave
    comments intact for "diff").

 8. Test the programs:
        a. Create a user ``eztest'' or edit ezmlm-test to use another user name.
           This user should be able to execute the new binaries and also needs
           to have read access to ezmlm-test (chmod 755 ezmlm-test).
        b. Change to that user.
        c. From the build directory, execute ezmlm-test:
                % ./ezmlm-test

        ezmlm-test will set up a test list, execute the various programs, and
        test most functions of most programs. It works only if your qmail
        installation works and allows sending mail to the local user. If you
        use another user name, add ``-u other_user_name''. NOTE that the
        arguments must be separated by a space from the switches.

        Occasionally, ezmlm-test fails. This is usually due to problems with
        ezmlm-test on your particular platform/installation and not due to
        problems in ezmlm-idx. Please report problems with ezmlm-test, and if
        you can, patches for correcting it.


 9. To test the SQL functions, set up a mysql database ``ezmlm'' accessible
    to a user at this host (see MySQL/PostgreSQL docs; the ezmlm-mktab script
    creates the necessary tables (see man page) but you must first create a
    database and a user with sufficient access.

    The following command creates a database for use with ezmlm-test.
    NOTE that ezmlm-mktab and ezmlm-test options must be separated from the
    switch, whereas the passwd argument for mysql -p must immediately
    follow the switch.
        % ./ezmlm-mktab -d list | mysql -hhost -uuser -ppasswd -f ezmlm

    or for PostgresSQL:
        % ./ezmlm-mktab -d list | pgsql [...] ezmlm

    Now, as the ``eztest'' user, execute:
        % ./ezmlm-test -l user -p passwd -h host

    This will test the SQL part of the binaries. ``host'' defaults to
    ``localhost'' and ``user'' defaults to ``ezmlm''. There is no default
    for passwd and indeed ezmlm-test uses this switch to know to work
    with SQL support. To execute under a user other than ``eztest'',
    add a ``-u testuser'' switch. Note that -p has to be specified even if
    the database has no password. In this case, use -p ''.

10. If you for some reason want to rebuild binaries without MySQL support, do:
        % make std
        % make

11. Copy binaries and man pages to the correct locations.
        # make setup
        (or copy manually).
    If you'd like to retest the installation, change uid to the test user
    ``eztest'' and change to the ezmlm binary directory. Now run ezmlm-test
    as before.


12. Your lists will run as before. To enable ezmlm-idx features like
    threaded archive access, digest, etc, use:

        % ezmlm-make -e [switches] DIR dot local host

    where ``DIR dot local host'' are the arguments used to create the list,
    and ``switches'' are desired options (see ezmlm-make man page). Future
    adjustments can be made with:

        % ezmlm-make -+ [switches] DIR

    where ``switches'' are desired _changes_ from the previous configuration.

------ OPTIONAL ------

13. If you want qmail to add a subscriber-adapted List-Unsubscribe header to
    outgoing messages, apply the enclosed qmail-verh-0.03.tar.gz patch to
    qmail-1.03 and follow the documentation in that archive. This is a
    failsafe way in which to unsubscribe, even if subscriber or list have
    changed address.

14. If you want to use large lists with custom QMQP servers, apply the
    qmail-qmqp.tar.gz patch per instructions in the archive. You need this
    only if you want per-[sub]list control over the QMQP servers used.
 
15. (This can be done later if you decide to use ezmlm-cron(1). It is not
    needed for normal lists and mainly for ``legacy installations''.)
    The ezmlm-cron(1) program can be run SUID/SGID a special user with crond
    access. This allows your users to use ezmlm-cron to generate digest
    trigger messages, without being able to directly use crond. To enable
    this feature create a special user, e.g. "ezmlm". Then:

        # chown ezmlm /usr/local/bin/ezmlm-cron
        # chmod 4555 /usr/local/bin/ezmlm-cron

    and create ~ezmlm/ezcronrc as described in the ezmlm-cron(1) man
    page. You may need to modify the path in the commands above if
    you have installed ezmlm in a non-default location. ezmlm-cron refuses
    to run SUID root.

    This user can read its crontab file which may contain digest codes from
    other users. Thus, this should be a reserved user name, not one of an 
    ordinary user.


16. If you would like to make your archived lists available via the World
    Wide Web, you must install the ezmlm-cgi program which comes with
    ezmlm-idx versions starting with ezmlm-idx-0.40. When ezmlm-idx is compiled
    with the 'make' command, ezmlm-cgi is compiled also, however, it is not
    installed. Installation of the program allows one to view the archives by
    date, thread and author.  See, ezmlm-cgi.1 for more details.

17. ezmlm-cgi must be installed where all other common gateway interface
    ("CGI") programs are installed on your system. For most Un*x based system,
    this will be in a directory titled 'cgi-bin' which is also, generally
    speaking, in the root directory for your web server. For example, for apache
    installations where /usr/local/apache is the root directory for the web
    server, the directory /usr/local/apache/cgi-bin is where globally availably
    CGI programs are located. You must copy the ezmlm-cgi program to this
    location:

        % cp /ezmlm-0.53/ezmlm-cgi /usr/local/apache/cgi-bin

18. ezmlm-cgi should be installed SUID root. Examine the source code to make
    yourself comfortable that the program is safe. After copying the program to
    the 'cgi-bin' directory, change the ownerships and permissions as follows:

        % chown root.root ezmlm-cgi
        % chmod 4755 ezmlm-cgi

    If you are using ezmlm-cgi for a single user, you can install it SUID that
    user and place the config file (see below) as .ezcgirc in the same directory
    as the program. If the list archive is readable to the httpd user, you do
    not have to install it SUID at all (see man page for details).

19. ezmlm-cgi uses a configuration files called 'ezcgirc' which must reside
    in the /etc/ezmlm directory. First create the directory:

        % mkdir /etc/ezmlm

    Then use your favorite text editor to create the ezcgirc file. 

    The file parameters are set forth on the first line. Comments are
    allowed if preceded by the '#' in position 1. Lists are input by number
    which is an arbitrary identifier with the exception of list '0' which is the
    default list shown on the web page. As an example, the following utilizes a
    list 'test@example.com' which is owned by the 'alias' user with a UID of
    7827. The list resides in the directory '/var/qmail/alias/test' and its home
    page is at 'http://www.example.com/test'. With the foregoing setup, the
    ezcgirc file's contents are as follows:

# Format for ezcgirc file
#listno;uid;listdir;listaddr;buttonbar;charset;style;bannerprog
0;7827;/var/qmail/alias/test;test@example.com;[Home]=http://www.example.com/test

    Note there are no entries for 'charset', 'style' and 'bannerprog' Where
    no entries are made, the default variables are assumed. The above
    configuration assumes that the character set 'iso-8859-1' and that no
    style sheet is used. Since formatting is largely controlled by the
    style sheet, the output doesn't look exciting on a GUI browser. Start with
    ezcgi.css in the distribution, and modify to taste. See www.ezmlm.org
    for URLs to archives using different style sheets/banners.

20. Finally, before accessing the list via the web, you must archive any
    existing list and add an entry to listdir/editor to archive future posts.
    You must also run ezmlm-idx (first see man pages for both programs):
        
        % ezmlm-idx DIR
        % ezmlm-archive -c DIR

21. For any existing lists which you would like to archive,
    add the following line after the call to ezmlm-send in listdir/editor:

        | /usr/local/ezmlm/ezmlm-archive listdir/DIR || exit 0

    This is automatically done when running:

        % ezmlm-make -+i DIR

22. To display your web based archive, open your browser as follows:

        %lynx http://localhost/cgi-bin/ezmlm-cgi

 ------------- End Optional items -----------   

23. That's it! To report success (helps to track platform-specific problems):

       % ( echo 'First M. Last'; cat `cat SYSDEPS` ) \
         | mail cfl-src@id.wustl.edu

Replace First M. Last with your name.

Send bugs reports, ideally with patch, to 'lindberg@id.wustl.edu'.