Frequently Asked Questions for MailMan version 2.0

Last-modified: Thursday, July 23, 1998

------------------------------

------------------------------

Subject: 2.1) Table of Contents

------------------------------

Subject: 3.1) Overview

This section provides an overview of the basic top-level questions about what MailMan is and what it does.

------------------------------

MailMan is a system that provides any user with an interface to his or her own email account from any web browser anywhere in the world. MailMan is a piece of software that runs on a web server as a part of an existing web site that interacts with a mail server and displays the results through the web server.

------------------------------

A MailMan installation could support a free email advertisement site. A different installation of MailMan could provide essential email access for the students at a small community college or the students at a large university. A different installation of MailMan could allow the users of a neighborhood ISP to access their local email accounts through the web without configuring a mail reader. A different installation of MailMan could provide access to any email address anywhere in the world for the patrons of a cyber café. Another installation might allow business workers to stay in touch while away from their desks, even while at a pay kiosk in an airport or at a borrowed workstation at another corporation. Another installation might allow a family to keep in touch with friends through Grandma’s WebTV box while visiting for Christmas. There are other uses for MailMan that we have not even thought of yet. If you think of others, please let us know.

------------------------------

We designed MailMan with applications such as standalone kiosks in mind. The only caveat that we would mention is that when you design an interactive kiosk, privacy issues become a big concern. You do not want a user to be able to walk up to a kiosk and see the mail that a previous user was reading. To this end, please be very careful in the selection of an appropriate web browser for kiosk applications. Specifically, please note that the Microsoft Internet Explorer (all known versions 1.0 through 4.01, as of this writing) does not conform to accepted Internet standards for the expiration of web pages from page caches (the "Expires:" HTTP response header, see RFC 1945 for more details on this directive). The Microsoft Internet Explorer also does not conform to accepted Internet standards for directing a browser to not cache web pages in the first place (the "Cache-control:" response header, see RFC 2068 for more details on this directive). Because of these non-conformance issues, Endymion strongly recommends against using any version of the Microsoft Internet Explorer for kiosk applications involving MailMan. Netscape Navigator, Opera, and many other popular web browsers properly conform to Internet communications protocol standards and are very well suited for kiosk applications.

------------------------------

Free Internet mail services such as the ones mentioned above provide the same basic services that MailMan does, but they provide them through a proprietary web site, generally with the purpose of selling advertisements to a guaranteed repeat audience. Free email sites provide the user with a mailbox and the server to access the mailbox. MailMan is different because it is simply a piece of software, a technology to be applied in any number of ways. MailMan works in conjunction with other mail servers in order to process incoming and outgoing mail, communicating with those servers though well-accepted Internet standards such as the POP3 and STMP protocols. The primary advantage of MailMan is that administrators can control their own MailMan installations. They have the power to specify what mail servers MailMan connects to, what MailMan looks like when it runs, who has access to MailMan, etc. When you use MailMan, you are accessing the same email account that you normally access, not a new account that was created just for you to access through a free email service. Some free email services allow you to access your own email address through the service, but you are still forced into using someone else’s web server and you are forced into watching someone else’s advertisements. With MailMan you have much more control.

------------------------------

------------------------------

The heart of MailMan is a CGI application written in Perl, version 5. The mail application generates MailMan’s user interface dynamically by reading template files filled with HTML code, processing them, and producing output for the user through a web server. To obtain useful email information, MailMan obtains a user’s email account authentication information directly from the user (a username, password and server name) and communicates with the user’s POP3 email server the way that any client-side mail software ordinarily would. The user sees a list of messages and can select messages for viewing, deletion, and other normal mail tasks. If a user wishes to reply to a message, forward a message, or create a new message, MailMan communicates with an SMTP mail server to send the outgoing message the way that any ordinary client-side software would.

------------------------------

The current version of MailMan supports a frames-based interface that provides the user with a message list in a top frame and individual messages in the bottom frame. This feature makes browsing your mail through a web interface very simple and stress-free and eliminates some of the lag issues that are normally associated with web-based email. No other web-based email system that we know of supports this type of sophisticated interface.

