next up previous contents index
Next: Index Up: Sympa Mailing Lists Management Software version Previous: 27. Using Sympa commands   Contents   Index

Subsections


28. Internals

This chapter describes these modules (or a part of) :


28.1 mail.pm

This module deals with mail sending and does the SMTP job. It provides a function for message distribution to a list, the message can be encrypted. There is also a function to send service messages by parsing tt2 files, These messages can be signed. For sending, a call to sendmail is done or the message is pushed in a spool according to calling context.

28.1.1 public functions

mail_file(), mail_message(), mail_forward(), set_send_spool(), reaper().


28.1.1.1 mail_file()

Message is written by parsing a tt2 file (or with a string ). It writes mail headers if they are missing and they are encoded. Then the message is sent by calling mail::sending() function (see 28.1.2, page [*]).

IN :

  1. filename : string - tt2 filename '' - no tt2 filename sent
  2. rcpt (+) : SCALAR ref(ARRAY) - SMTP "RCPT To:" field
  3. data (+) : ref(HASH) - used to parse tt2 file, contains header values, keys are :
  4. robot (+) : robot
  5. sign_mode : 'smime'- the mail is signed with smime undef - no signature

OUT : 1


28.1.1.2 mail_message()

Distributes a message to a list. The message is encrypted if needed, in this case, only one SMTP session is used for each recepient otherwise, recepient are grouped by domain for sending (it controls the number recepient arguments to call sendmail). Message is sent by calling mail::sendto() function (see 28.1.2, page [*]).

IN :

  1. message (+) : ref(Message) - message to distribute
  2. from (+) : message from
  3. robot (+) : robot
  4. rcpt (+) : ARRAY - recepients

OUT : $numsmtp = number of sendmail process undef


28.1.1.3 mail_forward()

Forward a message by calling mail::sending() function (see 28.1.2, page [*]).

IN :

  1. msg (+) : ref(Message) ref(MIME::Entity) string - message to forward
  2. from (+) : message from
  3. rcpt (+) : ref(SCALAR) ref(ARRAY) - recepients
  4. robot (+) : robot

OUT : 1 undef


28.1.1.4 set_send_spool()

Used by other processes than sympa.pl to indicate to send message by writting message in spool instead of calling mail::smtpto() function (see 28.1.2, page [*]). The concerned spool is set in $send_spool global variable, used by mail::sending() function (see 28.1.2, page [*]).

IN :

  1. spool (+) : the concerned spool for sending.

OUT : -


28.1.1.5 reaper()

Non blocking function used to clean the defuncts child processes by waiting for them and then decreasing the counter. For exemple, this function is called by mail::smtpto() (see 28.1.2, page [*]), main loop of sympa.pl, task_manager.pl, bounced.pl.

IN :

  1. block

OUT : the pid of the defunct process -1 if there is no such child process.

28.1.2 private functions

sendto(), sending(), smtpto().


28.1.2.1 sendto()

Encodes subject header. Encrypts the message if needed. In this case, it checks if there is only one recepient. Then the message is sent by calling mail::sending() function (see 28.1.2, page [*]).

IN :

  1. msg_header (+) : ref(MIME::Head) - message header
  2. msg_body (+) : message body
  3. from (+) : message from
  4. rcpt (+) : ref(SCALAR) ref(ARRAY) - message recepients (ref(SCALAR) for encryption)
  5. robot (+) : robot
  6. encrypt : 'smime_crypted' the mail is encrypted with smime undef - no encryption

OUT : 1 - sending by calling smtpto (sendmail) 0 - sending by push in spool undef


28.1.2.2 sending()

Signs the message according to $sign_mode. Chooses sending mode according to context. If $send_spool global variable is empty, the message is sent by calling mail::smtpto() function (see 28.1.2, page [*]) else the message is written in spool $send_spool in order to be handled by sympa.pl process (because only this is allowed to make a fork). When the message is pushed in spool, these mail headers are added :

A message pushed in spool like this will be handled later by sympa::DoSendMessage() function (see 28.3, page [*])

IN :

  1. msg (+) : ref(MIME::Entity) string - message to send
  2. rcpt (+) : ref(SCALAR) ref(ARRAY) - recepients (for SMTP : "RCPT To:" field)
  3. from (+) : for SMTP : "MAIL From:" field for spool sending : "X-Sympa-From" field
  4. robot (+) : robot
  5. listname : listname ''
  6. sign_mode (+) : 'smime' 'none'for signing
  7. sympa_email : for the file name for spool sending

OUT : 1 - sending by calling smtpto() (sendmail) 0 - sending by pushing in spool undef


28.1.2.3 smtpto()

Calls to sendmail for the recipients given as argument by making a fork and an exec. Before, waits for number of children process number allowed by sympa.conf by calling mail::reaper() function (see 28.1.1, page [*]).

IN :

  1. from (+) : SMTP "MAIL From:" field
  2. rcpt (+) : ref(SCALAR)) ref(ARRAY) - SMTP "RCPT To:" field
  3. robot (+) : robot

OUT : mail::$fh - file handle on opened file for ouput, for SMTP "DATA" field undef


28.2 List.pm

