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.
The Sympa distribution is available from http://listes.cru.fr/sympa/. All important resources are referenced there:
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.
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.
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.
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.
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.
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/.
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.catIf 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.
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.
This directory contains one directory per active
list, as well as some message files like helpfile,
lists.header, lists.footer
Sympa uses 5 queues to store:
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 directory where the general configuration files (~sympa/expl/lists and ~sympa/expl/helpfile files) and the sub-directories specific to each list are located.
Example: home /home/sympa/expl
The directory where listmaster can store site-specfic scenari
(, page
).
Example: home /home/sympa/expl
This keyword is mandatory. It is the name of the machine used in From: header during responses to administrative requests.
Example: host listhost.cru.fr
Address (left part, name before the @ sign) used in From: header during responses to administrative requests.
Example: email listserv
The email address of the listmaster user who can perform global serveur command.
Example: email listmaster@cru.fr
File name for list subscribers files.
List config files name.
List statistic file name.
Name of the helpfile file (located in the ~sympa/expl/ directory) containing the help sent in response to a HELP command.
The files sample/helpfile.fr, sample/helpfile.gb, sample/helpfile.advanced.fr and sample/helpfile.advanced.gb
in the source distribution are given as a minimum user documentation.
Name of the helpfile.advanced file. List's owners and editors will receive this file in addition to helpfile file with documentation about privilegied commands.
When Sympa answers to the LISTS command, it uses first the file given by the lists_header keyword, then it inserts the list of lists with one line per list (using list parameters subject and visibility). Then, it adds the file given by the lists_footer keyword at the end.
Information returned by LISTS command are conditional to visibility list parameter, which default value is conceal.
File name for welcome messages.
Directory name where Sympa store list archives.
File name for good bye messages, sent at unsubscription time.
File name for removed messages, sent when an owner deletes a subscription.
File name for header added to list messages. The file which name is defined here should be placed in list directory.
File name for footer added to list messages
Default mask for file creation (see umask(2)).
Example: umask 007
Name of sub-system (facility) for sending messages.
Example: syslog LOCAL2
Sympa communication with syslogd can be performed using either UDP or Unix socket type. Set log_socket_type to inet to use UDP or unix for Unix sockets.
Maximum number of SMTP delivery child processes launched by Sympa. This is the main load control parameter.
Example: maxsmtp 500
Maximum size allowed for messages distributed by Sympa. This may be custumized per list by setting max_size list parameter.
Example: max_size 2097152
Maximum number of recipients per sendmail call. This grouping factor makes it possible for the MTA (sendmail) to optimize the number of SMTP sessions for message distribution.
Maximum number of different internet domains within addresses per sendmail call.
Absolute call path to SMTP message transfert agent (sendmail for example).
Example: sendmail /usr/sbin/postfix
The directory which contains the queue, used both by the queue program and the sympa.pl daemon.
Example: queue /home/sympa/queue
This directory contains the queue for messages to be moderated.
Directory containing the queue for the digests (only for lists offering a digest mode).
Example: queuedigest /home/sympa/queuedigest
Subscription expiration process queue
Queue for messages awaiting confirmation from their sender (see send privatekey and publickey parameter)
Queue to store all messages distributed in a list configured for WWSympa html archives. (see web_archive parameter)
Conservation time (in days) for ``bad'' messages in spool (as specified by queue). Sympa keeps messages rejected for various reasons (badly formatted messages, messages coming from loops, etc.) in this directory, under a name prefixed by BAD. This configuration variable controls the number of days these messages are kept.
Example: clean_delay_queue 3
Expiration date (in days) in moderation spool (as specified by queuemod). Beyond this deadline, messages that have not been processed are deleted. The content of this spool can be consulted for each moderated list using a key along with the MODINDEX command.
Expiration delay (in days) in an authentication queue. Beyond this deadline, messages not enabled are deleted.
This is the multilinguale catalogs location (nls). Must be set accordind to the ~src/nls/Makefile.
The is the language for Sympa. The corresponding message catalog (.cat) located in msgcat directory will be used.
Waiting period (in seconds) between each scan of main queue. Never set this value to 0!
Priority applied to Sympa commands while running the spool.
Available since release 2.3.1.
Priority for processing of messages for <listname>-request, ie for owners of the list.
Available since release 2.3.3
Priority for processing messages for <listname>-owner in the spool. This address will receive non-delivery reports (bounces) and should have a low priority.
Available since release 2.3.3
Default priority for messages if not defined in list configuration file.
Available since release 2.3.1.
The file where the sympa.pl daemon stores its process number. Warning: the sympa user must be able to write in this file, and to create it if it doesn't exist.
Example: pidfile /var/run/sympa.pid
The following parameters are needed when using a RDBMS and not required otherwise:
Database management system used (e.g. mysql, Pg, Oracle)
Name of the database containing user information. See
detailed description on database structure, ,
page
.
Database host name.
User with read access on the database.
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 ).
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
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).
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.
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.
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.
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
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>
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.
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:
Sets debug mode in maximum verbosity, tracing each subroutine calls.
su sympa -c "/usr/local/sympa/bin/sympa.pl -l fr"