MailMan can receive message attachments through any web browser. Message attachments can be MIME encoded using either Base64 or Quoted-Printable encoding, or they can be simple Uuencoded binaries. If you are using a browser that supports file uploading (Netscape 2.0 and above and Microsoft's Internet Explorer 4.0 and above, as of this writing) then you can also send message attachments.

------------------------------

One of the primary benefits of MailMan is that the entire interface that is presented to the user is the result of a collection of template files that contain ordinary HTML. These templates can be modified to incorporate specific branding of any web site as long as they still contain certain vital keywords that allow MailMan to insert valuable information.

------------------------------

The standard edition of MailMan is more of a 'viewer' for a POP3 server than a complete mailer. It does not store any user information on the server side. It does not store messages anywhere, so the only messages that you see are the messages that are actually on the POP3 server at that time. The professional edition stores messages on the server side after they have been fetched from the POP3 server, allowing you to organize them into a folder hierarchy like you might in Eudora or whatever mail program you ordinarily use. The professional edition also stores user settings on the server side, allowing users to configure options such as a default SMTP server or a signature message to append to outgoing messages. The standard edition is a version that we intend for use by users as a secondary mail system that will compliment an existing client-side mail package, the professional edition is intended for use by novice users as a primary mailer. Experienced users will probably not be happy with any version of MailMan as a primary mailer, just like they would not use HotMail or ExciteMail for a primary mailer.

Another difference, on a more practical level, is that the professional edition is not yet complete, and won't even go beta for at least two or three weeks. (This was written on Monday, July 20, 1998, at the official release of MailMan 2.0 Standard)

------------------------------

In order to make use of MailMan you must have a functioning web server that has the ability to run Perl CGI applications. To read incoming mail you must have access to a functioning POP3 mail server and to send outgoing messages you must have access to a functioning STMP mail server. These are all very common Internet standards and you probably have access to the necessary mail servers if you have an Internet email account.

For the generation of HTTP headers, MailMan conforms as closely as possible with the proposed standard RFC 2068, "Hypertext Transfer Protocol -- HTTP/1.1", as well as the earlier related specifications such as RFC 1945, "Hypertext Transfer Protocol -- HTTP/1.0."

MailMan's user interface is generated using messages that comply as closely as possible with RFC 1866, "HyperText Markup Language Specification - 2.0" and related specifications.

Persistent state information for the frames-based MailMan interface is maintained according to RFC 2109, "HTTP State Management Mechanism".

For communication with incoming internet email servers, MailMan conforms as closely as possible with RFC 1939, "Post Office Protocol - Version 3", and was originally based on the earlier specification, RFC 1725. MailMan is in strict compliance with end of line delimiters specified in the POP3 standards documents and should be compatible with POP3 servers regardless of the end of line delimiter used in the server's host operating system.

For communication with outgoing internet email servers, MailMan conforms as closely as possible with RFC 821, "Simple Mail Transfer Protocol". MailMan does not make use of enhancements provided by later approved extension standards such as RFC 1869 or RFC 1870.

The messages that MailMan processes and generates are compliant as closely as possible with RFC 822, "Standard for the format of ARPA Internet text messages". Formatted messages and messages with attachments are automatically handled by portions of MailMan that are compliant as closely as possible with the specifications in RFC 2045, RFC 2046, RFC 2047, RFC 2048 and RFC 2049, "Multipurpose Internet Mail Extensions (MIME)", parts one through five.

------------------------------

Subject: 4.1) Licensing

------------------------------

No, MailMan is not free. An employee of Endymion Corporation originally started MailMan as a spare time project in 1996. The first version of MailMan was released through the Endymion Corporation web site in 1997 under the GNU Public License, in the hope that people would find the software valuable and contribute to its development. In the time since then, many people have downloaded MailMan and used the application and some have even contributed suggestions and bug fixes, but nobody has undertaken further development. Since MailMan has survived the test of time, Endymion Corporation has decided to pronounce MailMan an official, supported product. We have invested the time and resources in developing MailMan version 2.0, a vast improvement over the original freeware incarnation of MailMan, and we are offering it for license.