This module includes list processing functions.

Here are described functions about :

Follows a description of structure and access on list parameters.

28.2.1 Functions for message distribution

distribute_message(), send_msg(), send_msg_digest().

These functions are used to message distribution in a list.


28.2.1.1 distribute_msg()

Prepares and distributes a message to a list :

IN :

  1. self (+) : ref(List) - the list concerned by distribution
  2. message (+): ref(Message) - the message to distribute

OUT : result of List::send_msg() function (number of sendmail process)


28.2.1.2 send_msg()

This function is called by List::distribute_msg() (see 28.2.1, page [*]) to select subscribers according to their reception mode and to the ``Content-Type'' header field of the message. Sending are grouped according to their reception mode :

The message is sent by calling List::mail_message() (see 28.1.1, page [*]). If the message is ``smime_crypted'' and the user has not got any certificate, a message service is sent to him.

IN :

  1. self (+) : ref(List) - the list concerned by distribution
  2. message (+): ref(Message) - the message to distribute

OUT : $numsmtp : addition of mail::mail_message() function results ( = number of sendmail process ) undef


28.2.1.3 send_msg_digest()

Sends a digest message to the list subscribers with reception digest, digestplain or summary : it creates the list of subscribers in various digest modes and then creates the list of messages. Finally sending to subscribers is done by calling List::send_file() function (see 28.2.2, page [*]) with mail template ``digest'', ``digestplain'' or ``summary''.

IN :

  1. self (+): ref(List) - the concerned list

OUT :

28.2.2 Functions for template sending

send_file(), send_global_file().

These functions are used by others to send files. These files are made from template given in parameters.


28.2.2.1 send_file()

Sends a message to a user, relative to a list. It finds the $tpl.tt2 file to make the message. If the list has a key and a certificat and if openssl is in the configuration, the message is signed. The parsing is done with variable $data set up first with parameter $context and then with configuration, here are set keys :

The message is sent by calling mail::mail_file() function (see 28.1.1, page [*]).

IN :

  1. self (+) : ref(List)
  2. tpl (+) : template file name without .tt2 extension ($tpl.tt2)
  3. who (+) : SCALAR ref(ARRAY) - recepient(s)
  4. robot (+) : robot
  5. context : ref(HASH) - for the $data set up

OUT : 1 undef


28.2.2.2 send_global_file()

Sends a message to a user not relative to a list. It finds the $tpl.tt2 file to make the message. The parsing is done with variable $data set up first with parameter $context and then with configuration, here are set keys :

The message is sent by calling mail::mail_file() function (see 28.1.1, page [*]).

IN :

  1. tpl (+) : template file name (filename.tt2), without .tt2 extension
  2. who (+) : SCALAR ref(ARRAY) - recepient(s)
  3. robot (+) : robot
  4. context : ref(HASH) - for the $data set up

OUT : 1 undef

28.2.3 Functions for service messages

archive_send(), send_to_editor(), request_auth(), send_auth().

These functions are used to send services messgase, correponding to a result of a command.


28.2.3.1 archive_send()

Sends an archive file ($file) to $who. The archive is a text file, independant from web archives. It checks if the list is archived. Sending is done by callingList::send_file() (see 28.2.2, page [*]) with mail template ``archive''.

IN :

  1. self (+): ref(List) - the concerned list
  2. who (+): recepient
  3. file (+): name of the archive file to send

OUT : - undef


28.2.3.2 send_to_editor()

Sends a message to the list editor for a request concerning a message to distribute. The message awaiting for moderation is named with a key and is set in the spool queuemod. The key is a reference on the message for editor. The message for the editor is sent by calling List::send_file() (see 28.2.2, page [*]) with mail template ``moderate''. In msg_topic context, the editor is asked to tag the message.

IN :

  1. self (+): ref(List) - the concerned list
  2. method : 'md5' - for "editorkey" 'smtp' - for "editor"
  3. message (+): ref(Message) - the message to moderate

OUT : $modkey - the moderation key for naming message waiting for moderation in spool queuemod. undef


28.2.3.3 request_auth()

Sends an authentification request for a requested command. The authentification request contains the command to be send next and it is authentified by a key. The message is sent to user by calling List::send_file() (see 28.2.2, page [*]) with mail template ``request_auth''.

IN :

  1. self : ref(List) not required if $cmd = ``remind''.
  2. email(+): recepient, the requesting command user
  3. cmd :
  4. robot (+): robot
  5. param : ARRAY

OUT : 1 undef


28.2.3.4 send_auth()

Sends an authentifiaction request for a message sent for distribution. The message for distribution is copied in the authqueue spool to wait for confirmation by its sender . This message is named with a key. The request is sent to user by calling List::send_file() (see 28.2.2, page [*]) with mail template ``send_auth''. In msg_topic context, the sender is asked to tag his message.

IN :

  1. self(+): ref(List) - the concerned list
  2. message(+): ref(Message) - the message to confirm

OUT : $modkey, the key for naming message waiting for confirmation in spool queuemod. undef

28.2.4 Functions for message notification

send_notify_to_listmaster(), send_notify_to_owner(), send_notify_to_editor(), send_notify_to_user().

