566 lines
14 KiB
HTML
566 lines
14 KiB
HTML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
|
|
"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en-us">
|
|
<head>
|
|
<title>Pyzor Usage Documentation</title>
|
|
</head>
|
|
|
|
<body>
|
|
<h1>Pyzor Usage Documentation</h1>
|
|
|
|
<p id="cvsid">$Id: usage.html,v 1.11 2002-10-10 21:37:08 ftobin Exp $</p>
|
|
|
|
<ul>
|
|
<li><a href="#client"><kbd>pyzor</kbd> (client)</a></li>
|
|
<li><a href="#server"><kbd>pyzord</kbd> (server)</a></li>
|
|
<li><a href="#files">Files</a></li>
|
|
<li><a href="#using-accounts">Using Accounts</a></li>
|
|
<li><a href="#razor-diff">User-level Differences from Razor</a></li>
|
|
<li><a href="#copyright">Copyright</a></li>
|
|
</ul>
|
|
|
|
<h2 id="client"><kbd>pyzor</kbd> (client)</h2>
|
|
|
|
<pre>
|
|
pyzor [-d] [--homedir <var class="filename">dir</var>] <var>command</var> [<var>command_options</var>]
|
|
</pre>
|
|
|
|
<h3 id="options">options</h3>
|
|
|
|
<dl>
|
|
<dt><kbd>-d</kbd></dt>
|
|
<dd>turn on debugging</dd>
|
|
|
|
<dt id="pyzor-homedir"><kbd>--homedir <var class="filename">dir</var></kbd></dt>
|
|
<dd>
|
|
use <var>dir</var> as the home directory
|
|
for Pyzor instead of the default
|
|
<span class="filename">~/.pyzor</span>.
|
|
See the <a href="#files">files section</a> for
|
|
more information on what files are inside of the
|
|
homedir.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<h3 id="commands">commands</h3>
|
|
|
|
<h4>General Output</h4>
|
|
|
|
<p>
|
|
In general, the output from <kbd>pyzor <var>command</var></kbd>
|
|
is of the form:
|
|
</p>
|
|
<pre>
|
|
<var>ip</var>:<var>port</var> (<var>response-code</var>, <var>response-text</var>) <var>command-specific-output</var>
|
|
</pre>
|
|
<p>
|
|
Note that these are separated by tabs.
|
|
</p>
|
|
|
|
<dl>
|
|
<dt id="check"><kbd>check</kbd></dt>
|
|
<dd>
|
|
<p>
|
|
Reads on standard input an RFC 822 (email) message.
|
|
Exit code is zero (0) if and only if a match is found
|
|
and the global whitelist count is zero.
|
|
</p>
|
|
<p>
|
|
If multiple servers are listed in the configuration file,
|
|
the exit code will be zero (0) if and only if there
|
|
is a match found on at least one server (without it
|
|
being whitelisted anyplace).
|
|
</p>
|
|
|
|
<p>
|
|
The command-specfic output for a <kbd>check</kbd> is
|
|
<samp><var>report-count</var> <var>whitelist-count</var></samp>.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt id="report"><kbd>report [--mbox]</kbd></dt>
|
|
<dd>
|
|
<p>
|
|
Reads on standard input an RFC 822 (email) message.
|
|
Reports to the server a digest of each message
|
|
in the mailbox as spam. Writes to standard output
|
|
a tuple of (error-code, message) from the server.
|
|
</p>
|
|
<p>
|
|
If <kbd>--mbox</kbd> is provided, then the input is
|
|
assumed to be a unix mailbox, and all messages in it
|
|
will be sent to the server.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt id="whitelist"><kbd>whitelist [--mbox]</kbd></dt>
|
|
<dd>
|
|
<p>
|
|
Reads on standard input an RFC 822 (email) message.
|
|
Sends to the server a digest of each message
|
|
in the mailbox for whitelisting. Writes to standard output
|
|
a tuple of (error-code, message) from the server.
|
|
</p>
|
|
<p>
|
|
If <kbd>--mbox</kbd> is provided, then the input is
|
|
assumed to be a unix mailbox, and all messages in it
|
|
will be sent to the server.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt id="discover"><kbd>discover</kbd></dt>
|
|
<dd>
|
|
<p>
|
|
Finds Pyzor servers, and writes them to
|
|
<span class="filename">~/.pyzor/servers</span>.
|
|
This may accomplished through querying already-known
|
|
servers or an HTTP call to a hard-coded address.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt id="ping"><kbd>ping</kbd></dt>
|
|
<dd>
|
|
<p>Merely requests a response from the servers.</p>
|
|
</dd>
|
|
|
|
<dt id="genkey"><kbd>genkey</kbd></dt>
|
|
<dd>
|
|
Based upon a secret passphrase gathered from the user
|
|
and salt gathered from /dev/random, prints to
|
|
standard output a tuple of "salt,key".
|
|
Used to put account information into the
|
|
<span class="filename">accounts</span> file.
|
|
See the section <a href="#using-accounts">Using Accounts</a>
|
|
for more information.
|
|
</dd>
|
|
|
|
<dt id="digest"><kbd>digest [--mbox]</kbd></dt>
|
|
<dd>
|
|
<p>
|
|
Reads on standard input an RFC 822 (email) message.
|
|
Writes the digest of the message to standard output.
|
|
</p>
|
|
<p>
|
|
If <kbd>--mbox</kbd> is provided, then the input is
|
|
assumed to be a unix mailbox, each message's digest
|
|
is written to standard output, separated by newlines.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt id="predigest"><kbd>predigest</kbd></dt>
|
|
<dd>
|
|
<p>
|
|
Reads on standard input an RFC 822 (email) message.
|
|
Writes to standard output the normalized lines
|
|
of data that are digested, with the exception
|
|
that the lines printed have newlines (all whitespace
|
|
is removed before digesting).
|
|
</p>
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
|
|
<h3>Using the Pyzor client with procmail</h3>
|
|
|
|
<p>
|
|
To use Pyzor in a procmail system, consider using the following
|
|
simple recipe.
|
|
</p>
|
|
|
|
<pre>
|
|
:0 Wc
|
|
| pyzor check
|
|
:0 a
|
|
pyzor-caught
|
|
</pre>
|
|
|
|
<p>
|
|
If you prefer, you can merely add a header to message
|
|
marked with Pyzor, instead of immediately filtering them
|
|
into a separate folder:
|
|
</p>
|
|
|
|
<pre>
|
|
:0 Wc
|
|
| pyzor check
|
|
:0 Waf
|
|
| formail -A 'X-Pyzor: spam'
|
|
</pre>
|
|
|
|
<h2>Using the Pyzor client with
|
|
<a href="http://readyexec.sourceforge.net/">ReadyExec</a></h2>
|
|
|
|
<p>
|
|
<a href="http://readyexec.sourceforge.net/">ReadyExec</a>
|
|
is a system to eliminate the high startup-cost
|
|
of executing scripts repeatedly. If you execute
|
|
<kbd>pyzor</kbd> a lot, you might be interested in installing
|
|
ReadyExec and using it with <kbd>pyzor</kbd>.
|
|
</p>
|
|
|
|
<p>
|
|
To use pyzor with ReadyExec, the readyexecd.py server
|
|
needs to be started as:
|
|
</p>
|
|
|
|
<pre>
|
|
readyexecd.py <var>socket_file</var> pyzor.client.run
|
|
</pre>
|
|
|
|
<p>
|
|
<var>socket_file</var> can be any (non-existing)
|
|
filename you wish ReadyExec
|
|
to use, such as <kbd class="filename">/tmp/pyzor</kbd>:
|
|
</p>
|
|
|
|
<pre>
|
|
readyexecd.py /tmp/pyzor pyzor.client.run
|
|
</pre>
|
|
|
|
<p>
|
|
Individual clients are then executed as:
|
|
</p>
|
|
|
|
<pre>
|
|
readyexec <var>socket_file</var> <var>options</var> <var>command</var> <var>cmd_options</var>
|
|
</pre>
|
|
|
|
<p>
|
|
For example:
|
|
</p>
|
|
|
|
<pre>
|
|
readyexec /tmp/pyzor check
|
|
readyexec /tmp/pyzor report
|
|
readyexec /tmp/pyzor whitelist --mbox
|
|
readyexec /tmp/pyzor -d ping
|
|
</pre>
|
|
|
|
|
|
<h2 id="server"><kbd>pyzord</kbd> (server)</h2>
|
|
|
|
<pre>
|
|
pyzord [-d] [--homedir <var>dir</var>]
|
|
</pre>
|
|
|
|
<p>
|
|
Note: pyzord does not daemonize itself.
|
|
</p>
|
|
|
|
<p>
|
|
Note: logging information is written to standard output.
|
|
</p>
|
|
|
|
<h3>options</h3>
|
|
|
|
<dl>
|
|
<dt><kbd>-d</kbd></dt>
|
|
<dd>Turn on debugging (writes information to standard error)</dd>
|
|
|
|
<dt id="pyzord-homedir"><kbd>--homedir <var class="filename">dir</var></kbd></dt>
|
|
<dd>
|
|
use <var>dir</var> as the home directory
|
|
for Pyzor instead of the default
|
|
<span class="filename">~/.pyzor</span>.
|
|
See the <a href="#files">files section</a> for
|
|
more information on what files are inside of the
|
|
homedir.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<h2 id="files">Files</h2>
|
|
|
|
<h3 id="config"><kbd>~/pyzor/config</kbd></h3>
|
|
|
|
<p>
|
|
The format of this file is INI-style
|
|
(<kbd><var>name</var>=<var>value</var></kbd>,
|
|
divided into <kbd>[<var>sections</var>]</kbd>).
|
|
Names are case insensitive.
|
|
All values which are filenames can have shell-style tildes
|
|
(<kbd>~</kbd>) in them. All values which are relative
|
|
filenames are interpreted to be relative to the Pyzor
|
|
<a href="#pyzor-homedir">homedir</a>.
|
|
</p>
|
|
|
|
<h4>Defaults</h4>
|
|
|
|
<pre>
|
|
<a href="#section-client">[client]</a>
|
|
<a href="#ServersFile">ServersFile</a> = servers
|
|
<a href="#AccountsFile">AccountsFile</a> = accounts
|
|
<a href="#DiscoverServersURL">DiscoverServersURL</a> = http://pyzor.sourceforge.net/cgi-bin/inform-servers-0-3-x
|
|
<a href="#Timeout">Timeout</a> = 5
|
|
|
|
<a href="#section-server">[server]</a>
|
|
<a href="#Port">Port</a> = 24441
|
|
<a href="#ListenAddress">ListenAddress</a> = 0.0.0.0
|
|
<a href="#DigestDB">DigestDB</a> = pyzord.db
|
|
<a href="#PasswdFile">PasswdFile</a> = pyzord.passwd
|
|
<a href="#AccessFile">AccessFile</a> = pyzord.access
|
|
</pre>
|
|
|
|
<h4>Definitions</h4>
|
|
|
|
<h5 id="section-client"><kbd>[client]</kbd> section</h5>
|
|
|
|
<dl>
|
|
<dt id="ServersFile">ServersFile</dt>
|
|
<dd>
|
|
A newline-separated list of server addresses to
|
|
report/whitelist/check with. Addresses are in the format
|
|
<kbd>host:port</kbd>. Can be populated with
|
|
<kbd>pyzor discover</kbd>.
|
|
</dd>
|
|
|
|
<dt id="AccountsFile">AccountsFile</dt>
|
|
<dd>
|
|
<p>
|
|
File containing information about accounts on servers.
|
|
Format is line-oriented, with each line being:
|
|
</p>
|
|
|
|
<pre>
|
|
<var>host</var> : <var>port</var> : <var>username</var> : <var>salt,key</var>
|
|
</pre>
|
|
|
|
<p>Example:</p>
|
|
|
|
<pre>
|
|
127.0.0.1 : 9999 : bob : 227bfb58efaba7c582d9dcb66ab2063d38df2923,8da9f54058c34e383e997f45d6eb74837139f83b
|
|
</pre>
|
|
|
|
<p>
|
|
See the section <a href="#using-accounts">Using Accounts</a>
|
|
for more information.
|
|
</p>
|
|
</dd>
|
|
|
|
<dt id="DiscoverServersURL">DiscoverServersURL</dt>
|
|
<dd>
|
|
During <kbd>pyzor discover</kbd>, the URL to use
|
|
in finding servers.
|
|
</dd>
|
|
|
|
<dt id="Timeout">Timeout</dt>
|
|
<dd>
|
|
Number of seconds to wait for response to a query.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<h5 id="section-server"><kbd>[server]</kbd> section</h5>
|
|
|
|
<dl>
|
|
<dt id="Port">Port</dt>
|
|
<dd>port to listen on </dd>
|
|
|
|
<dt id="ListenAddress">ListenAddress</dt>
|
|
<dd>address to listen on</dd>
|
|
|
|
<dt id="DigestDB">DigestDB</dt>
|
|
<dd>file containing the database of digests</dd>
|
|
|
|
<dt id="PasswdFile">PasswdFile</dt>
|
|
<dd>
|
|
<p>
|
|
File containing a list of user account information.
|
|
Line format:
|
|
</p>
|
|
|
|
<pre>
|
|
<var>username</var> : <var>key</var>
|
|
</pre>
|
|
|
|
<p>Example:</p>
|
|
<pre>
|
|
bob : 8da9f54058c34e383e997f45d6eb74837139f83b
|
|
</pre>
|
|
|
|
</dd>
|
|
|
|
<dt id="AccessFile">AccessFile</dt>
|
|
<dd>
|
|
<p>
|
|
File containing information about user privileges.
|
|
The format is very similar to the popular tcp_wrappers
|
|
hosts.{allow,deny}:
|
|
</p>
|
|
<pre>
|
|
<var>privilege ...</var> : <var>username ...</var> : allow|deny
|
|
</pre>
|
|
|
|
<dl>
|
|
<dt><var>privilege ...</var></dt>
|
|
<dd>
|
|
a list of whitespace-separated commands such as
|
|
<kbd>report</kbd>, <kbd>check</kbd>, and <kbd>whitelist</kbd>,
|
|
generally corresponding to the Pyzor client commands.
|
|
The keyword <kbd>all</kbd> can be used to to refer
|
|
to all commands.
|
|
</dd>
|
|
|
|
<dt><var>username ...</var></dt>
|
|
<dd>
|
|
a list of whitespace-separated usernames.
|
|
The keyword <kbd>all</kbd> can be used to refer to
|
|
all users. The anonymous user is refereed to as
|
|
<kbd>anonymous</kbd>.
|
|
</dd>
|
|
|
|
<dt>allow|deny</dt>
|
|
<dd>
|
|
Whether or not the specified user(s)
|
|
can perform the specified privilege(s) on the line.
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<p>
|
|
The file is processed from top to bottom, with the first
|
|
match for user/privilege being the value taken.
|
|
Every file has the following implicit final rule:
|
|
</p>
|
|
|
|
<pre>
|
|
all : all : deny
|
|
</pre>
|
|
|
|
<p>
|
|
If this file is nonexistant, the following default is used:
|
|
</p>
|
|
|
|
<pre>
|
|
check report ping info : anonymous : allow
|
|
</pre>
|
|
|
|
</dd>
|
|
|
|
</dl>
|
|
|
|
<h2 id="using-accounts">Using Accounts</h2>
|
|
|
|
<p>
|
|
To get an account on a server requires coordination
|
|
between the client user and server admin.
|
|
Use the following steps:
|
|
</p>
|
|
|
|
<ol>
|
|
<li>
|
|
User and admin should agree on a username for the user.
|
|
Allowed characters for a username are alpha-numerics,
|
|
the underscore, and dashes. The normative regular expression
|
|
it must match is <kbd>^[-\.\w]+$</kbd>. Let us assume
|
|
they have agreed on 'bob'.
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
User generates a key with <kbd>pyzor genkey</kbd>, and
|
|
puts an entry into their
|
|
<span class="filename">~/.pyzor/accounts</span>.
|
|
Let us say that it generates the salt,key of:
|
|
<samp>227bfb58efaba7c582d9dcb66ab2063d38df2923,8da9f54058c34e383e997f45d6eb74837139f83b</samp>.
|
|
Assuming the server is at 127.0.0.1:9999, the user puts
|
|
the following entry into
|
|
<span class="filename">~/.pyzor/accounts</span>:
|
|
</p>
|
|
<pre>
|
|
127.0.0.1 : 9999 : bob : 227bfb58efaba7c582d9dcb66ab2063d38df2923,8da9f54058c34e383e997f45d6eb74837139f83b
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
The user then sends the key (<em>the part to the
|
|
<strong>right</strong>-hand
|
|
side of the comma</em>) to the admin.
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
The admin adds the following to their
|
|
<span class="filename">~/.pyzor/pyzord.passwd</span>:
|
|
</p>
|
|
<pre>
|
|
bob : 8da9f54058c34e383e997f45d6eb74837139f83b
|
|
</pre>
|
|
</li>
|
|
|
|
<li>
|
|
<p>
|
|
Assuming the admin wants to give the privilege of whitelisting
|
|
(in addition to the normal permissions),
|
|
the admin then adds the appropriate permissions to
|
|
<span class="filename">~/.pyzor/pyzord.access</span>:
|
|
</p>
|
|
|
|
<pre>
|
|
check report ping info whitelist : bob : allow
|
|
</pre>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
The server needs to be restarted in order for this to take
|
|
effect.
|
|
</li>
|
|
|
|
</ol>
|
|
|
|
|
|
<h2 id="razor-diff">User-level Differences from Razor</h2>
|
|
|
|
<p>
|
|
This is a small list of user-recognizable differences
|
|
between Pyzor and Razor that one might notice if coming
|
|
from Razor to Pyzor.
|
|
</p>
|
|
|
|
<ul>
|
|
<li>
|
|
Pyzor does not consult a whitelist system for you
|
|
before checking whether to send a message. This is best
|
|
handled by other systems, such as other procmail rules.
|
|
</li>
|
|
<li>
|
|
Pyzor does not currently implement a web-of-trust system.
|
|
</li>
|
|
</ul>
|
|
|
|
<h2 id="copyright">Copyright</h2>
|
|
|
|
<p>
|
|
Copyright © 2002-9 Frank J. Tobin
|
|
<a href="mailto:ftobin@neverending.org">ftobin@neverending.org</a>
|
|
</p>
|
|
|
|
<p>
|
|
This program is free software; you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License as published by
|
|
the Free Software Foundation; either version 2 of the License, or
|
|
(at your option) any later version.
|
|
</p>
|
|
|
|
<p>
|
|
This program is distributed in the hope that it will be useful,
|
|
but <strong>without any warranty</strong>;
|
|
without even the implied warranty of
|
|
<strong>merchantability or fitness for a particular purpose</strong>.
|
|
See the <a href="http://www.gnu.org/copyleft/gpl.html">GNU
|
|
General Public License</a> for more details.
|
|
</p>
|
|
|
|
<p>
|
|
You should have received a copy of the GNU General Public License
|
|
along with this program; if not, visit the following URL:
|
|
<a href="http://www.gnu.org/copyleft/gpl.html">http://www.gnu.org/copyleft/gpl.html</a>.
|
|
</p>
|
|
|
|
</body>
|
|
</html>
|