Next: 4. Upgrading Sympa 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 INIT script
- 3.7 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://www.sympa.org`. All important resources are referenced there:

- sources
- `RELEASE_NOTES`
- .rpm and .deb packages for Linux
- user mailing list (see 1.6, 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 RDBMS (Oracle, MySQL, Sybase or PostgreSQL) and creating Sympa's Database. This is required for using the web interface for Sympa. Please refers to Sympa and its database section (7, page ).

- installation of CPAN 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);

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
- NetBSD
- Digital UNIX 4.x
- Solaris 2.5 and 2.6
- AIX 4.x
- HP-UX 10.20

Anyone willing to port it to NT ? ;-)

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 installation, you should make sure that you have a sufficiently recent release of the `sendmail` MTA, i.e. release 8.9.x or a more recent release. You may also use `postfix` or `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` 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. At `make` time, Sympa will prompt you for missing Perl modules and will attempt to install the missing ones automatically ; this operation requires root privileges.

Because Sympa features evolve from one relaease to another, the following list of modules might not be up to date :

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

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 LDAP 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 FastCGI. Therefore you need to install the following Perl module :

- `FCGI`

If you want to Download Zip files of list's Archives, you'll need to install perl Module for Archive Management :

- `Archive::Zip`

## 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 `/usr/local/sympa-os`.

# 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-5.1/` 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; a `locale/` 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-5.1.tar.gz | tar xf -`

Now you can run the installation process :

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

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

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

- `- - 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`, system admin executables in DIR (default /home/sympa/bin)

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

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

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

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

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

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

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

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

- `- - with-docdir=DIR`, man files in DIR (default /home/sympa/doc/)

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

- `- - with-lockdir=DIR`, create lock files in DIR (default /var/lock/subsys)

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

- `- - with-etcdir=DIR`, Config directories populated by the user are in DIR (default /home/sympa/etc)

- `- - with-localedir=DIR`, create language files in DIR (default /home/sympa/locale)

- `- - with-scriptdir=DIR`, create script files in DIR (default /home/sympa/script)

- `- - with-sampledir=DIR`, create sample files in DIR (default /home/sympa/sample)

- `- - with-spooldir=DIR`, create directory in DIR (default /home/sympa/spool)

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

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

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

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

- `- - with-sendmail_aliases=ALIASFILE`, set aliases file to be used by Sympa (default /etc/mail/sympa_aliases). (You can overright this value at runtime giving its value in `sympa.conf`)

- `- - 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`, set path to sendmail newaliases command (default /usr/bin/newaliases)

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

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

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

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

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

`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 6.1.9, 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 set (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 2.1, 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

See Robot aliases , 5.1, page )

# 3.5 Logs

Sympa keeps a trace of each of its procedures in its log file. However, this requires configuration of the `syslogd` daemon. By default Sympa will 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` configuration file (`/etc/syslog.conf`). For example:

    local1.*       /var/log/sympa

Then reload `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 (6.3.3, page ). You can test log feature by using `testlogs.pl`.

#
3.6 INIT script

The `make install` step should have installed a `sympa` init script in your `/etc/rc.d/init.d/` directory (you can change this at `configure` time with the `- - with-initdir` option). You should edit your runlevels to make sure Sympa starts after Apache and MySQL. Note that MySQL should also start before Apache because of `wwsympa.fcgi`.

#
3.7 sympa.pl

`sympa.pl` is the main daemon ; it processes mail commands and is in charge of messages distribution.

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

- `- - debug` | `-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.

- `service` process_command | process_message

  Sets Sympa daemon in way it process only message distribution (process_message) or in way it process only command (process_command).

- `- - config 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` | `-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` | `-l catalog`

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

- `- - keepcopy 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

- `- - create_list - - robot robotname - - input_file /path/to/list_file.xml`

  Create the list described by the xml file, see 16.3, page .

- `- - close_list listname@robot`

  Close the list (changing its status to closed), remove aliases and remove subscribers from DB (a dump is created in the list directory to allow restoring the list). See , page when you are in a family context.

- `- - dump listname `|` ALL`

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

- `- - import listname`

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

- `- - lowercase`

  Lowercases e-mail addresses in database.

- `- - help` | `-h`

  Print usage of sympa.pl.

- `- - make_alias_file`

  Create an aliases file in /tmp/ with all list aliases (only list which status is 'open'). It uses the list_aliases.tt2 template.

- `- - version` | `-v`

  Print current version of Sympa.

- `- - instanciate_family familyname robotname - - input_file /path/to/family_file.xml`

  Instantiate the family familyname. See 17, page .

- `- - close_family familyname - - robot robotname`

  Close the familyname family. See 17.2.4, page .

- `- - add_list familyname - - robot robotname - - input_file /path/to/list_file.xml`

  Add the list described in the XML file to the familyname family. See 17.2.5, page .

- `- - modify_list familyname - - robot robotname - - input_file /path/to/list_file.xml`

  Modify the existing family list, with description contained in the XML file. See 17.2.7, page .

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