NAME

       sympa_scenario - Authorization scenario

SYNOPSIS

       An example del.auth file:

         title    deletion performed only by list owners, need authentication
         title.es eliminacin reservada slo para el propietario, necesita autentificacin

         is_owner([listname],[sender])  smtp       -> request_auth
         is_listmaster([sender])        smtp       -> request_auth
         true()                         md5,smime  -> do_it

DESCRIPTION

   File format
       Basically, a scenario file is composed of titles on the first lines and a set of rules on
       the following lines.

       Rules consist of one or more line in the form:

         condition authentication_methods -> action

       Some terms of conditions may take one or more arguments.  The arguments are variables or
       literals (see "Terms of conditions", "Variables").

       Authentication methods is a comma-separated list of one or more methods (see
       "Authentication methods").

       Some actions may have optional modifiers (see "Actions").

       Terms of conditions

       "true" "(" ")"
           Always returns true.

       "equal" "(" var1"," var2 ")"
           Tests if two arguments are equial.

       "is_subscriber" "(" listname"," var ")"
       "is_owner" "(" listname"," var ")"
       "is_editor" "(" listname"," var ")"
           Tests if var is the subscriber, owner or editor of the list listname.  listname is the
           variable "[listname]" or list address, "name" or "name"@"domain".

       "is_listmaster" "(" var ")"
           Tests if var is the listmaster.

       "less_than" "(" var1"," var2 ")"
           Tests if var1 is less than var2.

       "match" "(" var"," "/"perl_regexp"/" ")"
           Tests if var matches with perl_regexp.

           perl_regexp is a perl regular expression.  Don't forget to escape special characters
           ("^", "$", "{", "(", ...): Check perlre(1) for regular expression syntax.  It can
           contain the string "[host]" (interpreted at run time as the list or robot domain).

       "newer" "(" date"," date ")"
           Returns true if first date is posterior to the second

       "older" "(" date"," date ")"
           Returns true if first date is anterior to the second date

           date is Unix time or the string "n"y"n"m"n"d"n"h"n"min"n"sec"", where each n is a
           number.

       "search" "(" named_filter_file"," var")"
           Tests if var is found by named filter.

           named_filter_file is a file name ending with ".ldap", ".sql" or ".txt".

       "verify_netmask" "(" network_block ")"
           Tests if "REMOTE_ADDR" CGI environment variable matches with network_block.

           This allows the user to configure their local network to only be accessible to those
           that are members of it.

       "CustomCondition::"package_name "(" arguments, ... ")"
           Evaluates custom condition.  package_name is the name of a Perl package in
           $SYSCONFDIR/custom_conditions/ (lowercase).

       Variables

       "[custom_vars->"custom_var_name"]"
           Allows you to introduce custom parameters in your scenario.  custom_var_name is the
           name of the custom parameter you want to use.

       "[date]"
           Date of reception of the message.

       "[env->"env_var"]"
           env_var is the name of CGI environment variable (note that it is case-sensitive).

       "[is_bcc]"
           Set to 1 if the list is neither in To: nor Cc: field.

       "[listname]"
           Name of current list.

       "[msg_encrypted]"
           Set to ""smime"" if the message was S/MIME encrypted.

       "[msg_header->"field_name"]"
       "[msg_header->"field_name"]["index"]"
           Value of message header field, available only when evaluating the authorization
           scenario for sending messages.  It can be used, for example, to require editor
           validation for multipart messages.  Optional index may be integer (may be less than 0)
           to choose particular entry from multile fields.

       "[msg_part->type]"
       "[msg_part->body]"
           The MIME content types and bodies; the body is available for MIME parts in text/xxx
           format only.

       "[previous_email]"
           Old email when changing subscription email in preference page.

       "[sender]"
           The email address of the current user (used on web or mail interface).  Default value
           is "nobody".

       "[topic]"
           Topic of the message.  This variable has a value if any of the previous "[topic-*]"
           variable has a value.

       "[topic-auto]"
           Topic of the message if it has been automatically tagged.

       "[topic-editor]"
           Topic of the message if it has been tagged by editor.

       "[topic-needed]"
           The message has not got any topic and message topic are required for the list.

       "[topic-sender]"
           Topic of the message if it has been tagged by sender.

       "[user_attributes->"user_attributes_key_word"]"
           user_attributes_key_word is one of the names of user attributes provided by the SSO
           system via environment variables.  Available only if user authenticated with a
           "generic_sso".

       Authentication methods

       The e-mail of authenticated user is given by "[sender]" variable.  If it is not given,
       '"nobody"' will be set.

       "smtp"
           Default method.  No actual authentication, and if any, sender of the message is used.

       "dkim"
           Authenticated by DKIM signature.

       "md5"
           Authenticated by web authentication (password), or by authentication key in e-mail
           message.

       "smime"
           Authenticated by S/MIME signature, or TLS client certificate.

       Actions

       An action consists of an action name and optional modifiers.

       Action names:

       "do_it"
           Allows operation.

       "editor"
           The message will be forwarded to list editor.

       "editorkey"
           The message will be held for moderation by list editor.

       "listmaster"
           Same as "do_it" but makes newly created list be pending.

       "owner"
           The operation is held and waits for approval by list owner.

       "reject"
           Denys operation.

       "request_auth"
           The operation is held and waits for confirmation by the user.

       Modifiers:

       "([email])"
           Only for "request_auth" action.  Sends authentication request to the target user of
           operation (given as the value of ""[email]"" variable) instead of original sender.

           Note that "[email]" is a literal and no other variable names can't be used.

       "," "notify"
           Only for "do_it" and "listmaster" actions.  Sends a notification to list owner.

       "," "quiet"
           Sends no notification to the message sender.

       "(reason="reason_key")"
           Only for "reject" action.  Matches a key in mail_tt2/authorization_reject.tt2 template
           corresponding to an information message about the reason of the reject of the user.
           reason_key have to be a static string enclosed by '...'.

       "(tt2="tpl_name")"
           Only for "reject" action.  Corresponding template (tpl_name".tt2") is sent to the
           sender.  tpl_name have to be a static string enclosed by '...'.

   Formal syntax
       # Below is the formal syntax definition by modified BNF.

       rule : condition spaces auth_list "->" action

       # Condition

       condition : "!" condition
           | "true" "(" ")"
           | "equal" "(" var "," var ")"
           | "is_editor" "(" listname "," var ")"
           | "is_listmaster" "(" var ")"
           | "is_owner" "(" listname "," var ")"
           | "is_subscriber" "(" listname "," var ")"
           | "less_than" "(" var "," var ")"
           | "match" "(" var "," "/" perl_regexp "/" ")"
           | "newer" "(" date "," date ")"
           | "older" "(" date "," date ")"
           | "search" "(" named_filter_file ")"
           | "verify_netmask" "(" network_block ")"
           | "CustomCondition::" package_name "(" var* ")"

       var : "[email]"
           | "[conf->" conf_key_word "]"
           | "[current_date]"
           | "[custom_vars->" custom_var_name "]"
           | "[env->" env_var "]"
           | "[is_bcc]"
           | "[list->" list_key_word "]"
           | "[msg_body]"
           | "[msg_encrypted]"
           | "[msg_header->" field_name "]" "[" index "]"
           | "[msg_header->" field_name "]"
           | "[msg_part->type]"
           | "[msg_part->body]"
           | "[previous_email]"
           | "[sender]"
           | "[subscriber->" subscriber_key_word "]"
           | "[topic]"
           | "[topic-auto]"
           | "[topic-editor]"
           | "[topic-needed]"
           | "[topic-sender]"
           | "[user->" user_key_word "]"
           | "[user_attributes->" user_attributes_keyword "]"
           | string

       listname : "[listname]"
           | listname_string
           | listname_string "@" domain_string

       date : "[date]"
           | date_expr
           | integer

       user_key_word : "email"
           | "gecos"
           | "lang"
           | "password"
           | "cookie_delay_user"
           | additional_user_fields

       subscriber_key_word : "email"
           | "date"
           | "bounce"
           | "gecos"
           | "reception"
           | "update_date"
           | "visibility"
           | additional_subscriber_fields

       list_key_word : "name"
           | "address"
           | "host"
           | "lang"
           | "max_size"
           | "priority"
           | "reply_to"
           | "status"
           | "subject"
           | "total"
           | "account"

       conf_key_word : "domain"
           | "default_list_priority"
           | "email"
           | "lang"
           | "listmaster"
           | "max_size"
           | "request_priority"
           | "sympa_priority"

       # Authentication methods

       auth_list : auth "," auth_list
           | auth
           | ""

       auth : "smtp"
           | "dkim"
           | "md5"
           | "smime"

       # Actions

       action : "do_it" ( "," "quiet" | "," "notify" )*
           | "editor" [ "," "quiet" ]
           | "editorkey" [ "," "quiet" ]
           | "listmaster" [ "," "notify" ]
           | "owner" [ "," "quiet" ]
           | "reject" (
                 "(" "reason=" reason_key ")"
               | "(" "tt2=" tpl_name ")"
               | "," "quiet"
             )*
           | "reject(tt2=" tpl_name ")" [ "," "quiet" ]
           | "request_auth" [ "([email])" ]

FILES

       $EXPLDIR"/"list path"/scenari"
       $SYSCONFDIR"/"virtual host"/scenari"
       $SYSCONFDIR"/scenari"
       $DEFAULTDIR"/scenari"
           Path of scenario files: List, robot and site levels, and distribution defaults.

SEE ALSO

       Sympa::Scenario.

HISTORY

       Original contents of this document were partially taken from a chapter "Authorization
       scenarios" in Sympa, Mailing List Management Software - Reference manual.