These functions are used to notify listmaster, list owner, list editor or user about events.


28.2.4.1 send_notify_to_listmaster()

Sends a notice to listmaster by parsing ``listmaster_notification'' template. The template makes a specified or a generic treatement according to variable $param.type (:= $operation parameter). The message is sent by calling List::send_file() (see 28.2.2, page [*]) or List::send_global_file() (see 28.2.2, page [*]) according to the context : global or list context. Available variables for the template are set up by this function, by $param parameter and by List::send_global_file() or List::send_file().

IN :

  1. operation (+) : notification type, corresponds to $type in the template
  2. robot (+): robot
  3. param (+): ref(HASH) ref (ARRAY) - values for variable used in the template :

OUT : 1 undef


28.2.4.2 send_notify_to_owner()

Sends a notice to list owner(s) by parsing ``listowner_notification'' template. The template makes a specified or a generic treatement according to variable $param.type ( := $operation parameter). The message is sent by calling List::send_file() (see 28.2.2, page [*]). Available variables for the template are set up by this function, by $param parameter and by List::send_file().

IN :

  1. self (+): ref(List) - the list for owner notification
  2. operation (+) : notification type, corresponds to $type in the template
  3. param (+): ref(HASH) ref (ARRAY) - values for variable used in the template :

OUT : 1 undef


28.2.4.3 send_notify_to_editor()

Sends a notice to list editor(s) by parsing ``listeditor_notification'' template. The template makes a specified or a generic treatement according to variable $param.type ( := $operation parameter). The message is sent by calling List::send_file() (see 28.2.2, page [*]). Available variables for the template are set up by this function, by $param parameter and by List::send_file().

IN :

  1. self (+): ref(List) - the list for editor notification
  2. operation (+) : notification type, corresponds to $type in the template
  3. param (+): ref(HASH) ref (ARRAY) - values for variable used in the template :

OUT : 1 undef


28.2.4.4 send_notify_to_user()

Sends a notice to a user by parsing ``user_notification'' template. The template makes a specified or a generic treatement according to variable $param.type ( := with $operation parameter). The message is sent by calling List::send_file() (see 28.2.2, page [*]). Available variables for the template are set up by this function, by $param parameter and by List::send_file().

IN :

  1. self (+): ref(List) - the list for owner notification
  2. operation (+) : notification type, corresponds to $type in the template
  3. user (+) : user email to notify
  4. param (+): ref(HASH) ref (ARRAY) - values for variable used in the template :

OUT : 1 undef

28.2.5 Functions for topic messages

is_there_msg_topic(), is_available_msg_topic(), get_available_msg_topic(), is_msg_topic_tagging_required, automatic_tag(), compute_topic(), tag_topic(), load_msg_topic_file(), modifying_msg_topic_for_subscribers(), select_subscribers_for_topic().

These functions are used to manages message topics.

N.B.: There is some exception to use some parameters : msg_topic.keywords for list parameters and topics_subscriber for subscribers options in the DB table. These parameters are used as string splitted by ',' but to access to each one, use the function tools::get_array_from_splitted_string() (see 28.7, page [*]) allows to access the enumeration.


28.2.5.1 is_there_msg_topic()

Tests if some message topic are defined (msg_topic list parameter, see [*], page [*]).

IN : self (+): ref(List)

OUT : 1 - some msg_topic are defined 0 - no msg_topic


28.2.5.2 is_available_msg_topic()

Checks for a topic if it is available in the list : look foreach msg_topic.name list parameter (see [*], page [*]).

IN :

  1. self (+): ref(List)
  2. topic (+) : the name of the requested topic

OUT : topic if it is available undef


28.2.5.3 get_available_msg_topic()

Returns an array of available message topics (msg_topic.name list parameter, see [*], page [*]).

IN : self (+): ref(List)

OUT : ref(ARRAY)


28.2.5.4 is_msg_topic_tagging_required()

Returns if the message must be tagged or not (msg_topic_tagging list parameter set to 'required', see [*], page [*]).

IN : self (+): ref(List)

OUT : 1 - the message must be tagged 0 - the msg can be no tagged


28.2.5.5 automatic_tag()

Computes topic(s) (with compute_topic() function) and tags the message (with tag_topic() function) if there are some topics defined.

IN :

  1. self (+): ref(List)
  2. msg (+): ref(MIME::Entity)- the message to tag
  3. robot (+): robot

OUT : list of tagged topic : strings separated by ','. It can be empty. undef


28.2.5.6 compute_topic()

Computes topic(s) of the message. If the message is in a thread, topic is got from the previous message else topic is got from applying a regexp on the subject and/or the body of the message (msg_topic_keywords_apply_on list parameter, see[*], page [*]). Regexp is based on msg_topic.keywords list parameters (See [*], page [*]).

IN :

  1. self (+): ref(List)
  2. msg (+): ref(MIME::Entity)- the message to tag

OUT : list of computed topic : strings separated by ','. It can be empty.


28.2.5.7 tag_topic()

Tags the message by creating its topic information file in the /usr/local/sympa-stable/spool/topic/ spool. The file contains the topic list and the method used to tag the message. Here is the format :

