A list can have from three parameters to many tens of them. Some listmasters need to create a set of lists that have the same profile. In order to simplify the apprehension of these parameters, list families define a lists typology. Families provide a new level for defaults : in the past, defaults in Sympa were global and most sites using Sympa needed multiple defaults for different group of lists. Moreover families allow listmaster to delegate a part of configuration list to owners, in a controlled way according to family properties. Distribution will provide defaults families.
A family provides a model for all of its lists. It is specified by the following characteristics :
Here is a list of operation performed on a family :
Examples:
/home/sympa/etc/families/my_family /home/sympa/etc/my_robot/families/my_familyIn this directory you must provide these files :
Example:
subject [% subject %] status [% status %] [% IF topic %] topics [% topic %] [% END %] visibility noconceal send privateoreditorkey web_archive access public subscribe open_notify shared_doc d_edit [% shared_edit %] d_read [% shared_read %] lang [% language %] [% FOREACH o = owner %] owner email [% o.email %] profile privileged [% IF o.gecos %] gecos [% o.gecos %] [% END %] [% END %] [% IF moderator %] [% FOREACH m = moderator %] editor email [% m.email %] [% END %] [% END %] [% IF sql %] include_sql_query db_type [% sql.type %] host [% sql.host %] user [% sql.user %] passwd [% sql.pwd %] db_name [% sql.name %] sql_query [% sql.query %] [% END %] ttl 360
WARNING : Some parameters cannot be constrained, they are : msg_topic.keywords
(see 21.4.13, page ),owner_include.source_parameter
(see 21.1.6, page
), editor_include.source_parameter (see 21.1.2, page
). About digest parameter (see 21.4.9, page
) , just days can be constrained.
Example:
lang fr,us archive.period days,week,month visibility conceal,noconceal shared_doc.d_read public shared_doc.d_edit editor
Example of custom hierarchy :
/home/sympa/etc/families/myfamily/mail_tt2/ /home/sympa/etc/families/myfamily/mail_tt2/bye.tt2 /home/sympa/etc/families/myfamily/mail_tt2/welcome.tt2
Instantiation permits to generate lists.You must provide an XML file that is
composed of lists description, the root element is family and is only
composed of list elements. List elements are described in section
19.1.2, page . Each list is described
by the set of values for affectation list parameters.
Here is an sample command to instantiate a family :
sympa.pl --instantiate\_family my_family --robot \samplerobot --input\_file /path/to/my\_file.xmlThis means lists that belong to family my_family will be created under the robot my_robot and these lists are described in the file my_file.xml. Sympa will split this file into several xml files describing lists. Each list XML file is put in each list directory.
Example:
<?xml version="1.0" ?> <family> <list> <listname>liste1</listname> <subject>a list example</subject> <description/> <status>open</status> <shared_edit>editor</shared_edit> <shared_read>private</shared_read> <language>fr</language> <owner multiple="1"> <email>serge.aumont@cru.fr</email> <gecos>C.R.U.</gecos> </owner> <owner multiple="1"> <email>olivier.salaun@cru.fr</email> </owner> <owner_include multiple="1"> <source>my_file</source> </owner_include> <sql> <type>oracle</type> <host>sqlserv.admin.univ-x.fr</host> <user>stdutilisateur</user> <pwd>monsecret</pwd> <name>les_etudiants</name> <query>SELECT DISTINCT email FROM etudiant</query> </sql> </list> <list> <listname>liste2</listname> <subject>a list example</subject> <description/> <status>open</status> <shared_edit>editor</shared_edit> <shared_read>private</shared_read> <language>fr</language> <owner multiple="1"> <email>serge.aumont@cru.fr</email> <gecos>C.R.U.</gecos> </owner> <owner multiple="1"> <email>olivier.salaun@cru.fr</email> </owner> <owner_include multiple="1"> <source>my_file</source> </owner_include> <sql> <type>oracle</type> <host>sqlserv.admin.univ-x.fr</host> <user>stdutilisateur</user> <pwd>monsecret</pwd> <name>les_etudiants</name> <query>SELECT DISTINCT email FROM etudiant</query> </sql> </list> ... </family>
Each instantiation describes lists. Compared to the previous instantiation, there are three cases :
After list creation or modification, parameters constraints are checked :
diagram
In case of modification (see diagram), allowed customizations can be preserved :
Notes :
Closes every list (installed under the indicated robot) of this family : lists status are set to family_closed, aliases are removed and subscribers are removed from DB. (a dump is created in the list directory to allow restoration of the list).
Here is a sample command to close a family :
sympa.pl --close_family my_family --robot \samplerobot
Adds a list to the family without instantiate all the family. The list is created
as if it was created during an instantiation, under the indicated robot. The XML file
describes the list and the root element is <list>. List elements are described in section
19.3, page .
Here is a sample command to add a list to a family :
sympa.pl --add\_list my\_family --robot \samplerobot --input\_file /path/to/my\_file.xml
Closes the list installed under the indicated robot : the list status is set to family_closed, aliases are removed and subscribers are removed from DB. (a dump is created in the list directory to allow restoring the list).
Here is a sample command to close a list family (same as an orphan list) :
sympa.pl --close_list my_list@\samplerobot
Modifies a family list without instantiating the whole family. The list (installed under the indicated robot)
is modified as if it was modified during an instantiation. The XML file
describes the list and the root element is <list>. List elements are described in section
19.3, page .
Here is a sample command to modify a list to a family :
sympa.pl --modify\_list my\_family --robot \samplerobot --input\_file /path/to/my\_file.xml
array
Note : In order to preserve list customization for instantiation, every modified parameter (via the Web interface) is noted in the config_changes file.
You can benefit from the family concept to let Sympa automatically create lists for you. Let us suppose that you want to open a list according to specified criteria (age, geographical site...) within your organization. Maybe that would result in too many lists, and many of them would never be used.
Automatic list creation allows you to define those potential lists through family parameters, but they won't be created yet. The mailing list creation is trigerred when Sympa receives a message addressed to this list.
To enable automatic list creation you'll have to :
To do so, we have to configure our MTA for it to add a custom header field to the message. The easiest way is to customize your aliases manager, so mails for automatic lists aren't delivered to the normal queue program, but to the familyqueue dedicated one. For example, you can decide that the name of those lists will start with the auto- pattern, so you can process them separately from other lists you are hosting.
familyqueue expects 2 arguments : the list name and the family name (whereas the queue program only expects the list address).
Let's start with a use case : we need to communicate to groups of co-workers, depending on their age and their occupation. We decide that, for example, if I need to write to all CTOs who are fifty years old, I will use the auto-cto.50@lists.domain.com mailing list. The occupation and age informations are stored in our ldap directory (but of course we could use any Sympa data source : sql, files...). We will create the age-occupation family.
First of all we configure our MTA to deliver mail to 'auto-*' to familyqueue for the age-occupation family.
/etc/postfix/main.cf ... transport_maps = regexp:/etc/postfix/transport_regexp /etc/postfix/transport_regexp /^.*+owner\@lists\.domain\.com$/ sympabounce: /^auto-.*\@lists\.domain\.com$/ sympafamily: /^.*\@lists\.domain\.com$/ sympa: /etc/postfix/master.cf sympa unix - n n - - pipe flags=R user=sympa argv=/home/sympa/bin/queue ${recipient} sympabounce unix - n n - - pipe flags=R user=sympa argv=/home/sympa/bin/bouncequeue ${user} sympafamily unix - n n - - pipe flags=R user=sympa argv=/home/sympa/bin/familyqueue ${user} age-occupation
A mail addressed to auto-cto.50@lists.domain.com will be queued to the /home/sympa/spool/automatic spool,
defined by the queueautomatic sympa.conf parameter (see 7.6.11, page ).
The mail will first be processed by an instance of sympa.pl process dedicated to automatic list creation, then the mail
will be sent to the newly created mailing list.
We need to create the appropriate etc/families/age-occupation/config.tt2. All the magic comes from the TT2 language capabilities. We define on-the-fly the LDAP source, thanks to TT2 macros.
/home/sympa/etc/families/age-occupation/config.tt2 ... user_data_source include2 [% occupations = { cto = { title=>"chief technical officer", abbr=>"CHIEF TECH OFF" }, coo = { title=>"chief operating officer", abbr=>"CHIEF OPER OFF" }, cio = { title=>"chief information officer", abbr=>"CHIEF INFO OFF" }, } nemes = listname.split('-'); THROW autofamily "SYNTAX ERROR : listname must begin with 'auto-' " IF (nemes.size != 2 || nemes.0 != 'auto'); tokens = nemes.1.split('\.'); THROW autofamily "SYNTAX ERROR : wrong listname syntax" IF (tokens.size != 2 || ! occupations.${tokens.0} || tokens.1 < 20 || tokens.1 > 99 ); age = tokens.1 div 10; %] custom_subject [[% occupations.${tokens.0}.abbr %] OF [% tokens.1 %]] subject Every [% tokens.1 %] years old [% occupations.${tokens.0}.title %] include_ldap_query attrs mail filter (&(objectClass=inetOrgPerson)(employeeType=[% occupations.${tokens.0}.abbr %])(personAge=[% age %]*)) name ldap port 389 host ldap.domain.com passwd ldap_passwd suffix dc=domain,dc=com timeout 30 user cn=root,dc=domain,dc=com scope sub select all
The main variable you get is the name of the current mailing list via the listname variable as used in the example above.
Now we need to enable automatic list creation in Sympa. To do so, we have to
You can make Sympa delete automatic lists that were created with zero list members ; to do so you shoukd set the automatic_list_removal parameter to if_empty.
/home/sympa/etc/sympa.conf ... automatic_list_feature on automatic_list_creation public queueautomatic /home/sympa/spool/automatic automatic_list_removal if_empty
While writing your own automatic_list_creation scenarios, be aware that :
Now you can send message to auto-cio.40 or auto-cto.50, and the lists will be created on the fly.
You will receive an 'unknown list' error if either the syntax is incorrect or the number of subscriber is zero.