_ _ ____ _ ____ ____ ___ ____ _ _ ____ |\/| |__| | | | |__/ | \ | | |\/| | | | | | | _| |__| | \ |__/ |__| | | |__| Majordomo, noun: a person who speaks, makes arrangements, or takes charge for another. From Italian maggiordomo or Spanish mayordomo, both from Medieval Latin "major domus" - "chief of the house". (Barnhart Concise Dictionary of Etymology) Release 1.94.5 README -------------------------------------------------------------------------- -> Current users of Majordomo whom are upgrading will want to <- -> read the NEWS file for details on what has changed between <- -> this and the previous version of Majordomo. <- Release 1.94.5 of Majordomo is primarily a security and bugfix release, incorporating changes which fix problems or correct pressing deficiencies in version 1.94.4. Please read the NEWS file for changes between versions 1.94.4 and 1.94.5 * * * * * * * * * * * * * * If you know what Majordomo is and simply want install it, read the INSTALL file. Browse through this file, though; there's probably something new here. * * * * * * * * * * * * * * -------------------- * What is Majordomo? -------------------- From the fine Majordomo FAQ (found in Doc/FAQ), maintained by Dave Barr : Majordomo is a program which automates the management of Internet mailing lists. Commands are sent to Majordomo via electronic mail to handle all aspects of list maintenance. Once a list is set up, virtually all operations can be performed remotely, requiring no intervention upon the postmaster of the list site. Here's a short list of some of the features of Majordomo. * supports various types of lists, including moderated ones. * List options can be set easily through a configuration file, editable remotely. * Supports archival and remote retrieval of messages. * Supports digests. * Written in Perl, - easily customizable and expandable. * Modular in design. * Includes support for FTPMAIL. Majordomo is a "groupware" project. It has evolved from the initial code base done by Brent Chapman (brent@greatcircle.com), with further maintenance done by John Rouillard (rouilj@cs.umb.edu). The current Majordomo maintainer is Chan Wilson (cwilson@sgi.com). Along the way, it has picked up many features and additions from various authors. Because of this, and due to the initial design of Majordomo, certain features (archiving, digesting, and moderated lists) are currently done in a "non-optimum" fashion. In short, configuring Majordomo to do some of the advanced features can be confusing. This is a known problem and is being worked on. You'll need the following to use Majordomo: o Perl, version 4.036 or version 5.002 (or better) **NOTE** Future versions of Majordomo will *NOT* work with perl4. o a C compiler Other programs that might be useful are: o bulk_mailer: ftp://cs.utk.edu/pub/moore/bulk_mailer For large lists. * * * * * * * * * * * * * * The INSTALL file details how to install and configure Majordomo. Once you've installed Majordomo, the NEWLIST file describes how to add new lists under Majordomo control. * * * * * * * * * * * * * * The rest of this README file fills in background information on Majordomo, where to get help, find others using Majordomo, common problems, and some other bits: * Attributions * Mailing Lists/Support * More Documentation * The list configuration files * Common Problems * Error Messages * Using Digest and Archive * Other Programs * Tricks * Customizing the default list config values -------------- * Attributions -------------- Majordomo and digest were originally written by Brent Chapman, however he doesn't have the time currently to do more development on it. John Rouillard did a lot of work for configuration files and managed the releases for the 1.62 to 1.93 time frame. Chan Wilson (cwilson@sgi.com) is currently "release coordinator" for 1.94 and beyond. The FAQ was compiled by Vincent D. Skahan and is currently being maintained by David Barr . In addition to those above, the following people deserve recognition for their contributions in shaping Majordomo: Andrew Boyd Paul Close R. Gary Cutbill Hamilton Gilbert Jennifer Joy Alan Millar John C. Orthoefer Jerry Peek Paul Pomes Jason L Tibbitts III Dave Wolfe To anybody I left off the attributions list, my apologies. Let me know that I left you off, and I will make sure that you get mention in a future release. ----------------------- * Mailing Lists/Support ----------------------- There are four mailing lists about Majordomo on GreatCircle.com. The wise Majordomo-Owner is strongly advised to subscribe to Majordomo-Announce to learn of new versions and patches to Majordomo. This list is very low volume. People with questions about configuring, installing, or using Majordomo should subscribe to Majordomo-Users. People interesting in technical discussion of Majordomo, and developments on it, should join Majordomo-Workers. Majordomo-Users - for discussions on using Majordomo Majordomo-Announce - for announcements of new releases Majordomo-Workers - for people interested in development of Majordomo. Majordomo-Docs - for people interested in development of documentation for Majordomo. To subscribe to any of the lists above, send an appropriate "subscribe" command to "Majordomo@GreatCircle.COM". -------------------- * More Documentation -------------------- The 'Doc' directory contains the FAQ (Frequently Asked Questions), which should answer most of your questions. In the 'Doc/man' directory, you'll find manual pages for approve, bounce, bounce-remind, digest, resend, and majordomo. For your list-managers, the file Doc/list-owner-info contains some good information. It can be sent to them and should be enough information to get them started using majordomo. You'll want to update it for your site-specific needs. 'Doc/majordomo.ora' contains the chapter about Majordomo from the Nutshell Handbook "Managing Internet Information Services," written by Jerry Peek. The chapter is (c) Copyright 1994 by O'Reilly & Associates, Inc., and was included in the Majordomo distribution by permission of the publisher. While this chapter is a good introduction to setting up the majordomo software, it is a tad out of date, since it covers version 1.62. :-( Jerry is in the process of updating this for 1.94.3, and an updated version will hopefully be included in future releases. The original LISA 6 (Oct 1992, Long Beach, CA) paper describing Majordomo is at Doc/majordomo.lisa6.ps. PLEASE NOTE that it is useful only for getting a feel for majordomo. It should not be used as an installation document. You did read the FAQ, didn't you? ------------------------------ * The list configuration files ------------------------------ Each list has a configuration file associated with it, .config. If a list does not have it's .config file, issue a 'lists' command to Majordomo -- it'll create one for you. Ideally, the config file is meant to be self-documenting, but at the moment it can be overwhelming to a novice user. This will be fixed in a future release. The best way to learn about the configuration file is to issue a 'config ' to Majordomo, and carefully read through the results. Also read the Doc/list-owner-info file, which explains some of the more commonly tweaked variables. In addition to the .config file, there are .info and .intro files that hold informative and introduction information about the list. These files are best changed via Majordomo's 'newinfo' and 'newintro' commands. The file .intro contains the "intro" text for the list, which is sent in response to "intro" and successful "subscribe" commands. The file .info contains the "info" text for the list, which is sent in response to "info"; it's also sent after a "subscribe" command if no "intro" file exists. In a future version of majordomo, the option will be provided to keep the info in the config file rather than using an external file. However, the external file is useful if you are serving up the info information by some means other than majordomo (e.g. Web, finger, ftp). ------------------------------- * Common Problems and Debugging ------------------------------- Nearly all the install problems are now caught by the 'config-test' script that one runs after the install. What is left, then, is primarily incorrect usage caused by configuring the aliases improperly, and changing the ownership of Majordomo files after it is up and running. If you're still stuck, it's easy to turn some debugging on. If all else fails, the mailing lists mentioned above are a good place to ask for help. ** Insecure Usage If you get complaints about "insecure usage" from "wrapper", then you're probably invoking it incorrectly. The first argument to "wrapper" should be the simple filename of the program in the W_BIN directory (defined in the Makefile) that you want to run. You should NOT specify the full path name to the program; as a security measure, to keep people from being able to run anything they want with the setuid/setgid permissions of "wrapper" "wrapper" will ONLY run programs from the W_BIN directory. If what "wrapper" is told to run contains a "/", it assumes somebody is trying to make it run something from somewhere else, and complains about "insecure usage". For example, the right way to use wrapper is in something like this: majordomo: "|/usr/local/majordomo/wrapper majordomo" The WRONG way is "|/usr/local/majordomo/wrapper /usr/local/majordomo/majordomo" ** Permissions Make sure you've got all the permissions right. In particular, you need to watch for permissions of DIRECTORIES files are in, as well as permissions on the files themselves. Almost any time Majordomo tries to read a file, and every time it tries to write one, it tries to create a lock file in the same directory as the file. If it can't create that lock file for any reason (because the directory permissions won't allow it, or because a lock already exists for that file), Majordomo waits between 1 and 10 seconds (chosen randomly) and then tries again; it keeps trying for (by default) 5 minutes. If Majordomo isn't working for you, and takes some multiple of 5 minutes to fail, you've almost certainly got a permission problem; check the Majordomo log file. If there's nothing in the log file, then you've got a permission problem with the log file and/or the directory it's in. ---------------- ** Debugging If messages to a particular list are getting mangled, perhaps due to custom headers, footers, or something else, try defining the 'debug' variable for the list. This will cause resend (the Majordomo program that sends the message out to the list) to *not* send the message out, but leave it in $TMPDIR/resend..out. You can then examine the message contents. If you suspect something deeper is amiss, then put '$DEBUG = 1;' in your majordomo.cf. This causes Majordomo and resend to spew debug messages to $TMPDIR/majordomo.debug and $TMPDIR/resend.debug, respectively, but operate as normally. If you invoke your mailer in verbose mode ('Mail -v' or 'mail -v' will hopefully do this) then debug output will get sent to your terminal instead of the files. Finally, if you're up to mucking around in the perl code, symlinking perl into ~majordomo and invoking it via wrapper will give you a debug environment with Majordomo's permissions and view of the world: ~majordomo% ./wrapper perl -d majordomo Now set breakpoints, type 'continue', give it a valid email header and the desired Majordomo command. The only header that you need is a valid "reply-to" field. The rest is up to you. * Error Messages ---------------- Majordomo now catches most of problems that plagued earlier versions; disk space shortages, permissions problems, other resource problems. When at all possible, a comprehensible email is sent to the Majordomo-Owner, who should be able to fix things. List-specific problems are usually sent to the list-owner. Before attempting to track down errors and checking debug logs, be certain that running "wrapper config-test" as a normal user reports no problems. The config-test code will detect most common causes of errors. Here's most of the error messages that Majordomo will return, and an explanation of why they might be seen: MAJORDOMO ABORT - This error occurs anytime some anomaly occurs during the majordomo run. It causes majordomo to send an error message to the majordomo owner, and exit immediately. No further commands in the input message are processed. Mail is sent to the originator of the message that caused the abort consisting of the output from all command in the message that had succeeded before the abort. The types of errors that cause an abort are shown below. Hostile Address -- somebody submitted an address that majordomo deemed to be a potential security problem. Some mailers will execute any command line appearing after a vertical bar, and will use addresses beginning with a dash as an option instead of an address. In addition, if the addresses matches an existing file, the mailer may attempt to overwrite it. For these reasons, majordomo will refuse to process such addresses. Majordomo will do additional checks on messages containing '/' characters to verify that they are correct X400 addresses; these checks may be disabled in majordomo.cf. (See $no_true_x400 and $no_x400at.) Non-domained Address -- an address was submitted that was of the form user@host without a fully qualified domain name. Addresses of this form are usually caused by either confused users or improperly configured mail transfer agents. If your host is generating them, it is misconfigured. Can't open/append/read -- for some reason majordomo can't open/append/read a to a file that it was supposed to be able to access. Usually this is caused by improper permissions. chmod(, link(, operation not permitted -- the corresponding chmod or link operation failed when it shouldn't have. Usually this is caused by improper permissions, most often on the wrapper. Make certain that it is installed setuid, and that "wrapper config-test" run as a normal user (not root or the majordomo user) reports no problems. Can't invoke -- the program majordomo wanted to invoke to send mail couldn't be invoked. This error is usually only seen when you are tracing the SMTP connection using /usr/ucb/Mail -v. Can't connect to sendmail -- for some reason the attempt to run sendmail in the function resend_sendmail in the resend program failed. mailer not executable -- either the configured mailer did not exist or could not be run; make certain that config-test reports that the mailer is properly accessible. Bugs in previous versions caused errors of the form "mailer -fMajordomo-Owner not executable." These bugs should be fixed; please report any occurrences of this type of error just in case the bugs persist. mailer exited unexpectedly with error XX -- it is expected that the mailer will return a zero exit code upon success, so any nonzero code is reported as an error. The mail may or may not have been properly sent to your list. To track down the source of this error, first inspect the debug logs (see Debugging below) to see if the mailer emitted any diagnostics. Failing that, consult your mailer's documentation for the meaning of the exit status, or if you use Sendmail, consult the chart below for some of the more common errors: 64 - EX_USAGE - Sendmail uses this to indicate a command line usage error, but it also uses it to report a general error condition. Some versions of Sendmail do this somewhat unpredictably and for this reason the '-oee' flag has been added to the default mailer definitions. This flag should prevent these errors for versions of Sendmail that support it. 67 - EX_NOUSER - The alias that is used to send out list mail (which is passed as the last argument on resend's command line) does not exist. Make certain that there are no typographical errors in your alias file, and that the file has been properly rebuilt. 69 through 74, 77 - These are generally serious errors that are caused by either lack of resources or improper configuration of Sendmail. You should consult the Sendmail documentation. unknown mailer error XX - This can be caused by a number of things all relating to the wrappers inability to execute the perl script. This can include: the perl script is not executable the location of the perl program specified with the #! line is incorrect the location where the wrapper looks for the perl scripts is not the location where the scripts are located. The current wrapper doesn't use the standard sendmail error codes, hence the "unknown mailer error" annotation in the error message. A future wrapper version will use the appropriate errors from sysexits.h. -------------------------- * Using Digest and Archive -------------------------- Digesting and Archiving will be integrated into Majordomo soon. In the meantime, they require setting up additional aliases and configuring a few other things. For digests, read the README.digest and quick-digest-setup files in the Doc subdirectory, as well as the manual page in Doc/man For archiving, there are three archive programs available. The best one to use is called archive2.pl, and it is present in the main Majordomo directory. (If you'd like to use one of the other archivers, be sure to move it to, or make a link to it in, the main directory.) Comments at the top of the file explain all the options available, and here's a brief extract that details what most people want: # A sample /etc/aliases file entry to use "archive" add each incoming message # to a "my-list.YYMM" file in the "/usr/local/mail/lists/my-list.archive" # directory: # # my-list-archive: "|/usr/local/mail/majordomo/wrapper archive2.pl # -f /usr/local/mail/lists/my-list.archive/my-list # -m -a" ---------------- * Other Programs ---------------- The "bounce-remind" script should be run out of cron using a line similar to: 10 2 * * * /tools/majordomo/wrappers/bblisa/wrapper bounce-remind This sends mail to all of the people on the bounces list to warn them that they are no longer on the lists they thought they were on. The "medit" program is used to hand edit the mailing list files, but it locks the files first so that majordomo won't touch them while you are editing them. You may need to edit this program and change the location of the majordomo.cf file if the majordomo.cf file is not accessible as /etc/majordomo.cf). The "new-list" is used when starting a new list. Often there is a flood of mail when a list starts up. If you wish to allow a grace period for people to subscribe before actually putting the list "on-line", the new-list script can be put at the list address, and it will notify people that the list is not yet open for business. The "request-answer" program attached to the "-request" address for the list sends back a recording telling folks how to use the Majordomo address for their requests, or how to contact a human if they really need to. You can use majordomo with the -l option to sit at the -request address instead of using request-answer if you like. The "approve" program is intended to be used by a mailing list administrator to approve messages send by majordomo or resend. The "bounce" program removes an address from an active majordomo list, and subscribes it to the bounces list. This is used when mail to the address starts bouncing. -------- * Tricks -------- This section has a few tricks when using majordomo and resend. 1) How do I maintain the restrict_post file for resend? The easiest way is to create a pseudo list in majordomo. The file that contains this list if the file name used for the -I flag to resend. For example the filename "-can_post" can be created in the majordomo mailing lists directory. This list should be unadvertised and closed. Don't bother creating any sendmail aliases for it. This allows people to be added to or removed from the list using majordomo commands. 2) How can I have more than one moderator/owner for a list? Again majordomo is your friend. Create a mailing list called "-owner". Again create it nonadvertised and closed. Set up the appropriate aliases for the list: owner-listname::include:/usr/local/Lists/-owner listname-owner:owner-listname owner-owner-listname: owner-majordomo and you are done. 3) I run smail. How do I set up majordomo to work in this environment? Just set $sendmail_command to /bin/smail in your majordomo.cf. It has been reported that by default smail does not understand the :include: syntax, and that can be fixed by adding the following to /etc/smail/directors: aliasinclude: driver=aliasinclude, nobody; copysecure, copyowners, (Thanks to Steve Casey for this information.) ------------------------------------------------ * Customizing the default list config values ------------------------------------------------ The default values of the list configuration files are taken from the file 'config_parse.pl' in the associative array %known_keys. It's best to read the above section _The list configuration files_ and the Doc/list-owner-info file, as well as carefully reading an existing list configuration before continuing. If you want to change the defaults, change the values assigned to each keyword. There is some documentation in the config_parse.pl file. The config_parse.pl file is also a man page describing the programmatic interface to the config file parser and some other details about the config file parser. Paul Pomes p-pomes@uiuc.edu suggests the following as replacements for the message_fronter and message_footer default values. I haven't tested them, but they may be useful: 'message_fronter', '#! local($TEMP) = $list; if ( $list =~ /-digest$/ ) { $TEMP =~ s/-digest$//; "In this issue:\n\n\t_SUBJECTS_\n\nSee the end of the digest for information on subscribing to the $TEMP\nor $TEMP-digest mailing lists.\n"; } else { ""; }', 'message_footer', '#! local($TEMP) = $list; if ( $list =~ /-digest$/ ) { $TEMP =~ s/-digest$//; "To subscribe to $TEMP-digest, send the command:\n\n\t subscribe $TEMP-digest\n\nin the body of a message to \"Majordomo@ Majordomo.cso.uiuc.edu\". If you want\nto subscribe something other than the account the mail is coming from,\nsuch as a local redistribution list, then append that address to the\n\"subscribe\" command; for example, to subscribe \"local-$TEMP\":\n\n\tsubscribe $TEMP-digest local-$TEMP@your.domain.net\n\nA non-digest (direct mail) version of this list is also available; to\nsubscribe to that instead, replace all instances of \"$TEMP-digest\"\nin the commands above with \"$TEMP\"."; } else { ""; }', Note that the strings are all one line long. I have wrapped and broken them here for ease of viewing. --------------------