The authorization scenario (or simply “scenario”) is a small configuration language. It describes authorization for each operation of Sympa based on various conditions such as actors and authentication methods.
Location of scenario file
Each scenario file is named as “function
.name”. The function
corresponds to a function to be authorized, and the name distinguishes the
policy. Usually, some scenario files with different names are prepared for
For example, a scenario file
may be used to make subscription of a list be open. To do such,
- Edit list
configfile to add the following setting:
- In the web interface, choose “for anyone without authentication (open)” option on “Who can subscribe to the list (subscribe)” in the list configuration page.
To look for a particular scenario, Sympa searches following directories in order (see also “Configuration files”):
You can modify Sympa behavior if you create a new scenario with the same name as one of the scenario already included in the distribution but with a location related to the target site, domain or list. You can also add a new scenario ; it will automatically add an accepted value for the related parameter.
See also “Hiding scenario files”.
When customizing a scenario for your own site, domain or list, don’t modify
/scenaricontent or the next Sympa update will overwrite it (you must never modify anything in
$DEFAULTDIRunless you are patching Sympa).
When modifying an existing scenario you need to restart Sympa or touch list
configfile before Sympa use it.
Content of scenario file
Basically, a scenario file is composed of one or more titles on the first lines and a set of rules on the following lines. For example:
title.en-US deletion performed only by list owners, need authentication title.es eliminacin reservada slo para el propietario, necesita autentificacin title.fr suppression réservée au propriétaire avec authentification is_owner([listname],[sender]) smtp -> request_auth is_listmaster([sender]) smtp -> request_auth true() md5,smime -> do_it
The first line of a scenario file can contains its own title. This is the text that will later appear in the drop-down menu of your management web interface. This title can be just plain text:
title Restricted to subscribers
It can also be set to be internationalized:
title Restricted to subscribers title.en-US Restricted to subscribers title.es restringido a subscriptores title.fr limité aux abonnés
title.gettext Restricted to subscribers
In the first example, appropriate
title.lang line will be used for
title according to users’ language context (see also
“Language tag”). If no appropriate line is
title will be used as default.
In the second, the string following
title.gettext will be translated to
the users’ language using Sympa’s translation catalog. If there are no entry in
catalog, the string itself will be used.
- About detailed description on rules, see also sympa_scenario(5) manual page.
One or more lines for rules follow to title. Each rule has the following syntax:
Rules are evaluated in order, and once a rule matching with given condition and authentication method is found, action will be returned and subsequent rules will no longer be evaluated.
A condition is the term with optional arguments. Each argument may be a variable with a given value according to context, or a literal string.
is_owner([listname],[sender])succeeds if the user that requested the operation is the owner of the list.
As an argument, a variable
]allows you to introduce custom parameters in your scenario.
You can also create custom conditions by writing a Perl module: See “Custom scenario conditions” for details.
You can specify four different authentication methods to base your rules on (ordered from lower to higher levels):
If the specified authentication method was not used, a higher level of authentication methods can be requested.
These methods take a different meaning if you consider them in a web or mail context. For example with the scenario
send which will be evaluated when people try to send a message to a list:
If the message is sent through the web interface, Sympa will verify the identity of the sender based on information (login/password, certificate, etc.) provided by one of authentication mechanisms.
If it is sent by the mail client, the authentication is based on whatever authentication method the user’s email client associated with the SMTP message (S/MIME signature, From field, etc.).
However the same scenario file will be used in both cases. That means that the same authentication method will be used, whichever context we’re in. It is consequently important to understand what interpretation to give to each authentication method according to the context.
Here is a description of what is evaluated to authenticate the user depending of the context: web or mail.
|Method||Mail context||Web context|
||anonymous user (
||confirmation/approval with the authentication key in the message ||authentication mechanisms with username/password|
||valid S/MIME signature of the message ||TLS client authentication with X.509 certificate installed in the user’s browser|
md5will be used, in a mail context, when users answer to an authentication request, or when moderators moderate a message by replying to a moderation request mail.
-  Sympa also deals with S/MIME encrypted messages.
In most cases,
smtp will be used for mails, and
md5 for the web.
- On Sympa 6.1 to 6.2.70, before enabling DKIM feature you may have to update your customized scenario to introduce
dkimauthentication method. See “The
dkimauthentication method for scenarios”.
An action is one of following keywords:
do_itbut makes the status of newly created list “pending”. Only for
Requests the users of their own to authenticate (confirm) performing operation.
Forwards the message to the list moderators. Only for
Holds the message for moderation and sends notification to the moderators. Only for
Requests the list owners to authenticate performing operation. Only for
Some actions may have modifiers, for example:
quietmodifier, no notification is sent to the message sender.
For example, if a scenario rule is applied and result in
editorkey,quiet, the sender of the message will not receive the automatic information message telling them that their message has been forwarded to the list moderator.
notifymodifier sends a report to the list owner, if it will not be sent by default.
(reason=...)modifier returns a key in
mail_tt2/report.tt2template as the reason of rejection.
- On Sympa 6.2.18 or earlier,
mail_tt2/authorization_reject.tt2template was referred instead.
- On Sympa 6.2.18 or earlier,
(tt2=...)modifier sends the user a rejection message generated from specified template (extension
.tt2will be added).
This is an important issue to prevent backscatter messages. Backscatter messages are messages you receive as an automatic answer to a message you never sent. The following web page give you more details :
At the moment, Named Filters are only used in authorization scenarios. They enable to select a category of people who will be authorized or not to realize some actions.
As a consequence, you can grant privileges in a list to people belonging to an LDAP directory, an SQL database or a flat text file, thanks to an authorization scenario.
Note that only a subset of variables available in the scenario context are available here (including
LDAP Named Filters Definition
People are selected through an LDAP filter defined in a configuration file. This file must have the extension ‘.ldap’. It is stored in
You must provide some information in order to create a LDAP Named Filter:
A list of host:port LDAP directories (replicates) entries.
Defines the naming space covered by the search (optional, depending on the LDAP server).
Defines the LDAP search filter (RFC 4515). But you must absolutely take into account the first part of the filter which is:
(mail_attribute = [sender]), as shown in the example. You will have to replace
mail_attributeby the name of the attribute for the email. Sympa checks whether the user belongs to the category of people defined in the filter.
By default, the search is performed on the whole tree below the specified base object. This may be changed by specifying a scope:
base: search only the base object.
one: search the entries immediately below the base object.
sub: search the whole tree below the base object. This is the default option.
If anonymous bind is not allowed on the LDAP server, a DN and password can be used.
This password is used, combined with the
example.ldap: we want to select the teachers of mathematics in the University of Rennes 1 in France:
host ldap.univ-rennes1.fr:389,ldap2.univ-rennes1.fr:390 suffix dc=univ-rennes1.fr,dc=fr filter (&(canonic_mail = [sender])(EmployeeType = prof)(subject = math)) scope sub
SQL Named Filters Definition
People are selected through an SQL filter defined in a configuration file. This file must have the extension ‘.sql’. It is stored in
To create an SQL Named Filter, you have to configure SQL host, database and options, the same way you did it for the main Sympa database in
sympa.conf. Of course, you can use different database and options. Sympa will open a new Database connection to execute your statement.
Please refer to section “Database related” for a detailed explanation of each parameter.
Here, all database parameters have to be grouped in one
db_type MySQL|Oracle|PostgreSQL|SQLite; Database management system used. Mandatory and case sensitive.
Name of database to query. Mandatory.
Mandatory. The SQL statement to execute to verify authorization. This statement must returns 0 to refuse the action, or anything else to grant privileges. The
SELECT COUNT(*)...statement is the perfect query for this parameter. The keyword in the SQL query will be replaced by the sender’s email.
Please refer to main
sympa.confsection for description.
example.sql: we want to select the teachers of mathematics in the University of Rennes 1 in France:
sql_named_filter_query db_type mysql db_name people db_host dbserver.rennes1.fr db_user sympa db_passwd pw_sympa_mysqluser statement SELECT count(*) as c FROM users WHERE mail=[sender] AND EmployeeType='PROFESSOR' AND department='mathematics'
The search condition is used in authorization scenarios.
The syntax of this rule is:
search(example.ldap) smtp,smime,md5 -> do_it search(example.txt) smtp,smime,md5 -> do_it
The variable used by
search is the name of the LDAP configuration file or a txt matching enumeration.
Note that Sympa processes maintain a cache of processed search conditions to limit access to the LDAP directory or SQL server; each entry has a lifetime of one hour in the cache.
When using the ‘.txt’ file extension, each line is used to try to match the sender email address. You can use the “*” character as a wild card to replace any string.
Here is an example of such a file:
With such a file, the rule would be true for the following email addresses:
It would be false for the following email addresses :
This feature is used by the blocklist implicit scenario rule (see “Blocklist implicit rule”).
The method of authentication does not change.
Scenarios can also contain includes:
include commonreject match([sender], /cru\.fr$/) smtp,smime -> do_it true() smtp,smime -> owner
In this case, Sympa applies recursively the scenario named
include.commonreject before introducing the other rules. This possibility was introduced in order to facilitate the administration of common rules.
Scenario implicit inclusion
You can define a set of common scenario rules, used by all lists.
include.<action>.header is automatically added to evaluated scenarios. Note that you will need to restart Sympa processes to force reloading of list config files.
Blocklist implicit rule
For each service listed in parameter
following implicit scenario rule is added at the beginning of the scenario:
search(blocklist.txt) smtp,md5,smime -> reject,quiet
The goal is to block messages or other service requests from unwanted users. The blocklist can be defined for the domain or for the list. At the list level, the blocklist is to be managed by the list owner or the list moderator via the web interface.
- On Sympa 6.2.60 or earlier, the file named
blacklist.txtwas used for this implicit rule, and the name of corresponding parameter was
spam-status special scenario
(Work in progress)
Hiding scenario files
Because Sympa is distributed with many default scenario files, you may want to hide some of them to list owners (to make list administration menus shorter and readable). To hide a scenario file, you should create an empty file with the
:ignore suffix. Depending on where this file has been created, it will make it be ignored at either a global, domain or list level.
send scenario will be hidden (on the web admin interface), at the
mail.example.org domain level only.