next up previous contents index
Next: 3. Creation of mailing lists Up: Sympa Automatic Multi-posting System Previous: 1. Presentation   Contents   Index

Subsections

2. Installation

Sympa is a program written in Perl language. It also calls a short program written in C to perform some tasks for which it is not reasonable to entrust an interpreted language.

2.1 Getting Sympa, related links

The Sympa distribution is available from http://listes.cru.fr/sympa/. All important resources are referenced there:

2.2 Prerequisites

Sympa installation and configuration are relatively easy tasks for an administrator who already has a good deal of experience with Unix systems and installation of tools written in Perl.

The user will note that a large part of the installation time will be devoted to installation of the prerequisites if they are not already on the system. The number of ancillary tools required is not really of great importance, but on a current Unix system, it should be possible to do this without much of a problem. We strongly advise carrying out the system installations and checks in the order listed below; these steps will be explained in detail in later sections.

2.2.1 System requirements

You should have a Unix system that is more or less recent in order to be able to use Sympa. In particular, it is necessary that your system have an ANSI C compiler (on the whole, in the case which is of interest to us, your compiler should support prototypes) as well as XPG4-standard NLS (Native Language Support, for languages other than English) extensions.

Sympa has been installed and tested on the following systems, therefore you should not have any special problems:

Is there anyone who wants to port it on NT ? ;-)

If your Unix system has a gencat command as well as catgets(3) and catopen(3) functions, it is likely that it has NLS extensions and that these extensions comply with the XPG4 specifications.

Finally, most Unix systems are now supplied with an ANSI C compiler; if this is not the case, you can install the gcc compiler, which you will find on the nearest GNU site, for example in France.

To complete the operation, you should make sure that you have a recent enough release of the sendmail MTA, e.g. release 8.9.x or a more recent release. You may also use postfix or qmail.

2.2.2 Install Berkeley DB (NEWDB)

Unix systems often have a highly simple system to manage indexed files. This consists of extensions known under the name dbm and ndbm. For many programs, these are not sufficient, and in particular for Sympa, which uses the DB package initially developed at the University of California in Berkeley, and which is now maintained by the company Sleepycat software. Many UNIX systems like Linux,FreeBSD or Digital Unix 4.x have the DB package in the standard version. If not you should install this tool if you have not already done so.

You can retrieve DB on the Sleepycat site and read its documentation to install it in your system.

2.2.3 Install Perl

To be able to use Sympa, you must have release 5.004_03 of the Perl language or a later release and several CPAN modules. Run perl check_perl_modules.pl in src will check all perl requierements.

You will find a current release of the Perl interpreter in the nearest CPAN archive. If you do not know where to find a nearby site, use the CPAN multiplexer; it will find one for you.

2.2.4 Install other required CPAN modules

Sympa makes use of other modules, which are found on CPAN. These modules are:

If you plan to store and extract user data into or from a relational database (strongly recommended):

If you plan to interface some LDAP directory to extract subscribers:

You can retrieve these tools on any CPAN archive site. The suggested address is just one of these sites.

These modules are easy to install, as are most CPAN modules:

You have now completed installation of all the modules required to run Sympa correctly, and you can go on now to the installation and configuration of the actual Sympa program.

2.2.5 Create a Unix user

Last step before installing Sympa: create a Unix user, and preferably, a group specific to the program. Most of the installation will be carried out with this account. We suggest that you use the name sympa for both user and group.

If you are paranoid (and you are right to be so), you might prefer to work with two users: one for the files which are never changed and one for those that can be changed by Sympa. Since the selections for implementing this solution were not used in this documentation, it is left up to you to decide.

In the rest of this documentation, numerous files will be located in the user's login directory which you will have created in your system or in a sub-directory. We will mark this login directory with ~sympa/.

2.3 Compilation and installation

Before using Sympa, you have to customize the sources so that you can specify a few specific parameters in your installation.

To start, extract the sources from the archive file, for example from the ~sympa/ directory: the archive will create a directory named sympa-2.2.5/ where all the useful files and directories will be located. In particular, you will have a doc/ directory containing this documentation in various formats, a sample/ directory containing a few examples of a configuration file, nls/ directory where multi-linguage messages are stored and of course, the src/ directory.

Example:

# su - sympa
$ gzip -dc sympa-2.2.5.tar.gz | tar xf -

Before running make in both src/ and nls/ directories, you have to edit and configure src/Makefile and nls/Makefile so that you can customize the first part in them. We advise against changing anything located after the STOP line.

