[MajorCool]

MajorCool: A Web Interface To Majordomo

(This is a copy of the MajorCool master documentation set)
Introduction
Usage
System Requirements
Installation
Configuration
Future Direction
Licensing, FAQs, & Credits

The MajorCool source distribution is available as a gzipped tar file, which contains this documentation, the Perl source for both modules, and a few icons; the presentation material from the USENIX LISA'10 conference is available separately.

Installation of MajorCool is relatively straightforward. If you are upgrading from an earlier version of MajorCool, be sure to read and understand the migration section below.

Installation

  1. Unpack the archive somewhere on your Web server (which is also, I hope, a Majordomo list server). The actual location for unpacking is not important -- the files do not need to be anywhere near your Majordomo or Web server directories.

    WARNING: the tar file does not unpack into its own directory. Some people (a) don't look beforehand, and (b) don't like what results. I'll get it right for Mj2, but until then, you were warned.

  2. Run the Configure script ('sh Configure'). This script will prompt for some installation values and save the output to a default.sh file. This file can be edited at any time.

    After creating the default.sh file, Configure will then use this info to generate a majorcool_default.cf configuration file and install the application in the location that you specified. The cf file (and by relation, the source sh file) define the "personality" for a particular MajorCool installation. See the section on personalities for more explanation.

    To verify that everything installed correctly, the Configure program will test the execution of the newly installed MajorCool application. The expected output will be a bunch of HTML code -- relatively meaningless to you, but a good sign nonetheless.

    NOTE: You may edit the generated majorcool_default.cf file as described in the configuration section, but if the appropriate changes are not also made to default.sh and/or the majorcool.cf.common template, your cf changes will be overwritten the next time that the Configure tool is run.

  3. [optional] Add the owner keyword modification to allow dynamic aliasing and ensure proper list-owner mail addressing. If you choose to not add this feature, skip to the next step. However, if you are open to the prospect of this new keyword, the addition of the "owner" is very easily done using Majordomo's config file API:
    &main'new_keyword(
    	"owner",
    	"",
    	"grab_word",
    	"config",
    	"The owner of the list. The owner will receive all 
    	list errors. This keyword is required in order for 
    	the list to become active."
    );
    You may place this (and any other new_keyword invocations) near the end of the main config_parse.pl code, just prior to the "keep require happy" return of '1'. Alternatively, what we have done is to keep all Majordomo local extensions in a separate mj_local.pl file that is require'd near the end of config_parse.pl.

    To verify that your new_keyword() addition has been recognized by Majordomo, pick a list and issue a writeconfig command via e-mail. This will force Majordomo to rewrite the existing config file, creating an empty owner entry. Adding a new keyword is one of the more difficult parts of the installation, so if you get this far, you have done well.

    Once you know owner is working inside Majordomo, you should define the value to be the list owner's e-mail address. If a list is always shown as "unconfigured" in MajorCool, it will mean that either an owner value has not been set in the config file or the value has been set but the Key Cache file (described in a later step) has not been updated.

    Having implemented the owner keyword, be sure to check out mj_build_aliases in the contrib/ directory to see if it might be useful to you. This is a tool that can automatically build a set of sendmail aliases using the list.config values.

  4. [optional] To enable per-list control of MajorCool access, you can add a web_access keyword to the list config files using the Majordomo config file API. (Follow the keyword installation and testing steps as described above for the owner keyword.)
    &main'new_keyword(
    	"web_access", 
    	"none\001browse\001modify\001browse+modify\001browse+modify",
    	"grab_enum", 
    	"config",
    	"One of four possible values: none, browse, modify, or
    	browse+modify. This defines what level of access that
    	MajorCool is granted for this list."
    );

    If the existence of this keyword is not detected within a Majordomo installation, MajorCool will consider all lists on the system as accessible via the Web. But if this keyword is added, list owners will be able to selectively control MajorCool's access to their list:

    Why would you want this additional keyword, you may ask? Well, some individual list owners were overly paranoid about Web access to their list, thinking that (for example) it made hacking their admin passwords possible. This setting allows individual lists to opt-out without limiting the site as a whole. This keyword addition is a panacea of sorts, since restricting Web accessibility in no way translates to avoiding security incidents via the usual Majordomo processes. One can just as easily attempt to crack passwords via e-mail rather than Web.

    Note to site owners: adding this keyword will slow the BROWSE process slightly for all users, since each list config must be queried about its web_access status prior to display.

  5. [optional] To enable Web-based approval of BOUNCE messages -- ie, the "approval queue" -- Majordomo's resend program must be modified and some additional keywords (bounce_action, bounce_text) must be added. Since this is more than the API method can do (as used in the other "optional" steps), this enhancement must be performed by updating Majordomo via the patches found in contrib/. Unpack the approval.shar archive and follow the instructions in the README.

    If your modifications are successful, two new keywords will appear in the configuration files, and MajorCool will show an "Approval Queue" selection on the MODIFY screen.

    With the patch applied, resend will store BOUNCE messages in the standard archive area (if defined), or in the $TMPDIR of the Majordomo configuration. Alternately, if $bouncedir is defined in the Majordomo config file, it will be given precedence. MajorCool will look in those same places to assist in management (approve/reject/delete) of the queue.

  6. Implement the Key Caching function,
    	$homedir/wrapper mj_key_cache
    via cron or similar mechanism. The initial run of the Configure script will create a basic cache file, but this needs to be refreshed frequently in order to correctly display up-to-date list info under the Web interface.

    The "cache" (.majordomo_keys) is a flat-file database of one-line keyword entries indexed by the list name. The keys cached are all the config attributes that are necessary to perform any initial data display and processing (such as "owner", "description", advertise/noadvertise, etc). Keys not cached are retrieved via Majordomo's get_config() API function when specifically needed.

    Use of this cache was required when it was found that list-by-list access via the Majordomo get_config() function was found to be exceedingly slow when dealing with a large number of lists. A way was needed to obtain necessary config information without incurring the cost of numerous run-time list accesses via the config library.

    An alternative to updating via 'cron' is the "auto cache" patch for Majordomo which rebuilds the key cache whenever newconfig is executed by Majordomo (contributed by Tom White <tom@net.msstate.edu> and located in the contrib/ directory).

    NOTE: if you are providing multiple end-user access scripts and they reside in the shared Majordomo $homedir directory, then you will have to make use of the

    	-K <cache> -C <domo_cf>
    command line arguments and set up multiple cron jobs. In a Majordomo virtual server implementation with shared $homedir, there is only one copy of mj_key_cache installed. You will need the additional arguments to override the default cache file location and ensure that all necessary cache files are updated.

  7. Done! You may need to do some additional configuration, but your installation should be functional now. Also, don't forget the optional site.info file that allows you to reflect local Majordomo information in the OnLine Help. In addition, you may customize the snapshots shown in the help screens to better reflect your site's appearance.

    Try accessing as /cgi-bin/majordomo (or whatever script name was used to install the application).

    If the CGI does not run:

    For other install questions, don't forget to check the FAQ!

