New Mailman 2.0 documentation. Uses ht2html site generator, with the

MMGenerator style.  The ht2html tool isn't included here, but it's
available from

	http://www.wooz.org/users/barry/software/pyware.html

It's not completely filled in, but it's better than it was!

Note that we're checking in both the templates and the generated html
files, so distros contain the final documentation.

1 files changed, 170 insertions, 0 deletions

diff --git a/admin/www/faq.ht b/admin/www/faq.ht
new file mode 100644
index 000000000..058b20f10
--- /dev/null
+++ b/admin/www/faq.ht
@@ -0,0 +1,170 @@
+Title: Mailman Frequently Asked Questions
+
+ <h3>Mailman Frequently Asked Questions</h3>
+
+<b> Q. How do you spell this program?
+
+</b><br> A. You spell it "Mailman", with a leading capital "M" and a lowercase
+   second "m".  It is incorrect to spell it "MailMan" (i.e. you should
+   not use StudlyCaps).
+<p> <b> Q. What if I get "document contains no data" from the web server, or
+   mail isn't getting delivered, or I see "Premature end of script
+   headers" or "Mailman CGI error!!!"
+
+</b><br> A. The most likely cause of this is that the GID that is compiled into
+   the C wrappers does not match the GID that your Web server invokes
+   CGI scripts with.  Note that a similar error could occur if your
+   mail system invokes filter programs under a GID that does not match
+   the one compiled into the C mail wrapper.
+<p>    To fix this you will need to re-configure Mailman using the
+   --with-cgi-gid and --with-mail-gid options.  See the INSTALL file
+   for details.
+<p>    These errors are logged to syslog and they do not show up in the
+   Mailman log files.  Problems with the CGI wrapper do get reported
+   in the Web browser though, and include the expected GID, so that
+   should help a lot.
+<p>    You may want to have syslog running and configured to log the
+   mail.error log class somewhere; on Solaris systems, the line
+<p>        mail.debug                /var/log/syslog
+<p>    causes the messages to go to them in /var/log/syslog, for example.
+   (The distributed syslog.conf forwards the message to the loghost,
+   when present.  See the syslog man page for more details.)
+<p>    If your system is set like this, and you get a failure trying to
+   visit the mailman/listinfo web page, and it's due to a UID or GID
+   mismatch, then you should get an entry at the end of
+   /var/log/syslog identifying the expected and received values.
+<p> <b> Q. Why do my web pages hang?
+
+</b><br> A. CERN Web servers might leave Python processes running, and in some
+   cases might hang the CGI completely.  In that case, switch to
+   Apache.
+<p>    It is also possible that you have stale locks.  Mailman tries to
+   be very careful about the lock files it creates to ensure the
+   integrity of its databases, but sometimes system faults can
+   cause stale locks to persist.  Look in $prefix/locks for any
+   stale list locks and remove them (you can determine if they're
+   stale by getting the pid from the file contents and using ps to
+   see if those processes are still running or not).
+<p> <b> Q. What should I check periodically?
+
+</b><br> A. Many of the scripts have their standard error logged to
+   ~mailman/logs/error, and some of the modules write caught errors
+   there, as well, so you should check there at least occasionally to
+   look for bugs in the code and problems in your setup.
+<p>    One thing that is *not* caught by the standard error hook is syntax
+   errors, but any of these should have been caught in the
+   installation phase, which byte-compiles all .py files in the
+   distribution.  There may be syntax errors lurking if you hacked the
+   code, or in the scripts that are not modules.
+<p>    You can always use the Python module `compile' or `compileall' to
+   force byte compilation of a file, or just fire up the Python
+   interpreter and try importing the module.
+<p> <b> Q. Why doesn't the archive link work?
+
+</b><br> A. Have any messages been posted to the list?  This is a known buglet;
+   the archive link doesn't work until at least one message has been
+   posted.
+<p> <b> Q. Okay, the archive link works, but I can't access the public
+   archives.  Why?
+
+</b><br> A. If you are using Apache, you must make sure that FollowSymLinks is
+   enabled for the path to the public archives.  Note that the actual
+   archives always reside in the private tree, and only when archives
+   are public, is the symlink followed. See this archive message for
+   more details:
+<p>    <a href="http://www.python.org/pipermail/mailman-users/1998-November/000173.html">http://www.python.org/pipermail/mailman-users/1998-November/000173.html</a>
+<p> <b> Q. Still having problems?  Running QMail?
+
+</b><br> A. Make sure that you are using "preline" before calling "wrapper":
+<p>        |preline /home/mailman/mail/wrapper post listname
+<p>    "preline" adds a Unix-style "From " header which the archiver requires.
+   You can fix the archive mbox files by adding:
+<p>        From somebody Mon Oct  9 12:27:34 MDT 2000
+<p>    before every message and re-running the archive command
+   "bin/arch listname".  The archives should now exist.  See README.QMAIL
+   for more information.
+<p> <b> Q. Still having problems?  Running on GNU/Linux?
+
+</b><br> A. See the README.LINUX file.
+<p> <b> Q. I want to get rid of some messages in my archive.  How do I do
+   this?
+
+</b><br> A. David Rocher posts the following recipe:
+<p> <li>
+    remove $prefix/archives/private/<em>listname</em>
+<li>
+    edit $prefix/archives/private/<em>listname</em>.mbox/<em>listname</em>.mbox [optional]
+<li>
+    run $prefix/bin/arch <em>listname</em> 
+<p> <b> Q. I set member_posting_only to yes because I want to limit posts to
+   members only, however it seems like all messages coming from
+   members are held for approval.  Why?
+
+</b><br> A. There appears to be a problem on some systems where the envelope
+   sender (e.g. the Unix "From " line) is set incorrectly.  This will
+   cause a negative match when checking to see if the sender is a
+   member of the list.  Until 1.0b12, Mailman defaulted to using the
+   envelope sender before the sender (i.e. "From:" header) because the
+   former is set by the SMTP agent while the latter is easily
+   spoofable by the end user.
+<p>    [ The possible causes for envelope sender munging taking place are
+     many, but the "owner-alias" sendmail feature probably deserves
+     special mention:
+<p>      If mail arrives for list "foo", and there is an alias entry for
+     "owner-foo" as well, the envelope sender of the message will be
+     changed to the single-level expansion of the "owner-foo" alias.
+<p>      Code has been included in post-1.0rc2 Mailman releases to try
+     working around the problem this (unconfigurable) sendmail feature
+     constitutes.  Prior to this, some people worked around the
+     problem by not including the suggested "owner-LISTNAME" alias
+     entries for Mailman lists in their alias files. ]
+<p>    However, if you are having this problem, you may opt to favor the
+   From: header over the envelope sender.  Do this by adding the
+   following line to your mm_cfg.py file:
+<p>    USE_ENVELOPE_SENDER=0
+<p>    if you want (arguably) more security, add this to your mm_cfg.py
+   file:
+<p>    USE_ENVELOPE_SENDER=1
+<p>    However, read the comments about this variable in the Defaults.py
+   file for a full discussion of the issues.  By default, Mailman 2.0
+   relies on the From: header for doing address matching.
+<p> <b> Q. How secure are the authentication mechanisms used in Mailman's web
+   interface?
+
+</b><br> A. If your Mailman installation run on an SSL-enabled web server
+   (i.e. you access the Mailman web pages with "https://..." URLs),
+   you should be as safe as SSL itself is.
+<p>    However, most Mailman installation run under standard,
+   encryption-unaware servers.  There's nothing wrong with that for
+   most applications, but a sufficiently determined cracker *could*
+   get unauthorized access by:
+<p> <li>
+    Packet sniffing: The password used to do the initial
+     authentication for any non-public Mailman page is sent as clear
+     text over the net.  If you consider this to be a big problem, you
+     really should use an SSL-enabled server.
+<p> <li>
+    Stealing a valid cookie: After successful password
+     authentication, Mailman sends a "cookie" back to the user's
+     browser.  This cookie will be used for "automatic" authentication
+     when browsing further within the list's protected pages.  Mailman
+     employs "session cookies" which are set until you quit your
+     browser or explicitly log out.
+<p>      Gaining access to the user's cookie (e.g. by being able to read
+     the user's browser cookie database, or by means of packet
+     sniffing, or maybe even by some broken browser offering all it's
+     cookies to any and all sites the user accesses), and at the same
+     time being able to fulfill the other criteria for using the
+     cookie could result in unauthorized access.
+<p>      Note that this problem is more easily exploited when users browse
+     the web via proxies -- in that case, the cookie would be valid
+     for any connections made through that proxy, and not just for
+     connections made from the particular machine the user happens to
+     be accessing the proxy from.
+<p> <li>
+    Getting access to the user's terminal: This is really just
+     another kind of cookie stealing.  The short cookie expiration
+     time is supposed to help defeat this problem.  It can be
+     considered the price to pay for the convenience of not having to
+     type the password in every time.
+<p>
\ No newline at end of file