Now for the exceptions. Endymion Corporation automatically grants a license for free to installations of MailMan that meet one of the following criteria:

1. Educational Institutions, including government, private, and non-profit institutions. In situations where the nature of your institution is disputed, Endymion Corporation reserves the right to require a copy of your 501(c)(3) form or a local equivalent before granting a license.
2. Non-profit institutions, including religious institutions, but with the specific exception of the Church of Scientology International or any other organizations directly related to the Church of Scientology. Endymion Corporation reserves the right to require a United States federal non-profit tax ID number or a local equivalent before granting a license.
3. Private individuals or families.

All installations of MailMan that do not clearly fit into one of the three clearly-defined categories above must be licensed. So that there is no confusion, installations of MailMan that must be licensed include, but are not limited to, the following examples:

• Internet café mail kiosks
• Large ISPs
• Small-town ISPs
• Free Internet email services
• Corporate messaging applications

------------------------------

MailMan began life as a GPL product. Because of our desire to help to move the world forward just a little bit at a time by sharing our efforts with others and because of a general sense of honesty and openness, we originally made the source code for MailMan available to the world under the same non-commercial license that allowed you to install and use MailMan. Unfortunately, we were almost immediately (less than a week after the release) bitten by pirates. Apparently there are people out there that are unable or too lazy to develop something like MailMan by themselves, so they just removed the "Endymion Corporation" headers from the source code and started trying to sell MailMan as their own product. Because of these pirates and other abuses we are making the true MailMan source code available only to licensees. This does not preclude non-profit organizations from obtaining the MailMan source for modification. If you represent a verifiable non-profit organization and you are interested in obtaining the MailMan source code, just contact mailman@endymion.com for information about obtaining the source code through your non-commercial license. The final effect of our closing the source code is actually very small. Organizations that have a legitimate need for the source code for examination or modification need to license MailMan anyway, and we continue to make the source available to verifiable non-profits.

------------------------------

------------------------------

We’re not. Our intent is to provide MailMan for free to private individuals and to organizations that are acting selflessly and could use the applications but might not be able to budget for it. For-profit organizations foot the bill in our little Robin Hood game. We don’t think that this is too much to ask, since the bill that we’re talking about is miniscule. The Church of Scientology does not fit into our definition of ‘an organization that acts selflessly and might not be able to pay for a license’. We have nothing nasty to say about Scientology or the Church of Scientology other than that. To each his own.

------------------------------

Subject: 5.1) Installation

This section describes how to install MailMan.

------------------------------

There are two different distributions of each edition of MailMan version 2.0, a Unix distribution and an NT distribution. In reality either distribution should work on any server, but we have found it to be more convenient for our users to package the application in a way that is more targeted to the final platform. The primary difference between the two distributions is that the files in the NT distribution have been processed so that the lines in the mail MailMan source file end with a CRLF, while the lines in the same file in the Unix distribution are terminated with a simple LF. If you don’t know what that means, don’t worry about it, it’s really not that important usually. Another difference is that the main MailMan source file in the Unix distribution is called "mm<something>.cgi", while the same file in the NT distribution is called "mm<something>.pl". We have found that this arrangement reduces confusion in most cases. If you disagree about our file naming conventions you are perfectly welcome to rename the files to whatever you want.

------------------------------

I have described the steps in this item in more detail in the OS-specific items below, this item provides an overview of the process.

1. Unpack your distribution
2. Copy the distribution to the location on your web server where it will be installed, "/public_html/mailman/" for example. Make sure that the following files are present:
   "mmstdo.cgi" or "mmstdo.pl" (it comes under different names), "cgi-lib.pl", all of the "i_*.gif" files, and all of the "t_*.htm" files.
3. Make sure that your copy of "mmstdo.cgi" or "mmstdo.pl" is executable, and is executable by your web server. If you don’t know how to do this, consult an expert on your operating system and web server.

------------------------------

This item provides a more detailed explanation of the above procedure for Unix systems. Before you install MailMan, make sure that you have Perl 5 installed. On most Unix systems, especially web hosting systems, Perl will already be installed. If Perl is not installed, or if Perl version 5 is not installed, consult your system administrator.

