Table of Contents
Please take note that this work is still ongoing. The documentation should grow in a near future. 
Internals
In this chapter, we will provide extensive information on what Sympa looks like “under the hood”. We hope this documentation will be particularly helpful to developers.
Focus on the main Sympa modules
This chapter describes these modules (or a part of them):
- src/mail.pm: low level of email sending;
- src/List.pm: list processing and informations about structure and access to list configuration parameters;
- src/sympa.pl: the main script, for messages and mail commands processing;
- src/Commands.pm: mail commands processing;
- wwsympa/wwsympa.fcgi: web interface;
- src/report.pm: notification and error reports about requested services (email and web);
- src/tools.pm: various tools;
- src/Message.pm: message object used to encapsule a message received.
- wwsympa/SympaSession.pm: session object use to manage user context with a single cookie and a session table
- wwsympa/Auth.pm
to be completed
Sympa modules sorted by directory
This section presents all the files used in the Sympa engine. The files described are those contained in the sources, consequently:
- you will not find the files generated at compilation time,
- the files are not located in the same directory as you will find them in the compiled application.
Failing a better alternative, we present them as they appear in the src directory from the source distribution.
''./'' : Sympas sources root directory
These scripts are run at installation time. They perform the operations necessary to the correct install and runtime of Sympa.
- check_perl_modules.pl : This script checks installed and required Perl modules. It also does the required installations.
- important_changes.pl : This script prints important changes in Sympa since last install. It is based on the NEWS ***** entries.
- set_symlinks.pl : This script sets symbolic links at installation time.
- subst.pl : This script replaces --VAR-- occurences at installation time.
''./doc/''
''./po/''
''./soap/''
''./src/''
''./src/etc/script/''
''./wwsympa/''
''./wwsympa/Marc/''
Database
Work in progress. All the tables are described already though.
This chapter describes the Sympa database.
Overall organization
The Sympa database contains 5 tables which are :
- admin_table, this table stores a cache version of the moderators and owners of lists,
- user_table, this tables registers the users as individual people,
- subscriber_table, this table registers subscribers; it stores couples ”(user, list)”, thus producing one entry by subscription for each user.
- logs_table: this tables stores the Sympa logs,
- netidmap_table, this table stores informations relative to authentification.
Tables description
We provide here, for each table, a data dictionary and a fields' description.
admin_table
This table is just a cache of the informations found in sympa.conf, robot.conf and lists' config files. It is used to speed up the access to informations regarding administrators. The sources of these informations are the configuration files and not this table.
data catalogue
| Field | Type | Encoding | Null | Default |
|---|---|---|---|---|
 list_admin | varchar(50) | latin1_swedish_ci | No | |
