Sympa Logo
Translations of this page:

WWSympa, Sympa's web interface

WWSympa is Sympa's web interface.

Organization

WWSympa is fully integrated with Sympa. It uses sympa.conf and Sympa's libraries. The default Sympa installation will also install WWSympa.

Every single piece of HTML in WWSympa is generated by the CGI code using template files (See Template file format). This makes internationalization of pages, as well as per-site customization, easier.

The code consists of one single PERL CGI script, wwsympa.fcgi. To enhance performances you can configure WWSympa to use FastCGI; the CGI will be persistent in memory.
All data will be accessed through the CGI, including web archives. This is required to allow the authentication scheme to be applied systematically.

Authentication is based on passwords stored in the database table user_table; if the appropriate Crypt::CipherSaber is installed, passwords are encrypted in the database using reversible encryption based on RC4. Otherwise, they are stored in clear text. In both cases, reminding of passwords is possible.

To keep track of authentication information, WWSympa uses HTTP cookies stored on the client side. The HTTP cookie only indicates that a specified email address has been authenticated; permissions are evaluated when an action is requested.

The same web interface is used by the listmaster, list owners, subscribers and others. Depending on permissions, the same URL may generate a different view.

WWSympa's main loop algorithm is roughly the following:

  1. check authentication information returned by the HTTP cookie;
  2. evaluate user's permissions for the requested action;
  3. process the requested action;
  4. set up variables resulting from the action;
  5. parse the HTML template files.

Web server setup

wwsympa.fcgi access permissions

Because Sympa and WWSympa share a lot of files, wwsympa.fcgi must run with the same uid/gid as archived.pl, bounced.pl and sympa.pl. There are different ways to achieve this.

Default behaviour

Until version 5.3: SetuidPerl

This is the default method but might be insecure. If you don't set the --enable_secure configuration option, wwsympa.fcgi is installed with the SetUID bit set. On most systems, you will need to install the suidperl package.

Starting version 5.4: C wrapper

The C wrapper presented in the preceding section will be automatically built starting version 5.4.

The wwsympa.fcgi is wrapped in a small C script, wwsympa-wrapper.fcgi, in order to avoid to use the – unsecure and no longer maintained – SetuidPerl mode.

Alternatives (all versions)

Sudo

Use sudo to run wwsympa.fcgi as user sympa. Your Apache configuration should use wwsympa_sudo_wrapper.pl instead of wwsympa.fcgi. You should edit your /etc/sudoers file (with visudo command) as follows:

apache ALL = (sympa)  NOPASSWD: /home/sympa/bin/wwsympa.fcgi

You should also check that the requiretty and env_reset flags are not set in the sudoers configuration file :

#Defaults    requiretty
#Defaults    env_reset

With requiretty set, sudo would only run when the user is logged in to a real tty; with env_reset set, most of your environment variables would be ignored... including your server name, the URL requested, etc.

Dedicated Apache server

Run a dedicated Apache server with sympa.sympa as uid.gid (the Apache default is apache.apache);

Apache suExec

Use an Apache virtual host with sympa.sympa as uid.gid; Apache needs to be compiled with suexec. Be aware that the Apache suexec usually define a lowest UID/GID allowed to be a target user for suEXEC. For most systems, including binaries distribution of Apache, the default value 100 is common. So Sympa UID (and Sympa GID) must be higher than 100 or suexec must be tuned in order to allow lower UID/GID. Check http://httpd.apache.org/docs/suexec.html#install for details. The User and Group directive have to be set before the FastCgiServer directive is encountered;

suExec usage example. Written by Daniel Marczisovszky

The following configuration example uses pathes used by Debian. Please set your paths according to your own configuration.

To use suExec with FastCGI, enable both modules in your Apache config.

LoadModule fastcgi_module /usr/lib/apache2/modules/mod_fastcgi.so
LoadModule suexec_module /usr/lib/apache2/modules/mod_suexec.so

Note for Debian/Ubuntu users: these modules can be enabled with the a2enmod helper script:

a2enmod suexec
a2enmod fastcgi

