#title Sympa Mailinglist Manager
#author Stefan Hornburg (Racke)
#SORTtopics Sympa; Nginx; Exim; Postfix; Perl
#lang en
** Setup
*** Database Connection
In order to use a local socket connection to PostgreSQL, use the socket directory as database host in the Sympa configuration:
db_host /var/run/postgresql
This allows the Sympa user to safely connect to the database without password.
*** Listmaster
In your initial setup, you most likely need to adjust the global *listmaster* setting in =sympa.conf=:
listmaster mail@post.perl.dance
*** Fast CGI
Make sure that =use_fastcgi= is enabled in =sympa.conf=:
## use_fast_cgi
## Is FastCGI module for HTTP server installed (0 | 1)
## This module provide much faster web interface
use_fast_cgi 1
Fast CGI will be automatically enabled from Sympa 6.2.24.
*** Logging
Follow logs on a *systemd* based setup:
journalctl -u nginx-sympa -u sympa-archived -u sympa-bounced -u sympa.bulk -u sympa -u sympa-task-manager -u postfix
** Configuration
*** Messages
The maximum size of an email is 5 MB.
This setting can be changed by the *max_size* variable which uses bytes as
unit.
So in order to set the maximum size to 50 MB (50 * 1024 * 1024 bytes):
{{{
max_size 52428800
}}}
** Aliases
Aliases are used to push incoming emails to Sympa. We distinguish between
generic aliases and list aliases.
*** Generic aliases
**** Listmaster
Email sent to the listmaster alias (e.g. *listmaster@sympa.pm*) will be
relayed to all listmasters.
From: the original sender
Envelope from: sympa-request (e.g. *sympa_request@sympa.pm*).
** Virtual domains (Robots)
A robot for a virtual domain (e.g. =mydomain.sympa.pm=) is specified by a
configuration file =robot.conf= in a directory with the same name as the
virtual domain.
This directory is located in the configuration directory (usually
=/etc/sympa=).
So for our example *mydomain.sympa.pm* the path to the configuration file
would be =/etc/sympa/mydomain.sympa.pm/robot.conf=.
A minimal example of that configuration file looks like:
{{{
domain mydomain.sympa.pm
wwsympa_url https://mydomain.sympa.pm/sympa
}}}
In addition to that, a directory with the same name as the virtual domain is
**required** in the list home directory, e.g =/usr/local/sympa/list_data/mydomain.sympa.pm=.
** Exim integration
*** Routers
We need a routers for the generic aliases and for the list aliases.
A simple solution for a single domain
would be the following router:
{{{
sympa_list_aliases:
debug_print = "R: sympa list aliases for $local_part@$domain"
driver = redirect
domains = sympa.example.com
allow_fail
allow_defer
data = ${lookup{$local_part}lsearch{/etc/mail/sympa/aliases}}
user = sympa
group = sympa
pipe_transport = address_pipe
}}}
This applies to a setup with Debian packages, split configuration enabled.
Add a file with your routers, e.g. =etc/exim4/conf.d/router/450_sympa-routers=:
{{{
sympa_generic_router:
driver = accept
local_part_suffix_optional
local_part_suffix = -bounces : -bounces+* : -editor : \
-confirm+* : -join : -leave : \
-request : -admin : -subscribe : -unsubscribe
transport = sympa_transport
}}}
Add a file with your transports, e.g. =etc/exim4/conf.d/transport/30_sympa-transports=:
{{{
sympa_transport:
driver = pipe
command = /usr/lib/sympa/bin/queue ${local_part}${local_part_suffix}\@$domain
user = sympa
group = sympa
}}}
Update your Exim configuration file with =update-exim4.conf=.
*** Multiple domains
We are using one alias file per robot in =etc/mail/sympa=.
Add this router to the Exim configuration:
{{{
sympa_alias_router:
debug_print = "R: list aliases $local_part@$domain"
driver = redirect
allow_fail
allow_defer
domains = dsearch;/etc/mail/sympa/
data = ${expand:${lookup{$local_part}lsearch*@{/etc/mail/sympa/$domain}}}
retry_use_local_part
user = sympa
group = sympa
pipe_transport = address_pipe
file_transport = address_file
no_more
}}}
The location of the alias file is configured in the corresponding robot configuration file,
e.g. for the domain =post.perl.dance=:
{{{
/etc/sympa# cat post.perl.dance/robot.conf
wwsympa_url https://post.perl.dance/sympa
title Perl Dancer mailing lists
sendmail_aliases /etc/exim4/sympa-robots/post.perl.dance
}}}
** Postfix integration
This applies to a setup with Debian packages.
*** Aliases
We put the generic Sympa aliases like =sympa=, =sympa-request= and =sympa-owner= into =/etc/aliases=.
List aliases are going into =/etc/mail/sympa/aliases=. These are automatically updated by Sympa. Please make sure that this file is owned by the *sympa* user.
Add the file with Sympa aliases to =main.cf=:
alias_maps = hash:/etc/aliases,hash:/etc/mail/sympa/aliases
alias_database = hash:/etc/aliases,hash:/etc/mail/sympa/aliases
Remember that each time you update this file manually, you have to run the following command:
postalias /etc/mail/sympa/aliases
** FCGI with systemd socket and multiwatch
This is the recommended method and will be used in future releases of Debian
and Fedora packages.
*** Socket unit (Debian)
{{{
#include sympa/wwsympa.socket
}}}
*** Service unit (Debian)
{{{
#include sympa/wwsympa.service
}}}
** Nginx integration
#nginx
The systemd unit file for Debian looks like that:
[Unit]
Description=WWSympa - Web interface for Sympa mailing list manager
After=syslog.target
BindTo=sympa.service
[Service]
Type=forking
PIDFile=/run/sympa/wwsympa.pid
ExecStart=/usr/bin/spawn-fcgi -F $FCGI_CHILDREN \
-P /run/sympa/wwsympa.pid \
-u $FCGI_USER -g $FCGI_GROUP $FCGI_OPTS -- \
/usr/lib/sympa/bin/wwsympa.fcgi
Environment="FCGI_CHILDREN=5"
Environment="FCGI_USER=sympa"
Environment="FCGI_GROUP=sympa"
Environment="FCGI_OPTS=-s /run/sympa/wwsympa.socket -M 0600 -U nginx"
EnvironmentFile=-/etc/sysconfig/sympa
Restart=always
[Install]
WantedBy=multi-user.target
This requires spawn-fcgi
to be installed.
We are using the following snippet for inclusion into virtual hosts:
location /wws {
gzip off;
fastcgi_pass unix:/var/run/sympa/wwsympa.sock;
fastcgi_split_path_info ^(/wws)(.+)$;
fastcgi_param QUERY_STRING $query_string;
fastcgi_param REQUEST_METHOD $request_method;
fastcgi_param CONTENT_TYPE $content_type;
fastcgi_param CONTENT_LENGTH $content_length;
fastcgi_param PATH_INFO $fastcgi_path_info;
fastcgi_param SCRIPT_NAME $fastcgi_script_name;
fastcgi_param REQUEST_URI $request_uri;
fastcgi_param DOCUMENT_URI $document_uri;
fastcgi_param DOCUMENT_ROOT $document_root;
fastcgi_param SERVER_PROTOCOL $server_protocol;
fastcgi_param GATEWAY_INTERFACE CGI/1.1;
fastcgi_param SERVER_SOFTWARE nginx;
fastcgi_param REMOTE_ADDR $remote_addr;
fastcgi_param REMOTE_PORT $remote_port;
fastcgi_param SERVER_ADDR $server_addr;
fastcgi_param SERVER_PORT $server_port;
fastcgi_param SERVER_NAME $server_name;
fastcgi_param REMOTE_USER $remote_user;
fastcgi_param SCRIPT_FILENAME /usr/lib/cgi-bin/sympa/wwsympa-wrapper.fcgi;
fastcgi_param HTTP_HOST $server_name;
fastcgi_param HTTPS $https;
fastcgi_intercept_errors on;
}
** Archives
Whether archives are used for a list is controlled by the *process_archive*
variable.
Although the default for this variable is =off=, virtually every list is
created with archiving enabled.
This can only be prevented if you modify a list template or create a new
list template with *process_archive* set to off.
** Templates
[[https://sympa-community.github.io/manual/customize/basics-templates.html][Documentation]]
*** Customizing
In order to customize templates you need to **copy them first** from their
installation directory into the Sympa configuration directory.
For example, to edit the template for the welcome letter:
{{{
mkdir -p /etc/sympa/mail_tt2
cp /usr/share/sympa/default/mail_tt2/welcome.tt2 /etc/sympa/mail_tt2
}}}
The directories differ depending on your distribution and installation
method.
*** Email
**** Password request
=sendpasswd.tt2= :: Password request
**** Subscriptions
=bye.tt2= :: Confirmation of unsubscription
=removed.tt2= :: Notification of removal from mailing list
=welcome.tt2= :: Welcome letter
**** Subscription expiration
=expire_deletion.tt2= ::
=expire_warning1.tt2= ::
=expire_warning2.tt2= ::
**** Messages
=reject.tt2= :: Rejection (only for moderated lists)
**** Reminders
=global_remind.tt2= :: Reminder for all subscriptions
=remind.tt2= :: Reminder for mailing list
**** Digests
=digestplain.tt2= ::
=digest.tt2= ::
**** Shared documents
=d_install_shared.tt2= :: Successful document upload
=d_reject_shared.tt2= :: Failed document upload
*** Web
=compose_mail.tt2= :: Form to compose emails
=footer.tt2= :: Footer (Logo and Sympa version)
=header.tt2= :: Top menu bar
=list_menu.tt2= :: Left hand side menu
=list_panel.tt2= :: Panel with subscribers, owners and editors
=editsubscriber.tt2= :: Edit subscriber information
=review.tt2= :: Administer subscribers
=user_menu.tt2= :: User dropdown menu in top bar
=user_notification.tt2= :: Various notifications, e.g. info email for new
moderators
*** Custom list templates
Directory =/etc/sympa/create_list_templates=
Each template consists of a config (=config.tt2)= and comment (=comment.tt2=) template.
The contents of the comment template are shown on the "Request a List" page.
Don't put comments other than on the top into the config template as they will get mangled in the resulting
config file.
Available templates can be configured in =/etc/sympa/create_list.conf=.
** Bounces
Sympa uses the *ErrorsTo* header for the return address, e.g. test-owner@mylist.de.
** Topics
Configuration file: =/etc/sympa/topics.conf=
Topics are loaded by =load_topics=
** Commandline
The new syntax refers to Sympa release 6.2.68 and later.
*** Create a (test) list
Command:
{{{
sympa --create_list --input_file=/var/lib/sympa/testlist.xml
}}}
Sample contents of the file:
testliste
html-news-letter
Test list
computer
open
racke@linuxia.de
test@linuxia.de
*** Add user to a list
{{{
~ echo test@linuxia.de | sympa add test@sympa.icdev.de
add [notice] 1 subscribers added
add [notice] User test@linuxia.de has been notified
}}}
Old syntax:
{{{
~ echo racke@linuxia.de | sympa --import test@sympa.icdev.de
add [notice] User racke@linuxia.de is now subscriber of list test.
Total imported subscribers: 1
}}}
Add =--quiet= parameter to prevent a welcome email send to the subscriber.
*** Trigger list synchronisation
For subscribers:
{{{
$ sympa include testlist@sympa.icdev.de
}}}
For owners:
{{{
$ sympa include --role=owner testlist@sympa.icdev.de
}}}
Old syntax:
{{{
$ sympa --sync_include=test@linuxia.de
}}}
*** Close a list
{{{
~# sympa --close_list test
close_list [notice] List has been closed
}}}
Lists that are included in another list through =include_sympa_list= can't be closed.
*** Purge a list
This **completely removes** a list. It can't be restored or reopened.
{{{
~# sympa --purge_list test
close_list [notice] List has been purged
}}}
New syntax:
{{{
$ sympa close --mode=purge test
close_list [notice] List has been purged
}}}
*** Open a list
{{{
~# sympa --open_list test
open_list [notice] Aliases have been installed.
open_list [notice] List has been restored
}}}
*** Move list to another robot
{{{
~# sympa --rename_list=test@linuxia.de --new_listname=test
--new_listrobot=icdev.de
}}}
*** Change configuration values
{{{
$ sympa config lang=en
/etc/sympa/sympa.conf have been updated.
Previous versions have been saved as /etc/sympa/sympa.conf.20221129114546.
}}}
*** Mail aliases
Create a temporary file with all aliases:
sympa --make_alias_file
** Scripts
** General Data Protection Regulation (GDPR)
In order to comply with the GDPR, Sympa allows users to delete their account and cancel subscriptions
if the configuration parameter *allow_account_deletion*
is set to *On*.
This feature was introduced with version 6.2.42 and considered as experimental.
** Troubleshooting
*** No outgoing emails
Posts appear in the archives, but they are not sent to the subscribers.
Check if *sympa-outgoing* service is running.
*** Login problems
Grep the Sympa log for the term =check_auth=:
{{{
$ grep check_auth /var/log/sympa.log
Jan 31 10:26:21 mysympa wwsympa[844003]: notice Sympa::WWW::Auth::ldap_authentication() Authentication for "test@example.com" failed: No entry
Jan 31 10:26:21 mysympa wwsympa[844003]: err main::#1556 > main::do_login#3175 > Sympa::WWW::Auth::check_auth#60 > Sympa::WWW::Auth::authentication#201 Incorrect password for user test@example.com
}}}
This is especially useful to find out why authentication with LDAP / Active Domain
Controller fails.
*** Maintenance mode
This happens when WWSympa discovers that your installation has defects,
e.g. if the value in =/etc/sympa/data_structure.version= is different than
your actual Sympa version.
*** Sending emails
Sympa will drop emails that don't match the following requirements:
- unique message ID
- Sender: header
*** Important changes
**** Release 6.2.68
Introduced new CLI interface (sympa add instead of sympa.pl --add)
*** Known bugs
#knownbugs
This list is by all means not exhaustive.
These bugs are already fixed unless otherwise noted.
Fixed in next release (6.2.64)
- Sympa should not lock out users using password authentication with LDAP [[https://github.com/sympa-community/sympa/issues/1132][(#1132)]]
Release 6.2.58 (and older)
- Upgrade fails with stricter SQL mode in MySQL 8 ([[https://github.com/sympa-community/sympa/issues/1028][#1028]])
Release 6.2.54 (and older)
- Crash due to syntax error in regular expression ([[https://github.com/sympa-community/sympa/issues/860][#860]])
Release 6.2.52 (only)
- Evaluation of scenari fails ([[https://github.com/sympa-community/sympa/issues/841][#841]])
Release 6.2.52 (and older)
- Error on messages signed with PGP/Mime ([[https://github.com/sympa-community/sympa/issues/867][#867]])
- Gecos missing from file import ([[https://github.com/sympa-community/sympa/pull/873][#873]]), introduced through version 6.2.48
Release 6.2.40 (and older)
- Shared feature can not be turned off ([[https://github.com/sympa-community/sympa/issues/1035][#1035]])
** Internal processes
*** Distribute Message
The following modules are called:
- Sympa::Spindle::TransformIncoming
- Sympa::Spindle::ToArchive
- Sympa::Spindle::TransformOutgoing
- Sympa::Spool::Outgoing
- Sympa::Spindle::ToDigest
- Sympa::Spindle::ToList
Sympa::Spool::Outgoing stores the messages in the bulk spool (bulk/msg and
bulk/pct).
The bulk daemon picks up these messages.
*** Moderation
Spindle :: Sympa::Spindle::ModerateMessage
The message is either distributed (we pass to Sympa::Spindle::DistributeMessage) or rejected.
The following steps are taken before we distributing the message:
- Add =X-Validation-by= header
- Inform author (unless *quiet* is enabled)
*** Outgoing messages
This applies to other messages than list posts.
Spindle :: Sympa::Spindle::ToOutgoing
*** Bounces
Spindle :: Sympa::Spindle::ProcessBounce
** Resources
GitHub repository :: [[https://github.com/sympa-community/sympa]]