Next: 4. sympa.conf parameters Up: Sympa Mailing Lists Management Software version Previous: 2. what does Sympa consist of Contents Index
Subsections

- 3.1 Obtaining Sympa, related links
- 3.2 Prerequisites
  - 3.2.1 System requirements
  - 3.2.2 Install Berkeley DB (NEWDB)
  - 3.2.3 Install PERL and CPAN modules
  - 3.2.4 Required CPAN modules
  - 3.2.5 Create a UNIX user
- 3.3 Compilation and installation
  - 3.3.1 Choosing directory locations
- 3.4 Robot aliases
- 3.5 Logs
- 3.6 sympa.pl

# 3. Installing Sympa

Sympa is a program written in PERL. It also calls a short program written in C for tasks which it would be unreasonable to perform via an interpreted language.

# 3.1 Obtaining Sympa, related links

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

- sources
- `RELEASE_NOTES`
- .rpm and .deb packages for Linux
- user mailing list (see , page )
- contributions
- ...

# 3.2 Prerequisites

Sympa installation and configuration are relatively easy tasks for experienced UNIX users who have already installed PERL packages.

Note that most of the installation time will involve putting in place the prerequisites, if they are not already on the system. No more than a handful of ancillary tools are needed, and on recent UNIX systems their installation is normally very straightforward. We strongly advise you to perform installation steps and checks in the order listed below; these steps will be explained in detail in later sections.

- identification of host system characteristics

- installation of DB Berkeley module (already installed on most UNIX systems)

- installing a (, , or ) and creating Sympa's Database. This is required for using the web interface for Sympa. Please refers to ¨Sympa and its databasesection (, page ).

- installation of CPAN (Comprehensive PERL Archive Network) modules

- creation of a UNIX user

## 3.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 (in other words, 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:

- Linux (various distributions)
- FreeBSD 2.2.x and 3.x
- Digital UNIX 4.x
- Solaris 2.5 and 2.6
- AIX 4.x
- HP-UX 10.20

Anyone willing to port it to NT ? ;-)

If your UNIX system has a `gencat` `gencat` command as well as `catgets(3)` `catgets(3)` and `catopen(3)` `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` `gcc` compiler, which you will find on the nearest GNU site, for example in France.

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

## 3.2.2 Install Berkeley DB (NEWDB)

UNIX systems often include a particularly unsophisticated mechanism to manage indexed files. This consists of extensions known as `dbm` and `ndbm`, which are unable to meet the needs of many more recent programs, including 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, where you will also find clear installation instructions.

##
3.2.3 Install PERL and CPAN modules

To be able to use Sympa you must have release 5.004_03 or later of the PERL language, as well as several CPAN modules.

At `make` time, the `check_perl_modules.pl` `check_perl_modules.pl` script is run to check for installed versions of required PERL and CPAN modules. If a CPAN module is missing or out of date, this script will install it for you.

You can also download and install CPAN modules yourself. 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 multiplexor; it will find one for you.

## 3.2.4 Required CPAN modules

The following CPAN modules required by Sympa are not included in the standard PERL distribution. We try to keep this list up to date ; if you have any doubts run the `check_perl_modules.pl` `check_perl_modules.pl` script.

- `DB_File` (v. 1.50 or later)
- `Msgcat`
- `Digest-MD5`
- `MailTools` (version 1.13 o later)
- `IO-stringy`
- `MIME-tools` (may require IO/Stringy)
- `MIME-Base64`
- `CGI`
- `File-Spec`

Since release 2, Sympa requires an RDBMS to work properly. It stores users' subscriptions and preferences in a database. Sympa is also able to extract user data from within an external database. These features require that you install database-related PERL libraries. This includes the generic Database interface (DBI) and a Database Driver for your RDBMS (DBD) :

- `DBI` (DataBase Interface)

- `DBD` (DataBase Driver) related to your RDBMS (e.g. Msql-Mysql-modules for MySQL)

If you plan to interface Sympa with an directory to build dynamical mailing lists, you need to install PERL LDAP libraries :

- `Net::LDAP` (perlldap).

Passwords in Sympa database can be crypted ; therefore you need to install the following reversible cryptography library :

- `CipherSaber`

For performence concerns, we recommend using WWSympa as a persistent CGI, using . Therefore you need to install the following Perl module :

- `FCGI`

## 3.2.5 Create a UNIX user