TOPIC topicname,...
METHOD editor|sender|auto

IN :

  1. self (+): ref(List)
  2. msg_id (+): string - the message ID of the message to tag
  3. topic_list (+): the list of topics (strings splitted by ',')
  4. method (+): 'auto' 'editor''sender' - the method used for tagging

OUT : name of the created topic information file (directory/listname.msg_id) undef


28.2.5.8 load_msg_topic_file()

Search and load msg topic file corresponding to the message ID (directory/listname.msg_id). It returns information contained inside.

IN :

  1. self (+): ref(List)
  2. msg_id (+): the message ID
  3. robot (+): the robot

OUT : undef ref(HASH), keys are :


28.2.5.9 modifying_msg_topic_for_subscribers()

Deletes topics of subscriber that does not exist anymore and send a notify to concerned subscribers. (Makes a diff on msg_topic parameter between the list configuration before modification and a new state by calling tools::diff_on_arrays() function, see 28.7, page [*]). This function is used by wwsympa::do_edit_list().

IN :

  1. self (+): ref(List) - the concerned list before modification
  2. new_msg_topic (+) : ref(ARRAY) - new state of msg_topic parameters

OUT :

  1. 1 if some subscriber topics have been deleted
  2. 0 else


28.2.5.10 select_subscribers_for_topic()

Selects subscribers that are subscribed to one or more topic appearing in the topic list incoming when their reception mode is 'mail', and selects the other subscribers (reception mode different from 'mail'). This function is used by List::send_msg() function during message diffusion (see 28.2.1, page [*] ).

IN :

  1. self (+): ref(List)
  2. string_topic (+): string splitted by ',' - the topic list
  3. subscribers (+): ref(ARRAY) - list of subscriber emails

OUT : ARRAY - list of selected subscribers


28.2.6 Scenario evaluation

The following function is used to evaluate scenario file ``<action>.<parameter_value>'', where <action>action corresponds to a configuration parameter for an action and <parameter_value> corresponds to its value.

28.2.6.1 request_action()

Return the action to perform for one sender using one authentication method to perform an operation

IN :

  1. operation (+): SCALAR - the requested action corresponding to config parameter
  2. auth_method (+): 'smtp''md5''pgp''smime'
  3. robot (+): robot
  4. context (): ref(HASH) - contains value to instantiate scenario variables (hash keys)
  5. debug (): boolean - if true adds keys 'condition' and 'auth_method' to the returned hash.

OUT : undef ref(HASH) with keys :

28.2.7 Structure and access to list configuration parameters

List parameters are representated in the list configuration file, in the list object (list->{'admin'}) and on the Web interface. Here are translation and access functions :

    other (3)    
  (1) (5)  
CONFIG FILE   LIST OBJECT   WEB INTERFACE
  (2) (4) (6)  

  1. Loading file in memory :
     List::_load_admin_file(),_load_include_admin_user_file(),_load_list_param()
    
  2. Saving list configuration in file :
     List::_save_admin_file(),_save_list_param()
    
  3. Tools to get parameter values :
     List::get_param_value(),_get_param_value_anywhere(),_get_single_param_value()
    
  4. Tools to initialize list parameter with defaults :
     List::_apply_default()
    
  5. To present list parameters on the web interface :
     wwsympa::do_edit_list_request(),_prepare_edit_form(),_prepare_data()
    
  6. To get updates on list parameters from the web interface :
     wwsympa::do_edit_list(),_check_new_value
    

List parameters can be simple or composed in paragraph, they can be unique or multiple and they can singlevalued or multivalued. Here are the different kinds of parameters and an exemple :

parameters SIMPLE COMPOSED
SINGLE singlevalued (a) (b)
    lang archiv.period
  multivalued (c) (d)
    topics available_user_option.reception
MULTIPLE singlevalued (e) (f)
    include_list owner.email
  multi values not defined not defined

Here are these list parameters format in list configuration file in front of perl representation in memory :

  List Configuration FILE $list->{'admin'}
(a) param value 'scalar'
(b) param  
  p1 val1 'HASHscalar'
  p2 val2  
(c) param val1,val2,val3 'ARRAY(scalar & split_char)'
(d) param  
  p1 val11, val12, val13 'HASHARRAY(scalar & split_char)'
  p2 val21, val22, val23  
(e) param val1 'ARRAY(scalar)'
  param val2  
(d) param  
  p1 val11 'ARRAY(HASHscalar)'
  p2 val12  
     
  param  
  p1 val21  
  p2 val22  


28.3 sympa.pl

This is the main script ; it runs as a daemon and does the messages/commands processing. It uses these funstions : DoFile(), DoMessage(), DoCommand(), DoSendMessage(), DoForward(), SendDigest(), CleanSpool(), sigterm(), sighup().

Concerning reports about message distribution, function List::send_file() (see 28.2.2, page [*]) or List::send_global_file() (see 28.2.2, page [*]) is called with mail template ``message_report''. Concernong reports about commands, it is the mail template ``command_report''.


28.3.0.1 DoFile()

Handles a received file : function called by the sympa.pl main loop in order to process files contained in the queue spool. The file is encapsulated in a Message object not to alter it. Then the file is read, the header and the body of the message are separeted. Then the adequate function is called whether a command has been received or a message has to be redistributed to a list.