The src/Makefile file contains explanations for the fields, which you may have to change. Make sure that the only parameter that has to be hard coded into Sympa is the default location of the configuration file (default is /etc/sympa.conf), and it is of course possible for you to select another Sympa start command line from it. We recommend that you put the complete access path of the ~sympa/bin/ directory in the DIR variable. This directory will automatically be created during the first installation. The PERL, INSTALL, etc. variables in src/Makefile may also be changed.

Once this file has been configured, you need to run make;make install commands in the src/ directory. This will generate the binary for the queue program, and install the Sympa binaries in their final slot, while having propagated a few parameters in the Perl files, as for example the access path to the Perl program:

$ id
uid=89(sympa) gid=89(sympa)
$ cd src ; make ;  make install
gcc -g -DCONFIG=\"/etc/sympa.conf\" -o queue queue.c
Checking needed CPAN modules ...
/usr/bin/perl ./check_perl_modules.pl
******* Check perl for SYMPA ********

Checking for PERL version:
-----------------------------
your version of perl is OK (5.00404  >= 5.00403)

Checking for REQUIRED modules:
-----------------------------
MailTools           : OK (1.32 >= 1.13)
MIME-Base64         : OK (2.09 >= 1.0)
IO-stringy          : OK (1.113  >= 1.0)
Msgcat              : OK (1.00 >= 1.0)
DB_FILE             : OK (1.60 >= 1.0)
MIME-Tools          : OK (4.121  >= 1.0)
MD5                 : OK (1.7 >= 1.0)