1. Copy the distribution to the location that you want to unpack it in. "/public_html/mailman/" in the above example.
2. Unpack the distribution with tar. On most systems you can type "tar –zxvf <distribution>.tgz" and your system will expand the file. You should now have a collection of "i_*.gif" files, "t_*.htm" files, "mmstdo.cgi", "cgi-lib.pl", and some documentation (this document, in particular). On systems where that doesn’t work, try "gnutar –zxvf <distribution>.tgz". If that doesn’t work, you will have to manually unzip the file with "gunzip" and then untar the file with "tar –xvf <distribution>.tar". If all else fails, fetch the NT distribution and unzip it.
3. Make sure that your copy of "mmstdo.cgi" is executable by issuing the command "chmod 755 mmstdo.cgi" Your copy of "cgi-lib.pl" must also be executable. "chmod 755 cgi-lib.pl". Also, just to be sure, make sure that your "t_*.htm" and "i_*.gif" files are marked so that the web server process can read them. Sometimes you can read your own files, but you inadvertently have your files set so that your web server can’t access them. These are the same rules that you should be following when you publish ordinary web content. "chmod 644 i_*.gif t_*.htm" should do the trick.
4. Make sure that the first line of the "mmstdo.cgi" file refers to the correct location of your Perl interpreter. Be warned that it probably does not. You can find out where your Perl interpreter is located on most Unix systems by typing "where perl" on the command line. Some system administrators keep Perl 4 and Perl 5 both installed at the same time, with "perl" referring to Perl 4 and "Perl" or "perl5" referring to Perl 5. If your system operates this way, make sure that you are referring to the correct location of Perl 5. MailMan will not operate with Perl 4.

------------------------------

1. Copy the distribution to the location that you want to unpack it in. "/public_html/mailman/" in the above example.
2. Unpack the distribution with your favorite unzip utility.
3. If you are using IIS, make sure that the directory where your MailMan installation resides is marked executable in the IIS administration interface. Also make sure that your "mmstd.pl" file ends in an extension that will be recognized by your system as a Perl 5 script. Most of the time "mmstd.pl" will do the trick, but your installation of Perl 5 may be different.

NT systems seem to be very, very resistent to running Perl scripts without serious hassle, and NT administrators are generally unfamiliar with dealing with this sort of thing, so we have provided a few more tips for NT installations that we have developed over time:

On some NT systems, when you try to run MailMan you are presented with completely un-helpful error messages like 'The script misbehaved by producing no output' and things like that. We have worked out a simple process to get the system up and running that starts out by running the script alone, without going through CGI, then slowly builds up to running through CGI through the server:

1) To test that the script itself is working okay under simple conditions:

Switch to the directory that MailMan is installed in via the command line, DOS prompt, whatever you want to call it. Do 'C:', then 'cd inetpub\wwwroot\mailman', then do 'perl mmstd.pl', or 'c:\perl5\bin\perl mmstd.pl', or whatever. You should see a bunch of HTML code for the login page, if that works okay then your script is fine. Otherwise, that's where you have problems.

2) To test that the script has the path information set up correctly so that it will run even when IIS screws up the 'current directory' when it runs, do this:

Switch to some other directory, say the root of the C: drive. Run MailMan, something like 'perl inetpub\wwwroot\mmstd.pl'. If the path information is correctly set up, it should still be able to find the 'cgi-lib.pl' library and it should still be able to locate the template for the login page. Otherwise that's where you have problems.

3) Now try to get it working through CGI, if the above two tests work then we're not sure why this might break, but under NT anything is possible.

------------------------------

------------------------------