So this function can call various functions :

About command process a report can be sent by calling List::send_global_file() (see 28.2.2, page [*]) with template ``command_report''. For message report it is the template ``message_report''.

IN : file(+): the file to handle

OUT : $status - result of the called function undef


28.3.0.2 DoMessage()

Handles a message sent to a list (Those that can make loop and those containing a command are rejected). This function can call various functions :

IN :

  1. which(+): 'list_name@domain_name - the concerned list
  2. message(+): ref(Message) - sent message
  3. robot(+): robot

OUT : 1 if everything went fine in order to remove the file from the queue undef


28.3.0.3 DoCommand()

Handles a command sent to sympa. The command is parse by calling Commands::parse() (see 28.4.1, page [*]).

IN :

  1. rcpt : recepient <listname>-<subscribeunsubscribe>
  2. robot(+): robot
  3. msg(+): ref(MIME::Entity) - message containing the command
  4. file(+): file containing the message

OUT : $success - result of Command::parse() function undef.


28.3.0.4 DoSendMessage()

Sends a message pushed in spool by another process (ex : wwsympa.fcgi) by calling function mail::mail_forward() (see 28.1.1, page [*]).

IN :

  1. msg(+): ref(MIME::Entity)
  2. robot(+): robot

OUT : 1 undef


28.3.0.5 DoForward()

Handles a message sent to <listname>-editor : the list editor, <list>-request : the list owner or the listmaster. The message is forwarded according to $function by calling function mail::mail_forward() (see 28.1.1, page [*]).

IN :

  1. name(+): list name if ($function != 'listmaster')
  2. function(+): 'listmaster' 'request' 'editor'
  3. robot(+): robot
  4. msg(+): ref(MIME::Entity)

OUT : 1 undef


28.3.0.6 SendDigest()

Reads the queuedigest spool and send old digests to the subscribers with the digest option by calling List::send_msg_digest() function mail::mail_forward() (see 28.2.1, page [*]).

IN : - OUT : - undef


28.3.0.7 CleanSpool()

Cleans old files from spool $spool_dir older than $clean_delay.

IN :

  1. spool_dir(+) : the spool directory
  2. clean_delay(+) : the delay in days

OUT : 1


28.3.0.8 sigterm()

This function is called when a signal -TERM is received by sympa.pl. It just changes the value of $signal loop variable in order to stop sympa.pl after endding its message distribution if in progress. (see 4.3, page [*])

IN : - OUT : -


28.3.0.9 sighup()

This function is called when a signal -HUP is received by sympa.pl. It changes the value of $signal loop variable and switchs of the "-mail" (see 4.3, page [*]) logging option and continues current task.

IN : - OUT : -


28.4 Commands.pm

This module does the mail commands processing.

28.4.1 Commands processing

parse(), add(), del(), subscribe(), signoff(), invite(), last(), index(), getfile(), confirm(), set(), distribute(), reject(), modindex(), review(), verify(), remind(), info(), stats(), help(), lists(), which(), finished().


28.4.1.1 parse()

Parses the command line and calls the adequate subroutine (following functions) with the arguments of the command. This function is called by sympa::DoCommand() (see 28.3, page [*]).

IN :

  1. sender(+): the command sender
  2. robot(+): robot
  3. i(+): command line
  4. sign_mod : 'smime' undef

OUT : 'unknown_cmd' $status - command process result


28.4.1.2 add()

Adds a user to a list (requested by another user), and can send acknowledgements. New subscriber can be notified by sending template 'welcome'.

IN :

  1. what(+): command parameters : listname, email and comments eventually
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef


28.4.1.3 del()

Removes a user to a list (requested by another user), and can send acknowledgements. Unsubscriber can be notified by sending template 'removed'.

IN :

  1. what(+): command parameters : listname and email
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1


28.4.1.4 subscribe()

Subscribes a user to a list. New subscriber can be notified by sending him template 'welcome'.

IN :

  1. what(+): command parameters : listname and comments eventually
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef


28.4.1.5 signoff()

Unsubscribes a user from a list. He can be notified by sending him template 'bye'.

IN :

  1. which(+): command parameters : listname and email
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 'syntax_error' 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef


28.4.1.6 invite()

Invites someone to subscribe to a list by sending him the template 'invite'.

IN :

  1. what(+): command parameters : listname, email and comments
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef


28.4.1.7 last()

Sends back the last archive file by calling List::archive_send() function (see 28.2.3, page [*]).

IN :

  1. which(+): listname
  2. robot(+): robot

OUT : 'unknown_list' 'no_archive' 'not_allowed' 1


28.4.1.8 index()

Sends the list of archived files of a list.

IN :

  1. which(+): listname
  2. robot(+): robot

OUT : 'unknown_list' 'no_archive' 'not_allowed' 1


28.4.1.9 getfile()

Sends back the requested archive file by calling List::archive_send() function (see 28.2.3, page [*]).

IN :

  1. which(+): commands parameters : listname and filename(archive file)
  2. robot(+): robot