Checking for OPTIONAL modules:
-----------------------------
perl-ldap           : OK (0.10 >= 0.10)
DBI                 : OK (1.06 >= 1.0)
******* NOTE *******
You can retrive all theses modules from any CPAN server
(for example ftp://ftp.pasteur.fr/pub/computing/CPAN/CPAN.html)

Doing multiple substitutions while installing ...
Overwriting /home/sympa/bin/sympa.pl
Overwriting /home/sympa/bin/Archive.pm
Overwriting /home/sympa/bin/Commands.pm
Overwriting /home/sympa/bin/Conf.pm
Overwriting /home/sympa/bin/Language.pm
Overwriting /home/sympa/bin/List.pm
Overwriting /home/sympa/bin/Log.pm
Overwriting /home/sympa/bin/mail.pl
Overwriting /home/sympa/bin/msg.pl
Overwriting /home/sympa/bin/smtp.pm
Overwriting /home/sympa/bin/tools.pl
Overwriting /home/sympa/bin/Version.pm
Installing Queue binary...

Now proceed to the message catalog generation:

\$ cd ../nls ; make ;  make install
generating catalog fr
generating catalog us
generating catalog es

Installing catalog.../home/sympa/nls/fr.cat
Installing catalog.../home/sympa/nls/us.cat
Installing catalog.../home/sympa/nls/es.cat
If you want to customize existing NLS or to produce a new language supported by Sympa, refer to nls/README.

If everything goes smoothly, the ~sympa/bin/ directory will contain various Perl programs as well as the queue binary. You will note that this binary has the set-uid-on-exec bit (owner is the sympa user): this is normal and indispensable for Sympa to run correctly.

2.3.1 Choosing directory location

The previous step does not automatically copy all the files required because the location of all other components must be configured by the administrator in the /etc/sympa.conf file.

It is possible to disperse files and directories everywhere in the Unix system, however we recommand storing all the directories and files in the sympa user's login directory.

You also have to create these directories now. You can use restrictive authorizations if you like, since only programs running with the sympa account will have to access them.

Here is a typical Sympa hierarchy with 2 lists named foo and news-letter. Emphasized objects are optional, bold objects need your attention and others are automatically created by Sympa at either installation or run time.


2.4 Robot configuration file /etc/sympa.conf

The preceding step does not install the configuration files (in some cases, this may require the use of privileges), in particular the /etc/sympa.conf file, which will supposedly have been installed in a system file, so as to prevent a user, even the sympa user from being able to change it, whether or not it is voluntary.

The /etc/sympa.conf configuration file contains numerous parameters which are read on start-up of Sympa and allow the program to run. If you have to change this file, do not forget that you have to restart Sympa. You will find an example of this file in the sample/ directory in the source distribution. Make a copy of it and work with the copy; that way, you will always have the master copy at hand's reach, only minor adaptation should be necessary.

The /etc/sympa.conf file contains directives in the following format:

keyword value

Comments start with the # character at the beginning of a line. Empty lines are also considered as comments and are ignored. There should only be one directive per line, but their order in the file is of no importance.

The following parameters are needed when using a RDBMS and not required otherwise:


2.5 Robot aliases

An electronic list manager such as Sympa runs in two steps:

To differentiate processing of administrative requests (subscription, unsubscription, help request, etc.) from messages sent to a list, a special mail alias is reserved for administrative requests, so that Sympa can be accessible and users can join it. Thus, the lines below must be added to the sendmail alias file (often /etc/aliases):

sympa:             "|/usr/local/sympa/bin/queue sympa"
sympa-request:     postmaster@cru.fr
sympa-owner:       postmaster@cru.fr

should be the address of the robot administrator, who is the person who takes care of Sympa management (here ).

is the return address for Sympa error messages.

Do not forget to run newaliases after any change to the /etc/aliases file!

Note: aliases based on (in addition to those based on ) can be added in order to facilitate the task of users accustomed to the and names. For example:

listserv:          sympa
listserv-request:  sympa-request
majordomo:         sympa
listserv-owner:    sympa-owner

Note: it will also be necessary to add entries in this alias file to create lists (see list creation section, 3.1, page [*]).

2.6 Logs

Sympa keeps traces of each of its procedures in its log file. Nevertheless, this requires configuration of the syslogd daemon. In fact, Sympa, by default, uses local1 facility, as specified in /etc/sympa.conf. Thus, a line must be added in the syslogd configuration file (/etc/syslog.conf). For example:

local1.*       /var/log/sympa

Then reload syslogd.


2.7 Using Sympa with a RDBMS

It is possible for Sympa to store its user information within a Relational DataBase System such as MySQL, PostgreSQL, Oracle, Ingres. Currently only MySQL is implemented although other RDBMS should be easy to recognise thanks to the standard API used by Sympa: DBI (DataBase Interface).

2.7.1 Prerequisites

You need to have a DataBase System installed (not necessarily on the same host as Sympa) as far as a Perl DBD (DataBase Driver) is provided for it. Check the DBI Module Availability.

2.7.2 Install Perl modules

Sympa will use DBI to communicate with the database system and therefore requires the DBD for your database system. DBI and DBD::YourDB (Msql-Mysql-modules for MySQL) are distributed as CPAN modules. Refer to  [*], page [*] for installation details of these modules.

2.7.3 Create sympa DataBase

2.7.3.1 Database structure

The sympa database structure is slightly different from the structure of a subscribers file. A subscribers file is a text file based on paragraphs (almost similar to the config file) ; each paragraph completely describes a subscriber. If somebody is subscribed to two lists, he/she appears in both subscribers files.

The DataBase distinguishes information relative to a person (email, real name, password) and his/her subscription options (list concerned, date of subscription, reception option, visibility option). This results in separating the data in two tables : user_table and subscriber_table joined together by a user/subscriber email.

2.7.3.2 Database creation

create_db script below will create the sympa database for you. You can find it in the script/ directory of the distribution (currently scripts are for mysql and postgresql).

## MySQL Database creation script
CREATE DATABASE sympa;

## Connect to DB 
\r sympa

CREATE TABLE user_table (
        email_user              char (100) NOT NULL,
        gecos_user              char (150),
        password_user           char (20),
        cookie_delay_user       int,
        lang_user               char (5),
        PRIMARY KEY (email_user)
);

CREATE TABLE subscriber_table (
        list_subscriber         char (50) NOT NULL,
        user_subscriber         char (100) NOT NULL,
        date_subscriber         datetime NOT NULL,
        visibility_subscriber   char (20),
        reception_subscriber    char (20),
        PRIMARY KEY (list_subscriber, user_subscriber)
);

You can execute the script using a simple SQL shell such as mysql or psql.

Example:

# mysql  < create_db.mysql

2.7.3.3 Import data from subscribers files

You might need to import subscribers data from an older version of Sympa into sympa database. script/load_subscribers script should do the job :

# load_subscribers.pl <listname>

2.7.4 Sympa configuration

To store subscribers information in your newly created database, you first need to tell Sympa what kind of database he's going to work with, then you must configure your list to work with the database.

You define the database source in sympa.conf : db_type, db_name, db_host, db_user, db_passwd.

In the list config file, set user_data_source to database. Sympa will now extract and store user information for this list from the database instead of using subscribers file. Though subscribers information are dumped in subscribers.db.dump at every shutdown to allow hand rescue restart (by renaming subscribers.db.dump to subscribers and changing user_data_source parameter) if the database is out of order.

2.8 Daemon loading

Once all files are configured, all you have to do is start Sympa. To do this, add the following sequence or its equivalent in your /etc/rc.local:

su sympa -c /usr/local/sympa/bin/sympa.pl

sympa.pl recognises the following command line arguments:


next up previous contents index
Next: 3. Creation of mailing lists Up: Sympa Automatic Multi-posting System Previous: 1. Presentation   Contents   Index
root
1999-10-21