'\" t .\" .\" .\" Title: webmlmd .\" Author: Sam Varshavchik .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 10/28/2020 .\" Manual: Double Precision, Inc. .\" Source: Courier Mail Server .\" Language: English .\" .TH "WEBMLMD" "1" "10/28/2020" "Courier Mail Server" "Double Precision, Inc." .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" webmlmd \- WebMLM interface to couriermlm .SH "SYNOPSIS" .HP \w'\fBcp\ /usr/lib/courier/courier/webmail/webmlm\ /var/www/cgi\-bin\fR\ 'u \fBcp /usr/lib/courier/courier/webmail/webmlm /var/www/cgi\-bin\fR .HP \w'\fBwebmlmd\fR\ 'u \fBwebmlmd\fR {[start] | [restart] | [stop]} {/etc/courier/webmlmrc} .SH "DESCRIPTION" .PP WebMLM is a service that offers an alternative web\-based access to some \fBcouriermlm\fR commands, as an alternative to submitting them via E\-mail\&. .PP At this time, WebMLM implements requests to subscribe and unsubscribe from the mailing list, and configuration of basic mailing list settings\&. .PP Before configuring WebMLM, the mailing list must be set up using \fBcouriermlm\fR(1)\&. WebMLM is not a separate application, it is an add\-on to \fBcouriermlm\fR\&. WebMLM will not work correctly until the mailing list is fully configured, and all \&.courier files, that correspond to this list, are installed\&. .SH "OVERVIEW" .PP WebMLM consists of three parts: .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} A configuration file, (default: /etc/courier/webmlmrc) that enumerates all \fBcouriermlm\fR\-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 \fBwebmlm\fR and \fBwebmlmd\fR programs talk to each other, and several other configuration parameters\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fBwebmlmd\fR is a background daemon process that reads the configuration file, creates the communication socket specified by the configuration file, and listens for web requests\&. .RE .sp .RS 4 .ie n \{\ \h'-04'\(bu\h'+03'\c .\} .el \{\ .sp -1 .IP \(bu 2.3 .\} \fBwebmlm\fR is a small stub program which must be installed as a script in Apache http server\*(Aqs cgi\-bin directory\&. Apache runs the script to process every request received from a web client/browser\&. \fBwebmlm\fR reads web browser\*(Aqs request, reads the configuration file, opens the communication socket file specified in the configuration file, sends the request to the \fBwebmlmd\fR daemon process, and waits for \fBwebmlmd\fR\*(Aqs response, which is forwarded to the web browser/client\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br \fBwebmlm\fR is originally installed in the /usr/lib/courier/courier/webmail directory, and must be manually copied to Apache\*(Aqs 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 \fBwebmlm\fR directly into the cgi\-bin directory\&. Installing the subpackage is all that\*(Aqs needed in those cases\&. .sp .5v .RE .RE .PP Use the following process to web\-enable \fBcouriermlm\fR\-managed mailing lists: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} Configure the LISTNAME, LISTDESCR, LISTPW and URL \fBcouriermlm\fR list options\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} Set up the webmlmrc configuration file\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 3.\h'+01'\c .\} .el \{\ .sp -1 .IP " 3." 4.2 .\} Start \fBwebmlmd\fR, and arrange start it automatically during the system boot\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 4.\h'+01'\c .\} .el \{\ .sp -1 .IP " 4." 4.2 .\} Install \fBwebmlm\fR in your web server\*(Aqs cgi\-bin directory\&. .RE .SH "CONFIGURE COURIERMLM LIST OPTIONS" .PP Use the \(lq\fBcouriermlm\fR set \fIdirectory\fR \fIname\fR=\fIvalue\fR\(rq command, for each \fBcouriermlm\fR list \fIdirectory\fR to set the following settings: .PP LISTNAME .RS 4 The mailing list\*(Aqs short title, or caption\&. Example: \(lqThe courier\-users mailing list\(rq\&. .RE .PP LISTDESCR .RS 4 This is a longer, more verbose description of this mailing list\&. This setting is displayed, as raw HTML, on the list\*(Aqs main page\&. This is an optional setting\&. .RE .PP URL .RS 4 The URL to the main page for this mailing list\&. You\*(Aqll need to figure out what this URL should be set to by planning ahead where \fBwebmlm\fR gets installed, in the last step in this installation process\&. .sp After installing \fBwebmlm\fR in Apache\*(Aqs cgi\-bin directory, the URL for the \fBwebmlm\fR command would probably be something like \(lqhttp://\fIservername\fR/cgi\-bin/webmlm\(rq\&. The list\*(Aqs URL is the name of the list\*(Aqs directory appended to \fBwebmlm\fR\*(Aqs URL\&. .sp For example, if the \fBcouriermlm\fR mailing list directory is /var/lists/devel\-list, its URL \fIMUST\fR be \(lqhttp://\fIservername\fR/cgi\-bin/webmlm/devel\-list\(rq\&. .RE .PP LISTPW .RS 4 This is the password to the mailing list administration screen\&. The password must be set using the \fBcouriermlm\fR command\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br 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\&. .sp 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 \fBwebmlmd\fR\&. .sp 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\&. .sp .5v .RE .RE .PP Put apostrophes around each option setting when running \fBcouriermlm\fR\&. Most of these configuration settings (especially LISTDESCR) contain special shell characters and must be quoted\&. .SH "SETTING UP THE WEBMLMRC CONFIGURATION FILE" .PP A default \fBwebmlmd\fR configuration file is installed as /etc/courier/webmlmrc\&. The file contains a description of each required configuration setting\&. Briefly: .PP PORT .RS 4 The filesystem socket port file\&. This is a local filesystem socket that\*(Aqs used to process web requests\&. The directory that contains the filesystem socket must either be owned by the same userid that owns the \fBcouriermlm\fR mailing list directory, or \fBwebmlmd\fR 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\*(Aqs only writable by root, so \fBwebmlmd\fR needs to be started by root, in the step step, in the default configuration\&. .sp 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\*(Aqs default configuration\&. .RE .PP LISTS .RS 4 A colon\-separated list of \fBcouriermlm\fR mailing list directories, as absolute paths\&. A single instance of WebMLM is capable of handling multiple lists, provided that: .sp .RS 4 .ie n \{\ \h'-04' 1.\h'+01'\c .\} .el \{\ .sp -1 .IP " 1." 4.2 .\} The names of all mailing list directories, the last components of all directories, are unique\&. .RE .sp .RS 4 .ie n \{\ \h'-04' 2.\h'+01'\c .\} .el \{\ .sp -1 .IP " 2." 4.2 .\} All mailing list directories are owned by the same userid and groupid\&. .RE .sp Otherwise, multiple, separate instances of WebMLM must be set up\&. .RE .SH "STARTING WEBMLMD" .PP The following command starts \fBwebmlmd\fR: .sp .if n \{\ .RS 4 .\} .nf webmlmd start \fIconfigfile\fR .fi .if n \{\ .RE .\} .PP This command should be added to your system start up script (replacing \fIconfigfile\fR with the absolute pathname to the configuration file)\&. .if n \{\ .sp .\} .RS 4 .it 1 an-trap .nr an-no-space-flag 1 .nr an-break-flag 1 .br .ps +1 \fBNote\fR .ps -1 .br .PP 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 \fBwebmlmd\fR\&. .sp .5v .RE .PP The \fBwebmlmd\fR command returns immediately, it continues to run as a background daemon process)\&. To stop the daemon process: .sp .if n \{\ .RS 4 .\} .nf webmlmd stop \fIconfigfile\fR .fi .if n \{\ .RE .\} .PP As mentioned previously, \fBwebmlmd\fR must be either invoked as root, or under the same userid that owns the mailing list directories, provided that \fBPORT\fR\*(Aqs directory is writable by the userid\&. .SH "INSTALLING WEBMLM" .PP Install the \fBwebmlm\fR program by either manually copying it from the /usr/lib/courier/courier/webmail directory to your Apache\*(Aqs 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 \fBwebmlm\fR directly into the cgi\-bin directory .SH "MULTIPLE WEBMLM INSTANCES" .PP 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\&. .SS "Install multiple copies of webmlm" .PP Make separate copies of the \fBwebmlm\fR program, one for each instance of WebMLM\&. Install them all in your web server\*(Aqs cgi\-bin directory\&. This can be done with soft or hard links, but there must be separate instances of \fBwebmlm\fR\&. .PP Each instance of \fBwebmlm\fR reads a configuration file whose name is formed by appending \(lqrc\(rq to the command, and looking for the file in /etc/courier\&. For example, the unmodified \fBwebmlm\fR reads /etc/courier/webmlmrc\&. If a second copy named \fBwebmlm2\fR exists, it will read /etc/courier/webmlm2rc\&. .PP Additionally, the optional \fBWEBMLMRC_DIR\fR environment variable overrides the /etc/courier portion of the configuration filename\&. If \fBwebmlm\fR finds that this environment variable is set, its contents replace the \(lq/etc/courier\(rq portion\&. For example, a \fBwebmlm\fR that reads \(lq/etc/lists\(rq from \fBWEBMLMRC_DIR\fR will open the /etc/lists/webmlmrc configuration file\&. Similarly, if its own name, in the web server\*(Aqs script directory, is \fBwebmlm2\fR, it will open /etc/lists/webmlm2rc\&. .PP Use Apache\*(Aqs \(lqSetEnv\(rq directory to set environment variables: .sp .if n \{\ .RS 4 .\} .nf SetEnv WEBMLMRC_DIR /etc/lists .fi .if n \{\ .RE .\} .PP Use whatever mechanism makes sense for you to arrange a unique configuration file for each copy of the \fBwebmlm\fR command\&. .SH "SEE ALSO" .PP \m[blue]\fB\fBcouriermlm\fR(1)\fR\m[]\&\s-2\u[1]\d\s+2 .SH "AUTHOR" .PP \fBSam Varshavchik\fR .RS 4 Author .RE .SH "NOTES" .IP " 1." 4 \fBcouriermlm\fR(1) .RS 4 \%http://www.courier-mta.org/couriermlm.html .RE