next up previous contents index
Next: 21. Reception mode Up: Sympa Mailing Lists Management Software version Previous: 19. Lists Families   Contents   Index

Subsections


20. List configuration parameters

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 !

20.1 List description


20.1.1 editor

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 20.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 20.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 20.1.5, page [*]), even when several moderators are defined.


20.1.2 editor_include

The config file contains one editor_include paragraph per data inclusion file (see 17.7, page [*]). It concerns dynamic editor definition : inclusion of external data. For static editor definition and more information about moderation see 20.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 20.1.6, page [*]), even when several moderators are defined.


20.1.3 host

(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-stable/etc/sympa.conf.


20.1.4 lang

(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 16.4, page [*] for available languages.


20.1.5 owner

The config file contains one owner paragraph per owner. It concerns static owner definition. For dynamic definition see 20.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 27.2, page [*]) and DELETE (see 27.2, page [*]) commands on behalf of other users.

When the subscribe parameter (see 20.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:


20.1.6 owner_include

The config file contains one owner_include paragraph per data inclusion file (see 17.7, page [*]. It concerns dynamic owner definition : inclusion of external data. For static owner definition and more information about owners see 20.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:


20.1.7 subject

subject subject-of-the-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.


20.1.8 topics

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. This parameter is different from (msg_topic) parameter used to tag mails.


20.1.9 visibility

(Default value: conceal)

visibility parameter is defined by an authorization scenario (see 13, page [*])

This parameter indicates whether the list should feature in the output generated in response to a LISTS command.

20.2 Data source related

20.2.1 user_data_source

(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).

20.2.2 ttl

(Default value: 3600)

ttl delay_in_seconds

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.

20.2.3 include_list

include_list listname

This parameter will be interpreted only if user_data_source is set to include or include2. All subscribers of list listname become members 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.

Example: include_list local-list

Example: include_list other-local-list@other-local-robot

20.2.4 include_remote_sympa_list

include_remote_sympa_list

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 :


20.2.5 include_sql_query

include_sql_query

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 :

Example :

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


20.2.6 include_ldap_query

include_ldap_query

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.

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


20.2.7 include_ldap_2level_query

include_ldap_2level_query

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.

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


20.2.8 include_file

include_file path_to_file

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


20.2.9 include_remote_file

include_remote_file

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 :

Example:

include_remote_file
url     http://www.myserver.edu/myfile
user    john_netid
passwd  john_passwd

20.3 Command related


20.3.1 subscribe

(Default value: open)

subscribe parameter is defined by an authorization scenario (see 13, page [*])

The subscribe parameter defines the rules for subscribing to the list. Predefined authorization scenarios are :


20.3.2 unsubscribe

(Default value: open)

unsubscribe parameter is defined by an authorization scenario (see 13, 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 :


20.3.3 add

(Default value: owner)

add parameter is defined by an authorization scenario (see 13, page [*])

This parameter specifies who is authorized to use the ADD command. Predefined authorization scenarios are :


20.3.4 del

(Default value: owner)

del parameter is defined by an authorization scenario (see 13, page [*])

This parameter specifies who is authorized to use the DEL command. Predefined authorization scenarios are :


20.3.5 remind

(Default value: owner)

remind parameter is defined by an authorization scenario (see 13, page [*])

This parameter specifies who is authorized to use the remind command. Predefined authorization scenarios are :

20.3.6 remind_task

(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

20.3.7 expire_task

(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


20.3.8 send

(Default value: private)

send parameter is defined by an authorization scenario (see 13, page [*])

This parameter specifies who can send messages to the list. Valid values for this parameter are pointers to scenarios.


20.3.9 review

(Default value: owner)

review parameter is defined by an authorization scenario (see 13, page [*])

This parameter specifies who can use REVIEW (see 27.1, page [*]), administrative requests.

Predefined authorization scenarios are :


20.3.10 shared_doc

This paragraph defines read and edit access to the shared document repository.

20.3.10.1 d_read

(Default value: private)

d_read parameter is defined by an authorization scenario (see 13, page [*])

This parameter specifies who can read shared documents (access the contents of a list's shared directory).

Predefined authorization scenarios are :

20.3.10.2 d_edit

(Default value: owner)

d_edit parameter is defined by an authorization scenario (see 13, 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

20.3.10.3 quota

quota number-of-Kbytes

This parameter specifies the disk quota (the unit is Kbytes) for the document repository, in kilobytes. If quota is exceeded, file uploads fail.

20.4 List tuning


20.4.1 reply_to_header

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.

Example :

reply_to_header
value other_email
other_email listowner@my.domain
apply forced


20.4.2 max_size

(Default value: max_size robot parameter)

max_size number-of-bytes

Maximum size of a message in 8-bit bytes. The default value is set in the /usr/local/sympa-stable/etc/sympa.conf file.


20.4.3 anonymous_sender

anonymous_sender value

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:


20.4.4 custom_header

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.


20.4.5 rfc2369_header_fields

(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.


20.4.6 loop_prevention_regex

(Default value: loop_prevention_regex sympa.conf parameter) loop_prevention_regex mailer-daemon|sympa|listserv|majordomo|smartlist|mailman

This regular expression is applied to messages sender address. If the sender address matches the regular expression, then the message is rejected. The goal of this parameter is to prevent loops between Sympa and other robots.

20.4.7 custom_subject

custom_subject value

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].


20.4.8 footer_type

(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.

20.4.9 digest

digest daylist hour:minutes

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.

N.B.: In family context, digest can be constrainted only on days.


20.4.10 digest_max_size

(Default value: 25)

Maximum number of messages in a digest. If the number of messages exceeds this limit, then multiple digest messages are sent to each recipient.

20.4.11 available_user_options

The available_user_options parameter starts a paragraph to define available options for the subscribers of the list.

Example :

## Nomail reception mode is not available
available_user_options
reception  	digest,mail

20.4.12 default_user_options

The default_user_options parameter starts a paragraph to define a default profile for the subscribers of the list.

Example :

default_user_options
reception  	digest
visibility	noconceal

20.4.13 msg_topic

The msg_topic parameter starts a paragraph to define a message topic used to tag a message. Foreach message topic, you have to define a new paragraph.(See 21.1, page [*])

Example:

msg_topic
name os
keywords linux,mac-os,nt,xp
title Operating System

Parameter msg_topic.name and msg_topic.title are mandatory. msg_topic.title is used on the web interface (``other'' is not allowed for msg_topic.name parameter). The msg_topic.keywords parameter allows to select automatically message topic by searching keywords in the message.

N.B.: In a family context, msg_topic.keywords parameter is uncompellable.

20.4.14 msg_topic_keywords_apply_on

The msg_topic_keywords_apply_on parameter defines on which part of the message is used to perform automatic tagging.(See 21.1, page [*])

Example:

msg_topic_key_apply_on subject
Its values can be : subject body subject_and_body.

20.4.15 msg_topic_tagging

The msg_topic_tagging parameter indicates if the tagging is optional or required for a list. (See 21.1, page [*])

Example:

msg_topic_tagging optional
Its values can be : optional required

20.4.16 cookie

(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 20.1.5, page [*]).

Example: cookie secret22


20.4.17 priority

(Default value: default_list_priority robot parameter)

priority 0-9

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.

20.5 Bounce related


20.5.1 bounce

This paragraph defines bounce management parameters :

Example:

## Owners are warned with 10% bouncing addresses
## message distribution is halted with 20% bouncing rate
bounce
warn_rate	10
halt_rate	20


20.5.2 bouncers_level1


20.5.3 bouncers_level2

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


20.5.4 welcome_return_path

(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 (7.8.2, page [*]).


20.5.5 remind_return_path

(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 (7.8.3, page [*]).

20.6 Archive related

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-stable/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.


20.6.1 archive

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-stable/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.


20.6.2 web_archive

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

20.6.2.1 access

access_web_archive parameter is defined by an authorization scenario (see 13, page [*])

Predefined authorization scenarios are :

20.6.2.2 quota

quota number-of-Kbytes

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.


20.6.3 archive_crypted_msg

(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.

20.7 Spam protection

20.7.1 spam_protection

(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 :

20.7.2 web_archive_spam_protection

(Default value: web_archive_spam_protection robot parameter)

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.

20.8 Intern parameters


20.8.1 family_name

This parameter indicates the name of the family that the list belongs to.

Example:

family_name my_family


20.8.2 latest_instantiation

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


next up previous contents index
Next: 21. Reception mode Up: Sympa Mailing Lists Management Software version Previous: 19. Lists Families   Contents   Index
root 2006-09-25