The last step in setting up the LWGate on your HTTP server is to create the LWGate database. This database stores all the necessary information on each mailing list available on this LWGate. Maintaining this database will be an ongoing task. This page is intended to explain the format of the database so that you can add and update any information related to the lists served by this script.
The database is in a standard comma-delimited format, that meaning that each record exists on a single line and each field in that record is separated by commas. The text-qualifier for these fields is the double-quote character ("). This means th at any field which has a comma or the text-qualifier character within it will be surrounded by the text-qualifier. If the text-qualifier character exists within a field, each instance of it will be immediately preceeded by another instance of itsel f. Whitespace is not allowed between the text-qualifier of a field and the comma delimiter. Thus, a record containing the phrases:
Stimpson the "Masked Marvel" Wildcat, Esq.
would form a record of the following format:
Stimpson,"the ""Masked Marvel""","Wildcat, Esq."
Records that begin with a pound-sign (#) are considered comments and are not parsed as an entry in the database.
With several fields to deal with, this can become quite complex. Thus, the LWGate tries to assist the entry of new lists into the database. Built in to the LWGate is a request-add form, which gathers and processes requests to be added to the LWGa te. This form is available from the URL of "your-script-URL/request-add.html" and is linked to from the LWGate home page, provided that you have set the $OFFER_ADDS variable to 1. For instance, the NetSpace LWGate request-add form is avail able at <URL:http://www.netspace.org/cgi-bin/lwgate/request-add.html >.
Whenever the request form is submitted, it tries to build an appropriate record to be entered into the database, which it then mails to the address set in the $ADMIN_MAIL variable. Note that this record is line-wrapped to transmit it via electronic mail, so you will need to reconstruct the one-line record from the multi-line phrase. The only other deficiency is that the form cannot process list owner names or email addresses that contain commas; though this is unlikely to be n eeded, the database (using text-qualified fields) can support this, however the request form processor needs to assume that each comma delimits separate entries. If a user has a comma in his or her name or email address, s/he should so note it in t he request form's comment field. You will then need to manually modify the entry suggested by the form processor, and appropriately add the comma.
The various fields the compose each record are described below. At the end, we will construct a sample entry.
The name of the list.
The descriptive title of the list.
A phrase identifying the type of mailing list server which provides this mailing list. Valid entries are lserv for LISTSERV(TM), lproc for ListProcessor, lproc(private) for a ListProcessor list with priv ate archives, mdomo for Majordomo, and slist for SmartList.
This is the primary address which the script will use when sending commands. The script processes commands executed by clients into the command format of the appropriate list type, and then mails these commands to this primary address. If a l ist owner wishes the commands to be processed automatically by the mailing list server, this field will contain the address of that server. The list owner, however, could ask that commands be sent to his/her personal account so that use of the scri pt can be approved on a case-by-case basis.
According to RFC822, multiple email addresses may be specified by delimiting them by commas. However, this field is parsed as a whole by the script, not as a comma-delimited record within a field, and used is as an address when invoking the serve r's mail program. With this feature, commands could be sent both to the mailing list server for automatic processing and a list owner's address to monitor script activity.
This field specifies a list of commands to be redirected to a secondary address (defined next). If a command is listed within this field, the formatted output will not be sent to the primary address, but rather to the secondary address. This allows a list owner to define two classes of commands which will be mailed to two different addresses. Thus, a list owner could allow all commands except signoff requests to be processed by the primary address; however, to prevent abuse, the list o wner defines the signoff command as a secondary command and defines the secondary address as his personal account.
This field is a comma delimited list of the below names for the describe commands:
subscribe Subscribe commands signoff Unsubscribe commands set Set Subscription Options commands confirm Confirm Subscription commands index Archive File Index commands query Query Subscription Options commands database Search Archives commands review Review Distribution List commands get Get Archive File commands information Get Information File commands
The set, query, information, and database commands are only available to LISTSERV(TM) and ListProcessor mailing lists. The confirm command is available to only LISTSERV(TM) lists. The review command is available to all list types except SmartList. .
This field is treated as the primary address field, except that the output of the defined secondary commands will be sent to this address. As with the primary address, RFC822 allows for multiple addresses to be specified.
This field is a list of comma delimited command names which are to be restricted from being used for the list. Forms will not be processed for restricted commands. This is a good way for list owners to prevent abuse of the LWGate, or to preve nt users from being confused by unavailable commands. (e.g. Some LISTSERV(TM) lists may not require subscription confirmation, so this command should be restricted.) It is not necessary to restrict commands which are not supported by the type of ma iling list server; this will be accomplished by the script itself.
The names of the commands are:
subscribe Subscribe commands signoff Unsubscribe commands set Set Subscription Options commands set(digest) Digest Option for the Set Form confirm Confirm Subscription commands index Archive File Index commands query Query Subscription Options commands database Search Archives commands review Review Distribution List commands get Get Archive File commands information Get Information File commands
The set, set(digest), query, information, and database commands are only available to LISTSERV(TM) and ListProcessor mailing lists. The confirm command is available to only LISTSERV(TM) lists. The review command is available to all list types exc ept SmartList.
This field defines the names and email addresses of a list's owners. The field is comma delimited, with a list owner's as the first field followed by the address in the next field. Another owner can be expressed by adding another pair of fiel ds to this one. Since this field is treated as a record in itself, fields within this field may need to be text qualified and then text qualified again as a whole for a field within the database record. Thus, if a list owner's name contains a ", in the database file it will be expressed as """".
This should be an RFC822 address spec, but is not parsed by the script. This indicates to users where to send postings to for this list, but is used by the script only to present this information.
This should be an RFC822 address spec, but is not parsed by the script. This indicates to users where to send list commands, if they wish to build their own commands and send them manually.
A paragraph describing the list.
The LWGate can present a hypertext interface to archives which exist on the local server. This field defines the root archive directory for the list. Only files within this directory or subdirectories of it will be available to the script. Al l archive files and directories must be readable to the script when executed by the HTTPD. Note that the LWGate cannot support archives that have back-slashes ("\") in their names.
This field is a Perl regular expression which identifies the names of all files and directories to make available from the script. Any file which matches this regular expression will be treated as an archive file. Any directory whose name mat ches the regular expression will be made available, and the client will be able to view any archive files or matching subdirectories within this directory. This regular expression should be constructed assuming that is will be delimited by slashes (/).
If the LWGate $DECOMP variable is properly configured (see configuring the LWGate), the LWGate can present list archives that have been compressed in a standard format.
This field is for LISTSERV(TM) mailing lists which support and have defined a set of topics. This is a comma-delimited list of those topics, and will be presented in the Set Subscription Options form.
Let's work through an example. FOOBAR-L is a LISTSERV(TM) mailing list, entitled "All Things FOOBAR." Our list owner wants to have most commands processed automatically by LISTSERV, so the primary address is "LISTSERV@foo.bar.org". So far, our en try is a simple one:
FOOBAR-L,All Things FOOBAR,lserv,LISTSERV@foo.bar.org
Now, our list owner is concerned that signoff and review commands might be abused, so she wants to have these designated as secondary commands. She wants these commands to be processed automatically by LISTSERV(TM), but also wants them mail to he r, "owner@bar.org", to make her aware of any suspicious requests. Furthermore, the FOOBAR-L list doesn't require subscription confirmation, so the confirm command should be restricted.
The secondary commands field consists of "signoff" and "review" separated by commas, and since there is a comma in this field, it must be text qualified. The secondary address field consists of the LISTSERV(TM) address and the list owner address, again separated by commas and thus text-qualified. The restricted commands field consists only of confirm. Our entry now looks like:
FOOBAR-L,All Things FOOBAR,lserv,LISTSERV@foo.bar.org,"signoff,review","LISTSERV@foo.bar.org,owner@bar.org",confirm
The list owner is called "Renwina "The Lovely" Hoek" and her email address, as mentioned before, is "owner@bar.org." This is where the example gets complicated. The list owner field consists of a set of comma-delimited fields. Since the list own er's name contains the text-qualifier, that field must be text qualified. Thus, treated as a record, the two fields look like this:
"Renwina ""The Lovely"" Hoek",owner@bar.org
However, this record itself must become a field within the list record. Since the above contains the text-qualifier character, this field must be text-qualified. All double-quote characters must be doubled, and the entire field is enclosed in dou ble-quotes. Now we have a record of:
FOOBAR-L,All Things FOOBAR,lserv,LISTSERV@foo.bar.org,"signoff,review","LISTSERV@foo.bar.org,owner@bar.org",confirm,"""Renwina """"The Lovely"""" Hoek"",owner@bar.org"
Users should send posts to "LISTSERV@foo.bar.org" and posts to "FOOBAR-L@foo.bar.org". These two fields are added, making our record look like this:
FOOBAR-L,All Things FOOBAR,lserv,LISTSERV@foo.bar.org,"signoff,review","LISTSERV@foo.bar.org,owner@bar.org",confirm,"""Renwina """"The Lovely"""" Hoek"",owner@bar.org",LISTSERV@foo.bar.org,FOOBAR-L@foo.bar.org
The list owner wants a description to read "FOOBAR-L, where you can talk about all things FOOBAR." This field must be text-qualified, since it contains a comma. Our record now looks like:
FOOBAR-L,All Things FOOBAR,lserv,LISTSERV@foo.bar.org,"signoff,review","LISTSERV@foo.bar.org,owner@bar.org",confirm,"""Renwina """"The Lovely"""" Hoek"",owner@bar.org",LISTSERV@foo.bar.org,FOOBAR-L@foo.bar.org,"FOOBAR-L, where you c an talk about all things FOOBAR."
Since the archives to FOOBAR-L are available on the local server, our list owner wants to make them available from the LWGate. The archive directory is "/home/listserv/archives/foobar-l/" and all archives are matched by the regular expression "^f oobar-l\.log.+$". Thus, these two fields are added, but note that any directories from the specified archive directory on down which match the regular expression will also be visible to the LWGate. Note that only files which are readable and subdir ectories which are both readable and executable by the LWGate script when executed by the HTTP server will be available.
Here is our final record, which ought to be one single line:
FOOBAR-L,All Things FOOBAR,lserv,LISTSERV@foo.bar.org,"signoff,review","LISTSERV@foo.bar.org,owner@bar.org",confirm,"""Renwina """"The Lovely"""" Hoek"",owner@bar.org",LISTSERV@foo.bar.org,FOOBAR-L@foo.bar.org,"FOOBAR-L, where you c an talk about all things FOOBAR.",/home/listserv/archives/foobar-l/,^foobar-l\.log.+$
Most of this effort will be taken care of by the request form processor in the LWGate script, but occassionaly you will need to edit and enter entries by hand. Hopefully this discussion has been lucid enough to make this possible.
Congratulations! Now you have completed installing the LWGate script. Have fun!
Copyright 1996, David W. Baker.