The final step prior to installing Sympa: create a UNIX user (and if possible 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.

Numerous files will be located in the Sympa user's login directory. Throughout the remainder of this documentation we shall refer to this login directory as `~sympa/`.

# 3.3 Compilation and installation

Before using Sympa, you must customize the sources in order to specify a small number of parameters specific to your installation.

First, extract the sources from the archive file, for example in the `~sympa/src/` directory: the archive will create a directory named `sympa-3.3.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 configuration files; an `nls/` directory where multi-lingual messages are stored; and, of course, the `src/` directory for the mail robot and `wwsympa` for the web interface.

Example:

> `# su -
> $ gzip -dc sympa-3.3.5.tar.gz | tar xf -`

Now you can run the installation process :

> `$ ./configure
> $ make
> $ make install
> `

`configure` `configure` will build the `Makefile` ; it recognizes the following command-line arguments :

- `- -prefix=PREFIX` `- -prefix=PREFIX`, the Sympa homedirectory (default /home/sympa/)

- `-with-bindir=DIR` `-with-bindir=DIR`, user executables in DIR (default /home/sympa/bin/)
  `queue` and `bouncequeue` programs will be installed in this directory. If sendmail is configured to use smrsh (check the mailer prog definition in your sendmail.cf), this should point to `/etc/smrsh`. This is probably the case if you are using Linux RedHat.

- `-with-sbindir=DIR` `-with-sbindir=DIR`, system admin executables in DIR (default /home/sympa/bin)

- `-with-libexecdir=DIR` `-with-libexecdir=DIR`, program executables in DIR (default /home/sympa/bin)

- `-with-cgidir=DIR` `-with-cgidir=DIR`, CGI programs in DIR (default /home/sympa/bin)

- `-with-iconsdir=DIR` `-with-iconsdir=DIR`, web interface icons in DIR (default /home/httpd/icons)

- `-with-datadir=DIR` `-with-datadir=DIR`, default configuration data in DIR (default /home/sympa/bin/etc)

- `-with-confdir=DIR` `-with-confdir=DIR`, Sympa main configuration files in DIR (default /etc)
  `sympa.conf` and `wwsympa.conf` will be installed there.

- `-with-exlpdir=DIR` `-with-exlpdir=DIR`, modifiable data in DIR (default /home/sympa/expl/)

- `-with-libdir=DIR` `-with-libdir=DIR`, code libraries in DIR (default /home/sympa/bin/)

- `-with-mandir=DIR` `-with-mandir=DIR`, man documentation in DIR (default /usr/local/man/)

- `-with-initdir=DIR` `-with-initdir=DIR`, install System V init script in DIR (default /etc/rc.d/init.d)

- `-with-piddir=DIR` `-with-piddir=DIR`, create .pid files in DIR (default /home/sympa/)

- `-with-perl=FULLPATH` `-with-perl=FULLPATH`, set full path to Perl interpreter (default /usr/bin/perl)

- `-with-openssl=FULLPATH` `-with-openssl=FULLPATH`, set path to OpenSSL (default /usr/local/ssl/bin/openssl)

- `-with-gencat=FULLPATH` `-with-gencat=FULLPATH`, set path to gencat (default /usr/bin/gencat)

- `-with-user=LOGIN` `-with-user=LOGIN`, set sympa user name (default sympa)
  Sympa daemons are running under this UID.

- `-with-group=LOGIN` `-with-group=LOGIN`, set sympa group name (default sympa)
  Sympa daemons are running under this UID.

- `-with-sendmail_aliases=ALIASFILE` `-with-sendmail_aliases=ALIASFILE`, set aliases file to be used by Sympa (default /etc/mail/sympa_aliases)

- `-with-virtual_aliases=ALIASFILE` `-with-virtual_aliases=ALIASFILE`, set postfix virtual file to be used by Sympa (default /etc/mail/sympa_virtual)

  This is used by the `alias_manager.pl` script :

- `-with-newaliases=FULLPATH` `-with-newaliases=FULLPATH`, set path to sendmail newaliases command (default /usr/bin/newaliases)

- `-with-newaliases_arg=ARGS` `-with-newaliases_arg=ARGS`, set arguments to newaliases command (default NONE)

  This is used by the `postfix_manager.pl` script :

- `-with-postmap=FULLPATH` `-with-postmap=FULLPATH`, set path to postfix postmap command (default /usr/sbin/postmap)

- `-with-postmap_arg=ARGS` `-with-postmap_arg=ARGS`, set arguments to postfix postmap command (default NONE)

`make` `make` will build a few binaries (`queue`, `bouncequeue` and `aliaswrapper`) and help you install required CPAN modules.

`make install` `make install` does the installation job. It it recognizes the following option :

- DESTDIR, can be set in the main Makefile to install sympa in DESTDIR/DIR (instead of DIR). This is useful for building RPM and DEB packages.

Since version 3.3 of Sympa colors are `sympa.conf` parameters (see , page )

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

## 3.3.1 Choosing directory locations

All directories are defined in the `/etc/sympa.conf` file, which is read by Sympa at runtime. If no `sympa.conf` file was found during installation, a sample one will be created. For the default organization of directories, please refer to , page .

It would, of course, be possible to disperse files and directories to a number of different locations. However, we recommend storing all the directories and files in the `sympa` user's login directory.

These directories must be created manually now. You can use restrictive authorizations if you like, since only programs running with the `sympa` account will need to access them.

#
3.4 Robot aliases

An electronic list manager such as Sympa is built around two processing steps:

- a message sent to a list or to Sympa itself (for subscribe, unsubscribe, help messages, etc.) is received by the SMTP server (`sendmail` `sendmail` or `qmail` `qmail`). The SMTP server, on reception of this message, runs the `queue` program (supplied in this package) to store the message in a queue, i.e. in a special directory.

- the `sympa.pl` daemon, set in motion at system startup, scans the queue. As soon as it detects a new message, it processes it and performs the requested action (distribution or processing of an administrative request).

To separate the processing of administrative requests (subscription, unsubscription, help requests, etc.) from the processing of messages destined for mailing lists, a special mail alias is reserved for administrative requests, so that Sympa can be permanently accessible to users. The following lines must therefore be added to the `sendmail` `sendmail` alias file (often `/etc/aliases`):

    sympa:             "| /home/sympa/bin/queue sympa"
    listmaster: 	   "| /home/sympa/bin/queue listmaster"
    bounce+*:          "| /home/sympa/bin/bouncequeue sympa"
    sympa-request:     postmaster
    sympa-owner:       postmaster

`sympa-request` should be the address of the robot administrator, i.e. a person who looks after Sympa (here `postmastercru.fr`).

`sympa-owner` is the return address for Sympa error messages.

The alias bounce+* is dedicated to collect bounces. It is useful only if at least one list uses `welcome_return_path unique` or `remind_return_path unique`. Don't forget to run `newaliases` `newaliases` after any change to the `/etc/aliases` file!

Note: aliases based on `listserv` (in addition to those based on `sympa`) can be added for the benefit of users accustomed to the `listserv` and `majordomo` 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 when lists are created (see list creation section, , page ).

# 3.5 Logs

Sympa keeps a trace of each of its procedures in its log file. However, this requires configuration of the `syslogd` `syslogd` daemon. By default Sympa wil use the `local1` facility (`syslog` parameter in `sympa.conf`). WWSympa's logging behaviour is defined by the `log_facility` parameter in `wwsympa.conf` (by default the same facility as Sympa).
To this end, a line must be added in the `syslogd` `syslogd` configuration file (`/etc/syslog.conf`). For example:

    local1.*       /var/log/sympa

Then reload `syslogd` `syslogd`.

Depending on your platform, your syslog daemon may use either a UDP or a UNIX socket. Sympa's default is to use a UNIX socket; you may change this behavior by editing `sympa.conf`'s `log_socket_type` parameter (, page ).

#
3.6 sympa.pl

Once the files are configured, all that remains is to start Sympa. At startup, `sympa.pl` will change its UID to sympa (as defined in `Makefile`). To do this, add the following sequence or its equivalent in your `/etc/rc.local`:

    ~sympa/bin/sympa.pl
    ~sympa/bin/archived.pl
    ~sympa/bin/bounced.pl
    ~sympa/bin/task_manager.pl

`sympa.pl` recognizes the following command line arguments:

- `-debug` `-debug` | `-d` `-d`

  Sets Sympa in debug mode and keeps it attached to the terminal. Debugging information is output to STDERR, along with standard log information. Each function call is traced. Useful while reporting a bug.

- `-config config_file` `-config config_file` | `-f config_file` `-f config_file`

  Forces Sympa to use an alternative configuration file. Default behavior is to use the configuration file as defined in the Makefile ($CONFIG).

- `-mail` `-mail` | `-m` `-m`

  Sympa will log calls to sendmail, including recipients. Useful for keeping track of each mail sent (log files may grow faster though).

- `-lang catalog` `-lang catalog` | `-l catalog` `-l catalog`

  Set this option to use a language catalog for Sympa. The corresponding catalog file must be located in `~sympa/nls` directory.

  For example, with the `fr.cat` catalog:

- `-keepcopy recipient_directory` `-keepcopy recipient_directory` | `-k recipient_directory` `-k recipient_directory`

  This option tells Sympa to keep a copy of every incoming message, instead of deleting them. recipient_directory is the directory to store messages.

      /home/sympa/bin/sympa.pl

- `-dump listname `|` ALL` `-dump listname `|` ALL`

  Dumps subscribers of a list or all lists. Subscribers are dumped in `subscribers.db.dump`.

- `-import listname` `-import listname`

  Import subscribers in the listname list. Data are read from STDIN.

- `-lowercase` `-lowercase`

  Lowercases e-mail addresses in database.

- `-help` `-help` | `-h` `-h`

  Print usage of sympa.pl.

- `-version` `-version` | `-v` `-v`

  Print current version of Sympa.

Next: 4. sympa.conf parameters Up: Sympa Mailing Lists Management Software version Previous: 2. what does Sympa consist of Contents Index