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 (or owner_include) 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).
It concerns static editor definition. For dynamic definition and more information about editors see 18.1.2,
page .
Example:
editor email Pierre.David@prism.uvsq.fr gecos Pierre (Universite de Versailles St Quentin)
Only the editor of a list is authorized to send messages
to the list when the send parameter (see 18.3.8,
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 18.1.5, page ),
even when several moderators are defined.
The config file contains one editor_include paragraph
per data inclusion file (see 15.7, page ).
It concerns dynamic editor definition : inclusion of external data. For static editor definition and more information about moderation see 18.1.1, page
.
Example:
editor_include reception mail source myfile source_parameters a,b,c
The syntax of this directive is the same as that of the owner_include parameter (see 18.1.6, page ),
even when several moderators are defined.
(Default value: domain robot parameter)
host fully-qualified-domain-name
Domain name of the list, default is the robot domain name set in the related robot.conf file or in file /usr/local/sympa-os/etc/sympa.conf.
(Default value: lang robot parameter)
Example:
lang en_US
This parameter defines the language used for the list. It is used to initialize a user's language preference ; Sympa command reports are extracted from the associated message catalog.
See 14.6, page
for available languages.
The config file contains one owner paragraph per owner.
It concerns static owner definition. For dynamic definition see 18.1.6, page .
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 24.2, page ) and
DELETE (see 24.2, page
)
commands on behalf of other users.
When the subscribe parameter (see 18.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.
The config file contains one owner_include paragraph per data inclusion file
(see 15.7, page .
It concerns dynamic owner definition : inclusion of external data. For static owner definition and more information
about owners see 18.1.5, page
.
Example:
owner_include source myfile source_parameters a,b,c reception nomail profile normal
The owner_include directive is followed by one or several lines giving details regarding the owner(s) included characteristics:
This is an mandatory field : it indicates the data inclusion file myfile.incl (but declared myfile). This file can be a template. In this case, it will be interpreted with values given by subparameter source_parameter.
It contains values enumeration that will be affected to the param array used in the template file (see 15.7, page ).
Optional attribute for owner(s) who does not wish to receive mails.
Profile of the owner(s).
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.
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 an authorization scenario (see 12, page )
This parameter indicates whether the list should feature in the output generated in response to a LISTS command.
(Default value: file|database, if using an RDBMS)
user_data_source file | database | include | include2
Sympa allows the mailing list manager to choose how Sympa loads subscriber and administartive data. User 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. This can be used for instance to share subscriber
data 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 a database in place of text files.
It will improve performance, and solve possible conflicts between
Sympa and WWSympa. Please refer to the
¨Sympa and its databasesection
(7, 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_remote_sympa_list, include_sql_query and include_ldap_query.
This is a replacement for the include mode. In this mode, the members cache is no more maitained in
a DB FIle but in the main database instead. The behavior of the cache is detailed in the database chapter
(see 7.6, page ). This is the only mode that run the database for administrative data
in the database
(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.
Sympa can contact another Sympa service using https to fetch a remote list in order to include each member of a remote list as subscriber. You may include as many lists as required, using one include_remote_sympa_list paragraph for each included list. Be careful, however, not to give rise an infinite loop making cross includes.
For this operation, one Sympa site act as a server while the other one act as client. On the server side, the only setting needed is to give permition to the remote Sympa to review the list. This is controled by the review authorization scenario.
From the client side you must define the remote list dump URI.
Because https offert a easy and secure client authentication, https is the only one protocole currently supported. A additional parameter is needed : the name of the certificate (and the private key) to be used :
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 database type (mysql, Pg, Oracle, Sybase, CSV ...). 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.
This parameter is optional and specific to each RDBMS.
These options are appended to the connect string.
Example :
user_data_source include include_sql_query db_type mysql host sqlserv.admin.univ-x.fr user stduser passwd mysecret db_name studentbody sql_query SELECT DISTINCT email FROM student connect_options mysql_connect_timeout=5
Connexion timeout is set to 5 seconds.
This parameter is optional ; it is needed for some RDBMS (Oracle).
Sets a list of environment variables to set before database connexion. This is a ';' separated list of variable assignment.
Example for Oracle:
db_env ORACLE_TERM=vt100;ORACLE_HOME=/var/hote/oracle/7.3.4
This parameter is optional.
It provides a human-readable name to this datasource. It will be used within the REVIEW page to indicate what datasource each list member comes from (usefull when having multiple data sources).
This parameter is optional, only used when accessing a CSV datasource.
When connecting to a CSV datasource, this parameter indicates the directory where the CSV files are located.
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 or a comma separated list of host:port. The second form is usefull if you are using some replication ldap host.
Example :
host ldap.cru.fr:389,backup-ldap.cru.fr:389
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).
Timeout when connecting the remote 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.
By default the search is performed on the whole tree below the specified base object. This may be changed by specifying a scope parameter with one of the following values.
Example :
include_ldap_query host ldap.cru.fr suffix dc=cru, dc=fr timeout 10 filter (&(cn=aumont) (c=fr)) attrs mail select first scope one
This paragraph defines parameters for a two-level LDAP query returning a list of subscribers. Usually the first-level query returns a list of DNs and the second-level queries convert the DNs into e-mail addresses. 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 or a comma separated list of host:port. The second form is usefull if you are using some replication ldap host.
Example :
host ldap.cru.fr:389,backup-ldap.cru.fr:389
Port on which the Directory accepts connections (this parameter is ignored if host definition include port specification).
Username with read access to the LDAP directory.
Defines the naming space covered by the first-level search (optional, depending on the LDAP server).
Timeout for the first-level query when connecting to the remote server.
Defines the LDAP search filter for the first-level query (RFC 2254 compliant).
The attribute containing the data in the returned object that will be used for the second-level query. This data is referenced using the syntax ``[attrs1]''.
Defines whether to use only the first attribute value, all the values, or only those values matching a regular expression.
The Perl regular expression to use if ``select1'' is set to ``regex''.
By default the first-level search is performed on the whole tree below the specified base object. This may be changed by specifying a scope parameter with one of the following values.
Defines the naming space covered by the second-level search (optional, depending on the LDAP server). The ``[attrs1]'' syntax may be used to substitute data from the first-level query into this parameter.
Timeout for the second-level queries when connecting to the remote server.
Defines the LDAP search filter for the second-level queries (RFC 2254 compliant). The ``[attrs1]'' syntax may be used to substitute data from the first-level query into this parameter.
The attribute containing the e-mail address(es) in the returned objects from the second-level queries.
Defines whether to use only the first address, all the addresses, or only those addresses matching a regular expression in the second-level queries.
The Perl regular expression to use if ``select2'' is set to ``regex''.
By default the second-level search is performed on the whole tree below the specified base object. This may be changed by specifying a scope2 parameter with one of the following values.
Example : (cn=testgroup,dc=cru,dc=fr should be a groupOfUniqueNames here)
include_ldap_2level_query host ldap.univ.fr port 389 suffix1 ou=Groups,dc=univ,dc=fr scope1 one filter1 (&(objectClass=groupOfUniqueNames) (| (cn=cri)(cn=ufrmi))) attrs1 uniquemember select1 all suffix2 [attrs1] scope2 base filter2 (objectClass=n2pers) attrs2 mail select2 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 with an optional user description, separated from the email address by spaces (lines beginning with a "#" are ignored).
Sample included file:
## Data for Sympa member import john.smith@sample.edu John Smith - math department sarah.hanrahan@sample.edu Sarah Hanrahan - physics department
This parameter (organized as a paragraph) does the same as the include_file parameter, except that it gets a remote file. This paragraph is used only if user_data_source is set to include. Using this method you should be able to include any exotic data source that is not supported by Sympa. The paragraph is made of the following entries :
This is the URL of the remote file to include.
This entry is optional, only used if HTTP basic authentication is required to access the remote file.
This entry is optional, only used if HTTP basic authentication is required to access the remote file.
Example:
include_remote_file url http://www.myserver.edu/myfile user john_netid passwd john_passwd
(Default value: open)
subscribe parameter is defined by an authorization scenario (see 12, page )
The subscribe parameter defines the rules for subscribing to the list. Predefined authorization scenarios are :
(Default value: open)
unsubscribe parameter is defined by an authorization scenario (see 12, 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 authorization scenarios are :
(Default value: owner)
add parameter is defined by an authorization scenario (see 12, page )
This parameter specifies who is authorized to use the ADD command. Predefined authorization scenarios are :
(Default value: owner)
del parameter is defined by an authorization scenario (see 12, page )
This parameter specifies who is authorized to use the DEL command. Predefined authorization scenarios are :
(Default value: owner)
remind parameter is defined by an authorization scenario (see 12, page )
This parameter specifies who is authorized to use the remind command. Predefined authorization scenarios are :
(Default value: no default value)
This parameter states which model is used to create a remind task. A remind task regurlaly sends to the subscribers a message which reminds them their subscription to list.
example :
remind annual
(Default value: no default value)
This parameter states which model is used to create a remind task. A expire task regurlaly checks the inscription or reinscription date of subscribers and asks them to renew their subscription. If they don't they are deleted.
example :
expire annual
(Default value: private)
send parameter is defined by an authorization scenario (see 12, page )
This parameter specifies who can send messages to the list. Valid values for this parameter are pointers to scenarios.
(Default value: owner)
review parameter is defined by an authorization scenario (see 12, page )
This parameter specifies who can use
REVIEW (see 24.1, page ),
administrative requests.
Predefined authorization scenarios are :
This paragraph defines read and edit access to the shared document repository.
(Default value: private)
d_read parameter is defined by an authorization scenario (see 12, page )
This parameter specifies who can read shared documents (access the contents of a list's shared directory).
Predefined authorization scenarios are :
(Default value: owner)
d_edit parameter is defined by an authorization scenario (see 12, page )
This parameter specifies who can perform changes within a list's shared directory (i.e. upload files and create subdirectories).
Predefined authorization scenarios are :
Example:
shared_doc d_read public d_edit private
This parameter specifies the disk quota for the document repository, in kilobytes. If quota is exceeded, file uploads fail.
The reply_to_header 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), both list and sender (all) 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.
Example :
reply_to_header value other_email other_email listowner@my.domain apply forced
(Default value: max_size robot parameter)
Maximum size of a message in 8-bit bytes. The default value is set in the /usr/local/sympa-os/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.
(Default value: rfc2369_header_fields sympa.conf parameter) rfc2369_header_fields help,archive
RFC2369 compliant header fields (List-xxx) to be added to distributed messages. These header-fields should be implemented by MUA's, adding menus.
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). This string will be surrounded by [] characters.
The custom subject can also refer to list variables ([list->sequence] in the example bellow).
Example: custom_subject sympa-users.
Example: custom_subject newsletter num [list->sequence].
(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. /usr/local/sympa-os/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 rythm 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 could 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 18.1.5,
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.
(Default value: d)aily
Name of the task template use to remove old bounces. Usefull to remove bounces for a subscriber email if some message are distributed without receiving new bounce. In this case, the subscriber email seems to be OK again. Active if task_manager.pl is running.
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: bouncers_level1_rate config parameter)
Each bouncing user have a score (from 0 to 100).This parameter define the lower score for a user to be a level1 bouncing user. For example, with default values : Users with a score between 45 and 80 are level1 bouncers.
(Default value: bouncers_level1_action config parameter)
This parameter define which task is automaticaly applied on level 1 bouncing users: for exemple, automaticaly notify all level1 users.
(Default value: owner)
When automatic task is executed on level 1 bouncers, a notification email can be send to listowner or listmaster. This email contain the adresses of concerned users and the name of the action executed.
(Default value: bouncers_level2_rate config parameter)
Each bouncing user have a score (from 0 to 100).This parameter define the lower score for a user to be a level 2 bouncing user. For example, with default values : Users with a score between 75 and 100 are level 2 bouncers.
(Default value: bouncers_level1_action config parameter)
This parameter define which task is automaticaly applied on level 2 bouncing users: for exemple, automaticaly notify all level1 users.
(Default value: owner)
When automatic task is executed on level 2 bouncers, a notification email can be send to listowner or listmaster. This email contain the adresses of concerned users and the name of the action executed.
Example:
## All bouncing adresses with a score between 75 and 100 ## will be unsubscribed, and listmaster will recieve an email Bouncers level 2 rate :75 Points action : remove\_bouncers Notification : Listmaster
(Default value: welcome_return_path robot parameter) welcome_return_path unique | owner
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. See welcome_return_path sympa.conf
parameter (6.8.3, page ).
(Default value: remind_return_path robot parameter) remind_return_path unique | owner
Same as welcome_return_path, but applied to remind
messages. See remind_return_path sympa.conf
parameter (6.8.4, page ).
Sympa maintains 2 kinds of archives: mail archives and web archives.
Mail archives can be retrieved via a mail command send to the robot, they are stored in /usr/local/sympa-os/expl/mylist/archives/ directory.
Web archives are accessed via the web interface (with access control), they are stored in a directory defined in wwsympa.conf.
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 (/usr/local/sympa-os/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 quota 10000
access_web_archive parameter is defined by an authorization scenario (see 12, page )
Predefined authorization scenarios are :
This parameter specifies the disk quota for the list's web archives, in kilobytes. This parameter's default is default_archive_quota sympa.conf parameter. If quota is exceeded, messages are no more archived, list owner is notified. When archives are 95% full, the list owner is warned.
(Default value: cleartext)
archive_crypted_msg cleartext | decrypted
This parameter defines Sympa behavior while archiving S/MIME crypted messages. If set to cleartext the original crypted form of the message will be archived ; if set to decrypted a decrypted message will be archived. Note that this apply to both mail and web archives ; also to digests.
(Default value: spam_protection robot parameter)
There is a need to protection Sympa web site against spambot which collect email adresse in public web site. Various method are availible into Sympa and you can choose it with spam_protection and web_archive_spam_protection parameters. Possible value are :
Idem spam_protection but restricted to web archive. A additional value is available : cookie which mean that users must submit a small form in order to receive a cookie before browsing archives. This block all robot, even google and co.
This parameter indicates the name of the family that the list belongs to.
Example:
family_name my_family
This parameter indicates the date of the latest instantiation.
Example:
latest_instantiation email serge.aumont@cru.fr date 27 jui 2004 at 09:04:38 date_epoch 1090911878