<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>webmlmd</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"/><link rel="home" href="#webmlmd" title="webmlmd"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--

Copyright 1998 - 2009 S. Varshavchik.  See COPYING for distribution
information.

--></head><body><div class="refentry"><a id="webmlmd" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>webmlmd — WebMLM interface to couriermlm</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">cp @libexecdir@/courier/webmail/webmlm /var/www/cgi-bin</code> </p></div><div class="cmdsynopsis"><p><code class="command">webmlmd</code>  {[start] |  [restart] |  [stop]} {@sysconfdir@/webmlmrc}</p></div></div><div class="refsect1"><a id="webmlmd_description" shape="rect"> </a><h2>DESCRIPTION</h2><p>
    <span class="application">WebMLM</span> is a service that
    offers an alternative web-based access to some
    <span class="command"><strong>couriermlm</strong></span> commands, as an
    alternative to submitting them via E-mail.</p><p>At this time, 
    <span class="application">WebMLM</span> implements requests to
    subscribe and unsubscribe from the mailing list, and
configuration of basic mailing list settings.</p><p>Before configuring 
    <span class="application">WebMLM</span>, the mailing list must be set
    up using 
    <span class="citerefentry"><span class="refentrytitle">couriermlm</span>(1)</span>. 
    <span class="application">WebMLM</span> is not a separate application,
    it is an add-on to 
    <span class="command"><strong>couriermlm</strong></span>. 
    <span class="application">WebMLM</span> will not work correctly until
    the mailing list is fully configured, and all 
    <code class="filename">.courier</code> files, that correspond to this
    list, are installed.</p></div><div class="refsect1"><a id="webmlmd_overview" shape="rect"> </a><h2>Overview</h2><p>
    <span class="application">WebMLM</span> consists of three
    parts:</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>A configuration file, (default:
        <code class="filename">@sysconfdir@/webmlmrc</code>) that enumerates
        all 
        <span class="command"><strong>couriermlm</strong></span>-created mailing list
        directories for which 
        <span class="application">WebMLM</span> will offer its services
(a single instance of <span class="application">WebMLM</span> can support multiple
mailing list directories).
        The configuration file also specifies the name of a local
        filesystem socket (a named pipe) where
        <span class="command"><strong>webmlm</strong></span> and 
        <span class="command"><strong>webmlmd</strong></span> programs talk to each other,
and several other
        configuration parameters.</p></li><li class="listitem"><p><span class="command"><strong>webmlmd</strong></span> is a background daemon process
        that reads the configuration file, creates the
        communication socket specified by the configuration file,
        and listens for web requests.</p></li><li class="listitem"><p><span class="command"><strong>webmlm</strong></span> is a small stub program which must
        be installed as a script in 
        <span class="application">Apache</span> http server's 
        <code class="filename">cgi-bin</code> directory. 
        <span class="application">Apache</span> runs the script to process
        every request received from a web client/browser. 
        <span class="command"><strong>webmlm</strong></span> reads web browser's request, reads
        the configuration file, opens the communication socket file
        specified in the configuration file, sends the request to
        the 
        <span class="command"><strong>webmlmd</strong></span> daemon process, and waits for 
        <span class="command"><strong>webmlmd</strong></span>'s response, which is forwarded
        to the web browser/client.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
          <span class="command"><strong>webmlm</strong></span> is originally installed in the 
          <code class="filename">@libexecdir@/courier/webmail</code> directory, and
          must be manually copied to Apache's 
          <code class="filename">cgi-bin</code> directory. Most installable 
          <span class="application">Courier</span> packages (including the
          
          <span class="application">Courier</span>
          <acronym class="acronym">RPM</acronym> package built using its default 
          <acronym class="acronym">RPM</acronym> build script) have a separate
          subpackage that installs 
          <span class="command"><strong>webmlm</strong></span> directly into the 
          <code class="filename">cgi-bin</code> directory. Installing the
          subpackage is all that's needed in those cases.</p></div></li></ul></div><p>