OUT : 'unknown_list' 'no_archive' 'not_allowed' 1


28.4.1.10 confirm()

Confirms the authentification of a message for its distribution on a list by calling function List::distribute_msg() for distribution (see 28.2.1, page [*]) or by calling List::send_to_editor() for moderation (see [*], page [*]).

IN :

  1. what(+): authentification key (command parameter)
  2. robot(+): robot

OUT : 'wrong_auth' 'msg_not_found' 1 undef


28.4.1.11 set()

Changes subscription options (reception or visibility)

IN :

  1. what(+): command parameters : listname and reception mode (digestdigestplainnomailnormal...) or visibility mode(concealnoconceal).
  2. robot(+): robot

OUT : 'syntax_error' 'unknown_list' 'not_allowed' 'failed' 1


28.4.1.12 distribute()

Distributes the broadcast of a validated moderated message.

IN :

  1. what(+): command parameters : listname and authentification key
  2. robot(+): robot

OUT : 'unknown_list' 'msg_not_found' 1 undef


28.4.1.13 reject()

Refuses and deletes a moderated message. Rejected message sender can be notified by sending him template 'reject'.

IN :

  1. what(+): command parameters : listname and authentification key
  2. robot(+): robot

OUT : 'unknown_list' 'wrong_auth' 1 undef


28.4.1.14 modindex()

Sends a list of current messages to moderate of a list (look into spool queuemod) by using template 'modindex'.

IN :

  1. name(+): listname
  2. robot(+): robot

OUT : 'unknown_list' 'not_allowed' 'no_file' 1


28.4.1.15 review()

Sends the list of subscribers of a list to the requester by using template 'review'.

IN :

  1. listname(+): list name
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 'unknown_list' wrong_auth no_subscribers 'not_allowed' 1 undef


28.4.1.16 verify()

Verifies an S/MIME signature.

IN :

  1. listname(+): list name
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 1


28.4.1.17 remind()

Sends a personal reminder to each subscriber of a list or of every list (if $which = *) using template 'remind' or 'global_remind'.

IN :

  1. which(+): * listname
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 'syntax_error' 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef


28.4.1.18 info()

Sends the list information file to the requester by using template 'info_report'.

IN :

  1. listname(+): name of concerned list
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 'unknown_list' 'wrong_auth' 'not_allowed' 1 undef


28.4.1.19 stats()

Sends the statistics about a list using template 'stats_report'.

IN :

  1. listname(+): list name
  2. robot(+): robot
  3. sign_mod : 'smime' undef - authentification

OUT : 'unknown_list' 'not_allowed' 1 undef


28.4.1.20 help()

Sends the help file for the software by using template 'helpfile'.

IN :

  1. : ?
  2. robot(+): robot

OUT : 1 undef


28.4.1.21 lists()

Sends back the list of public lists on this node by using template 'lists'.

IN :

  1. : ?
  2. robot(+): robot

OUT : 1 undef


28.4.1.22 which()

Sends back the list of lists that sender is subscribed to. If he is owner or editor, managed lists are noticed. Message is sent by using template 'which'.

IN :

  1. : ?
  2. robot(+): robot

OUT : 1


28.4.1.23 finished()

Called when 'quit' command is found. It sends a notification to sender : no process will be done after this line.

IN : -

OUT : 1

28.4.2 tools for command processing

get_auth_method()


28.4.2.1 get_auth_method()

Called by processing command functions to return the authentification method and to check the key if it is 'md5' method.

IN :

  1. cmd(+): requesting command
  2. email(+): used to compute auth if needed in command
  3. error(+): ref(HASH) - keys are :
  4. sign_mod(+): 'smime' - smime authentification undef - smtp or md5 authentification
  5. list: ref(List) undef - in a list context or not
OUT : 'smime' 'md5' 'smtp' - authentification method if checking not failed undef


28.5 wwsympa.fcgi

This script provides the web interface to Sympa.

do_subscribe(), do_signoff(), do_add(), do_del(), do_change_email(), do_reject(), do_send_mail(), do_sendpasswd(), do_remind(), do_set(), do_send_me(), do_request_topic(), do_tag_topic_by_sender().


28.5.0.1 do_subscribe()

Subscribes a user to a list. New subscriber can be notified by sending him template 'welcome'.


28.5.0.2 do_signoff()

Unsubscribes a user from a list. The unsubscriber can be notified by sending him template 'bye'.


28.5.0.3 do_add()

Adds a user to a list (requested by another user) and can send acknowledgements. New subscriber can be notified by sending him template 'welcome'.


28.5.0.4 do_del()

Removes a user from a list (requested by another user) and can send acknowledgements. Unsubscriber can be notified by sending template 'removed'.


28.5.0.5 do_change_email()

Changes a user's email address in Sympa environment. Password can be send to user by sending template 'sendpasswd'.


28.5.0.6 do_reject()

Refuses and deletes moderated messages. Rejected message senders are notified by sending them template 'reject'.


28.5.0.7 do_distribute()

Distributes moderated messages by sending a command DISTRIBUTE to sympa.pl. For it, it calls mail::mail_file() (see 28.1.1, page [*]). As it is in a Web context, the message will be set in spool. In a context of message topic, tags the message by calling to function List::tag_topic() (see 28.2.5, page [*]).


