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:
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.
siteaddr()
InterfacesThe default MajorCool distribution includes 6 sample
siteaddr/
files:
$whereami
), then both fully-qualified and
username-only addresses will match. If not in the domain, no mapping occurs.
rolo
program (a simple
text-file database used by NCR Corporation to provide
First.Lastname to user@host.domain address mapping).
ldapsearch
program
(available from the University of Michigan) to query the NCR X.500
Associate Directory.
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.)
To build your own siteaddr()
interface, you need to
develop a Perl include file that defines 3 objects:
%siteaddr
%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()
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()
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:
#~
' indicates text to be extracted and used as the
file "explanation" during the install.#~This is file foo. #~The text can span multiple lines.
#+
' indicates a variable dependency. The named
variable will be prompted for during configuration; the value will
be stored in the generated config.sh
and substituted on
all files.#+BINDIR
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.
$sitename
$sitehome
$header
/$footer
$opt_hiddenlists
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
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
$opt_trustident
$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
$opt_subverify
$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
config
command). Remember: the user will always have this option
via e-mail command unless Majordomo itself is
modified.
$opt_cfcomments
0
), only the keyword variables and their
values will be saved.
$opt_multipart
0
) this update feature altogether.
$opt_prefsreturn
0
), security
is increased at the cost of minor functionality.
$opt_robots
0
), the program instance will not
be indexed by these agents.
$opt_scansteps
$opt_multipart
)
option to be enabled and a browser that supports this MIME
content.
@admin_keywords
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
-d {description} -o {owner} -p {passwd} listnameYou 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
-o {owner} -p {passwd} oldlist newlistYou 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
-o {owner} -p {passwd} listnameYou 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.
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.
Allow Browser To Cache Pages
Enable Style Sheet Font Control (Where Supported)
Default Font Face & Point Size
Use JavaScript Enhancements
Sort Subscriber List in BROWSE and MODIFY Views
by_siteaddr()
function).
Use 'Menu' Style User Interface
Default Action for Menu Mode
Default Screen Width
Use Images for Form Buttons
Tool Tips on Button Bars
Show Nested Lists As Hyperlinks
Link to Subscribers When Following Nested Lists
Show Line Numbers In Subscriber List
Use 2-Column Table For Configuration File
Show Help With Configuration File Fields
Show Majordomo Subsystem For Each Configuration Field
Maximum Size Supported By Browser TextArea
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:
ACTION
referring to your MajorCool
instance. The form METHOD
can be either GET
or PUT.
action
variable (usually a hidden
element) set to remote.
list
variable identifying the list that
this operation will apply to. This can be implemented as a hidden,
text, pull-down, or other element as required.
command
variable identifying the command that
will be applied to the list. This can be implemented as a hidden,
text, pull-down, or other element as required.
siteaddr
text element, which is where the
user will enter their e-mail address (or other suitable input for the
siteaddr()
function). This is the same type of input as
would be expected of the MajorCool instance if it were not
accessed remotely. In other words, if your installation's main screen
expects an X.500 attribute, your remote form must also. NOTE: This field
is required even for non-subscription requests, since commands such as
who
and info
often use the e-mail address
to validate access privileges.
You can combine these elements to provide a variety of remote
invocation styles:
Basic Subscription
Subscription Pick-List
Command Choice
As might be expected with MajorCool, this remote invocation offers more functionality than the basic Majordomo mail-based interaction, providing:
info
,
intro
, and who
query results
subscribe
and
unsubscribe
status
siteaddr()
address translation & equivalencies