xenial (1) webmlmd.1.gz

Provided by: courier-mlm_0.68.2-1ubuntu7_amd64 bug

NAME

       webmlmd - WebMLM interface to couriermlm

SYNOPSIS

       cp /usr/lib/courier/courier/webmail/webmlm /var/www/cgi-bin

       webmlmd {[start] | [restart] | [stop]} {/etc/courier/webmlmrc}

DESCRIPTION

       WebMLM is a service that offers an alternative web-based access to some couriermlm commands, as an
       alternative to submitting them via E-mail.

       At this time, WebMLM implements requests to subscribe and unsubscribe from the mailing list, and
       configuration of basic mailing list settings.

       Before configuring WebMLM, the mailing list must be set up using couriermlm(1).  WebMLM is not a separate
       application, it is an add-on to couriermlm.  WebMLM will not work correctly until the mailing list is
       fully configured, and all .courier files, that correspond to this list, are installed.

OVERVIEW

       WebMLM consists of three parts:

       •   A configuration file, (default: /etc/courier/webmlmrc) that enumerates all couriermlm-created mailing
           list directories for which WebMLM will offer its services (a single instance of WebMLM can support
           multiple mailing list directories). The configuration file also specifies the name of a local
           filesystem socket (a named pipe) where webmlm and webmlmd programs talk to each other, and several
           other configuration parameters.

       •   webmlmd is a background daemon process that reads the configuration file, creates the communication
           socket specified by the configuration file, and listens for web requests.

       •   webmlm is a small stub program which must be installed as a script in Apache http server's cgi-bin
           directory.  Apache runs the script to process every request received from a web client/browser.
           webmlm reads web browser's request, reads the configuration file, opens the communication socket file
           specified in the configuration file, sends the request to the webmlmd daemon process, and waits for
           webmlmd's response, which is forwarded to the web browser/client.

               Note
               webmlm is originally installed in the /usr/lib/courier/courier/webmail directory, and must be
               manually copied to Apache's cgi-bin directory. Most installable Courier packages (including the
               Courier RPM package built using its default RPM build script) have a separate subpackage that
               installs webmlm directly into the cgi-bin directory. Installing the subpackage is all that's
               needed in those cases.

       Use the following process to web-enable couriermlm-managed mailing lists:

        1. Configure the LISTNAME, LISTDESCR, LISTPW and URL couriermlm list options.

        2. Set up the webmlmrc configuration file.

        3. Start webmlmd, and arrange start it automatically during the system boot.

        4. Install webmlm in your web server's cgi-bin directory.

CONFIGURE COURIERMLM LIST OPTIONS

       Use the “couriermlm set directory name=value” command, for each couriermlm list directory to set the
       following settings:

       LISTNAME
           The mailing list's short title, or caption. Example: “The courier-users mailing list”.

       LISTDESCR
           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.

       URL
           The URL to the main page for this mailing list. You'll need to figure out what this URL should be set
           to by planning ahead where webmlm gets installed, in the last step in this installation process.

           After installing webmlm in Apache's cgi-bin directory, the URL for the webmlm command would probably
           be something like “http://servername/cgi-bin/webmlm”. The list's URL is the name of the list's
           directory appended to webmlm's URL.

           For example, if the couriermlm mailing list directory is /var/lists/devel-list, its URL MUST be
           “http://servername/cgi-bin/webmlm/devel-list”.

       LISTPW
           This is the password to the mailing list administration screen. The password must be set using the
           couriermlm command.

               Note
               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 options 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 options file is ineffective, it will be restored the
               next time any configuration setting is changed.

               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
               SSL with webmlmd.

               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.

       Put apostrophes around each option setting when running couriermlm. Most of these configuration settings
       (especially LISTDESCR) contain special shell characters and must be quoted.

SETTING UP THE WEBMLMRC CONFIGURATION FILE

       A default webmlmd configuration file is installed as /etc/courier/webmlmrc. The file contains a
       description of each required configuration setting. Briefly:

       PORT
           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 couriermlm mailing list directory, or webmlmd must be started as root (in the next step
           of this installation process). The default /etc/courier/webmlmrc configuration file sets the
           filesystem socket file to a Courier directory that's only writable by root, so webmlmd needs to be
           started by root, in the step step, in the default configuration.

           Additionally, the filesystem socket port file must be accessible by the userid that executes web
           cgi-bin scripts. This is the nobody user, in Apache's default configuration.

       LISTS
           A colon-separated list of couriermlm mailing list directories, as absolute paths. A single instance
           of WebMLM is capable of handling multiple lists, provided that:

            1. The names of all mailing list directories, the last components of all directories, are unique.

            2. All mailing list directories are owned by the same userid and groupid.

           Otherwise, multiple, separate instances of WebMLM must be set up.

STARTING WEBMLMD

       The following command starts webmlmd:

           webmlmd start configfile

       This command should be added to your system start up script (replacing configfile with the absolute
       pathname to the configuration file).

           Note
           Most installable Courier packages (including the Courier RPM package built using its default RPM
           build script) install a system startup script. The script invokes the appropriate magical incantation
           if the configuration file (/etc/courier/webmlmrc) has a non-empty LISTS setting. Initially, LISTS is
           empty and nothing happens. Once the mailing list directories are defined, the startup script will
           take care of starting webmlmd.

       The webmlmd command returns immediately, it continues to run as a background daemon process). To stop the
       daemon process:

           webmlmd stop configfile

       As mentioned previously, webmlmd must be either invoked as root, or under the same userid that owns the
       mailing list directories, provided that PORT's directory is writable by the userid.

INSTALLING WEBMLM

       Install the webmlm program by either manually copying it from the /usr/lib/courier/courier/webmail
       directory to your Apache's cgi-bin directory. Most pre-built Courier packages typically do not have a
       /usr/lib/courier/courier/webmail directory, but have have an optional subpackage that installs webmlm
       directly into the cgi-bin directory

MULTIPLE WEBMLM INSTANCES

       Sometimes, very specialized environments may require multiple instances of WebMLM. For example, to
       support mailing list directories that are owned by different userids. This may not be supported by most
       generic, pre-built, Courier packages, and must be done manually.

   Install multiple copies of webmlm
       Make separate copies of the webmlm program, one for each instance of WebMLM. Install them all in your web
       server's cgi-bin directory. This can be done with soft or hard links, but there must be separate
       instances of webmlm.

       Each instance of webmlm reads a configuration file whose name is formed by appending “rc” to the command,
       and looking for the file in /etc/courier. For example, the unmodified webmlm reads /etc/courier/webmlmrc.
       If a second copy named webmlm2 exists, it will read /etc/courier/webmlm2rc.

       Additionally, the optional WEBMLMRC_DIR environment variable overrides the /etc/courier portion of the
       configuration filename. If webmlm finds that this environment variable is set, its contents replace the
       “/etc/courier” portion. For example, a webmlm that reads “/etc/lists” from WEBMLMRC_DIR will open the
       /etc/lists/webmlmrc configuration file. Similarly, if its own name, in the web server's script directory,
       is webmlm2, it will open /etc/lists/webmlm2rc.

       Use Apache's “SetEnv” directory to set environment variables:

           SetEnv WEBMLMRC_DIR /etc/lists

       Use whatever mechanism makes sense for you to arrange a unique configuration file for each copy of the
       webmlm command.

SEE ALSO

       couriermlm(1)[1]

AUTHOR

       Sam Varshavchik
           Author

NOTES

        1.

                   couriermlm(1)

           [set $man.base.url.for.relative.links]/couriermlm.html