28.5.0.8 do_modindex()

Allows a moderator to moderate a list of messages and documents and/or tag message in message topic context.


28.5.0.9 do_viewmod()

Allows a moderator to moderate a message and/or tag message in message topic context.


28.5.0.10 do_send_mail()

Sends a message to a list by the Web interface. It uses mail::mail_file() (see 28.1.1, page [*]) to do it. As it is in a Web context, the message will be set in spool.


28.5.0.11 do_sendpasswd()

Sends a message to a user, containing his password, by sending him template 'sendpasswd' list by the Web interface.


28.5.0.12 do_request_topic()

Allows a sender to tag his mail in message topic context.


28.5.0.13 do_tag_topic_by_sender()

Tags a message by its sender by calling List::tag_topic() and allows its diffusion by sending a command CONFIRM to sympa.pl.


28.5.0.14 do_remind()

Sends a command remind to sympa.pl by calling mail::mail_file() (see 28.1.1, page [*]). As it is in a Web context, the message will be set in spool.


28.5.0.15 do_set()

Changes subscription options (reception or visibility)


28.5.0.16 do_send_me()

Sends a web archive message to a requesting user It calls mail::mail_forward() to do it (see 28.1.1, page [*]). As it is in a Web context, the message will be set in spool.


28.6 report.pm

This module provides various tools for notification and error reports in every Sympa interface (mail diffusion, mail command and web command).

For a requested service, there are four kinds of reports to users:

For other reports than non authorizations templates used depends on the interface :


28.6.1 Message diffusion

These reports use template mail_tt2/message_report.tt2 and there are two functions : reject_report_msg() and notice_report_msg().


28.6.1.1 reject_report_msg()

Sends a notification to the user about an error rejecting his requested message diffusion.

IN :

  1. type(+): 'intern''intern_quiet''user''auth' - the error type
  2. error: SCALAR - depends on $type :
  3. user(+): SCALAR - the user to notify
  4. param: ref(HASH) - for variable instantiation message_report.tt2 (key msgid(+) is required if type == 'intern')
  5. robot: SCALAR - robot
  6. msg_string: SCALAR - rejected message
  7. list: ref(List) - in a list context

OUT : 1 undef


28.6.1.2 notice_report_msg()

Sends a notification to the user about a success about his requested message diffusion.

IN :

  1. entry(+): $entry in message_report.tt2
  2. user(+): SCALAR - the user to notify
  3. param: ref(HASH) - for variable instantiation message_report.tt2
  4. robot(+): SCALAR - robot
  5. list: ref(List) - in a list context

OUT : 1 undef


28.6.2 Mail commands

A mail can contains many commands. Errors and notices are stored in module global arrays before sending (intern_error_cmd, user_error_cmd, global_error_cmd, auth_reject_cmd, notice_cmd). Moreover used errors here we can have global errors on mail containing commands, so there is a function for that. These reports use template mail_tt2/command_report.tt2 and there are many functions :


28.6.2.1 init_report_cmd()

Inits global arrays for mail command reports.

IN : -

OUT : -


28.6.2.2 is_there_any_report_cmd()

Looks for some mail command reports in one of global arrays.

IN : -

OUT : 1 if there are some reports to send


28.6.2.3 global_report_cmd()