Personalities

MajorCool supports the notion of "personalities": multiple cf files that cause MajorCool to behave in distinct & different ways. This feature can be used to support the virtual capabilities of Majordomo (e.g., separate majordomo.cf files for different domain name configurations residing on the same server), or multiple entry-points into the same MajorCool installation (e.g., separate tools for the Admin and End-User).

To create these different "personalities", simply run the Configure script for each of the Majordomo servers (or MajorCool entry-points) you wish to target, specifying different config names (e.g., 'Configure other.sh'). The default config name if not specified is default.sh. Settings obtained by Configure are saved to the named config file, which in turn is used to create a MajorCool cf file. Each file specifies a distinct MajorCool configuration detailing Majordomo location, CGI script name, installed modules, config options, etc.

OnLine Help

The OnLine Help for MajorCool is built on-the-fly during installation with the Configure script. There will be different Help files for each installed "personality". Pieces of this documentation set (Usage, Configuration) are extracted and combined to form the Help system. An additional file, install/site.info, is appended to the bottom of the OnLine Help. This file is intended to be site-specific for any information relevant to your local users.

A sample site.info.sample file has been included. You may copy this to site.info and modify as needed. The URLs referenced in the sample are NCR-specific info that is not accessible outside our firewall. However, it should be disclosed that the "End User Guide" is the Majordomo chapter from the O'Reilly MIIS book, and the "Admin Guide" is the list-admin info for new users. Both documents are already included in the base Majordomo package.

