Update of /cvsroot/tmda/tmda/htdocs
In directory sc8-pr-cvs1:/tmp/cvs-serv13691
Modified Files:
tmda-cgi.ht tmda-cgi.html
Log Message:
Modified instructions for no-su mode. They now say to use os.umask instead of
setting a variable in Defaults.py to change pending e-mail file permissions.
Index: tmda-cgi.ht
===================================================================
RCS file: /cvsroot/tmda/tmda/htdocs/tmda-cgi.ht,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -r1.5 -r1.6
--- tmda-cgi.ht 1 Dec 2002 05:21:47 -0000 1.5
+++ tmda-cgi.ht 2 Dec 2002 23:40:25 -0000 1.6
@@ -1,430 +1,434 @@
-Title: tmda-cgi HOWTO
-Links: overview-links.h usage-links.h howto-links.h support-links.h
-
-<h1>tmda-cgi</h1>
-<hr>
-<h2>What is it?</h2>
-<p>tmda-cgi is an alpha-release program for managing your TMDA account over the
- web. At the time of this writing, tmda-cgi can:</p>
-<ul>
- <li>Page through lists of pending e-mail (mail received by your MTA, but still
- awaiting confirmation)
- <li>View the text content (and see what sorts of attachments are included) in
- any of your pending e-mails
- <li>Release (move into your mail folder as if a confirmation had been received)
- any of your pending e-mails.
- <li>Delete any pending e-mail
- <li>Whitelist or blacklist the author of any pending e-mails.
-</ul>
-<p>At the moment, tmda-cgi's focus is clearly manipulating pending e-mails. At
- some point, I would like tmda-cgi to become more of a general system tool. Features
- I hope to add soon include:</p>
-<ul>
- <li>Filter configuration</li>
- <li>List editing</li>
- <li>Automated clean-ups of pending e-mails</li>
- <li>E-mail address generation (keyword, dated, or sender)</li>
-</ul>
-<p>tmda-cgi provides quick and easy access to your pending e-mails. This is an
- ideal tool for users who either do not have access to a shell account or are
- intimidated by operating in a command-line environment.</p>
-<p>Although TMDA users do not generally need to mess with their pending e-mails,
- there are times when this is the most convenient way to go. For instance:</p>
-<ul>
- <li>When you use a web site that says it will automatically mail you a password,
- authentication link, or a receipt for a transaction you are making right now,
- but you're not interested in any follow-up e-mail they will likely send you
- in the future (and you don't feel like generating a dated address).
- <p> Simply fill out the web form like you normally would and give your regular,
- filtered e-mail address. The web site will send the e-mail to your mail
- server, and your mail server will send a confirmation request back to the
- web site (which will most likely never be seen by a human being). Then log
- into tmda-cgi and manually release their letter. Any further mail they send
- you will sit quietly in your pending directory like the one you released.
- </li>
- <li>To search your incoming mail for automated mailings you want to receive.
- <p> Using tmda-cgi regularly for a few weeks or months after you begin filtering
- your e-mail is a good way to make sure your filters are configured correctly.
- <li>
- <p>To look for "lost" e-mail.
- <p> It's really rare that e-mail will get lost, but it's bound to happen
sometimes.
- Perhaps Aunt Margaret can't figure out what the confirmation e-mail meant
- (even though it is written in a very obvious way). Perhaps your boss was
- in a hurry and deleted the confirmation request thinking
<em><strong>it</strong></em>
- was spam (or perhaps he has a really crappy spam filter that mistook the
- confirmation for spam). Perhaps Grandpa Joe sent you some e-mail from someone
- else's e-mail account and they deleted the confirmation request, not realizing
- what it was.
- <li>
- <p>To remind you <em><strong>why</strong></em> you got TMDA in the first place.
- <p> "Wow, I would have gotten 100 e-mails about Viagara, cheap cigarettes,
- weight loss drugs, penis enlargement, and Nigerian swindles today! Now I
- remember why the rest of my family thinks that e-mail is a pain."</ul>
-<hr>
-<h2>Requirements</h2>
-<p>TBD. Until we do more testing it isn't clear what systems have problems with
- tmda-cgi.</p>
-<hr>
-<h2>Installation</h2>
-<p>tmda-cgi is provided in your distribution's <tt>contrib/cgi</tt> directory,
- however with this being alpha-revision software, revisions come out quite
frequently.
- You should consider downloading from <a
href="http://sourceforge.net/cvs/?group_id=24680"; target="_blank">CVS</a>
- and joining the <a href="mailto:[EMAIL PROTECTED]";>tmda-cgi mailing
- list</a> to keep up on the sub-project's current state of development.</p>
-<p>Once you've obtained a copy of tmda-cgi, you need to decide how you want to
- use tmda-cgi. tmda-cgi has been designed to run three different ways: system-wide,
- single-user, and in no-su modes.</p>
-<ul>
- <li>In system-wide mode, multiple users can use tmda-cgi to access their TMDA
- system. The program launches as root and then performs a <tt>seteuid</tt>
- to run as the requested user once password authentication has been accomplished.
- This is the best solution for system administrators who wish to set up their
- TMDA system for use by multiple users.<br>
- </li>
- <li>In single-user mode, only one user can access tmda-cgi. That user will still
- need to authenticate their access with a password, but the program runs as
- the user who compiled it and therefore cannot access anyone else's personal
- data. If multiple users wish to install tmda-cgi in single-user mode (strange,
- but not absurd) then each user can compile a different 14k shell that launches
- the Python code. This method is less convenient than the system-wide
installation,
- but it is the best solution for users without root access to their server,
- or for users who don't trust any program running as root that does not absolutely
- have to run as root.<br>
- </li>
- <li>no-su mode, which is in testing, runs the program with no special privileges
- of any sort. The downside of such an installation is that to allow the program
- access to your personal files (such as pending e-mails) you will have to make
- some of your files and directories group or world readable and writable. no-su
- mode is a good solution for an unusual breed of user: someone who doesn't
- trust the software, but trusts the other users on the server (since they could
- get read/write access to his/er pending e-mail)</li>
-</ul>
-<p><b><i>Notes:</i></b></p>
-<ul>
- <li>tmda-cgi assumes it will run from within the source tree. No testing has
- been done to date to see if it will work in other locations.<br>
- </li>
- <li>You will have to recompile tmda-cgi if you move your configuration files
- or source tree.<br></li>
- <li>You will have to recompile tmda-cgi if you change which mode (system-wide,
- single-user, or no-su) you run in.</li>
-</ul>
-<h3>Installing system-wide</h3>
-<p>As root, change to the cgi directory.</p>
-<blockquote>
- <pre># cd contrib/cgi</pre>
-</blockquote>
-<p>Compile tmda-cgi to a web directory that is configured to execute CGI. The
- filename you use is completely up to you. For example:</p>
-<blockquote>
- <pre># ./compile -t /path/to/cgi-bin/directory</pre>
-</blockquote>
-<p> or</p>
-<blockquote>
- <pre># ./compile -t /path/to/webpage/directory/index.cgi</pre>
-</blockquote>
-<p>Finally, tmda-cgi expects to find a variety of visual elements in a subdirectory
- called "display". This directory should be located directly below
- the CGI itself. Sample files are provided in <tt>contrib/cgi/display</tt>. Feel
- free to use these files as-is or modify/replace them to personalize the program.</p>
-<p>The simplest way to provide this directory is with a symbolic link (assuming
- you have you web server configured to follow symbolic links). For example:</p>
-<blockquote>
- <pre># ln -s display /path/to/webpage/directory</pre>
-</blockquote>
-<h3>Installing single-user</h3>
-<p>As the (only) user who will be able to access tmda-cgi, change to the cgi
directory.</p>
-<blockquote>
- <pre>$ cd contrib/cgi</pre>
-</blockquote>
-<p>Compile tmda-cgi to a web directory that is configured to execute CGI. The
- filename you use is completely up to you. For example:</p>
-<blockquote>
- <pre>$ ./compile -t /path/to/cgi-bin/directory</pre>
-</blockquote>
-<p>or</p>
-<blockquote>
- <pre>$ ./compile -t /path/to/webpage/directory/index.cgi</pre>
-</blockquote>
-<p>Finally, tmda-cgi expects to find a variety of visual elements in a subdirectory
- called "display". This directory should be located directly below
- the CGI itself. Sample files are provided in <tt>contrib/cgi/display</tt>. Feel
- free to use these files as-is or modify/replace them to personalize the program.</p>
-<p>The simplest way to provide this directory is with a symbolic link (assuming
- you have you web server configured to follow symbolic links). For example:</p>
-<blockquote>
- <pre>$ ln -s display /path/to/webpage/directory</pre>
-</blockquote>
-<h3>Installing no-su</h3>
-<p>To compile tmda-cgi for no-su mode, first change to the cgi directory.</p>
-<blockquote>
- <pre>$ cd contrib/cgi</pre>
-</blockquote>
-<p>Compile tmda-cgi to a web directory that is configured to execute CGI. The
- filename you use is completely up to you. For example:</p>
-<blockquote>
- <pre>$ ./compile -nt /path/to/cgi-bin/directory</pre>
-</blockquote>
-<p> or</p>
-<blockquote>
- <pre>$ ./compile -nt /path/to/webpage/directory/index.cgi</pre>
-</blockquote>
-<p>tmda-cgi expects to find a variety of visual elements in a subdirectory called
- "display". This directory should be located directly below the CGI
- itself. Sample files are provided in <tt>contrib/cgi/display</tt>. Feel free
- to use these files as-is or modify/replace them to personalize the program.</p>
-<p>The simplest way to provide this directory is with a symbolic link (assuming
- you have you web server configured to follow symbolic links). For example:</p>
-<blockquote>
- <pre>$ ln -s display /path/to/webpage/directory</pre>
-</blockquote>
-<p>At this point you will have to change permissions on any existing pending mail
- and change the value of <tt>PENDING_FILE_PERM</tt> to make sure any new mail
- that is placed in the pending directory is given the correct permissions.</p>
-<p>If you multiple users plan on using tmda-cgi in no-su mode, then you might
- consider moving all of your TMDA files into one central location. This will
- make it easier to keep group permissions on your directories and files. Here's
- some sample directories and file contents I set up for my user <tt>cgitest</tt>:</p>
-<blockquote>
- <pre>/etc:
--rw-r--r-- 1 root root 22 Nov 24 23:54 tmda-cgi
--rw-r--r-- 1 root root 557 Nov 27 15:05 tmdarc
--rw------- 1 tofmipd tofmipd 49 Nov 10 11:02 tofmipd
-
-/var:
-drwxr-s--x 3 root nobody 72 Nov 27 11:24 tmda
-
-/var/tmda:
-drwx--s--- 6 cgitest nobody 200 Nov 27 11:39 cgitest
-
-/var/tmda/cgitest:
--rw-r----- 1 cgitest nobody 0 Nov 27 11:39 config
--rw-r----- 1 cgitest nobody 41 Nov 27 11:39 crypt_key
-drwx--s--- 2 cgitest nobody 96 Nov 27 12:55 filters
-drwx--s--- 2 cgitest nobody 144 Nov 27 12:59 lists
-drwx--s--- 2 cgitest nobody 120 Nov 27 12:57 logs
-drwxrws--- 2 cgitest nobody 48 Nov 27 11:37 pending
-drwx--s--- 2 cgitest nobody 768 Nov 29 09:54 responses
-
-/var/tmda/cgitest/filters:
--rw-rw---- 1 cgitest nobody 153 Nov 27 12:54 incoming
--rw-rw---- 1 cgitest nobody 150 Nov 27 12:55 outgoing
-
-/var/tmda/cgitest/lists:
--rw-rw---- 1 cgitest nobody 0 Nov 27 12:59 blacklist
--rw-rw---- 1 cgitest nobody 0 Nov 27 12:59 confirmed
--rw-rw---- 1 cgitest nobody 0 Nov 27 12:59 whitelist
-
-/var/tmda/cgitest/logs:
--rw-r----- 1 cgitest nobody 0 Nov 27 12:57 debug
--rw-r----- 1 cgitest nobody 0 Nov 27 12:57 in
--rw-r----- 1 cgitest nobody 0 Nov 27 12:57 out
-
-/etc/tmda-cgi:
-cgitest:XPkY0q/9Uge9I
-
-/var/tmda/cgitest/filters/incoming:
-from-file /var/tmda/cgitest/lists/blacklist reject
-from-file /var/tmda/cgitest/lists/whitelist accept
-from-file /var/tmda/cgitest/lists/confirmed accept
-
-/var/tmda/cgitest/filters/outgoing:
-to-file /var/tmda/cgitest/lists/whitelist tag envelope dated=10d from bare
-to-file /var/tmda/cgitest/lists/confirmed tag envelope dated=10d from bare
-
-/etc/tmdarc:
-import Util
-
-DATADIR = "/var/tmda/%s/" % Util.getusername()
-CGI_ACTIVE = 1
-FILTER_INCOMING = DATADIR + "filters/incoming"
-FILTER_OUTGOING = DATADIR + "filters/outgoing"
-LOGFILE_DEBUG = DATADIR + "logs/debug"
-LOGFILE_INCOMING = DATADIR + "logs/in"
-LOGFILE_OUTGOING = DATADIR + "logs/out"
-PENDING_BLACKLIST_APPEND = DATADIR + "lists/blacklist"
-PENDING_WHITELIST_APPEND = DATADIR + "lists/whitelist"
-PENDING_FILE_PERM = 0660
-ADDED_HEADERS_CLIENT = { "X-Primary-Address": "%s@%s" % \
- (Util.getusername(), Util.gethostname()) }
-
-~cgitest/.qmail:
-|preline /usr/src/tmda/bin/tmda-filter -c /var/tmda/cgitest/config
-./Maildir/</pre>
-</blockquote>
-<p>tmda-cgi was compiled with the following:</p>
-<blockquote>
- <pre>./compile -nc /var/tmda/~/config -t /www/tmda.cgi</pre>
-</blockquote>
-<p>Use the <tt>./compile -h</tt> for more details on how to use compile.</p>
-<h3>Passwords</h3>
-<p>tmda-cgi currently authenticate logins against user name & password pairs
- stored in a password file (or files). tmda-cgi will look in two different places
- for password file(s), but it (they) must be readable by the CGI.</p>
-<p>If you are running in system-wide mode, the password file can be owned by root.
- If you are running in single-user mode, the password file can be owned by the
- user who will be running the CGI. If you are running in no-su mode, the file
- must either be owned by "nobody" (or whatever user your web server
- is configured to run as) or made globally readable See the table below for a
- better breakdown of your options.</p>
-<p>tmda-cgi first checks for a readable file called <tt>tmda-cgi</tt> in the same
- directory as the user's configuration file (if that location has been specified,
- otherwise it will look in <tt>~user/.tmda/tmda-cgi</tt>). It then tries
<tt>/etc/tmda-cgi</tt>
- if it can't find a match or cannot read the file. This allows the system
administrator
- to keep a list of access passwords while allowing the user to override what
- the sysadmin has set.</p>
-<table border="0" cellpadding="0" cellspacing="0">
- <tr>
- <td width="35"> </td>
- <td width="10"> </td>
- <td> </td>
- <td width="10"> </td>
- <td colspan="2" align="center" nowrap
bgcolor="#FFFFCC"><tt>~user/.tmda/tmda-cgi</tt></td>
- <td width="10" align="center" nowrap> </td>
- <td colspan="2" align="center" nowrap
bgcolor="#FFFFCC"><tt>/etc/tmda-cgi</tt></td>
- </tr>
- <tr>
- <td> </td>
- <td> </td>
- <td> </td>
- <td> </td>
- <td width="80" align="center" bgcolor="#FFFFCC">owner</td>
- <td width="90" align="center" bgcolor="#FFFFCC">permissions</td>
- <td align="center"> </td>
- <td width="80" align="center" bgcolor="#FFFFCC">owner</td>
- <td width="90" align="center" bgcolor="#FFFFCC">permissions</td>
- </tr>
- <tr>
- <td> </td>
- <td bgcolor="#CCFFFF"> </td>
- <td bgcolor="#CCFFFF">system-wide</td>
- <td bgcolor="#CCFFFF"> </td>
- <td align="center" bgcolor="#CCFFCC">user</td>
- <td align="center" bgcolor="#CCFFCC">600</td>
- <td align="center" bgcolor="#CCFFFF"> </td>
- <td align="center" bgcolor="#CCFFCC">root</td>
- <td align="center" bgcolor="#CCFFCC">600</td>
- </tr>
- <tr>
- <td> </td>
- <td> </td>
- <td>single-user</td>
- <td> </td>
- <td align="center" bgcolor="#FFFFCC">user</td>
- <td align="center" bgcolor="#FFFFCC">600</td>
- <td align="center"> </td>
- <td colspan="2" align="center" bgcolor="#FFFFCC">n/a</td>
- </tr>
- <tr>
- <td> </td>
- <td bgcolor="#CCFFFF"> </td>
- <td bgcolor="#CCFFFF">no-su</td>
- <td bgcolor="#CCFFFF"> </td>
- <td align="center" bgcolor="#CCFFCC">user</td>
- <td align="center" bgcolor="#CCFFCC">644</td>
- <td align="center" bgcolor="#CCFFFF"> </td>
- <td align="center" bgcolor="#CCFFCC">root<br>
- nobody </td>
- <td align="center" bgcolor="#CCFFCC">644<br>
- 600 </td>
- </tr>
- <tr>
- <td> </td>
- <td colspan="8" align="center">File owner & permission options</td>
- </tr>
-</table>
-<p>The password file for tmda-cgi is formatted in much the same way as the password
- file for tofmipd. In fact, if you are using a password file with tofmipd and
- you wish to run tmda-cgi in system-wide mode, feel free to make a symbolic link
- between the two:</p>
-<blockquote>
- <pre> # ln -s /etc/tofmipd /etc/tmda-cgi</pre>
-</blockquote>
-<p>Password files for tmda-cgi look like:</p>
-<blockquote>
- <pre><user1>:<password1>
-<user2>:<password2></pre>
-</blockquote>
-<p>where each item in <tt><></tt> is replaced with text.</p>
-<p>The difference between this password file and the one for tofmipd is that the
- file does not need to have <br>
- permissions of 400 or 600. If you, for example, are running in no-su mode, you
- will have to make your password file group or world readable.</p>
-<p>To keep the passwords secure, tmda-cgi will assume all passwords are DES encrypted
- if the file permissions are anything other than 400 or 600. Plaintext passwords
- will <i><b>not</b></i> work in such cases.</p>
-<p>Additionally, any entry with a blank password field, such as:</p>
-<blockquote>
- <pre>cantlogin:</pre>
-</blockquote>
-<p>will be prohibited from login, regardless of the file permissions.</p>
-<p><tt>contrib/cgi/genpass.py</tt> is provided for encrypted password generation.
- Output from <tt>genpass.py</tt> can be safely piped with <tt>></tt> or
<tt>>></tt>
- into a password file. For example:</p>
-<blockquote>
- <pre># contrib/cgi/genpass.py joe >> /etc/tmda-cgi</pre>
-</blockquote>
-<p> or</p>
-<blockquote>
- <pre>$ contrib/cgi/genpass.py joe > /home/joe/.tmda/tmda-cgi</pre>
-</blockquote>
-<p>If you encounter difficulties logging in, the problem may be a result of incorrect
- permissions on your password file(s). To debug this, append a <tt>?debug=1</tt>
- onto the end of your CGI URL. This will display some diagnostic information
- if the login fails instead of simply saying "Wrong password. Try
again."</p>
-<hr>
-<h2>Configuration</h2>
-<p>tmda-cgi is configured by a set of parameters in your <tt>/etc/tmdarc</tt>,
- <tt>~user/.tmdarc</tt>, or <tt>~user/.tmda/config</tt> files. More details on
- these variables can be found in your <tt>Defaults.py</tt>, but <b><i>do not
- edit <tt>Defaults.py</tt></i></b>. Place your variables in your configuration
- file(s) and they will override the defaults in <tt>Defaults.py</tt>.</p>
-<dl>
- <dt><tt>CGI_ACTIVE</tt></dt>
- <br>
-
- <dd>Must be set to 1 to use the tmda-cgi. Set this in <tt>/etc/tmdarc</tt> if
- you set up tmda-cgi in system-wide mode.</dd>
- <br>
-
- <dt><tt>CGI_CLEANUP_ODDS</tt></dt>
- <br>
-
- <dd>Chance of cleaning up temporary session files. You probably won't need to
- adjust this parameter.</dd>
- <br>
-
- <dt><tt>CGI_DATE_FORMAT</tt></dt>
- <br>
-
- <dd>Configuration string which sets the date format you see when viewing a list
- of pending e-mails. It defaults to "<tt>%a %1m/%d</tt>" which generates
- American-style dates like "Mon 12/31".</dd>
- <br>
-
- <dt><tt>CGI_PAGER_SIZE</tt><br>
- </dt>
- <dd>Maximum number of e-mails shown on a listing page.</dd>
- <br>
-
- <dt><tt>CGI_SESSION_EXP</tt><br>
- </dt>
- <dd>The number of seconds a session may sit idle before it can expire. Set this
- to a larger number if you surf pages so slowly that the program makes you
- log in again.</dd>
- <br>
-
- <dt><tt>CGI_USE_JS_CONFIRM</tt><br>
- </dt>
- <dd>Set this to 0 if your browser cannot use Javascript or you don't like having
- to confirm when you delete or blacklist an item.</dd>
- <br>
-
- <dt><tt>CGI_USER</tt><br>
- </dt>
- <dd>Set this to the user name used by your web server. The default is
"nobody",
- but some systems are configured to run as "apache" or other
low-privilege
- user.</dd>
- <br>
-
-</dl>
+Title: tmda-cgi HOWTO
+Links: overview-links.h usage-links.h howto-links.h support-links.h
+
+<h1>tmda-cgi</h1>
+<hr>
+<h2>What is it?</h2>
+<p>tmda-cgi is an alpha-release program for managing your TMDA account over the
+ web. At the time of this writing, tmda-cgi can:</p>
+<ul>
+ <li>Page through lists of pending e-mail (mail received by your MTA, but still
+ awaiting confirmation)
+ <li>View the text content (and see what sorts of attachments are included) in
+ any of your pending e-mails
+ <li>Release (move into your mail folder as if a confirmation had been received)
+ any of your pending e-mails.
+ <li>Delete any pending e-mail
+ <li>Whitelist or blacklist the author of any pending e-mails.
+</ul>
+<p>At the moment, tmda-cgi's focus is clearly manipulating pending e-mails. At
+ some point, I would like tmda-cgi to become more of a general system tool. Features
+ I hope to add soon include:</p>
+<ul>
+ <li>Filter configuration</li>
+ <li>List editing</li>
+ <li>Automated clean-ups of pending e-mails</li>
+ <li>E-mail address generation (keyword, dated, or sender)</li>
+</ul>
+<p>tmda-cgi provides quick and easy access to your pending e-mails. This is an
+ ideal tool for users who either do not have access to a shell account or are
+ intimidated by operating in a command-line environment.</p>
+<p>Although TMDA users do not generally need to mess with their pending e-mails,
+ there are times when this is the most convenient way to go. For instance:</p>
+<ul>
+ <li>When you use a web site that says it will automatically mail you a password,
+ authentication link, or a receipt for a transaction you are making right now,
+ but you're not interested in any follow-up e-mail they will likely send you
+ in the future (and you don't feel like generating a dated address).
+ <p> Simply fill out the web form like you normally would and give your regular,
+ filtered e-mail address. The web site will send the e-mail to your mail
+ server, and your mail server will send a confirmation request back to the
+ web site (which will most likely never be seen by a human being). Then log
+ into tmda-cgi and manually release their letter. Any further mail they send
+ you will sit quietly in your pending directory like the one you released.
+ </li>
+ <li>To search your incoming mail for automated mailings you want to receive.
+ <p> Using tmda-cgi regularly for a few weeks or months after you begin filtering
+ your e-mail is a good way to make sure your filters are configured correctly.
+ <li>
+ <p>To look for "lost" e-mail.
+ <p> It's really rare that e-mail will get lost, but it's bound to happen
+sometimes.
+ Perhaps Aunt Margaret can't figure out what the confirmation e-mail meant
+ (even though it is written in a very obvious way). Perhaps your boss was
+ in a hurry and deleted the confirmation request thinking
+<em><strong>it</strong></em>
+ was spam (or perhaps he has a really crappy spam filter that mistook the
+ confirmation for spam). Perhaps Grandpa Joe sent you some e-mail from someone
+ else's e-mail account and they deleted the confirmation request, not realizing
+ what it was.
+ <li>
+ <p>To remind you <em><strong>why</strong></em> you got TMDA in the first place.
+ <p> "Wow, I would have gotten 100 e-mails about Viagara, cheap cigarettes,
+ weight loss drugs, penis enlargement, and Nigerian swindles today! Now I
+ remember why the rest of my family thinks that e-mail is a pain."</ul>
+<hr>
+<h2>Requirements</h2>
+<p>TBD. Until we do more testing it isn't clear what systems have problems with
+ tmda-cgi.</p>
+<hr>
+<h2>Installation</h2>
+<p>tmda-cgi is provided in your distribution's <tt>contrib/cgi</tt> directory,
+ however with this being alpha-revision software, revisions come out quite
+frequently.
+ You should consider downloading from <a
+href="http://sourceforge.net/cvs/?group_id=24680"; target="_blank">CVS</a>
+ and joining the <a href="mailto:[EMAIL PROTECTED]";>tmda-cgi mailing
+ list</a> to keep up on the sub-project's current state of development.</p>
+<p>Once you've obtained a copy of tmda-cgi, you need to decide how you want to
+ use tmda-cgi. tmda-cgi has been designed to run three different ways: system-wide,
+ single-user, and in no-su modes.</p>
+<ul>
+ <li>In system-wide mode, multiple users can use tmda-cgi to access their TMDA
+ system. The program launches as root and then performs a <tt>seteuid</tt>
+ to run as the requested user once password authentication has been accomplished.
+ This is the best solution for system administrators who wish to set up their
+ TMDA system for use by multiple users.<br>
+ </li>
+ <li>In single-user mode, only one user can access tmda-cgi. That user will still
+ need to authenticate their access with a password, but the program runs as
+ the user who compiled it and therefore cannot access anyone else's personal
+ data. If multiple users wish to install tmda-cgi in single-user mode (strange,
+ but not absurd) then each user can compile a different 14k shell that launches
+ the Python code. This method is less convenient than the system-wide
+installation,
+ but it is the best solution for users without root access to their server,
+ or for users who don't trust any program running as root that does not absolutely
+ have to run as root.<br>
+ </li>
+ <li>no-su mode, which is in testing, runs the program with no special privileges
+ of any sort. The downside of such an installation is that to allow the program
+ access to your personal files (such as pending e-mails) you will have to make
+ some of your files and directories group or world readable and writable. no-su
+ mode is a good solution for an unusual breed of user: someone who doesn't
+ trust the software, but trusts the other users on the server (since they could
+ get read/write access to his/er pending e-mail)</li>
+</ul>
+<p><b><i>Notes:</i></b></p>
+<ul>
+ <li>tmda-cgi assumes it will run from within the source tree. No testing has
+ been done to date to see if it will work in other locations.<br>
+ </li>
+ <li>You will have to recompile tmda-cgi if you move your configuration files
+ or source tree.<br></li>
+ <li>You will have to recompile tmda-cgi if you change which mode (system-wide,
+ single-user, or no-su) you run in.</li>
+</ul>
+<h3>Installing system-wide</h3>
+<p>As root, change to the cgi directory.</p>
+<blockquote>
+ <pre># cd contrib/cgi</pre>
+</blockquote>
+<p>Compile tmda-cgi to a web directory that is configured to execute CGI. The
+ filename you use is completely up to you. For example:</p>
+<blockquote>
+ <pre># ./compile -t /path/to/cgi-bin/directory</pre>
+</blockquote>
+<p> or</p>
+<blockquote>
+ <pre># ./compile -t /path/to/webpage/directory/index.cgi</pre>
+</blockquote>
+<p>Finally, tmda-cgi expects to find a variety of visual elements in a subdirectory
+ called "display". This directory should be located directly below
+ the CGI itself. Sample files are provided in <tt>contrib/cgi/display</tt>. Feel
+ free to use these files as-is or modify/replace them to personalize the program.</p>
+<p>The simplest way to provide this directory is with a symbolic link (assuming
+ you have you web server configured to follow symbolic links). For example:</p>
+<blockquote>
+ <pre># ln -s display /path/to/webpage/directory</pre>
+</blockquote>
+<h3>Installing single-user</h3>
+<p>As the (only) user who will be able to access tmda-cgi, change to the cgi
+directory.</p>
+<blockquote>
+ <pre>$ cd contrib/cgi</pre>
+</blockquote>
+<p>Compile tmda-cgi to a web directory that is configured to execute CGI. The
+ filename you use is completely up to you. For example:</p>
+<blockquote>
+ <pre>$ ./compile -t /path/to/cgi-bin/directory</pre>
+</blockquote>
+<p>or</p>
+<blockquote>
+ <pre>$ ./compile -t /path/to/webpage/directory/index.cgi</pre>
+</blockquote>
+<p>Finally, tmda-cgi expects to find a variety of visual elements in a subdirectory
+ called "display". This directory should be located directly below
+ the CGI itself. Sample files are provided in <tt>contrib/cgi/display</tt>. Feel
+ free to use these files as-is or modify/replace them to personalize the program.</p>
+<p>The simplest way to provide this directory is with a symbolic link (assuming
+ you have you web server configured to follow symbolic links). For example:</p>
+<blockquote>
+ <pre>$ ln -s display /path/to/webpage/directory</pre>
+</blockquote>
+<h3>Installing no-su</h3>
+<p>To compile tmda-cgi for no-su mode, first change to the cgi directory.</p>
+<blockquote>
+ <pre>$ cd contrib/cgi</pre>
+</blockquote>
+<p>Compile tmda-cgi to a web directory that is configured to execute CGI. The
+ filename you use is completely up to you. For example:</p>
+<blockquote>
+ <pre>$ ./compile -nt /path/to/cgi-bin/directory</pre>
+</blockquote>
+<p> or</p>
+<blockquote>
+ <pre>$ ./compile -nt /path/to/webpage/directory/index.cgi</pre>
+</blockquote>
+<p>tmda-cgi expects to find a variety of visual elements in a subdirectory called
+ "display". This directory should be located directly below the CGI
+ itself. Sample files are provided in <tt>contrib/cgi/display</tt>. Feel free
+ to use these files as-is or modify/replace them to personalize the program.</p>
+<p>The simplest way to provide this directory is with a symbolic link (assuming
+ you have you web server configured to follow symbolic links). For example:</p>
+<blockquote>
+ <pre>$ ln -s display /path/to/webpage/directory</pre>
+</blockquote>
+<p>At this point you will have to change permissions on any existing pending mail
+ and add something akin to:</p>
+<blockquote>
+ <pre>os.umask(027)</pre>
+</blockquote>
+<p>to your configuration file. That will make sure that future pending e-mails
+ are written such that they can be read by group members (i.e. the CGI).</p>
+<p>If you multiple users plan on using tmda-cgi in no-su mode, then you might
+ consider moving all of your TMDA files into one central location. This will
+ make it easier to keep group permissions on your directories and files. Here's
+ some sample directories and file contents I set up for my user <tt>cgitest</tt>:</p>
+<blockquote>
+ <pre>/etc:
+-rw-r--r-- 1 root root 22 Nov 24 23:54 tmda-cgi
+-rw-r--r-- 1 root root 557 Nov 27 15:05 tmdarc
+-rw------- 1 tofmipd tofmipd 49 Nov 10 11:02 tofmipd
+
+/var:
+drwxr-s--x 3 root nobody 72 Nov 27 11:24 tmda
+
+/var/tmda:
+drwx--s--- 6 cgitest nobody 200 Nov 27 11:39 cgitest
+
+/var/tmda/cgitest:
+-rw-r----- 1 cgitest nobody 0 Nov 27 11:39 config
+-rw-r----- 1 cgitest nobody 41 Nov 27 11:39 crypt_key
+drwx--s--- 2 cgitest nobody 96 Nov 27 12:55 filters
+drwx--s--- 2 cgitest nobody 144 Nov 27 12:59 lists
+drwx--s--- 2 cgitest nobody 120 Nov 27 12:57 logs
+drwxrws--- 2 cgitest nobody 48 Nov 27 11:37 pending
+drwx--s--- 2 cgitest nobody 768 Nov 29 09:54 responses
+
+/var/tmda/cgitest/filters:
+-rw-rw---- 1 cgitest nobody 153 Nov 27 12:54 incoming
+-rw-rw---- 1 cgitest nobody 150 Nov 27 12:55 outgoing
+
+/var/tmda/cgitest/lists:
+-rw-rw---- 1 cgitest nobody 0 Nov 27 12:59 blacklist
+-rw-rw---- 1 cgitest nobody 0 Nov 27 12:59 confirmed
+-rw-rw---- 1 cgitest nobody 0 Nov 27 12:59 whitelist
+
+/var/tmda/cgitest/logs:
+-rw-r----- 1 cgitest nobody 0 Nov 27 12:57 debug
+-rw-r----- 1 cgitest nobody 0 Nov 27 12:57 in
+-rw-r----- 1 cgitest nobody 0 Nov 27 12:57 out
+
+/etc/tmda-cgi:
+cgitest:XPkY0q/9Uge9I
+
+/var/tmda/cgitest/filters/incoming:
+from-file /var/tmda/cgitest/lists/blacklist reject
+from-file /var/tmda/cgitest/lists/whitelist accept
+from-file /var/tmda/cgitest/lists/confirmed accept
+
+/var/tmda/cgitest/filters/outgoing:
+to-file /var/tmda/cgitest/lists/whitelist tag envelope dated=10d from bare
+to-file /var/tmda/cgitest/lists/confirmed tag envelope dated=10d from bare
+
+/etc/tmdarc:
+import Util
+
+DATADIR = "/var/tmda/%s/" % Util.getusername()
+CGI_ACTIVE = 1
+FILTER_INCOMING = DATADIR + "filters/incoming"
+FILTER_OUTGOING = DATADIR + "filters/outgoing"
+LOGFILE_DEBUG = DATADIR + "logs/debug"
+LOGFILE_INCOMING = DATADIR + "logs/in"
+LOGFILE_OUTGOING = DATADIR + "logs/out"
+PENDING_BLACKLIST_APPEND = DATADIR + "lists/blacklist"
+PENDING_WHITELIST_APPEND = DATADIR + "lists/whitelist"
+os.umask(027)
+ADDED_HEADERS_CLIENT = { "X-Primary-Address": "%s@%s" % \
+ (Util.getusername(), Util.gethostname()) }
+
+~cgitest/.qmail:
+|preline /usr/src/tmda/bin/tmda-filter -c /var/tmda/cgitest/config
+./Maildir/</pre>
+</blockquote>
+<p>tmda-cgi was compiled with the following:</p>
+<blockquote>
+ <pre>./compile -nc /var/tmda/~/config -t /www/tmda.cgi</pre>
+</blockquote>
+<p>Use the <tt>./compile -h</tt> for more details on how to use compile.</p>
+<h3>Passwords</h3>
+<p>tmda-cgi currently authenticate logins against user name & password pairs
+ stored in a password file (or files). tmda-cgi will look in two different places
+ for password file(s), but it (they) must be readable by the CGI.</p>
+<p>If you are running in system-wide mode, the password file can be owned by root.
+ If you are running in single-user mode, the password file can be owned by the
+ user who will be running the CGI. If you are running in no-su mode, the file
+ must either be owned by "nobody" (or whatever user your web server
+ is configured to run as) or made globally readable See the table below for a
+ better breakdown of your options.</p>
+<p>tmda-cgi first checks for a readable file called <tt>tmda-cgi</tt> in the same
+ directory as the user's configuration file (if that location has been specified,
+ otherwise it will look in <tt>~user/.tmda/tmda-cgi</tt>). It then tries
+<tt>/etc/tmda-cgi</tt>
+ if it can't find a match or cannot read the file. This allows the system
+administrator
+ to keep a list of access passwords while allowing the user to override what
+ the sysadmin has set.</p>
+<table border="0" cellpadding="0" cellspacing="0">
+ <tr>
+ <td width="35"> </td>
+ <td width="10"> </td>
+ <td> </td>
+ <td width="10"> </td>
+ <td colspan="2" align="center" nowrap
+bgcolor="#FFFFCC"><tt>~user/.tmda/tmda-cgi</tt></td>
+ <td width="10" align="center" nowrap> </td>
+ <td colspan="2" align="center" nowrap
+bgcolor="#FFFFCC"><tt>/etc/tmda-cgi</tt></td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ <td> </td>
+ <td width="80" align="center" bgcolor="#FFFFCC">owner</td>
+ <td width="90" align="center" bgcolor="#FFFFCC">permissions</td>
+ <td align="center"> </td>
+ <td width="80" align="center" bgcolor="#FFFFCC">owner</td>
+ <td width="90" align="center" bgcolor="#FFFFCC">permissions</td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td bgcolor="#CCFFFF"> </td>
+ <td bgcolor="#CCFFFF">system-wide</td>
+ <td bgcolor="#CCFFFF"> </td>
+ <td align="center" bgcolor="#CCFFCC">user</td>
+ <td align="center" bgcolor="#CCFFCC">600</td>
+ <td align="center" bgcolor="#CCFFFF"> </td>
+ <td align="center" bgcolor="#CCFFCC">root</td>
+ <td align="center" bgcolor="#CCFFCC">600</td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td> </td>
+ <td>single-user</td>
+ <td> </td>
+ <td align="center" bgcolor="#FFFFCC">user</td>
+ <td align="center" bgcolor="#FFFFCC">600</td>
+ <td align="center"> </td>
+ <td colspan="2" align="center" bgcolor="#FFFFCC">n/a</td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td bgcolor="#CCFFFF"> </td>
+ <td bgcolor="#CCFFFF">no-su</td>
+ <td bgcolor="#CCFFFF"> </td>
+ <td align="center" bgcolor="#CCFFCC">user</td>
+ <td align="center" bgcolor="#CCFFCC">644</td>
+ <td align="center" bgcolor="#CCFFFF"> </td>
+ <td align="center" bgcolor="#CCFFCC">root<br>
+ nobody </td>
+ <td align="center" bgcolor="#CCFFCC">644<br>
+ 600 </td>
+ </tr>
+ <tr>
+ <td> </td>
+ <td colspan="8" align="center">File owner & permission options</td>
+ </tr>
+</table>
+<p>The password file for tmda-cgi is formatted in much the same way as the password
+ file for tofmipd. In fact, if you are using a password file with tofmipd and
+ you wish to run tmda-cgi in system-wide mode, feel free to make a symbolic link
+ between the two:</p>
+<blockquote>
+ <pre> # ln -s /etc/tofmipd /etc/tmda-cgi</pre>
+</blockquote>
+<p>Password files for tmda-cgi look like:</p>
+<blockquote>
+ <pre><user1>:<password1>
+<user2>:<password2></pre>
+</blockquote>
+<p>where each item in <tt><></tt> is replaced with text.</p>
+<p>The difference between this password file and the one for tofmipd is that the
+ file does not need to have <br>
+ permissions of 400 or 600. If you, for example, are running in no-su mode, you
+ will have to make your password file group or world readable.</p>
+<p>To keep the passwords secure, tmda-cgi will assume all passwords are DES encrypted
+ if the file permissions are anything other than 400 or 600. Plaintext passwords
+ will <i><b>not</b></i> work in such cases.</p>
+<p>Additionally, any entry with a blank password field, such as:</p>
+<blockquote>
+ <pre>cantlogin:</pre>
+</blockquote>
+<p>will be prohibited from login, regardless of the file permissions.</p>
+<p><tt>contrib/cgi/genpass.py</tt> is provided for encrypted password generation.
+ Output from <tt>genpass.py</tt> can be safely piped with <tt>></tt> or
+<tt>>></tt>
+ into a password file. For example:</p>
+<blockquote>
+ <pre># contrib/cgi/genpass.py joe >> /etc/tmda-cgi</pre>
+</blockquote>
+<p> or</p>
+<blockquote>
+ <pre>$ contrib/cgi/genpass.py joe > /home/joe/.tmda/tmda-cgi</pre>
+</blockquote>
+<p>If you encounter difficulties logging in, the problem may be a result of incorrect
+ permissions on your password file(s). To debug this, append a <tt>?debug=1</tt>
+ onto the end of your CGI URL. This will display some diagnostic information
+ if the login fails instead of simply saying "Wrong password. Try
+again."</p>
+<hr>
+<h2>Configuration</h2>
+<p>tmda-cgi is configured by a set of parameters in your <tt>/etc/tmdarc</tt>,
+ <tt>~user/.tmdarc</tt>, or <tt>~user/.tmda/config</tt> files. More details on
+ these variables can be found in your <tt>Defaults.py</tt>, but <b><i>do not
+ edit <tt>Defaults.py</tt></i></b>. Place your variables in your configuration
+ file(s) and they will override the defaults in <tt>Defaults.py</tt>.</p>
+<dl>
+ <dt><tt>CGI_ACTIVE</tt></dt>
+ <br>
+
+ <dd>Must be set to 1 to use the tmda-cgi. Set this in <tt>/etc/tmdarc</tt> if
+ you set up tmda-cgi in system-wide mode.</dd>
+ <br>
+
+ <dt><tt>CGI_CLEANUP_ODDS</tt></dt>
+ <br>
+
+ <dd>Chance of cleaning up temporary session files. You probably won't need to
+ adjust this parameter.</dd>
+ <br>
+
+ <dt><tt>CGI_DATE_FORMAT</tt></dt>
+ <br>
+
+ <dd>Configuration string which sets the date format you see when viewing a list
+ of pending e-mails. It defaults to "<tt>%a %1m/%d</tt>" which generates
+ American-style dates like "Mon 12/31".</dd>
+ <br>
+
+ <dt><tt>CGI_PAGER_SIZE</tt><br>
+ </dt>
+ <dd>Maximum number of e-mails shown on a listing page.</dd>
+ <br>
+
+ <dt><tt>CGI_SESSION_EXP</tt><br>
+ </dt>
+ <dd>The number of seconds a session may sit idle before it can expire. Set this
+ to a larger number if you surf pages so slowly that the program makes you
+ log in again.</dd>
+ <br>
+
+ <dt><tt>CGI_USE_JS_CONFIRM</tt><br>
+ </dt>
+ <dd>Set this to 0 if your browser cannot use Javascript or you don't like having
+ to confirm when you delete or blacklist an item.</dd>
+ <br>
+
+ <dt><tt>CGI_USER</tt><br>
+ </dt>
+ <dd>Set this to the user name used by your web server. The default is
+"nobody",
+ but some systems are configured to run as "apache" or other
+low-privilege
+ user.</dd>
+ <br>
+
+</dl>
Index: tmda-cgi.html
===================================================================
RCS file: /cvsroot/tmda/tmda/htdocs/tmda-cgi.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- tmda-cgi.html 1 Dec 2002 05:21:47 -0000 1.1
+++ tmda-cgi.html 2 Dec 2002 23:40:25 -0000 1.2
@@ -1,589 +1,598 @@
-<HTML>
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
<!-- THIS PAGE IS AUTOMATICALLY GENERATED. DO NOT EDIT. -->
-<!-- Sat Nov 30 22:15:47 2002 -->
-<!-- USING HT2HTML 1.2 -->
-<!-- SEE http://barry.wooz.org/software/ht2html -->
+<!-- Mon Dec 2 17:14:26 2002 -->
+<!-- USING HT2HTML 2.0 -->
+<!-- SEE http://ht2html.sf.net -->
<!-- User-specified headers:
[...1124 lines suppressed...]
+
+ <dt><tt>CGI_USE_JS_CONFIRM</tt><br>
+ </dt>
+ <dd>Set this to 0 if your browser cannot use Javascript or you don't like having
+ to confirm when you delete or blacklist an item.</dd>
+ <br>
+
+ <dt><tt>CGI_USER</tt><br>
+ </dt>
+ <dd>Set this to the user name used by your web server. The default is
+"nobody",
+ but some systems are configured to run as "apache" or other
+low-privilege
+ user.</dd>
+ <br>
+
+</dl>
+
+</td><!-- end of body cell -->
+</tr><!-- end of sidebar/body row -->
+</table><!-- end of page table -->
+</body></html>
_______________________________________
tmda-cvs mailing list
http://tmda.net/lists/listinfo/tmda-cvs