Use the following process to web-enable <span class="command"><strong>couriermlm</strong></span>-managed
mailing lists:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Configure the <code class="literal">LISTNAME</code>,
<code class="literal">LISTDESCR</code>, <code class="literal">LISTPW</code>
and <code class="literal">URL</code>
<span class="command"><strong>couriermlm</strong></span> list options.</p></li><li class="listitem"><p>Set up the <code class="filename">webmlmrc</code> configuration
file.</p></li><li class="listitem"><p>Start <span class="command"><strong>webmlmd</strong></span>, and arrange start it
automatically during the system boot.</p></li><li class="listitem"><p>Install <span class="command"><strong>webmlm</strong></span> in your web server's
<code class="filename">cgi-bin</code> directory.</p></li></ol></div></div><div class="refsect1"><a id="webmlmd_configure_couriermlm_list_options" shape="rect"> </a><h2>Configure <span class="command"><strong>couriermlm</strong></span> list options</h2><p>
Use the <span class="quote">“<span class="quote"><span class="command"><strong>couriermlm</strong></span>
<code class="literal">set</code>
<em class="replaceable"><code>directory</code></em>
<em class="replaceable"><code>name</code></em>=<em class="replaceable"><code>value</code></em></span>”</span>
command,
for each <span class="command"><strong>couriermlm</strong></span> list
<em class="replaceable"><code>directory</code></em> to set the following settings:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">LISTNAME</span></dt><dd><p>The mailing list's short title, or caption.
Example: <span class="quote">“<span class="quote">The courier-users mailing list</span>”</span>.
</p></dd><dt><span class="term">LISTDESCR</span></dt><dd><p>
This is a longer, more verbose description of this mailing list.
This setting is displayed, as raw HTML, on the list's main page.
This is an optional setting.
</p></dd><dt><span class="term">URL</span></dt><dd><p>
The <acronym class="acronym">URL</acronym> to the main page for this mailing list.
You'll need to figure out what this <acronym class="acronym">URL</acronym> should be set to
by planning ahead where <span class="command"><strong>webmlm</strong></span> gets installed, in the last
step in this installation process.</p><p>
After installing <span class="command"><strong>webmlm</strong></span> in Apache's
<code class="filename">cgi-bin</code> directory, the URL for the
<span class="command"><strong>webmlm</strong></span> command would probably be something like
<span class="quote">“<span class="quote">http://<em class="replaceable"><code>servername</code></em>/cgi-bin/webmlm</span>”</span>.
The list's <acronym class="acronym">URL</acronym> is the name of the list's directory appended
to <span class="command"><strong>webmlm</strong></span>'s <acronym class="acronym">URL</acronym>.</p><p>
For example, if the <span class="command"><strong>couriermlm</strong></span> mailing list directory
is <code class="filename">/var/lists/devel-list</code>, its <acronym class="acronym">URL</acronym>
<span class="emphasis"><em>MUST</em></span> be
<span class="quote">“<span class="quote">http://<em class="replaceable"><code>servername</code></em>/cgi-bin/webmlm/devel-list</span>”</span>.</p></dd><dt><span class="term">LISTPW</span></dt><dd><p>
This is the password to the mailing list administration screen.
The password must be set using the <span class="command"><strong>couriermlm</strong></span>
command.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
We are not talking military-grade security, here!
Do not recycle sensitive passwords for this purpose.
The password is saved, in plain text, in the <code class="filename">options</code>
file in the mailing list directory.
You should consider removing the world read and execute permissions on
the mailing list directory.
Changing the permissions on the
<code class="filename">options</code> file is ineffective, it will be
restored the next time any configuration setting is changed.</p><p>
Furthermore, authorization for the administration screen is
provided by storing the list password in a browser cookie, which also
gets transmitted over the network, in the clear.
Consider using <acronym class="acronym">SSL</acronym> with <span class="command"><strong>webmlmd</strong></span>.</p><p>
This is a simple password-based implementation.
High levels of security require a lot of care to set up, and are usually
somewhat complicated to implement and manage.
Keep that in mind.</p></div></dd></dl></div><p>
Put apostrophes around each option setting when running
<span class="command"><strong>couriermlm</strong></span>.
Most of these configuration settings (especially <code class="literal">LISTDESCR</code>)
contain special shell characters and must be quoted.</p></div><div class="refsect1"><a id="webmlmd_setting_up_the_webmlmrc_configuration_file" shape="rect"> </a><h2>Setting up the <code class="filename">webmlmrc</code> configuration file</h2><p>
A default <span class="command"><strong>webmlmd</strong></span> configuration file is installed
as <code class="filename">@sysconfdir@/webmlmrc</code>.  The file contains a description
of each required configuration setting.  Briefly:</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">PORT</span></dt><dd><p>
The filesystem socket port file.
This is a local filesystem socket that's used to process web requests.
The directory that contains the filesystem socket must either be owned by
the same userid that owns the <span class="command"><strong>couriermlm</strong></span> mailing list
directory, or <span class="command"><strong>webmlmd</strong></span> must be started as root (in the
next step of this installation process).
The default <code class="filename">@sysconfdir@/webmlmrc</code> configuration file
sets the filesystem socket file to a <span class="application">Courier</span>
directory that's only writable by root, so <span class="command"><strong>webmlmd</strong></span> needs
to be started by root, in the step step, in the default configuration.</p><p>
Additionally, the filesystem socket port file must be accessible by the userid
that executes web cgi-bin scripts.  This is the <code class="literal">nobody</code>
user, in Apache's default configuration.</p></dd><dt><span class="term">LISTS</span></dt><dd><p>
A colon-separated list of <span class="command"><strong>couriermlm</strong></span> mailing list
directories, as absolute paths.
A single instance of <span class="application">WebMLM</span> is capable of handling
multiple lists, provided that:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
The names of all mailing list directories, the last components of all
directories, are unique.</p></li><li class="listitem"><p>
All mailing list directories are owned by the same userid and groupid.</p></li></ol></div><p>
Otherwise, multiple, separate instances of <span class="application">WebMLM</span>
must be set up.</p></dd></dl></div></div><div class="refsect1"><a id="webmlmd_starting_webmlmd" shape="rect"> </a><h2>Starting <span class="command"><strong>webmlmd</strong></span></h2><p>
The following command starts <span class="command"><strong>webmlmd</strong></span>:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
webmlmd start <em class="replaceable"><code>configfile</code></em></pre></div><p>
This command should be added to your system start up script (replacing
<em class="replaceable"><code>configfile</code></em> with the absolute pathname to the
configuration file).</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
Most installable <span class="application">Courier</span> packages (including the
<span class="application">Courier</span> <acronym class="acronym">RPM</acronym> package built using
its default <acronym class="acronym">RPM</acronym> build script) install a system
startup script.
The script invokes the appropriate magical incantation if the
configuration file (<code class="filename">@sysconfdir@/webmlmrc</code>) has a
non-empty <code class="literal">LISTS</code> setting.
Initially, <code class="literal">LISTS</code> is empty and nothing happens.
Once the mailing list directories are defined, the startup script will
take care of starting <span class="command"><strong>webmlmd</strong></span>.</p></div><p>
The <span class="command"><strong>webmlmd</strong></span> command returns immediately, it continues
to run as a background daemon process).
To stop the daemon process:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
webmlmd stop <em class="replaceable"><code>configfile</code></em></pre></div><p>
As mentioned previously, <span class="command"><strong>webmlmd</strong></span> must be either invoked
as root, or under the same userid that owns the mailing list directories,
provided that <code class="envar">PORT</code>'s directory is writable by the userid.</p></div><div class="refsect1"><a id="webmlmd_installing_webmlm" shape="rect"> </a><h2>Installing <span class="command"><strong>webmlm</strong></span></h2><p>Install the <span class="command"><strong>webmlm</strong></span> program by either manually
copying it from the <code class="filename">@libexecdir@/courier/webmail</code>
directory to your Apache's <code class="filename">cgi-bin</code> directory.
Most pre-built <span class="application">Courier</span> packages typically do not
have a <code class="filename">@libexecdir@/courier/webmail</code> directory, but have
have an optional subpackage that installs <span class="command"><strong>webmlm</strong></span>
directly into the <code class="filename">cgi-bin</code> directory</p></div><div class="refsect1"><a id="webmlmd_multiple_webmlm_instances" shape="rect"> </a><h2>Multiple <span class="application">WebMLM</span> instances</h2><p>
Sometimes, very specialized environments may require multiple instances
of <span class="application">WebMLM</span>.  For example, to support mailing list
directories that are owned by different userids.
This may not be supported by most generic, pre-built,
<span class="application">Courier</span> packages, and must be done manually.</p><div class="refsect2"><a id="webmlmd_install_multiple_copies_of_webmlm" shape="rect"> </a><h3>Install multiple copies of <span class="command"><strong>webmlm</strong></span></h3><p>
Make separate copies of the <span class="command"><strong>webmlm</strong></span> program, one
for each instance of <span class="application">WebMLM</span>.
Install them all in
your web server's <code class="filename">cgi-bin</code> directory.  This can be done
with soft or hard links, but there must be separate instances of
<span class="command"><strong>webmlm</strong></span>.</p><p>
Each instance of <span class="command"><strong>webmlm</strong></span> reads a configuration file
whose name is formed by appending <span class="quote">“<span class="quote">rc</span>”</span> to the command, and
looking for the file in <code class="filename">@sysconfdir@</code>.
For example, the unmodified <span class="command"><strong>webmlm</strong></span> reads
<code class="filename">@sysconfdir@/webmlmrc</code>.
If a second copy named <span class="command"><strong>webmlm2</strong></span> exists, it will read
<code class="filename">@sysconfdir@/webmlm2rc</code>.</p><p>
Additionally, the optional <code class="envar">WEBMLMRC_DIR</code> environment variable
overrides the <code class="filename">@sysconfdir@</code> portion of the configuration
filename.
If <span class="command"><strong>webmlm</strong></span> finds that this environment variable is set,
its contents replace the <span class="quote">“<span class="quote">@sysconfdir@</span>”</span> portion.
For example, a <span class="command"><strong>webmlm</strong></span> that reads <span class="quote">“<span class="quote">/etc/lists</span>”</span>
from <code class="envar">WEBMLMRC_DIR</code>
will open the <code class="filename">/etc/lists/webmlmrc</code> configuration file.
Similarly, if its own name, in the web server's script directory, is
<span class="command"><strong>webmlm2</strong></span>, it will open
<code class="filename">/etc/lists/webmlm2rc</code>.</p><p>
Use Apache's <span class="quote">“<span class="quote">SetEnv</span>”</span> directory to set environment
variables:</p><div class="informalexample"><pre class="programlisting" xml:space="preserve">
SetEnv WEBMLMRC_DIR /etc/lists
</pre></div><p>
Use whatever mechanism makes sense for you to arrange a unique configuration
file for each copy of the <span class="command"><strong>webmlm</strong></span> command.</p></div></div><div class="refsect1"><a id="webmlmd_see_also" shape="rect"> </a><h2>SEE ALSO</h2><p>
      <a class="ulink" href="couriermlm.html" target="_top" shape="rect">
        <span class="citerefentry"><span class="refentrytitle">couriermlm</span>(1)</span>
      </a>
    </p></div></div></body></html>
