The configuration file is composed of paragraphs separated by blank lines and introduced by a keyword.
Even though there are a very large number of possible parameters, the minimal list definition is very short. The only required parameters are owner and subject. All other parameters have a default value.
keyword value
WARNING: configuration parameters must be separated by blank lines and BLANK LINES ONLY !
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)
Only the editor of a list is authorized to send messages
to the list when the send parameter (see 11.3.6,
page ) is set to either editor, editorkey, or editorkeyonly.
The editor parameter is also consulted in certain other cases
( privateoreditorkey ).
The syntax of this directive is the same as that of the owner parameter (see 11.1.4, page ),
even when several moderators are defined.
(Default value: host robot parameter)
host fully-qualified-domain-name
Domain name of the server hosting the list (used for From: , for example). The default value is set in the /etc/sympa.conf file.
(Default value: lang robot parameter)
Example:
lang cn-big5
This parameter defines the language used for the list. It is used to initialize a user's lang preference ; Sympa command reports are extracted from the associated message catalog.
See 8.4, page
for available languages.
The config file contains one owner paragraph per owner.
Example:
owner email serge.aumont@cru.fr gecos C.R.U. info Tel: 02 99 76 45 34 reception nomail
The list owner is usually the person who has the authorization to send
ADD (see 15.2, page ) and
DELETE (see 15.2, page
)
commands on behalf of other users.
When the subscribe parameter (see 11.3.1,
page ) specifies a restricted list, it is
the owner who has the exclusive right to subscribe users, and
it is therefore to the owner that SUBSCRIBE requests
will be forwarded.
There may be several owners of a single list; in this case, each owner is declared in a paragraph starting with the owner keyword.
The owner directive is followed by one or several lines giving details regarding the owner's characteristics:
Owner's e-mail address
Optional attribute for an owner who does not wish to receive mails. Useful to define an owner with multiple e-mail addresses: they are all recognized when Sympa receives mail, but thanks to reception nomail, not all of these addresses need receive administrative mail from Sympa.
Public information on the owner
Available since release 2.3
Private information on the owner
Available since release 2.3.5
Profile of the owner. This is currently used to restrict access to some features of WWSympa, such as adding new owners to a list.
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 the ~sympa/expl/lists file (a static list of lists) exists.
topics computing/internet,education/university
This parameter allows the classification of lists. You may define multiple topics as well as hierarchical ones. WWSympa's list of public lists uses this parameter.
(Default value: conceal)
visibility parameter is defined by scenario (see 8.6, page )
This parameter indicates whether the list should feature in the output generated in response to a LISTS command. This parameter is not used by Sympa if the ~sympa/expl/lists file (a static list of lists) exists.
(Default value: file|database, if using an RDBMS)
user_data_source
file
database
include
Sympa allows the mailing list manager to choose how Sympa loads subscriber data. Subscriber information can be stored in a text file or relational database, or included from various external sources (list, flat file, result of LDAP or SQL query).
When this value is used, subscriber data are stored in a file whose name is defined by the subscribers parameter in sympa.conf. This is maintained for backward compatibility.
This mode was been introduced to enable data to be stored
in a relational database, in order, for example, for subscriber
data to be shared with an HTTP interface, or simply to facilitate
the administration of very large mailing lists. It has been
tested with MySQL, using a list of 200 000 subscribers.
We strongly recommend the use of database in place of text files.
It will improve performance, and solve possible conflicts between
Sympa and WWSympa. Please refer to the
Üsing Sympa with a relational databasesection
(6, page ).
Here, subscribers are not defined extensively (enumeration of their e-mail addresses) but intensively (definition of criteria subscribers must satisfy). Includes can be performed by extracting e-mail addresses using an SQL or LDAP query, or by including other mailing lists. At least one include paragraph, defining a data source, is needed. Valid include paragraphs (see below) are include_file, include_list, include_sql_query and include_ldap_query.
(Default value: 3600)
Sympa caches user data extracted using the include parameter. Their TTL (time-to-live) within Sympa can be controlled using 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 become subscribers of the current list. You may include as many lists as required, using one include_list listname line for each included list. Any list at all may be included ; the user_data_source definition of the included list is irrelevant, and you may therefore include lists which are also defined by the inclusion of other lists. Be careful, however, not to include list A in list B and then list B in list A, since this will give rise an infinite loop.
This parameter will be interpreted only if the user_data_source value is set to include, and is used to begin a paragraph defining the SQL query parameters :
The type of database (Oracle, MySQL , PostgreSQL, Sybase ...). This value identifies the PERL DataBase Driver (DBD) to be used, and is therefore case-sensitive.
The Database Server Sympa will try to connect to.
The hostname of the database system.
The user id to be used when connecting to the database.
Example :
user_data_source include include_sql_query db_type oracle host sqlserv.admin.univ-x.fr user stduser passwd mysecret db_name studentbody 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 the Net::LDAP (perlldap) PERL module.
Name of the LDAP directory host.
Port on which the Directory accepts connections.
Username with read access to 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).
The attribute containing the e-mail address(es) in the returned object.
Defines whether to use only the first address, or all the addresses, in cases where multiple values are returned.
Example :
include_ldap_query host ldap.cru.fr suffix dc=cru, dc=fr filter (&(cn=aumont) (c=fr)) attrs mail select first
This parameter will be interpreted only if the user_data_source value is set to include. The file should contain one e-mail address per line (lines beginning with a "#" are ignored).
(Default value: open)
subscribe parameter is defined by scenario (see 8.6, page )
The subscribe parameter defines the rules for subscribing to the list. Predefined scenarii are :
subscribe
open
owner
closed
auth
Anyone can join the list with the SUBSCRIBE mail command. The notification of list owners following each successful subscription can be specified by using
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.
All subscription requests refused (other than from owners
using the ADD command : see 15.2,
page ). The value of this parameter is forced to
closed for lists whose user_data_source is
set to include.
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 11.4.10,
page ) allows the allocation of a single
key.
When the optional notify parameter option is set, owners receive a notification of each subscription, unless their owner definition includes the nomail option.
(Default value: open)
unsubscribe parameter is defined by scenario (see 8.6, page )
This parameter specifies the unsubscription method for the list. Use open_notify or auth_notify to allow owner notification of each unsubscribe command. Predefined scenarii 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 authentication, Sympa sends a key, indicating that the ``auth key'' parameter should be placed in front of the command.
Note: it is advisable to enter the cookie parameter
(see 11.4.10, page ).
Unsubscription is not allowed. The value of this parameter is forced to closed for lists whose user_data_source is set to include.
(Default value: owner)
add parameter is defined by scenario (see 8.6, page )
This parameter specifies who is authorized to use the ADD command. Predefined scenarii are :
Only owners can add subscribers to the list.
Use of the ADD command requires prior authentication of the owner. To perform this authentication, Sympa sends a key, indicating that the ``auth key'' parameter should be placed in front of the command.
ADD is not allowed. The value of this parameter is forced to closed for lists whose user_data_source is set to include.
(Default value: owner)
del parameter is defined by scenario (see 8.6, page )
This parameter specifies who is authorized to use the DEL command. Predefined scenarii are :
Only owners can delete subscribers of the list.
Use of the DEL command requires prior authentication of the owner. To perform this authentication, Sympa sends a key, indicating that the ``auth key'' parameter should be placed in front of the command.
DEL is not allowed. The value of this parameter is forced to closed for lists whose user_data_source is set to include.
(Default value: owner)
remind parameter is defined by scenario (see 8.6, page )
This parameter specifies who is authorized to use the remind command. Predefined scenarii are :
Only owners can perform remind for the list.
Use of remind is a listmaster privilege.
(Default value: private)
send parameter is defined by scenario (see 8.6, page )
Predefined scenarii are :
public
private
privateoreditorkey
privateorpublickey
editor
editorkey
editorkeyonly
This parameter specifies who can send messages to the list. Valid values for this parameter are pointers to scenarii.
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. Messages from subscribers go through without requiring approval, whereas messages from non-subscribers are sent to moderators for approval or rejection.
All messages are stored on the server awaiting approval for distribution. An enabling key is sent to the moderators with a copy of the message. The message is distributed as soon as the Sympa robot receives a DISTRIBUTE command simply containing the key referring to the queued message.
The REJECT command deletes the message from the moderation spool (see the queuemod configuration variable).
Uses of this method:
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.
Sympa distributes only those messages
whose SMTP field From: or X-Sender: contains
the address of a moderator (see the editor parameter, 11.1.1,
page ).
Otherwise, it sends these list moderators a message entitled ``Article to moderate'' containing a copy of the text to be distributed. It is up to the moderator to send this copy of the message to be distributed back to the list, using a redirect, redistribute, forward, or other MUA function. The moderation mechanism is thus reliant on the processing of headers, which is performed by individual moderators' MUA's.
It should be noted that the security afforded by this method is only as strong as the level of protection of SMTP fields, that is to say very low.
This method combines the send editor and send editorkeyonly features. As long as one of the SMTP fields From:, X-Sender: or Approved: contains the address of a moderator, the message will be distributed.
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.
(Default value: owner)
review parameter is defined by scenario (see 8.6, page )
This parameter specifies who can use
REVIEW (see 15.1, page ),
administrative requests.
Predefined scenarii are :
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.
This paragraph defines read and edit access to the shared document repository.
(Default value: private)
This parameter specifies who can read shared documents (access the contents of a list's shared directory).
Predefined scenarii are :
READ access is not protected and anyone, even non-subscribers, can read the shared directory.
Reading the shared directory is only authorized for subscribers, list owner and listmaster.
Only the list owner and the listmaster can read the shared directory.
(Default value: owner)
This parameter specifies who can perform changes within a list's shared directory (i.e. upload files and create subdirectories).
Predefined scenarii are :
EDIT access is not protected and anyone, even non-subscribers, has write access to the shared directory.
Editing the shared directory is only authorized for subscribers, list owner and listmaster.
Only the list owner and the listmaster can edit the shared directory.
Example:
shared_doc d_read public d_edit private
The reply_to parameter starts a paragraph defining what Sympa will place in the Reply-To: SMTP header field of the messages it distributes.
This parameter indicates whether the Reply-To: field should indicate the sender of the message (sender), the list itself (list) or an arbitrary e-mail address (defined by the other_email parameter).
Note: it is inadvisable to change this parameter, and particularly inadvisable to set it to list. Experience has shown it to be almost inevitable that users, mistakenly believing that they are replying only to the sender, will send private messages to a list. This can lead, at the very least, to embarrassment, and sometimes to more serious consequences.
If value was set to other_email, this parameter defines the e-mail address used.
The default is to respect (preserve) the existing Reply-To: SMTP header field in incoming messages. If set to forced, Reply-To: SMTP header field will be overwritten.
(Default value: max_size robot parameter)
Maximum size of a message in 8-bit bytes. The default value is set in the /etc/sympa.conf file.
If this parameter is set for a list, all messages distributed via the list are rendered anonymous. SMTP From: headers in distributed messages are altered to contain the value of the anonymous_sender parameter. Various other fields are removed (Received:, Reply-To:, Sender:, X-Sender:, Message-id:, Resent-From:
custom_header header-field: value
This parameter is optional. The headers specified will be added to the headers of messages distributed via 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. It specifies a string which is added to the subject of distributed messages (intended to help users who do not use automatic tools to sort incoming messages).
Example: custom_subject [sympa-users].
(Default value: mime)
footer_type (optional, default value is mime)
mime
append
List owners may decide to add message headers or footers to messages sent via the list. This parameter defines the way a footer/header is added to a message.
The default value. Sympa will add the footer/header as a new MIME part. If the message is in multipart/alternative format, no action is taken (since this would require another level of MIME encapsulation).
Sympa will not create new MIME parts, but will try to append the header/footer to the body of the message. ~sympa/expl/mylist/message.footer.mime will be ignored. Headers/footers may be appended to text/plain messages only.
Definition of digest mode. If this parameter is present, subscribers can select the option of receiving messages in multipart/digest MIME format. Messages are then grouped together, and compilations of messages are sent to subscribers in accordance with the rhythm selected with this parameter.
Daylist designates a list of days in the week in number format (from 0 for Sunday to 6 for Saturday), 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 should scan the digest queue at least once between the time laid down for sending the digest and 12:00 AM (midnight). As a rule of thumb, do not use a digest time later than 11:00 PM.
The available_user_options parameter starts a paragraph to define available options for the subscribers of the list.
(Default value: reception mail,notice,digest,summary,nomail)
modelist is a list of modes (mail, notice, digest, summary, nomail), separated by commas. Only these modes will be allowed for the subscribers of this list. If a subscriber has a reception mode not in the list, sympa uses the mode specified in the default_user_options paragraph.
Example :
## Nomail reception mode is not available available_user_options reception digest,mail
The 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.
Example :
default_user_options reception digest visibility noconceal
(Default value: cookie robot parameter)
cookie random-numbers-or-letters
This parameter is a confidential item for generating authentication keys for administrative commands (ADD,
DELETE, etc.). This parameter should remain concealed,
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 11.1.4,
page ).
Example: cookie secret22
(Default value: default_list_priority robot parameter)
The priority with which Sympa will process messages for this list. This level of priority is applied while the message is going through the spool.
0 is the highest priority. The following priorities can be used: 0...9 z. z is a special priority causing messages to remain spooled indefinitely (useful to hang up a list).
Available since release 2.3.1.
This paragraph defines bounce management parameters :
(Default value: bounce_warn_rate robot parameter)
The list owner receives a warning whenever a message is distributed and the number (percentage) of bounces exceeds this value.
(Default value: bounce_halt_rate robot parameter)
NOT USED YET
If bounce rate reaches the halt_rate, messages for the list will be halted, i.e. they are retained for subsequent moderation. Once the number of bounces exceeds this value, messages for the list are no longer distributed.
Example:
## Owners are warned with 10% bouncing addresses ## message distribution is halted with 20% bouncing rate bounce warn_rate 10 halt_rate 20
(Default value: welcome_return_path robot parameter)
If set to unique, the welcome message is sent using a unique return path in order to remove the subscriber immediately in the case of a bounce.
(Default value: remind_return_path robot parameter)
Same as welcome_return_path, but applied to remind messages.
If the config file contains an archive paragraph Sympa will manage an archive for this list.
Example:
archive period week access private
If the archive parameter is specified, archives are accessible to users through the GET command, and the index of the list archives is provided in reply to the INDEX command (the last message of a list can be consulted using the LAST command).
period
day
week
month
quarter
year
This parameter specifies how archiving is organized: by day, week, month, quarter, or year. Generation of automatic list archives requires the creation of an archive directory at the root of the list directory (~sympa/expl/mylist/archives/), used to store these documents.
access
private
public
owner
closed
This parameter specifies who is authorized to use the GET, LAST and INDEX commands.
If the config file contains a web_archive paragraph Sympa will copy all messages distributed via the list to the "queueoutgoing" spool. It is intended to be used 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
The value of the web_archive access parameter must be one of the following :
access
private
public
owner
closed
listmaster