To create a mailing list, only system mail aliases modification requires system privileges. Other tasks will be carried out under sympa UID in order to guarantee that the files created have the right permissions.
For each new list, it is necessary to create three mail aliases (the location of the sendmail alias file varies from one system to another).
For example, to create the list, the following aliases must be added:
: "|/usr/local/sympa/bin/queue foo" : "|/usr/local/sympa/bin/queue foo-request" : "|/usr/local/sympa/bin/queue foo-editor" : "|/usr/local/Bounce.pl foo : "|/usr/local/sympa/bin/queue foo-subscribe" : "|/usr/local/sympa/bin/queue foo-unsubscribe"
The address should be the address of the person in charge of list management (the list owner). Sympa will forward messages for to the owner of list defined in ~sympa/expl/foo/config file. This feature avoids later changes to this alias when updating owner's addresses.
The address can be used as to contact the list editors if defined in ~sympa/expl/foo/config. This address definition is not mandatory.
The address is the address receiving non-delivery reports. These messages can also be rerouted to a bounce management program, such as Anabounce, as shown in the example above.
The address is for a fast and easy to explain subscription. Be carefull: subscription is so easy that spammer may subscribe by accident.
The address is for simple unsubscription. By the way, everything that simplifies unsubscription simplifies list administration.
Each list has its own directory which name defines the list name. We recommend to create it with the same name as the alias. This directory is located in the ~sympa/expl according bye defined in /etc/sympa.conf file.
The configuration file for the list is named ~sympa/expl/foo/config. Sympa reads it into memory the first time the list is referred to. For Sympa releases prior to 1.0, it is saved each time a change is made to a subscription.
It is not compulsory to close Sympa to take the configuration file into account. But be careful, when writing into this file, read access by Sympa is likely to be incoherent!
The configuration file is made up of paragraphs separated by empty lines and introduced by a keyword.
These keywords are: subject, visibility, owner, editor, subscribe, unsubscribe, send, review, remind, add, del, archive, web_archive, max_size, reply_to, custom_header, custom_subject, footer_type, host, digest, cookie, user_data_source, include_list, include_sql_query, include_ldap_query. include_priority.
However the number of parameters is important, the minimal list definition is very short, only owner and subject parameter are needed because all the other parameter have a default value.
keyword value
This parameter indicates the subject of the list, which is sent in response to the LISTS mail command. The subject is a free form text limited to one line. This parameter is not used by Sympa if ~sympa/expl/lists file exists (e.g. static list of lists).
visibility conceal | noconceal (default value : conceal)
This parameter indicates whether the list should be listed when replying to LISTS command. This parameter is not used by Sympa if ~sympa/expl/lists file exists (e.g. static list of lists).
The config file contains one owner paragraph per owner.
Example:
owner email serge.aumont@cru.fr gecos C.R.U. reception nomail
The list owner is usually the person who has the authorization to send
ADD (see 4.2, page ) and
DELETE (see 4.2, page
)
commands on behalf of other users.
When the subscribe parameter (see 3.3.5,
page ) specifies a restricted list, the
owner is the only one who has the capability to subscribe users.
In this case, SUBSCRIBE requests are forwarded to him.
There may be several owners of a single list; in this case, each owner is defined by a paragraph introduced by the owner keyword.
The owner directive is followed by one or several lines giving details regarding the owner's characteristics:
Owner's email address
Optional attribute for an owner who don't want to receive mails. Useful to define an owner with multiple email addresses: they are all recognized when Sympa receives mail, but only some of them are recipient of administrative mail from Sympa.
Miscellaneous information on the owner
Authentication method for owner commands. In release 1.0,
the only possible value is md5. When this parameter
is put into the owner characteristics, the owner will
receive a confirmation request for each of his or her
commands, accompanied by a single key. This key can be
generated according to the desired method (in this case,
md5), and can be customized using the cookie parameter (see 3.3.23, page ).
Not currently implemented
The config file contains one editor paragraph per moderator (or editor).
Example:
editor email Pierre.David@prism.uvsq.fr gecos Pierre (Université de Versaille St Quentin)
The editor of a list is the only one authorized to send messages
in the list when the send parameter (see 3.3.10,
page ) is set to editor.editorkey or editorkeyonly
This parameter is used also to redistribute mail in some other situation
( privateoreditorkey ).
The syntax of this directive is the same as that of the owner parameter (see 3.3.3, page ),
even when several moderators are defined.
Subscribe parameter define the rules for subscribing to the list. It is defined by scenario. Predefined scenari are :
subscribe open | owner | closed | auth |
Anyone can join the list with the SUBSCRIBE mail command. Optional notification of each succesful subscription to owners can be set for each list with:
subscribe open,notify.
Only the owner (see owner above) can subscribe or unsubscribe a user. The owner should send an ADD mail command to subscribe the user.
Any subscription is refused, except indirectly by the
owner using the ADD command (see 4.2,
page ). This parameter is forced to
closed value for lists defined using
user_data_sourceinclude.
Use of the SUBSCRIBE command requires prior authentication of the origin of the subscription request. Sympa sends a key to the requesting party, who should in return send Sympa a SUBSCRIBE command prefixed with auth key.
Note: The cookie parameter (see 3.3.23,
page ) allows allocation of a single
key.
When the optional notify parameter option is set, owners receive a notification of each subscription, unless their owner definition include the nomail option.
This parameter specifies the unsubscription method for the list. Use open,notify or auth,notify to allow owner notification of each unsubscribe command. This parameter is defined by scenari, predefined scenari are :
unsubscribe open[,notify] | auth[,notify] owner closed
Anyone can unsubscribe from the list.
Use of the SIGNOFF command requires prior authentication of the sender. To perform this authentification, Sympa sends a key, indicating that the ``auth key'' parameter should be put in front of the command.
Note: it is advisable to enter the cookie parameter
(see 3.3.23, page ).
This parameter specifies who can perform ADD command This parameter is defined by scenari, predefined scenari are :
Only owners can add subscribers to the list.
Use of the ADD command requires prior authentication of the owner. To perform this authentification, Sympa sends a key, indicating that the ``auth key'' parameter should be put in front of the command.
This parameter specifies who can perform DEL command This parameter is defined by scenari, predefined scenari are :
Only owners can delete subscribers of the list.
Use of the DEL command requires prior authentication of the owner. To perform this authentification, Sympa sends a key, indicating that the ``auth key'' parameter should be put in front of the command.
This parameter specifies who can perform remind command This parameter is defined by scenari, predefined scenari are :
Only owners can perform remind for the list.
Use of the remind is a listmaster privilege.
send (optional, default value is private public | private | privateoreditorkey | editor | editorkey | editorkeyonly
This parameter specifies who can send messages to the list:
Anyone can send a message to the list, including non-subscribers.
Anyone can send a message to the list, including non-subscribers; authentication is automatically requested by return mail.
Only subscribers or owners can send a message.
Only subscribers or owners can send a message; authentication is systematically requested by return mail.
Anyone can send a message to the list. Authentication is requested by return mail for non-subscribers.
Anyone can send a message to the list. Message for which the sender is not a subscriber are sent to the list editor to confirm or reject its distribution.
All messages are stored on the server awaiting approval for distribution. An enabling key is sent to the moderators wit a copy of the message. The message is distributed when the Sympa robot receives a DISTRIBUTE command with the sole key referring to the queued message.
The REJECT command delete the message from the moderation spool (see queuemod configuration variable).
This method is used for:
With this method, it is not possible for the moderator to change the message, which is always refused or distributed as a whole. This moderation feature is only available as of release 1.2.0 of Sympa.
In this configuration, Sympa distributes the messages for
which at least one of the SMTP fields From:,
X-Sender: or Approved: contains
the address of one of the moderators, distributing these
in the list (see editor parameter for list
description file, 3.3.4, page ).
In the opposite case, it sends these list moderators a message entitled ``Article to moderate'' containing a copy of the article to be distributed. It is up to the moderator to send this copy of the message to be distributed back to the list, using the redirect, redistribute, forward or other functions from its MUA (moderation depends on processing of headers, managed by each MUA).
It should be noted that the security level of this method is associated to the enabling level of the message SMTP fields; it is therefore rather low.
This method mixes send editor and send editorkeyonly functionalities: If one of the SMTP fields From:, X-Sender: or Approved: contains the address of one of the moderators, the message is distributed without any control.
In the opposite case, it works in the same way as a moderated list with send editorkeyonly.
Available as of release 1.2.0 of Sympa.
This is the priority Sympa will process messages for this list. This is applied while going through the spool. A default value for lists' priorities may be defined with default_list_priority global parameter.
0 is the highest priority. The following priorities can be used: 0...9 A...Z a...z. z is a special priority since messages will stay in spool forever (useful to hangup a list).
Available since release 2.3.1.
reply_to sender | list | email
This parameter indicates whether the Reply-To: field should point to the sender of the message (sender) or to the list itself (list) or to anyother e-mail. If Reply-To: SMTP header field is set in incoming message, Sympa will never modify it.
Note: it is unadvisable to change this field, especially to point to the list. Experience demonstrates that numerous users, thinking they are responding to the sender, send private messages to a list. This can lead to an embarrassing situation.
This parameter specifies who can use the
REVIEW (see 4.1, page ),
administrative requests. It is defined by scenari. Predifined scenari
are :
review public | private | owner |
REVIEW access is not protected and anyone, even non-subscribers, can use it.
The REVIEW command is only authorized for subscribers.
Only the list owner can use it.
If the config file contains a archive paragraph Sympa will manage an archive of this list
Example:
archive period week access private
If parameter archive is specified, archives are accessible to users through the GET command and the index of the list archives is given by the INDEX command.
period day | week | month | quarter | year
This parameter specifies how archiving is organised: by day, by week, by month, by quarter or by year. Generation of automatic list archives requires creation of an archive directory in the root of the list (~sympa/expl/foo/archives/) where these documents will be put.
access private | public | owner | closed |
This parameter specifies who is allowed to send GET or INDEX commands.
If the config file contains a web_archive paragraph Sympa will copy all messages ditributed in the list to the "queueoutgoing" spool. It is intented to be use with WWSympa html archive tools. This paragraph must contain at least the access parameter to control who can browse the web archive.
Example:
web_archive access private
Value for web_archive access parameter must be one of the following : access private | public | owner | closed | listmaster
Maximum size of a message in 8-bit bytes. Default value is set in /etc/sympa.conf file.
host fully-qualified-domain-name
Domain name hosting the list (used for From: , for example).Default value is set in /etc/sympa.conf file.
custom_header header-field: value
This parameter is optional. The header specified with this parameter will be placed in each of the message headers distributed in the list. As of release 1.2.2 of Sympa, it is possible to put several custom header lines in the configuration file at the same time.
Example: custom_header X-url: http://www.cru.fr/listes/apropos/sedesabonner.faq.html.
This parameter is optional. This parameter specifies a string which is added to the subject of distributed messages (this is intented to help users who do not use automatic tools to sort incoming messages).
Example: custom_subject [sympa-users].
footer_type (optional, default value is mime) mime | append
List owners may decide to add message header or footer to messages sent to the list. This parameter defines the way a footer/header is added to a message.
This is the default value. Sympa will add properly the footer/header as a new MIME part. If message if multipart/alternative, nothing is added (would require another level of MIME encapsulation).
In this configuration, sympa won't create new MIME parts but will try to append the header/footer to the body of the message. ~sympa/expl/foo/message.footer.mime will be ignored. Header/footer may be appendeded to text/plain messages only.
Definition of digest mode. If this parameter is filled in, subscribers can select the receive option in multipart/digest MIME format. Messages are then grouped together and this compilation is sent to the subscribers in accordance with the rythm selected with this parameter.
Daylist designates a list of days in the week in number format (from 1 for Monday to 7 for Sunday), separated by commas.
Example: digest 1,2,3,4,5 15:30
In this example, Sympa sends digests at 3:30 PM from Monday to Friday.
WARNING: if the sending time is too late, Sympa may not be able to process it. It is essential that Sympa scans the digest queue at least once between the time laid down for sending of the digest and 12:00 PM. Usually do not use digest time later than 11:00 PM.
default_user_options parameter starts a paragraph to define a default profile for the subscribers of the list.
Mail reception mode.
Visibility of the subscriber with the REVIEW command.
cookie random-numbers-or-letters
This parameter is a secret item for generating authentication keys for administrative commands (ADD,
DELETE, etc.). This parameter should remain secret,
even for owners. The cookie is applied to all list owners, and is
only taken into account when the owner has the auth
parameter (owner parameter, see 3.3.3,
page ).
Example: cookie secret22
user_data_source file | database | include
Sympa allows the mailing list manager to choose how Sympa loads subscribers' data. Subscriber's informations can be stored in a text file, in a RDBMS or included from various external sources (list, flat file, LDAP directory, RDBMS).
This is the default value. When used subscribers data are stored in a file which name is define sympa.conf, parameter subscribers.
This mode as been introduced to store data in a RDBMS
in order to share subscribers data with a HTTP interface
and also to be able to manage very large mailing lists
(tested with MySql, 200.000 subscribers in a single list).
This should become the main usage. Please refer to the
section Üsing Sympa with a RDBMS(2.7, page ).
Sympa caches users data extracted using the include parameter. The time to leave of these data in Sympa can be controled with this parameter. The default value is 3600.
This parameter will be interpreted only if user_data_source is set to include. All subscribers of list listname will become subscribers of the current list. You may include as many lists as needed using one include_list listname line for each included list. You can include any list whatever is its user_data_source definition. In particular, you can include lists which are also defined by inclusion of other lists. Be carefull not to include list A in list B and then list B in list A : this would start an infinite loop.
This parameter will be interpreted only if the user_data_source value is set to include, it is the begining of a paragraph which defines the SQL query parameters :
This is the DBD name (oracle, mysql , Pg ...). You must respect the case.
The Database Server Sympa will try to connect to.
The hostname of the database system.
The user id to connect to the database.
Example :
user_data_source include include_sql_query db_type oracle host sqlserv.admin.univ-x.fr user banalise passwd mysecret db_name scolarship sql_query SELECT DISTINCT email FROM student
This paragraph defines parameters for a LDAP query returning a list of subscribers. This paragraph is used only if user_data_source is set to include. This feature requires Net::LDAP (perlldap) Perl module.
Name of the LDAP directory host.
Port on which the Directory is accepting connections.
Username with read access on the LDAP directory.
Defines the naming space covered by the search (optional, depending on the LDAP server).
Defines the LDAP search filter (RFC 2254 compliant).
Example :
include_ldap_query host ldap.cru.fr suffix dc=cru, dc=fr filter (&(cn=aumont) (c=fr))
This parameter will be interpreted only if the user_data_source value is set to include, the file is interpreted as one email per line (line beginning with a "#" are ignored).
List parameters controlling commands' behaviour are defined using a scenario. These scenari may be included in the list configuration file. Example
subscribe match([sender], /univ-rennes1\.fr$/) smtp -> do_it true() smtp -> owner
Where Sympa accepts subscription requests from anyone domain univ-rennes1.fr. Other requests are forwarded to the owner. The goal is to allow fine and flexible list configuration for each command.
A bunch of scenari is provided with Sympa distribution ; it provides all possible configurations as defined in previous releases of Sympa (<= 2.3) whithout any change in your list configuration files.
These standard scenari are located in ~sympa/bin/scenari/ directory. Default scenari are named <command>.default.
You may also define and name your own scenari. Store them in scenari directory. Example:
Copy the previous scenario in scenari/subscribe.rennes1 :
match([sender], /univ-rennes1\.fr\$/) smtp -> do_it true() smtp -> owner
You may now refer to this scenario in any list configuration file as :
subscribe rennes1
A scenario consists in rules, evaluated from the first to the last. Rules are defined as follows :
<rule> ::= <condition> <auth> -> <action> <condition> ::= [!] <condition | true () | equal (<var>, <var>) | match (<var>, /perl_regexp/) | is_subscriber (<listname>, <var>) | is_owner (<listname>, <var>) | is_editor (<listname>, <var>) | is_listmaster (<var>) <var> ::= \\[email\\] | \\[sender\\] | <email_string> <listname> ::= \\[listname\\] | <listname_string> <auth> ::= smtp | md5 <action> ::= do_it [,notify] | do_it [,quiet] | reject | request_auth | owner
perl_regexp can containt the string [host].
This first example is for a list open to everyone:
subject First example (an open list) visibility noconceal owner email Pierre.David@prism.uvsq.fr send public review public
The second example is for a moderated list with authentified subscription:
subject Second example (a moderated list) visibility noconceal owner email moi@ici.fr editor email big.prof@ailleurs.edu send editor subscribe auth review owner reply\_to list cookie 142cleliste
The third example is for a moderated list, with subscription controlled by the owner, and running in digest mode. Subscribers who are in digest mode receive the mail on Monday and Thursday.
owner email moi@ici.fr editor email prof@ailleurs.edu send editor subscribe owner review owner reply\_to list digest 1,4 12:00
Scheme is exactly the same as bye message but it's used when a subscriber is removed by a owner with the DELETE mail command.
Scheme is exactly the same as welcome
This file contains a message which is sent to each subscriber when one of the list owners sends the command "remind foo". It is used to send a personal reminder to each subscriber with his real subscribtion email because many people forget the address they subscribe with. Because Sympa parses [subscriber_email] string to replace it by the address of each subscriber, Sympa sends a personal message to each one and this may be a long process when the list is large.
(optional, version 2.2.8 or later): If one of these files exists, Sympa add it to each message before distribution process (Sympa first look for .mime files). If defined list parameter footer_type defines whether to attach the footer as a MIME part (except for multipart/alternative messages) or to append a text to the message (if a text/plain message).
(optional, version 2.3 or later): Same comportement as message.header above.
Sympa will send a welcome message for each subscription. The welcome message can be customized for each list, then it sould be created in a simple text file named ~sympa/expl/foo/welcome or using any MIME format file using the file name ~sympa/expl/foo/welcome.mime.
If no welcome message is found in the list directory, Sympa will send a MIME file named ~sympa/expl/welcome.mime or by default ~sympa/expl/welcome. In each case, Sympa replaces at run time the string ``[listname]'' by the name of the list.
Sympa will send an unsubscription message for each received SIGNOFF mail command, using the same algorithm to find file name
as for welcome messages:
~sympa/expl/foo/bye.mime,
~sympa/expl/foo/bye, etc.
The ~sympa/expl/foo/stats file should be created manually (empty).
To do this, type: touch ~sympa/expl/foo/stats. Sympa will then automatically update this file.
The ~sympa/expl/foo/subscribers file is created and is automatically filled in. It contains information about list subscribers. It is not advisable to edit this file. Main parameters are:
Email address of subscriber.
Information about subscriber (family name, first name, etc.) This parameter is optional on signing up.
Special receive mode for emails that the subscriber has
selected. The mode can be either nomail or digest. In normal receive mode, the receive attribute
no longer appears for this subscriber. See the SET LISTNAME NOMAIL command (4.1,
page ) and the digest
parameter (3.3.21, page
).
Special mode which allows subscriber to be invisible when
there is a REVIEW command in the list. If this
parameter does not exist, the subscriber remains visible
by REVIEW. Note: this option does not affect
the results of a REVIEW command issued by an
owner. See the SET LISTNAME MAIL command (4.1, page ) for
details.
Sympa will not use this file if the list is configured in include or database user_data_source.