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
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.
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.
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.
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.
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.
$homedir/wrapper mj_key_cachevia 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.
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:
perl -c
) of the CGI and
majorcool.pl
scripts.
majorcool_default.cf
config file.
For other install questions, don't forget to check the FAQ!
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
MajorCool pre-release versions prior to 1.0pre7 used a
hand-maintained configuration file. The new Configure
process will overwrite this file during installation.
majorcool.cf
config file prior to
installation.
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.)
cf
copy to guide you in setting the
other configuration/installation options.
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.
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:
status
' was renamed
'criteria
', so $arg{status}
should be
replaced by $arg{criteria}
wherever BROWSE parameters
are passed.
list_match
' BROWSE parameter must be passed.
x-multipart-replace
MIME type, a call to send_done()
is necessary to properly
terminate the HTTP "push" session.
ncr-rolo
file has examples of all these changes.
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.
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.]
$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.
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.
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
).