Concerns global reports of mail commands. There are many uses cases :

  1. internal server error for a differed sending at the end of the mail processing :
  2. internal server error for sending every reports directly (by calling send_report_cmd()) :
  3. user error for a differed sending at the end of the mail processing :
    global_report_cmd('user',$error,$data
  4. user error for sending every reports directly (by calling send_report_cmd()) :
    global_report_cmd('user',$error,$data,$sender,$robot,1)

IN :

  1. type(+): 'intern''intern_quiet''user'
  2. error: SCALAR - depends on $type :
  3. data: ref(HASH) - for variable instantiation in command_report.tt2
  4. sender: SCALAR - the user to notify
  5. robot: SCALAR - robot
  6. now: BOOLEAN - send reports now if true

OUT : 1 undef


28.6.2.4 reject_report_cmd()

Concerns reject reports of mail commands. These informations are sent at the end of the mail processing. There are many uses cases :

  1. internal server error :
  2. user error :
    reject_report_cmd('user',$error,$data,$cmd)
  3. non authorization :
    reject_report_cmd('auth',$error,$data,$cmd)

IN :

  1. type(+): 'intern''intern_quiet''user''auth'
  2. error: SCALAR - depends on $type :
  3. data: ref(HASH) - for variable instantiation in command_report.tt2
  4. cmd: SCALAR - the rejected command, $xx.cmd in command_report.tt2
  5. sender: SCALAR - the user to notify
  6. robot: SCALAR - robot

OUT : 1 undef


28.6.2.5 notice_report_cmd()

Concerns positive notices of mail commands. These informations are sent at the end of the mail processing.

IN :

  1. entry: $notice.entry in command_report.tt2
  2. data: ref(HASH) - for variable instantiation in command_report.tt2
  3. cmd: SCALAR - the rejected command, $xx.cmd in command_report.tt2

OUT : 1 undef


28.6.2.6 send_report_cmd()

Sends the template command_report.tt2 to $sender with global arrays and then calls to init_report_command.tt2 function. (It is used by sympa.pl at the end of mail process if there are some reports in gloal arrays)

IN :

  1. sender(+): SCALAR - the user to notify
  2. robot(+): SCALAR - robot
OUT : 1


28.6.3 Web commands

It can have many errors and notices so they are stored in module global arrays before html sending. (intern_error_web, user_error_web, auth_reject_web, notice_web). These reports use web_tt2/notice.tt2 template for notices and web_tt2/error.tt2 template for rejects.


28.6.3.1 init_report_web()

Inits global arrays for web command reports.

IN : -

OUT : -


28.6.3.2 is_there_any_reject_report_web()

Looks for some rejected web command reports in one of global arrays for reject.

IN : -

OUT : 1 if there are some reject reports to send (not notice)


28.6.3.3 get_intern_error_web()

Return array of web intern error

IN : -

OUT : ref(ARRAY) - clone of intern_error_web


28.6.3.4 get_user_error_web()

Return array of web user error

IN : -

OUT : ref(ARRAY) - clone of user_error_web


28.6.3.5 get_auth_reject_web()

Return array of web authorisation reject

IN : -

OUT : ref(ARRAY) - clone of auth_reject_web


28.6.3.6 get_notice_web()

Return array of web notice

IN : -

OUT : ref(ARRAY) - clone of notice_web


28.6.3.7 reject_report_web()

Concerning reject reports of web commands, there are many uses cases :

  1. internal server error :
  2. user error :
    reject_report_web('user',$error,$data,$action, $list)
  3. non authorization :
    reject_report_web('auth',$error,$data,$action, $list)

IN :

  1. type(+): 'intern''intern_quiet''user''auth'
  2. error(+): SCALAR - depends on $type :
  3. data: ref(HASH) - for variable instantiation in notice.tt2
  4. action(+): SCALAR - the rejected actin, $xx.action in error.tt2, $action in listmaster_notification.tt2
  5. list: '' ref(List)
  6. user: SCALAR - the user for listmaster notification
  7. robot: SCALAR - robot for listmaster notification

OUT : 1 undef


28.6.3.8 notice_report_web()

Concerns positive notices of web commands.

IN :

  1. msg: $notice.msg in notice.tt2
  2. data: ref(HASH) - for variable instantiation in notice.tt2
  3. action: SCALAR - the noticed command, $notice.cmd in notice.tt2

OUT : 1 undef


28.7 tools.pl

This module provides various tools for Sympa.


28.7.0.1 checkcommand()

Checks for no command in the body of the message. If there are some command in it, it returns true and sends a message to $sender by calling List::send_global_file() (see 28.2.2, page [*]) with mail template ``message_report''.

IN :

  1. msg(+): ref(MIME::Entity) - the message to check
  2. sender(+): the message sender
  3. robot(+): robot

OUT :


28.7.0.2 get_array_from_splitted_string()

Return an array made from a string splitted by ','. It removes spaces.

IN : string(+): string to split

OUT : ref(ARRAY) -


28.7.0.3 diff_on_arrays()

Makes set operation on arrays seen as set (with no double) :

IN :

  1. A(+): ref(ARRAY) - set
  2. B(+): ref(ARRAY) - set

OUT : ref(HASH) with keys :


28.7.0.4 clean_msg_id()

Cleans a msg_id to use it without '
n', '
s', < and >.

IN : msg_id(+): the message id

OUT : the clean msg_id


28.7.0.5 clean_email()

Lower-case it and remove leading and trailing spaces.

IN : msg_id(+): the email

OUT : the clean email


28.7.0.6 make_tt2_include_path()

Make an array of include path for tt2 parsing

IN :

  1. robot(+): SCALAR - the robotset
  2. dir: SCALAR - directory ending each path
  3. lang: SCALAR - for lang directories
  4. list: ref(List) - for list directory

OUT : ref(ARRAY) - include tt2 path, respecting path priorities.


28.8 Message.pm

This module provides objects to encapsulate file message in order to prevent it from its alteration for using signatures.


28.8.0.1 new()

Creates an object Message and initialize it :

IN :

  1. pkg(+): Message
  2. file(+): the message file

OUT : ref(Message) undef


28.8.0.2 dump()

Dump the message object in the file descriptor $output

IN :

  1. self(+): ref(Message)
  2. output(+): file descriptor

OUT : '1'


28.8.0.3 add_topic()

Adds the message topic in the Message object (topic' and adds the 'X-Sympa-Topic' field in the ref(MIME::Entity) msg'.

IN :

  1. self(+): ref(Message)
  2. topic(+): string splitted by ',' - list of topic

OUT : '1'


28.8.0.4 get_topic()

Returns the topic(s) of the message

IN : self(+): ref(Message)

OUT : '' if no message topic | string splitted by ',' if message topic

N.B.:


next up previous contents index
Next: Index Up: Sympa Mailing Lists Management Software version Previous: 27. Using Sympa commands   Contents   Index
root 2006-09-25