To run FastCGI scripts combined with suExec, the FastCgiWrapper directive should be set. See more about this directive here: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html#FastCgiWrapper In theory FastCgiWrapper On could be enough, but FastCGI documentation says it is not reliable all the time. On Debian the path to the suExec executable is /usr/lib/apache2/suexec.

<IfModule mod_fastcgi.c>
  # Path to suexec executable
  FastCgiWrapper /usr/lib/apache2/suexec
  FastCgiIpcDir /var/lib/apache2/fastcgi
  # -restart kills crashed applications
  FastCgiConfig -restart
</IfModule>

Since suExec allows CGI scripts to be executed only within the server's document root (we assume it is /var/www), create this small wrapper in /var/www/_sympa_:

/var/www/_sympa_/wwsympa.fcgi:

#!/bin/bash
# Path to your real wwsympa.fcgi
exec /usr/lib/cgi-bin/sympa/wwsympa.fcgi

It should be executable, and both it's directory and the script itself should be owned by sympa:

chmod 755 /var/www/_sympa_/wwsympa.fcgi
chown -R sympa:sympa /var/www/_sympa_

To be able to use wwsympa, add these to your VirtualHost section in Apache config:

<VirtualHost *>
    SuexecUserGroup sympa sympa

    <Directory "/var/www/_sympa_/">
        AllowOverride None
        Options ExecCGI
        Order allow,deny
        Allow from all
        AddHandler fastcgi-script .fcgi
    </Directory>

    Alias /wwsicons /usr/share/sympa/icons
    Alias /wws /var/www/_sympa_/wwsympa.fcgi
    Alias /static-sympa /usr/share/sympa/static_content
</VirtualHost>

Installing wwsympa.fcgi in your Apache server

In the following code examples, we suppose you're using the default 5.3 behaviour (see wwsympa.fcgi access permissions). The script launching the web server is then wwsympa.fcgi. Depending to your configuration, this is likely to be changed as follows:

You first need to set an alias to the directory where Sympa stores static contents (CSS, member pictures, documentation) directly delivered by Apache.

Example:

Alias /static-sympa /home/sympa/static_content

If you chose to run wwsympa.fcgi as a simple CGI, you simply need to script alias it.

Example:

ScriptAlias /sympa /home/sympa/bin/wwsympa-wrapper.fcgi