The most likely cause of an error complaining about not being able to find "cgi-lib.pl" is that MailMan is ‘lost’. This happens when your server runs your CGI applications with a current directory other than the actual directory that the application is located in. If your MailMan installation is in "/public_html/mailman/mmstdo.cgi" for instance, your server might instantiate MailMan with "/public_html/mailman/mmstdo.cgi" as the current directory, in which case everybody is happy. It also might instantiate MailMan with "/usr/local/somedir/" as the current directory, in which case MailMan has no way of locating its own templates and dependencies. Luckily, there is a simple fix for this. At the top of the "mmstdo.cgi" file (or whatever your file happens to be called) there is a line that allows you to manually set the variable "$strLocalScriptLocation" to an absolute path that describes the location of your MailMan installation. In the above example you would set "$strLocalScriptLocation" to "/public_html/mailman/", letting MailMan know where it should look for dependencies and templates. Note that "$strLocalLocationScript" must be a complete directory name, with an absolute root and the terminating "/" or "\" character, depending on your operating system and file system. If you have problems with this, you will probably also have problems finding your templates once MailMan is running, so you should probably start out by setting "$strLocalTemplateLocation", which will automatically (by default) set "$strLocalScriptLocation" as well.

------------------------------

Subject: 6.1) Operation

This section describes how to work MailMan from a user’s point of view.

This section is still incomplete, sorry, check back after the MailMan public beta is over for a more current copy of this document with more useful information for this section.

------------------------------

We wish that there were other sources that we could reference that could explain the basics of using several different mailers at once. Unfortunately we don't know of any. If you know of any good write-ups with suggestions for novice users on this subject please let us know.

The key issue involved is configuring your mailer to leave its messages on the Internet mail server after it has downloaded them. If you receive a message from your boss on your computer at work and you decide that you would really rather go home and reply to the message after dinner, you can't do that if your mailer at work deletes the message from the server after it checks the message. If you set your mailer at work to not delete the message from the server, when you get home and check your mail, the message will still be there waiting for you to reply to it. Using MailMan in conjunction with other mailers is no different. All that you need to do is configure all of your mailers to leave messages on the mail server by default, and perhaps select one mailer as your 'official' mailer that is allowed to delete your messages. Most quality mail clients have options to leave messages on the server but delete them after a set number of days have passed. This option is extremely helpful when using many different mail clients to access the same mailbox.

------------------------------

------------------------------

Most well configured SMTP servers will not allow a user from outside of their own local domain to send a message to users that are also outside of that domain. You can send a message in from outside, or out from inside, but you can't send a message to your buddy at IBM through the MindSpring SMTP servers if you are, say, at AOL. This is to prevent spammers from abusing SMTP servers. This will happen if you are using a MailMan installation at a different location than your SMTP server. The easiest way to solve this problem would be to configure MailMan to use an SMTP server that will grant permission to the HTTP server machine that MailMan is installed on to send messages. You can also provide a default name for a server that is known to allow messages from the HTTP server machine.

------------------------------

Subject: 7.1) Innards

This section describes the inner working of MailMan for installation administrators that want to customize their installations.

This section is still incomplete, sorry, check back after the MailMan public beta is over for a more current copy of this document with more useful information for this section.

------------------------------

All of MailMan's output is defined by a collection of HTML templates. The templates are the ".htm" files that begin with "t_" in your distribution. We have provided a sample look and feel for MailMan that you are welcome to use for as long as you like. When you begin the customization process, simply open the templates in any HTML editor and make your modifications. Remember that the behavior of MailMan is dictated by hidden fields contained within the HTML templates, so make sure that you go slowly and check your results often, as it may be possible to 'break' your installation by accidentally deleting or modifying important keywords. We hope to provide more detailed information on what MailMan's keywords are and what they mean in this document at a later date.

------------------------------

Yes. The POP3 server used is referred to in the HTML templates by the substitution keyword "SERVER". Hunt down everywhere that MailMan allows the user to supply this value through a form field. The only place where this should happen is in the template "t_login.htm". Find this

form field:

<input type="text" name="SERVER" size="30">

And replace it with:

<input type="text" name="SERVER" size="30" value="popserver.mydomain.com">

The box will now be filled in by default for the user when they log on, but experienced users will still be able to aim MailMan at specific servers.

The SMTP server used by MailMan is specified by the keyword "OUTGOING". Change the form fields that set the "OUTGOING" keyword in both "t_f_messageform.htm" and "t_nf_messageform.htm" in order to rig the outgoing SMTP server to something specific.

------------------------------

------------------------------