| robot_admin | varchar(80) | latin1_swedish_ci | No | |
| role_admin | enum('listmaster', 'owner', 'editor') | latin1_swedish_ci | No | |
| user_admin | varchar(100) | latin1_swedish_ci | No | |
| comment_admin | varchar(150) | latin1_swedish_ci | Yes | NULL |
| date_admin | datetime | No | ||
| include_sources_admin | varchar(50) | latin1_swedish_ci | Yes | NULL |
| included_admin | int(1) | Yes | NULL | |
| info_admin | varchar(150) | latin1_swedish_ci | Yes | NULL |
| profile_admin | enum('privileged', 'normal') | latin1_swedish_ci | Yes | NULL |
| reception_admin | varchar(20) | latin1_swedish_ci | Yes | NULL |
| subscribed_admin | int(1) | Yes | NULL | |
| update_admin | datetime | Yes | NULL |
Fields' description
- list_admin:
- robot_admin:
- role_admin:
- user_admin:
- comment_admin:
- date_admin:
- include_sources_admin:
- included_admin:
- info_admin:
- profile_admin:
- reception_admin:
- subscribed_admin:
- update_admin:
subscriber_table
data catalogue
| Field | Type | Encoding | Null | Default |
|---|---|---|---|---|
| robot_subscriber | varchar(80) | latin1_swedish_ci | No | |
| list_subscriber | varchar(50) | latin1_swedish_ci | No | |
| user_subscriber | varchar(100) | latin1_swedish_ci | No | |
| bounce_address_subscriber | varchar(100) | latin1_swedish_ci | Yes | NULL |
| bounce_score_subscriber | smallint(6) | Yes | NULL | |
| bounce_subscriber | varchar(35) | latin1_swedish_ci | Yes | NULL |
| comment_subscriber | varchar(150) | latin1_swedish_ci | Yes | NULL |
| custom_attribute_subscriber | varchar(500) | latin1_swedish_ci | Yes | NULL |
| date_subscriber | datetime | No | ||
| include_sources_subscriber | varchar(50) | latin1_swedish_ci | Yes | NULL |
| included_subscriber | int(1) | Yes | NULL | |
| reception_subscriber | varchar(20) | latin1_swedish_ci | Yes | NULL |
| subscribed_subscriber | int(1) | Yes | NULL | |
| topics_subscriber | varchar(200) | latin1_swedish_ci | Yes | NULL |
| update_subscriber | datetime | Yes | NULL | |
| visibility_subscriber | varchar(20) | latin1_swedish_ci | Yes | NULL |
Fields' description
- robot_subscriber: the virtual host this subscription's list is hosted by.
- list_subscriber: the list to which the subscription is done,
- user_subscriber: the e-mail address of subscription
- bounce_address_subscriber:
- bounce_score_subscriber:
- bounce_subscriber:
- comment_subscriber: Comments about the subscription
- custom_attribute_subscriber: the XML fragment containing the user custom attributes for this subscriber
- date_subscriber: date the subscription was created
- include_sources_subscriber:
- included_subscriber: 1 if user is included
- reception_subscriber: the reception mode this user chose for this list
- subscribed_subscriber: 1 if user is subscribed
- topics_subscriber: the list of topics this subscriber is subscribed to
- update_subscriber:
- visibility_subscriber: the visibility preference of this subscriber.
user_table
data catalogue
| Field | Type | Encoding | Null | Default |
|---|---|---|---|---|
| email_user | varchar(100) | latin1_swedish_ci | No | |
| attributes_user | text | latin1_swedish_ci | Yes | NULL |
| cookie_delay_user | int(11) | Yes | NULL | |
| gecos_user | varchar(150) | latin1_swedish_ci | Yes | NULL |
| lang_user | varchar(10) | latin1_swedish_ci | Yes | NULL |
| password_user | varchar(40) | latin1_swedish_ci | Yes | NULL |
Fields' description
- email_user: User's e-mail address
- attributes_user:
- cookie_delay_user:
- gecos_user:
- lang_user: User's favourite language
- password_user: User's password.
logs_table
data catalogue
| Field | Type | Encoding | Null | Default |
|---|---|---|---|---|
| id_logs | bigint(20) | No | ||
| action_logs | varchar(50) | latin1_swedish_ci | No | |
| client_logs | varchar(100) | latin1_swedish_ci | Yes | NULL |
| daemon_logs | varchar(10) | latin1_swedish_ci | No | |
| date_logs | int(11) | No | ||
| error_type_logs | varchar(150) | latin1_swedish_ci | Yes | NULL |
| list_logs | varchar(50) | latin1_swedish_ci | Yes | NULL |
| msg_id_logs | varchar(255) | latin1_swedish_ci | Yes | NULL |
| parameters_logs | varchar(100) | latin1_swedish_ci | Yes | NULL |
| robot_logs | varchar(80) | latin1_swedish_ci | Yes | NULL |
| status_logs | varchar(10) | latin1_swedish_ci | No | |
| target_email_logs | varchar(100) | latin1_swedish_ci | Yes | NULL |
| user_email_logs | varchar(100) | latin1_swedish_ci | Yes | NULL |
Fields' description
- id_logs: unique log's identifier.
- action_logs: name of the Sympa subroutine which initiated the log
- client_logs: IP address of the client machine from which the message was sent.
- daemon_logs: name of the Sympa daemon which ran the action
- date_logs: date when the action was executed
- error_type_logs: name of the error string – if any – issued by the subroutine
- list_logs: name of the mailing-list in which context the action was executed
- msg_id_logs: identifier of the message which triggered the action.
- parameters_logs: List of commas-separated parameters. The amount and type of parameters can differ from an action to another.
- robot_logs: name of the robot in which context the action was executed
- status_logs: exit status of the action. If it was an error, it is likely that the error_type_logs field will contain a description of this error.
- target_email_logs: e-mail address (if any) targeted by the message
- user_email_logs: e-mail address of the message sender
netidmap_table
data catalogue
| Field | Type | Encoding | Null | Default |
|---|---|---|---|---|
| netid_netidmap | varchar(100) | latin1_swedish_ci | No | |
| robot_netidmap | varchar(80) | latin1_swedish_ci | No | |
| serviceid_netidmap | varchar(100) | latin1_swedish_ci | No | |
| email_netidmap | varchar(100) | latin1_swedish_ci | Yes | NULL |
Fields' description
- netid_netidmap:
- robot_netidmap:
- serviceid_netidmap:
- email_netidmap:
session_table
data catalogue
| Field | Type | Null | Default |
|---|---|---|---|
| id_session | varchar(30) | No | |
| start_date_session | int(11) | No | |
| date_session | int(11) | No | |
| data_session | text | Yes | |
| email_session | varchar(100) | Yes | NULL |
| hit_session | int(11) | Yes | NULL |
| remote_addr_session | varchar(60) | Yes | NULL |
| robot_session | varchar(80) | Yes | NULL |
Fields' description
- id_session: the identifier of the database record;
- start_date_session: the date when the session was created;
- date_session: date epoch of the last use of this session. It is used in order to expire old sessions ;
- data_session: parameters attached to this session that don't have a dedicated column in the database;
- email_session: the email associated to this session;
- hit_session: the number of hit performed during this session. Used to detect crawlers;
- remote_addr_session: The IP address of the computer from which the session was created;
- robot_session: The virtual host in which the session was created.