[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

MajorCool is a 2-piece application. Most of the work is done by the majorcool.pl script which is installed in the Majordomo $homedir. This script is run under the Majordomo wrapper program to ensure that all permissions are honored accordingly.

A CGI "shim" is used to link the world of the Web to the wrapper-based world of MajorCool. Since the wrapper procedure provides a limited environment (and does not pass parent env-vars), the sole purpose of the "shim" is to pass needed CGI variables to the MajorCool routine. This CGI is installed using the name that was entered during the Configure session for the appropriate cf file.

Customizing the operation of MajorCool can involve both install-time and run-time configuration. These settings control all the HTML, Cascading Style Sheets, and Javascripts which are dynamically generated by the majorcool.pl script -- there are no external HTML/CSS "source files".

Although MajorCool was designed primarily as a site administration tool with a complete view of all lists on a server, it also supports a remote mode for embedding individual actions (e.g., subscribe) in external (non-MajorCool) Web pages.

Site Configuration

Basic behavior of the MajorCool application is controlled by the majorcool_XXXX.cf configuration file (where "XXXX" comes from the named XXXX.sh source file output by Configure -- default.sh by default). The config tool will take the majorcool.cf.common base file, append a selected siteaddr/ file, and then perform variable substitutions to create an installed majorcool_XXXX.cf file.

NOTE: If the installed cf file is changed, be sure to update the appropriate sh and/or the template majorcool.cf.common as appropriate, or else the changes will be lost the next time Configure is run.

The configuration variables in the cf file determine MajorCool's level of security, visual presentation, and its integration with the local site. Most of these settings are directly supported by the Configure tool and thus will probably not require digging into any of the Perl code. If any local modifications are to be done, they will likely involve the support of the siteaddr() functions for interfacing to external name-to-address conversion tools.

siteaddr() External Query Interfaces

MajorCool provides an ability to interface with external functions that provide name-to-address conversions. For example, the NCR e-mail infrastructure utilizes a Rolodex-style database tool to allow delivery based on name as well as traditional host addresses. Thus, my own address is both bhoule@www.sandiegoca.ncr.com and Bill.Houle@SanDiegoCA.NCR.COM. While Majordomo can be configured to know the equivalencies between bhoule@www.sandiegoca.ncr.com and bhoule@sandiegoca.ncr.com (via the $mungedomain option), it cannot handle the address mapping when provided by an external function.

It was decided that, given our addressing complexities, MajorCool would be infinitely more useful if it was aware of the mapping equivalencies provided by external functions such as the NCR Rolodex. Taking the output of these external functions, we can build regular expression pattern matching strings that are used to determine list membership. By using regular expressions rather than fixed strings (as Majordomo does), MajorCool is able to identify list members by their multiple valid addresses.

The interface to these external functions is through siteaddr() functions contained in the MajorCool cf file. The main siteaddr() routine accepts a single string (as prompted for on the BROWSE screen), and returns a 3-value tuple:

  1. The "friendly name" of the address matched by the function, e.g., a "real name". This value is used for display purposes only.
  2. The preferred e-mail address to be associated with this user.
  3. A regular expression to match any address as appropriate for this user. See the additional comments below for more about this matching functionality.

For example, the resultant NCR siteaddr() on "Houle" might return the tuple

(
	"Bill Houle",
	"Bill.Houle@SanDiegoCA.NCR.COM",
	"/^Bill\.Houle$|^Bill\.Houle@|^bhoule@.*\.sandiegoca\.ncr\.com$/"
)
The latter regexp defines address matching patterns for (respectively): my unqualified Rolodex address, fully-qualified Rolodex address, and any host-based address in my domain that matched my login-id.

Pre-Defined siteaddr() Interfaces

The default MajorCool distribution includes 6 sample siteaddr/ files:

Other examples of external programs that could be used for customized siteaddr() functions include YP/NIS or Ph. (If you develop any functions that would be of interest to others, please send them to me so that they can be included in future releases.)

Building Your Own External Interface

To build your own siteaddr() interface, you need to develop a Perl include file that defines 3 objects:

%siteaddr
The %siteaddr associative array, which is used to define various text messages that appear on MajorCool screens. The prompt value defines the prompt for the field whose date that will be passed to the siteaddr() function, while the browse, modify, create, rename, and delete strings can be used to further explain features & functions on the forms for the associated modules.
siteaddr()
The siteaddr() function, which generates the 3-value tuple providing the real name, primary address, and regular expression matching parameters to the MajorCool application.
by_siteaddr()
The by_siteaddr() function, which is used to provide a customizable address sorting mechanism. Since the siteaddr() interface function defines a set of addresses that MajorCool uses to support multiple address classes, it may also be valuable to sort list members according to an order appropriate for your local address definitions.

Your siteaddr() may require some user interaction such as selecting a specific address from an externally provided list of possible matches. You may output HTML from within your function in order to to provide this interaction. If you perform interaction via HTML, you must be cognizant of MajorCool's support for multipart-MIME and be sure to pass any form arguments back to the calling BROWSE module -- see the ncr-rolo file which is a good example of this technique.

If you implement your own siteaddr() function, please note the special comment format used by Configure to support their installation:

Regular Expression Matching

The regular expression pattern matching capabilities of MajorCool are very powerful. They can also be very dangerous. A poorly constructed regexp may result in lists being accessible and incorrectly appearing to be subscribed. The functionality is primarily intended for string matching, and any use of metacharacters should be done with the utmost care. For example, you would not want to allow an input to generate a regexp such as /\w+@.*/ -- every address on a list might be matched!

Regexp matching is completely optional. To minimize the danger to functions that have no use for a pattern match, a null regexp value can be returned by the siteaddr() function. In this case, MajorCool will perform a straight text comparison of the address parameter, identical to the behavior of Majordomo itself.

If you utilize the regexp functionality, it is imperative that all efforts are made to ensure that inputs to siteaddr() are carefully scrutinized and no improper expressions are generated.

Modules

MajorCool functions are designed around 4 modules which determine which Majordomo actions are accessible: BROWSE (View/Change List Subscription Status), MODIFY (Administer an Existing List), CREATE (Create a New List), and DELETE (Delete an Existing List). Each of these modules can be selectively enabled or disabled in any given config file.

If a module is disabled, it's form or menu selection will not be shown on the main screen and any sub-functions that depend on this action being present will fail. The state of the enabled modules is contained in the %modules variable within the MajorCool cf file. For example, the setting of

	%modules = (
		browse,		1,
		modify,		1,
		create,		0,
		rename,		0,
		delete,		0,
	};
corresponds to a MajorCool configuration with the end-user and list-admin functionality active, but the list create/rename/delete functionality turned off. Normally, the Configure process will handle the setting of status for the various modules.

Other Config Variables

$sitename
The site or installation location name to be used in page titles.

$sitehome
The URL of the site's "home page". This address will be used as the destination for the "HOME" button.

$header/$footer
Optional header/footer pages to incorporate "look and feel" into MajorCool pages. If not present, MajorCool will provide beginning & ending <HTML> and <BODY> tags, resulting in a white page background. If a different look is desired, or a site wishes to incorporate its standard style, alternate files may be specified as header and footer pages. The footer should implement closing BODY and HTML tags, while the header should provide a beginning BODY tag. (MajorCool will always generate the opening HTML tag, since it also generates the document HEAD section.)

$opt_hiddenlists
If disabled (0), the MODIFY portion of the MajorCool opening screen will display a pick-list of all lists available for configuration. Since the pick-list is displayed before the user address is collected, there is no attention paid to advertise/noadvertise settings. Sites wishing to honor advertise settings will want to enable (1) this option to force the owner to explicitly enter the list name. Some older browsers will have trouble with long pick-lists, which is another valid reason for using this feature.

$opt_hiddenpasswd
If disabled (0), the admin_passwd setting will appear as a plain-text field on an equal level with all other fields on the list configuration screen. If enabled (1), the password field would be elevated to a "secret" double-entry process within a separate form. Sites wishing to protect their users from accidental changes or "glance-at-the-screen" compromises might prefer this option.

$opt_noadvertise
Majordomo can be configured to advertise lists to its members even if the list is not normally advertised. Unfortunately, to enable/disable this behavior, the appropriate source lines must be commented in/out. This setting achieves the same function in MajorCool programatically rather than via code changes.

$opt_trustident
Majordomo authenticates the user based on the e-mail address. If an address is forged for any particular command, there is some semblance of security because the e-mail result will be sent to the forged address rather than the forger. Now consider MajorCool: it is possible to masquerade as another user via the Web, and unlike Majordomo, there is no failsafe security -- results will be visible onscreen. If $opt_trustident is disabled (0), MajorCool will try to provide some hint of the same failsafe Majordomo security. Results of accessing "private" list options (e.g. private_who/who_access=list) will be returned via mail rather than displayed onscreen.

$opt_cmdverify
Enabling this option tells MajorCool to generate Majordomo commands and mail them to the user rather than sending them through the list processor. It would be the responsibility of the user to then forward the resulting commands back to Majordomo. This option is called "instruct" mode because in the process of re-sending the commands, the user might become familiar with Majordomo syntax. However, it is also known as "paranoia mode" because the underlying intent was to treat this as an added safety measure for the security-conscious. With this option enabled, no commands can ever be directly executed by a user with a falsified Web identity, since e-mail is used to let the "true" user confirm the actions.

$opt_subverify
A less comprehensive version of $opt_cmdverify, this setting will cause all subscribe/unsubscribe requests to be converted to command form and returned to the user via e-mail. The idea is that the user will then forward the mail back to Majordomo. This eliminates authentication insecurities at the cost of an extra step for the user.

$opt_sendcf
Set this variable to 0 if you do not wish to offer list admins the ability to request a configuration file sent via e-mail (i.e., the Majordomo config command). Remember: the user will always have this option via e-mail command unless Majordomo itself is modified.

$opt_cfcomments
Configuration files normally are stored with full comments included. By disabling this variable (0), only the keyword variables and their values will be saved.

$opt_multipart
The Netscape browser supports an experimental MIME type called 'multipart-mixed-replace'. With this MIME type, continued output can replace any previous screen displays. This feature, known as "server push", can be used to provide a sort of "please wait" status screen while MajorCool performs some of the more time-intensive tasks. Normally, MajorCool will detect which browser supports the "push" functionality and offer it accordingly, or you can disable (0) this update feature altogether.

$opt_prefsreturn
MajorCool can save "state" when presenting the Preferences module such that the user will be returned to the prior screen after the Prefs changes are applied. This is a cool feature that makes Prefs a modal function and allows the user to tweak Prefs settings and instantly see their effects. The downside to this feature is that the "state" that is saved will often include list password data that may be written to your Web server access logs [see A Note About Web Server Security on the Requirements page]. If disabled (0), security is increased at the cost of minor functionality.

$opt_robots
Some Internet search engines, crawlers, and "spiders" honor the "ROBOTS" META tag protocol. Setting this value determines how compliant Robots will react to MajorCool. If disabled (0), the program instance will not be indexed by these agents.

$opt_scansteps
When MajorCool scans the server for member subscription status and list access rights, it can be a time-consuming process. Setting a non-zero value will keep the user aware of the progress of this scan by giving a list countdown. The value set here is the step interval for this countdown (eg, 150..100..50..). Smaller numbers mean more frequent updates, and a corresponding increase in transmitted data and cached pages. This feature requires the MultiPart ($opt_multipart) option to be enabled and a browser that supports this MIME content.

@admin_keywords
This list defines which (and in what order) fields are presented to the list administrator in the "basic" view of the MODIFY screen. Please note that the distributed majorcool.cf.common file contains many NCR-specific keywords that can be removed if not implemented locally. (There is no harm if they remain, though.)

$list_create_cmd
If present (and executable), the referenced program will be invoked for any list-creation request, assuming an argument list of
-d {description}  -o {owner}  -p {passwd}  listname
You can write your own creation program, or use the script found in the contrib/ directory.

Regardless of the setting, all requests for new lists will be mailed to the Majordomo-owner address. The context of the setup will determine whether this mailing is an actual request or merely an FYI following the $list_create_cmd action.

NOTE: Because MajorCool itself runs under wrapper permissions, the specified program will inherit the same privileges. There is no need to include "wrapper" as part of the $list_create_cmd path.

$list_rename_cmd
If present (and executable), the referenced program will be invoked for any list-renaming request, assuming an argument list of
-o {owner}  -p {passwd}  oldlist  newlist
You can write your own creation program, or use the script found in the contrib/ directory.

Regardless of the setting, all requests for list renaming will be mailed to the Majordomo-owner address. The context of the setup will determine whether this mailing is an actual request or merely an FYI following the $list_rename_cmd action.

NOTE: Because MajorCool itself runs under wrapper permissions, the specified program will inherit the same privileges. There is no need to include "wrapper" as part of the $list_rename_cmd path.

$list_delete_cmd
If present (and executable), the referenced program will be invoked for any list-deletion request, assuming an argument list of
-o {owner}  -p {passwd}  listname
You can write your own creation program, or use the script found in the contrib/ directory.

Regardless of the setting, all requests for list deletion will be mailed to the Majordomo-owner address. The context of the setup will determine whether this mailing is an actual request or merely an FYI following the $list_delete_cmd action.

NOTE: Because MajorCool itself runs under wrapper permissions, the specified program will inherit the same privileges. There is no need to include "wrapper" as part of the $list_delete_cmd path.

Per-User Preferences

The configuration settings above reflect site-wide preferences for MajorCool operation. In addition to the per-site settings, MajorCool offers several options for individual per-user preferences. These preferences are implemented via HTTP "Cookies". Cookies are tokens saved in each user's client config and exchanged as part of the HTTP handshake between browser and the MajorCool application.

General Options

Allow Browser To Cache Pages
Browsers can, in the interest of performance, save visited pages in their cache for easier recall. In the case of MajorCool, a cached page may reflect the state of some Majordomo data relative only to the current MajorCool session, even though changes may have been performed via e-mail or other Web users. With the Cache setting, users may enable or disable the caching of page data depending upon their own personal preferences. If caching is disabled, "backing up" to a previous screen will require the browser to re-query for current data.

Enable Style Sheet Font Control (Where Supported)
If your browser supports HTML 4.0 "Style Sheets" (CSS), you may tailor the font family and point size used on all MajorCool pages to suit your liking. This preference can be used to toggle CSS support.

Default Font Face & Point Size
Requires CSS support in the browser and the above Style Sheet Font Control preference enabled. Since not all browsers support Style Sheets or some of the referenced fonts, these settings will have no apparent effect if unsupported.

Use JavaScript Enhancements
JavaScript offers some neat user-interface "bells & whistles" such as the ability to update the browser status line or swap images when "moused over". Most browsers will ignore what they can't understand, so there is no harm for those applications that do not support JavaScript. Naturally, none of these effects are particularly critical to the operation of MajorCool, but they are certainly "cool". However if a user finds them more "annoying" than "cool", they can be disabled.

Sort Subscriber List in BROWSE and MODIFY Views
With large lists, it can be difficult at times to locate specific addresses for verification, modification, or deletion. Users may prefer to have the subscriber list sorted (using the site-configured by_siteaddr() function).

Use 'Menu' Style User Interface
MajorCool can display configured modules (e.g., BROWSE, MODIFY, CREATE, DELETE, and PREFS) in two ways. In "Menu" mode, a selection of buttons is present across the top of the screen, with the 'active' (i.e., selected) action occupying the space between the header and footer. The alternative to Menu mode is to forego the button-bar and the concept of an 'active' action, showing all available actions on the main page. Menu mode is enabled by default.

Default Action for Menu Mode
When in "Menu" mode, the initial screen shown on start-up or restart will be the first available module from the list of BROWSE/MODIFY/CREATE/DELETE. This preference is used to override that ordering and start specifically at a particular module. For example, in a BROWSE/MODIFY configuration, a list owner may choose MODIFY as the preferred action if that is the most frequently performed MajorCool activity. Selecting a module that has been disabled by the site admin will have no effect.

Default Screen Width
The default screen size of MajorCool is designed to easily fit on a 640 pixel wide screen typical of most personal computers (your browser window may need to be widened accordingly). You can set your own desired pixel width, or even have the data follow the current width of the browser by setting the width to '100%'.

Use Images for Form Buttons
MajorCool can be very graphics-intensive, all the way down to its use of images for traditional SUBMIT buttons. Some people find the plain-Jane SUBMIT/RESET buttons more effective (not to mention faster to load), so the use of images for FORM buttons can be enabled or disabled.

Tool Tips on Button Bars
Tool Tips are available on the top (Menu Mode) and bottom button bars. Simply hold the mouse over the button and a window will pop up describing its function in more detail. Tool Tips require JavaScript Enhancements enabled (above).

Browse Options

Show Nested Lists As Hyperlinks
Subscriber lists may contain other local lists as members. These can be displayed as hyperlinks to facilitate the browsing of the nested list details.

Link to Subscribers When Following Nested Lists
Nested lists can be linked to either the Detail view of the referenced list, or directly to the subscriber list itself. Detail view is the default link type.

Show Line Numbers In Subscriber List
The subscriber list can be displayed with line numbers to ease viewing/searching. Note that these line numbers are not stored as part of the Majordomo list and are not permanently bound to individual addresses. In other words, the subscriber #1 in "sorted" mode may not be the same as subscriber #1 in the unsorted display.

Modify Options

Use 2-Column Table For Configuration File
MajorCool will, by default, display the list configuration file as a 2-column table: keywords on the left, values on the right. Although this makes it easy to locate keywords, it can make for a very wide display. If disabled, a more compact single-column format is used.

Show Help With Configuration File Fields
Majordomo provides field-level help descriptions as comments in the list config file. If Help is enabled, these comments will also be visible on-screen when editing the list configuration. Since these comments use a significant amount of screen real estate, experienced users may disable their display.

Show Majordomo Subsystem For Each Configuration Field
Majordomo consists of multiple subsystems -- the aliasing/address setup, the archive program, the digest program, the Majordomo command processor, and the list itself. This option will indicate which subsystem each keyword applies to.

Maximum Size Supported By Browser TextArea
List member files are edited using what is called a TEXTAREA element. On many browsers, the number of bytes that can fit within a TEXTAREA is limited, which can cause a problem when managing lists with many subscribers. Changing the value of this Preference will not change the capability of the browser -- only the manufacturer can do that. However, what this value will do is implement a threshold at which MajorCool will attempt to take alternative actions in order to get around the limitation. Alternative actions include switching to 'append' mode, or editing a subset of the list that matches a pattern.

Remote Invocation & Embedded Buttons

Certain Majordomo list functions such as subscribe, unsubscribe, info, intro, and who can be accessed independent of the normal site-wide BROWSE view. By using the remote interface, one-touch buttons can be embedded in external Web pages to invoke MajorCool remotely. (Since it is a subset of the BROWSE functionality, the BROWSE module must be enabled; there is no way to have BROWSE disabled and still have access to remote mode.)

To access the remote interface of MajorCool, a FORM must be used meeting the following requirements:

You can combine these elements to provide a variety of remote invocation styles:

As might be expected with MajorCool, this remote invocation offers more functionality than the basic Majordomo mail-based interaction, providing:


[Previous: Install] [Next: Future] [Top: Intro] [Home] [Feedback]