next up previous contents index
Next: 4. Using Sympa commands Up: Sympa Automatic Multi-posting System Previous: 2. Installation   Contents   Index

Subsections


3. Creation of mailing lists

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.


3.1 Mail aliases

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.

3.2 List directory

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.


3.3 List configuration 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


3.3.1 Subject parameter

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. This parameter is not used by Sympa if ~sympa/expl/lists file exists (e.g. static list of lists).


3.3.2 Visibility parameter (optional, default value is conceal)

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


3.3.3 Owner parameter

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:


3.3.4 Editor parameter (optional except for moderated lists)

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.


3.3.5 Subscribe parameter (optional, default value open)

Subscribe parameter define the rules for subscribing to the list. It is defined by scenario. Predefined scenari are :

subscribe open | owner | closed | auth |

When the optional notify parameter option is set, owners receive a notification of each subscription, unless their owner definition include the nomail option.


3.3.6 Unsubscribe parameter (optional, default value open)

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


3.3.7 Add parameter (optional, default value owner)

This parameter specifies who can perform ADD command This parameter is defined by scenari, predefined scenari are :

add auth | owner | closed


3.3.8 del parameter (optional, default value owner)

This parameter specifies who can perform DEL command This parameter is defined by scenari, predefined scenari are :

del auth | owner | closed


3.3.9 Remind parameter (optional, default value owner)

This parameter specifies who can perform remind command This parameter is defined by scenari, predefined scenari are :

remind owner | listmaster


3.3.10 Send parameter

send (optional, default value is private public | private | privateoreditorkey | editor | editorkey | editorkeyonly

This parameter specifies who can send messages to the list:


3.3.11 Priority parameter (optional, default value is 5)

priority 0-9a-z

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.


3.3.12 Reply_to parameter (optional, default value is sender)

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.


3.3.13 Review parameter (optional, default value is owner)

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 |


3.3.14 Archive parameter (optional)

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.


3.3.15 Web_archive parameter (optional)

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

3.3.16 Max_size parameter (optional)

max_size number-of-bytes

Maximum size of a message in 8-bit bytes. Default value is set in /etc/sympa.conf file.

3.3.17 Host parameter (optional)

host fully-qualified-domain-name

Domain name hosting the list (used for From: , for example).Default value is set in /etc/sympa.conf file.

3.3.18 Custom_header parameter (optional)

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.

3.3.19 Custom_subject parameter (optional)

custom_subject value

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


3.3.20 footer_type (optional)

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.


3.3.21 Digest parameter (optional)

digest daylist hour:minutes

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.


3.3.22 Default_user_options parameter (optional)

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


3.3.23 Cookie parameter (optional)

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


3.3.24 user_data_source (optional)

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


3.3.25 ttl

ttl delay in seconds

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.


3.3.26 include_list

include_list listname

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.


3.3.27 include_sql_query

include_sql_query

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 :

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


3.3.28 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 Net::LDAP (perlldap) Perl module.

Example :

    include_ldap_query
    host ldap.cru.fr
    suffix dc=cru, dc=fr
    filter (&(cn=aumont) (c=fr))


3.3.29 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 is interpreted as one email per line (line beginning with a "#" are ignored).

3.4 Scenari

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

3.5 Examples of configuration files

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

3.6 List specific files

3.7 List welcome message

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.


3.8 List unsubscription message

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.


3.9 List statistics

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.


3.10 Subscriber 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:

Sympa will not use this file if the list is configured in include or database user_data_source.


next up previous contents index
Next: 4. Using Sympa commands Up: Sympa Automatic Multi-posting System Previous: 2. Installation   Contents   Index
root
1999-10-21