Running FastCGI will provide much faster responses from your server and reduce load (to understand why, read http://www.fastcgi.com/devkit/doc/fcgi-perf.htm).

If you are using mod_fcgid Apache module :

SECURITY WARNINIG

mod_fastci was recently reported to have critical session management issues (at least when used with Sympa).

After logging in the Sympa web interface, users were attributed the identity of other previously logged in people. This could potentially lead to basic users being authenticated as listmaster.

Consequently we strongly discourage you from using mod_fastcgi until further notice. mod_fgcid does not have this bug and works otherwise as well as mod_fastcgi.

LoadModule fcgid_module modules/mod_fcgid.so

  <IfModule mod_fcgid.c>
    IPCCommTimeout 120
    MaxProcessCount 2
  </IfModule>

  <Location /sympa>
    SetHandler fcgid-script
  </Location>
  
  ScriptAlias /sympa /home/sympa/bin/wwsympa-wrapper.fcgi

If you are using mod_fastcgi Apache module :

  LoadModule fastcgi_module modules/mod_fastcgi.so
  FastCgiServer /home/sympa/bin/wwsympa-wrapper.fcgi -processes 2
  <Location /sympa>
  SetHandler fastcgi-script
  </Location>

  ScriptAlias /sympa /home/sympa/bin/wwsympa-wrapper.fcgi

If you run virtual hosts, then each FastCgiServer(s) can serve as multiple hosts. Therefore you need to define it in the common section of your Apache configuration file.

Installing wwsympa.fcgi in nginx

This configuration was submitted by E. Kovarski.

To save any future nginx users any headaches, here is a sample nginx.conf stanza which works with Sympa v5.3.3:

server {
        listen       80;
        server_name  my.domain.org;

        location / {
            fastcgi_pass   unix:/var/run/sympa/wwsympa.socket;
            fastcgi_param  QUERY_STRING       $query_string;
            fastcgi_param  REQUEST_METHOD     $request_method;
            fastcgi_param  CONTENT_TYPE       $content_type;
            fastcgi_param  CONTENT_LENGTH     $content_length;
            fastcgi_param  PATH_INFO          $fastcgi_script_name;
            fastcgi_param  REQUEST_URI        $request_uri;
            fastcgi_param  REMOTE_ADDR        $remote_addr;
            fastcgi_param  SERVER_NAME        $server_name;
        }

        location /static-sympa {
                alias /usr/local/sympa/static_content;
        }
}

Note that the request_uri fastcgi parameter is necessary for virtual hosting.

I got bit by the documentation which said server_name is compared against http_host but after some debugging I noticed that $robot was not set in wwsympa properly unless it can match http_host against request_uri.

Installing wwsympa.fcgi in lighttpd

This configuration was submitted by M. Deranek.

Here is a configuration snippet to make run Sympa with lighttpd (http://www.lighttpd.net) webserver.

Config might require some path tweaking as it customized to Gentoo...

server.modules += ("mod_fastcgi")
 
alias.url += ( "/static-sympa/icons/" => "/usr/share/sympa/icons/" )
alias.url += ( "/static-sympa/" => "/var/spool/sympa/static_content/" )
 
$HTTP["url"] =~ "\^/sympa" {
fastcgi.server = ( "/sympa" =>
    ((    "check-local"    =>    "disable",
        "bin-path"    =>    "/usr/libexec/sympa/wwsympa-wrapper.fcgi",
        "socket"    =>    "/var/run/lighttpd/sympa.sock",
        "max-procs"    =>     2,
        "idle-timeout"    =>     20,
    ))
)
}

Using FastCGI

FastCGI is an extension to CGI, that provides persistency for CGI programs. It is extremely useful with WWSympa, since source code interpretation and all initialisation tasks are performed only once when wwsympa.fcgi processes start. These processes then work as a servlet/daemon, endlessly waiting for client requests.

To run WWSympa with FastCGI, you need to :

  • install the FCGI Perl module (see installing_perl_and_cpan_modules) ;
  • install an Apache module that provides FastCGI features. You can choose between 2 such implementations :
    • mod_fastcgi, the historical one. Note that it was not extended to work with Apache 2. You can however apply the patch provided here.
    • mod_fcgid, an alternate implementation. The main difference between this module and mod_fastcgi is that fastcgi scripts are not launched at Apache startup, but when the first client request happens. This module should be preferred.

wwsympa.conf parameters

arc_path

(Default value: /home/httpd/html/arc)
Where to store HTML archives. This parameter is used by the archived.pl daemon. It is a good idea to install the archive outside the web hierarchy to prevent possible backdoors in the access control powered by WWSympa. However, if Apache is configured with a chroot, you may have to install the archive in the Apache directory tree.

archive_default_index thrd - mail

(Default value: thrd)
The default index organization when entering the web archive: either threaded or in chronological order.

archived_pidfile

(Default value: archived.pid)
The file containing the PID of archived.pl.

bounce_path

(Default value: /var/bounce)

This is the directory where bounced.pl daemon will store the last bouncing message for each user. These mails will be available through the web interface in the bounce management page.

This directory is organised as follows:

<bounce_path value>/<listname>@<robot_name>/<email_address>

<email_address> is a file containing the last bouncing message for this address in this list.

Warning: this parameter must not be mistaken with queuebounce which defines the the spool where incoming error reports are stored until bounced.pl picks them up and processes them.

bounced_pidfile

(Default value: bounced.pid)
The file containing the PID of bounced.pl.

cookie_expire

(Default value: 0)
Lifetime (in minutes) of HTTP cookies. This is the default value when not set explicitly by users.

cookie_domain

(Default value: localhost)
Domain for the HTTP cookies. If beginning with a dot (.), the cookie is available within the specified internet domain. Otherwise, for the specified host. Example:

  cookie_domain cru.fr
  cookie is available for host 'cru.fr'

  cookie_domain .cru.fr
  cookie is available for any host within 'cru.fr' domain

The only reason for replacing the default value would be where WWSympa's authentication process is shared with an application running on another host.

custom_archiver

(Default value : undefined)

Archives are prepared using Mhonarc. You may use an alternative program to process each message to be archived. In such case introduce the custom_archiver parameter which is the path of an external program. CAUTION: Note that Sympa always guess that the custom archiver script accepts two variables : ”–list” whose value is the address of the list (including the domain part) and ”–file” that will contain the absolute path to the message to be archived. Each time the custom archiver is called, it is called with these two parameters with their values filled.

default_home

(Default value: home)
Organization of the WWSympa home page. If you have only a few lists, the default value home (presenting a list of lists organized by topic) should be replaced by lists (a simple alphabetical list of lists).

icons_url (obsolete since Sympa 5.4)

log_facility

WWSympa will log using this facility. Defaults to Sympa's syslog facility. Configure your syslog according to this parameter.

mhonarc

(Default value: /usr/bin/mhonarc)
Path to the (superb) MhOnArc program. Required for the HTML archive.

htmlarea_url

(Default value: undefined)
Relative URL to the (superb) online HTML editor HTMLarea. If you have installed Javascript application you can use it when editing HTML documents in the shared document repository. In order to activate this plugin, the value of this parameter should point to the root directory where HTMLarea is installed. HTMLarea is a free opensource software you can download here: http://sourceforge.net/projects/freshmeat_htmlarea/

password_case sensitive | insensitive

(Default value: insensitive)
If set to insensitive, WWSympa's password check will be insensitive. This only concerns passwords stored in the Sympa database, not the ones in LDAP.

Be careful: in previous 3.xx versions of Sympa, passwords were lowercased before database insertion. Therefore changing to case-sensitive password checking could bring you some password checking problems.

title

(Default value: Mailing List Service)
The name of your mailing list service. It will appear in the Title section of WWSympa.

use_fast_cgi 0|1

(Default value: 1)
Choice of whether or not to use FastCGI. On http://listes.cru.fr, using FastCGI increases WWSympa's performance by as much as a factor of 10. Refer to http://www.fastcgi.com and the Apache config section of this document for details about FastCGI.

Database configuration

WWSympa needs an RDBMS (Relational Database Management System) in order to run. All database access is performed via the Sympa API. Sympa currently interfaces with MySQL, SQLite, PostgreSQL, Oracle and Sybase.

A database is needed to store user passwords and preferences. The database structure is documented in the Sympa documentation; scripts for creating it are also provided with the Sympa distribution (in script).

User information (password and preferences) are stored in the User table. User passwords stored in the database are encrypted using reversible RC4 encryption controlled with the cookie parameter, since WWSympa might need to remind users of their passwords. The security of WWSympa rests on the security of your database.

Logging in as listmaster

Once Sympa is running, you should log in on the web interface as a privileged user (listmaster) to explore the admin interface, create mailing lists, etc.

Multiple email addresses can be declared as listmasters via the sympa.conf (or robot.conf) listmaster configuration parameter (see sympa.conf parameters). Note that listmasters on the main robot (declared in sympa.conf) also have listmaster privileges on virtual hosts, but they will not receive the various mail notifications (list creations, warnings,...) regarding these virtual hosts.

The listmasters should log in with their canonical email address as an identifier (not listmaster@my.host). The associated password is not declared in sympa.conf; it will be allocated by Sympa when first hitting the Send me a password button on the web interface. As for any user, the password can then be modified via the Preferences menu.

Note that you must start the sympa.pl process with the web interface; it is responsible for delivering mail messages including password reminders.

The listmaster web interface

This section contains screenshots of the functionalities accessible through the Sympa web administration interface.

Overview

Identity change

As listmaster, you can assume another user's identity. Once done, the web interface will behave as if you were this person. This is useful for assistance.

Log level change

By modifying this option, you change the log level of Sympa without restarting it. This allows you to temporarily increase the amount of logs produced.

Session vizualisation

This button makes Sympa display a page with all the current session opened.

Suspend my subscription

Click on “Manage your lists” in the home menu. The form displayed allows you to suspend your subscription for one or more lists for a specified period of time. A summary table allows you to know the status of each list to which you are subscribed.
In order to suspend your subscription to one or more lists, follow these steps:

  • Select a start date through the calendar that appears when you click on the “start date” field;
  • if you wish, you can specify the date when you want your subscription to resume. Do it using the “end date” field. You can click on “indefinite.” In this case, you will have to return to this page to resume your subscription;
  • Select the lists you want to suspend you subscription for. The “Toogle selection” button allows you to invert the selection;
  • Click on “Submit” to confirm the suspension.

To resume your subscription to one or more lists, follow these steps:

  • Select the list(s) you want to reactivate. The “Toogle selection” button allows you to invert the selection;
  • Click “Restart”.

How to prevent suspension for certain lists?

Some institutional lists must not be allowed for suspension.

In that case, users must not be able to tick the checkbox in the suspension management screen.

B. Marchal (univ. Lorraine) provided the following tip to achieve it:

Modify the suspend_request.tt2 template like this:

    [% IF user.email %]
      [% IF suspend_list %]
        [% FOREACH sub = suspend_list %]
          <tr class="color0">
<!-- Start modification -->
          [% SET allowed_suspension = 1 %]
          [% current_list = get_which.shift %]
          [% IF current_list.admin.custom_vars %]
            [% FOREACH cvar IN current_list.admin.custom_vars %]
               [% IF cvar.name == 'disable_suspend' && cvar.value == 'on' %]
                   [% allowed_suspension = 0 %]
               [% END %]
            [% END %]
          [% END %]
    [% IF allowed_suspension %]
       <td><input type="checkbox" checked="checked" name="listname" value="[% sub.listname %]" /> 
    [% ELSE %]
       <td>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
    [% END %]
      [% hidden_head %][% sub.listname %][% hidden_end %]&nbsp;</td>
<!-- end modification -->
    [% IF sub.listsuspend %]
        <td></td>
        <td>&nbsp;[%|loc%]Suspended from[% END %] [% sub.liststartdate %] [%|loc%]to[% END %] [% IF sub.listenddate %][% sub.listenddate %][% ELSE %][%|loc%]indefinite end date[% END %][% END %]</td>	        
    [% ELSE %]
      <td> &nbsp; [% sub.listreception %] &nbsp; </td>
<!-- Start modification -->
      [% IF allowed_suspension %]
      	 <td></td>
      [% ELSE %]
	 <td>&nbsp;Suspension & désabonnement impossible&nbsp;</td>
      [% END %]
<!-- end modification -->
    [% END %]
          </tr>
  [% END %]
[% ELSE %]
        <p>[%|loc%]No subscription.[% END %]</p>
      [% END %]
    [% END %]
  </table>
  <input class="MainMenuLinks" type="button" value="[%|loc%]Toogle selection[%END%]" onclick="toggle_selection(document.suspend_request.listname)" />

Then define in the lists you don't want to be suspended a custom parameter with the name “disable_suspend” and the value “on”.

You list will appear in the suspension management screen, but without the checkbox allowing to suspend it.

Exclude users

If you are administrator of the list, click on “Review members”→“Exclude” button in “Manage list members”.
Users listed are excluded from the list. Beware, for this feature is different from the blacklist. Exclusion makes sense when a list is based on external data sources ; thanks to exclusion, a user can unsubscribe (or be removed by list owner) even though she was included via an external data source. Users get into the exclusion table, through the standard unsubscribe/delete functions. They get off the exclusion table with the standard subscribe/add functions.

manual/web-interface.txt · Last modified: 2013/11/06 17:35 by david.verdin@renater.fr

The Sympa software is provided by RENATER
Faq | News | Contact | Legal Notices