Images used in the OnLine Help (and also this documentation) can be customized as well. While most of the screen capture "cutouts" are fairly generic and suitable for all sites, the full-screen snapshots and associated thumbnails are very specific to the author's development site. You can tailor for your environment by replacing the mc_scrncap_full_[module].gif and mc_scrncap_mini_[module].gif files in the source /icons/ directory.

Migration Notes

Upgrading to 1.0

MajorCool pre-release versions prior to 1.0pre7 used a hand-maintained configuration file. The new Configure process will overwrite this file during installation.

  1. Save a copy of your majorcool.cf config file prior to installation.
  2. If you implemented your own siteaddr() functions, save them in a "module" file within the siteaddr/ subdirectory of the source distribution. (See other modules for an example of the special comments syntax.)
  3. Specify the newly created file when prompted for which module to use.
  4. Use your saved cf copy to guide you in setting the other configuration/installation options.

Upgrading to 1.0.3

Versions prior to 1.0.3 included siteaddr() examples that used the 'word boundary' regexp character (\b) to parse addresses containing RFC822 comments. The use of the character caused problems in some browsers due to Perl's interpretation as a backspace character in a certain context. As of release 1.0.3, the requirement of parsing within RFC822 comments has been eliminated, so any use of \b in custom siteaddr() modules is no longer necessary. If you implemented your own siteaddr() module and utilized the \b technique, you may remove those characters.

Upgrading to 1.1.0

siteaddr() support for regular expression matching is now optional. If pattern matching is not required for your site, the function may return an empty string for the regexp return value. In this case, a straight text comparison will be made against the returned address (the 2nd element of the 3-tuple return value).

If your custom siteaddr() function prompts for some user interaction (e.g., picking a name from a list), there are a number of changes that will be required:

Versions prior to 1.1.0 did not support multiple personalities via separate config files. The lone config file was called config.sh. As of 1.1.0, Configure will detect the old filename and rename it to the new default of default.sh. The script will also detect an outdated Key Cache file and re-run mj_key_cache for you. Not only has an extra field been added to the keys (unsubscribe_policy), but the field delimiter has been changed.

1.1.0 also adds some new icons and renames some others. It may be prudent to delete all mc_ prefixed icons from your Web server image directory and let the install process add only those needed.

Upgrading to 1.1.1

In prior versions, majorcool.info was a standalone file to be locally modified with site-specific Majordomo / MajorCool info, and accessible by clicking on the MajorCool banner. Unfortunately, that click action turned out to be non-intuitive. The file is now included as part of the online Help instead. If you had previously utilized this site-info file, you should move it back into the install/ directory as site.info. The Configure process will do the rest. [The corresponding $SITEINFO install variable is no longer needed.]

Upgrading to 1.1.2

$list_create_cmd and $list_delate_cmd have been moved out of the cf.common template file and into the config file. Jot down the values (if any) before upgrading and use them during the 1.1.2 Configure process.

Upgrading to 1.3.0

If you implemented the owner keyword as outlined previously, it was suggested to use "address" as the subsystem name. I have decided to change the name and leverage on the already existing "config" naming scheme instead. The main place these names are readily visible is in the "Subsystem" keyword group selection of the Configuration Screen.

Upgrading to 1.3.2

The behavior when using the standalone password form ($opt_hiddenpasswd=1) has changed slightly to be more like Majordomo. Under the previous scheme, an attempt to change the password was converted into a newconfig command unless the password file existed and was not linked to a MASTER.PASSWD file (read-only or otherwise). This "override" logic made it impossible to create an initial password file via the passwd command.

The new command-override behavior depends on the password file being marked as read-only rather than upon a particular naming convention; if detected as such, the newconfig method will be used. Thus, use of $opt_hiddenpasswd=1 will equate more directly to the traditional behavior of the Majordomo passwd command. If you do not want to encourage .passwd files to be created, you should treat the password change as part of the entire list configuration process ($opt_hiddenpasswd=0).


[Previous: Requirements] [Next: Config] [Top: Intro] [Home] [Feedback]