<?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>
distrib
>
Fedora
>
13
>
i386
>
media
>
os
>
by-pkgid
>
b82d4713a2a438897dfba836e4a8fd3a
>
files
>
20
