This commit was manufactured by cvs2svn to create branch

'Release_2_1-maint'.

1 files changed, 240 insertions, 0 deletions

diff --git a/admin/www/site.ht b/admin/www/site.ht
new file mode 100644
index 00000000..abb08bd6
--- /dev/null
+++ b/admin/www/site.ht
@@ -0,0 +1,240 @@
+Title: Site Administrator Documentation
+Links: doco-links.h
+
+<h3>Site Administrator Documentation</h3>
+
+By definition, the site administrator has shell access to the Mailman
+installation, and the proper permissions for total control over
+Mailman at the site.  The site admin can edit the
+<code>Mailman/mm_cfg.py</code> configuration file, and can run the
+various and sundry command line scripts.
+
+<h3>Command line scripts</h3>
+
+This is a brief overview of the current crop of command line scripts
+available to the site administrator in the <code>bin</code> directory.
+For more details, run the script with the <code>--help</code> option,
+which will print out the usage synopsis.  <em>You must run these
+scripts from the bin directory in the Mailman installation location,
+usually <code>/home/mailman</code></em>.
+
+<dl>
+<dt><b>add_members</b>
+<dd>Use this script to mass add members to a mailing list.  Input
+    files are plain text, with one address per line.  Command line
+    options allow you to add the addresses as digest or regular
+    members, select whether various notification emails are sent, and
+    choose which list to add the members to.
+
+<dt><b>addlang</b>
+<dd>Use this to add language support to a specific list.  The site
+    itself must have the language pack to add already installed.  Note
+    that removing language support from a list requires you to
+    manually <tt>rm</tt> the lists/<em>yourlist</em>/<em>lang</em>
+    subdirectory.
+
+<dt><b>arch</b>
+<dd>Use this to rebuild a list's archive.  This script can't be used
+    to modify a list's raw mbox file, but once you've edited the mbox
+    file some other way, you can use this script to regenerate the
+    HTML version of the on-line archive.
+
+<dt><b>change_pw</b>
+<dd>Use this to change the password for a specific mailing list.
+
+<dt><b>check_db</b>
+<dd>Use this script to check the integrity of a list's
+    <code>config.pck</code> and <code>config.pck.last</code> database
+    files.
+
+<dt><b>check_perms</b>
+<dd>Use this script to check, and optionally fix, the permissions of
+    the various files in a Mailman installation.
+
+<dt><b>clone_member</b>
+<dd>Use this script to <em>clone</em> an address on a particular list
+    into different address.  This is useful when someone is changing
+    email addresses and wants to keep all their old configuration
+    options.  Eventually members will be able to do their own cloning,
+    but for now, only the site administrator can do this.  Command
+    line options let you remove the old address, clone addresses in
+    the list managers addresses, etc.
+
+<dt><b>config_list</b>
+<dd>This is a very powerful script which lets you view and modify a
+    list's configuration variables from the command line.  E.g.  you
+    can dump out all the list options into a plain text file (actually
+    a valid Python file!), complete with comments explaining each
+    variable.  Or you can apply the configuration from such a file to
+    a particular list.
+
+    <p>Where this might be useful is if you wanted to change the
+    <code>web_page_url</code> attribute on every list.  You could
+    create a file containing only the line
+
+<blockquote>
+<pre>
+web_page_url = 'http://www.mynewsite.com/mailman-relocated/'
+</pre>
+</blockquote>
+
+    and then feed this file back to <code>config_list</code> for every
+    list on your system.  <code>config_list</code> only sets the
+    list variables that it finds in the input file.
+
+<dt><b>digest_arch</b>
+<dd>This script is deprecated.
+
+<dt><b>dumpdb</b>
+<dd>This script dumps the plain text representation for any <code>.db</code>
+    database file.  These files usually contain Python marshaled
+    dictionaries, and can be found in the <code>qfiles</code>
+    directory, the <code>lists/<em>listname</em></code> directory,
+    etc.  This script can also be used to print out the contents of a
+    pickled message file, which are stored in <code>.pck</code> files.
+
+<dt><b>find_member</b>
+<dd>Use this script to search all the lists, or some subset of lists,
+    for an address matching a regular expression.  command line
+    options let you also search the list managers as well.
+
+<dt><b>genaliases</b>
+<dd>Use this script to regenerate the plain text and <em>db</em> alias
+    files for Postfix (if you're using Postfix as you're MTA).
+
+<dt><b>list_admins</b>
+<dd>List all the owners of a mailing list.
+
+<dt><b>list_lists</b>
+<dd>List all, or some subset of, the mailing lists in the system.
+
+<dt><b>list_members</b>
+<dd>List the members of a mailing list.  Command line options let you
+    print just the regular or just the digest members, print the
+    case-preserved addresses of the members, etc.
+
+<dt><b>mailmanctl</b>
+<dd>The main qrunner control script.  Use this to start, stop, and
+    restart the qrunner.
+
+<dt><b>mmsitepass</b>
+<dd>Use this script to set the site password, which can be used any
+    where in the system a list or user password can be used.
+    Essentially, the site password trumps any other password, so
+    choose wisely!
+
+<dt><b>move_list</b>
+<dd>Use this script when you move Mailman to a new installation location.
+
+<dt><b>newlist</b>
+<dd>Use this script to create new mailing lists.
+
+<dt><b>qrunner</b>
+<dd>Use this to run a single qrunner once (for debugging).
+
+<dt><b>remove_members</b>
+<dd>Use this list to remove members from a mailing list.
+
+<dt><b>rmlist</b>
+<dd>Use this script to remove a mailing list.  By default, a list's
+    archives are not removed unless the <code>--archives</code> option
+    is given.
+
+<dt><b>sync_members</b>
+<dd>Use this to synchronize mailing lists in a list's database with a
+    plain text file of addresses, similar to what is used for
+    <code>add_members</code>.  In a sense, this script combines the
+    functionality of <code>add_members</code> and
+    <code>remove_members</code>.  Any addresses in the file that are
+    not present in the list roster are added, and any addresses in the
+    roster that are not present in the file are removed.
+
+    <p>Command line options let you send various notification emails,
+    preview the changes, etc.
+
+<dt><b>update</b>
+<dd>Don't use this script manually; it is used as part of the
+    installation and upgrade procedures.
+
+<dt><b>version</b>
+<dd>Prints the Mailman version number.
+
+<dt><b>withlist</b>
+<dd>This is the most powerful and flexible script in Mailman.  With it
+    you can do all manner of programmatic changes to mailing lists, or
+    look at and interactively inspect almost any aspect of Mailman.
+    By default, you run this using Python's interactive prompt, like
+    so:
+
+<blockquote>
+<pre>
+% cd /home/mailman
+% python -i bin/withlist mylist
+Loading list: mylist (unlocked)
+>>> 
+</pre>
+</blockquote>
+
+    Here you see that you're left at the Python prompt after the list
+    has been loaded and instantiated.  Note that without the
+    <code>--lock</code> option, the list is not locked.  List must be
+    locked if you plan to make modifications to any attributes (and
+    they must be explicitly saved, as <code>withlist</code> does not
+    automatically save changes to list objects).
+
+    <p>At the prompt, the global object <em>m</em> is the instantiated
+    list object.  It's a Python instance so you can do all the normal
+    things to it, view or change attributes, or make method calls on
+    it.
+
+    <p>Have a look also at the <code>--run</code> option, which lets
+    you put your programmatic changes into a Python module (file) and
+    run that module over any mailing list you want.  This makes
+    <code>withlist</code> essentially a framework for easily adding
+    your own list-specific command line scripts.
+</dl>
+
+<h3>Cron scripts</h3>
+
+Mailman comes with a number of scripts that are typically only run by
+cron.  However, it is generally okay for the site administrator to run
+these scripts manually, say to force a sending of accumulated digests,
+or to mail out member passwords, etc.  You generally run these by
+invoking the Python executable on them, like so:
+
+<blockquote>
+<pre>
+% cd /home/mailman
+% python -S cron/senddigests
+</pre>
+</blockquote>
+
+The <code>-S</code> option is an optimization and (minor) security
+recommendation; it inhibits Python's implicit <code>import site</code>
+on initialization.  Not all of these scripts support the
+<code>--help</code> option.  Here is a brief description of what the
+cron scripts do:
+
+<dl>
+<dt><b>bumpdigests</b>
+<dd><em>Bumps</em> the digest volume numbers for the specified lists.
+    Resets the issue number to 1.
+
+<dt><b>checkdbs</b>
+<dd>Checks for ending list requests (posts and subscriptions) and
+    mails the list manager if there are any.
+
+<dt><b>gate_news</b>
+<dd>Polls the NNTP servers for messages and forwards any new messages
+    to their mailing list gateways.
+
+<dt><b>mailpasswds</b>
+<dd>Sends the password reminder emails to all users and all mailing lists.
+
+<dt><b>nightly_gzip</b>
+<dd>Regenerates the Pipermail <code>gzip</code>'d flat archive files.
+
+<dt><b>senddigests</b>
+<dd>Sends all accumulated digests.
+
+</dl>