_ _ ____ _ ____ ____ ___ ____ _ _ ____ |\/| |__| | | | |__/ | \ | | |\/| | | | | | | _| |__| | \ |__/ |__| | | |__| Majordomo, noun: a person who speaks, makes arrangements, or takes charge for another. From Latin "major domus" - "master of the house". Release 1.94 README -------------------------------------------------------------------------- -> Current users of Majordomo whom are upgrading will want to <- -> read the Changelog for details on what has changed between <- -> versions of Majordomo. <- -> In particular, NOTE THE CHANGES TO THE CONFIGURATION FILE. <- -> Several new variables have been added to sample.cf, so check <- -> it out and merge your existing majordomo.cf with the supplied <- -> sample.cf. Running the 'config-test' script after upgrading <- -> will point out the variables you need to add. <- Release 1.94 of Majordomo is primarily a bugfix release, incorporating changes that are hopefully "low risk" to provide a stable foundation while the next generation of Majordomo is being written (See the FUTURE file for details on this.) * * * * * * * * * * * * * * If you know what Majordomo is and simply want install it, read the INSTALL file. Browse through this file, thou, 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 maintainance. 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 timeframe. 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 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, digest, 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, and it will hopefully be included in the final 1.94 release. 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 get fixed after the 1.94 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 1 second and then tries again; it keeps trying for 10 minutes. If Majordomo isn't working for you, and takes some multiple of 10 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. 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 had characters not usually found in valid internet email addresses. These characters are the forward slash "/" and the vertical bar "|". These characters can be used to try to write files on the majordomo host or execute programs on that host. The check is done in valid_addr in the file majordomo.pl. This check does cause problems for X.400 addresses since they have "/" delimited components. If anybody has any bright ideas about how to differentiate between a filename attempt, and a valid X.400 address, Majordomo-workers would like to hear from you. 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( -- the corresponding chmod or link operation failed when it shouldn't have. Usually this is caused by improper permissions. 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. 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 file in the Doc subdirectory, as well as the manual page in Doc/man For archiving, there are three archive programs available, all found in the Tools subdirectory. The best one to use is called archive2.pl. 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 -I 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 unadvertized 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) When using the lists command and the noadvertise pattern /.*/ the list is still listed. Why? This is a feature. If you are subscribed to the list, the list is always shown since it doesn't make any sense to not show it since you already know it is there by virtue of being subscribed to it. If you wish to disable this feature, you must edit the majordomo script itself. Remove the statement around line 890 that reads: $result = &is_list_member($reply_to, $listdir, $list) if ! $result; 4) I'm a uucp site, and 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. ------------------------------------------------ * 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 programatic 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. --------------------