# Pyzor Usage Documentation

$Id: usage.html,v 1.7 2002-09-08 03:33:44 ftobin Exp $

- `pyzor` (client)
- `pyzord` (server)
- Files
- Using Accounts
- User-level Differences from Razor
- Copyright

## `pyzor` (client)

    pyzor [-d] [--homedir dir] command [command_options]

### options

`-d`
  turn on debugging
`--homedir dir`
  use dir as the home directory for Pyzor instead of the default ~/.pyzor. See the files section for more information on what files are inside of the homedir.

### commands

#### General Output

In general, the output from `pyzor command` is of the form:

    ip:port (response-code, response-text) command-specific-output

Note that these are separated by tabs.

`check`

  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.

  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).

  The command-specfic output for a `check` is `report-count whitelist-count`.

`report [--mbox]`

  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.

  If `--mbox` is provided, then the input is assumed to be a unix mailbox, and all messages in it will be sent to the server.

`whitelist [--mbox]`

  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.

  If `--mbox` is provided, then the input is assumed to be a unix mailbox, and all messages in it will be sent to the server.

`discover`

  Finds Pyzor servers, and writes them to ~/.pyzor/servers. This may accomplished through querying already-known servers or an HTTP call to a hard-coded address.

`ping`

  Merely requests a response from the servers.

`shutdown server ...`

  Requests each `server` to be shutdown. Format for `server` is `host:port`.

`genkey`
  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 accounts file. See the section Using Accounts for more information.
`digest [--mbox]`

  Reads on standard input an RFC 822 (email) message. Writes the digest of the message to standard output.

  If `--mbox` is provided, then the input is assumed to be a unix mailbox, each message's digest is written to standard output, separated by newlines.

`predigest`

  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).

### Using the Pyzor client with procmail

To use Pyzor in a procmail system, consider using the following simple recipe.

    :0 Wc
    | pyzor check
    :0 a
    pyzor-caught

If you prefer, you can merely add a header to message marked with Pyzor, instead of immediately filtering them into a separate folder:

    :0 Wc
    | pyzor check
    :0 Waf
    | formail -A 'X-Pyzor: spam'

## Using the Pyzor client with ReadyExec

ReadyExec is a system to eliminate the high startup-cost of executing scripts repeatedly. If you execute `pyzor` a lot, you might be interested in installing ReadyExec and using it with `pyzor`.

To use pyzor with ReadyExec, the readyexecd.py server needs to be started as:

    readyexecd.py socket_file pyzor.client.run

socket_file can be any (non-existing) filename you wish ReadyExec to use, such as `/tmp/pyzor`:

    readyexecd.py /tmp/pyzor pyzor.client.run

Individual clients are then executed as:

    readyexec socket_file options command cmd_options

For example:

    readyexec /tmp/pyzor check
    readyexec /tmp/pyzor report
    readyexec /tmp/pyzor whitelist --mbox
    readyexec /tmp/pyzor -d ping

## `pyzord` (server)

    pyzord [-d] [--homedir dir]

### options

`-d`
  Turn on debugging
`--homedir dir`
  use dir as the home directory for Pyzor instead of the default ~/.pyzor. See the files section for more information on what files are inside of the homedir.

### Signal handling

HUP
  The server will re-open the logfile.
USR1
  The database is 'cleaned up'.

## Files

### `~/pyzor/config`

The format of this file is INI-style (`name=value`, divided into `[sections]`). Names are case insensitive. All values which are filenames can have shell-style tildes (`~`) in them. All values which are relative filenames are interpreted to be relative to the Pyzor homedir.

#### Defaults

    [client]
    ServersFile = servers
    AccountsFile = accounts
    DiscoverServersURL = http://pyzor.sourceforge.net/cgi-bin/inform-servers-0-3-x

    [server]
    Port = 24441
    ListenAddress = 0.0.0.0
    LogFile    = pyzord.log
    PidFile    = pyzord.pid
    DigestDB   = pyzord.db
    PasswdFile = pyzord.passwd
    AccessFile = pyzord.access

#### Definitions

##### `[client]` section

ServersFile
  A newline-separated list of server addresses to report/whitelist/check with. Addresses are in the format `host:port`. Can be populated with `pyzor discover`.
AccountsFile

  File containing information about accounts on servers. Format is line-oriented, with each line being:

      host : port : username : salt,key

  Example:

      127.0.0.1 : 9999 : bob : 227bfb58efaba7c582d9dcb66ab2063d38df2923,8da9f54058c34e383e997f45d6eb74837139f83b

  See the section Using Accounts for more information.

DiscoverServersURL
  During `pyzor discover`, the URL to use in finding servers.

##### `[server]` section

Port
  port to listen on
ListenAddress
  address to listen on
PidFile
  file to contain the process id of the server
LogFile
  file to contain server logs
DigestDB
  file containing the database of digests
PasswdFile

  File containing a list of user account information. Line format:

      username : key

  Example:

      bob : 8da9f54058c34e383e997f45d6eb74837139f83b

AccessFile

  File containing information about user privileges. The format is very similar to the popular tcp_wrappers hosts.{allow,deny}:

      privilege ... : username ... : allow|deny

  privilege ...
    a list of whitespace-separated commands such as `report`, `check`, and `whitelist`, generally corresponding to the Pyzor client commands. The keyword `all` can be used to to refer to all commands.
  username ...
    a list of whitespace-separated usernames. The keyword `all` can be used to refer to all users. The anonymous user is refereed to as `anonymous`.
  allow|deny
    Whether or not the specified user(s) can perform the specified privilege(s) on the line.

  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:

      all : all : deny

  If this file is nonexistant, the following default is used:

      check report ping info : anonymous : allow

## Using Accounts

To get an account on a server requires coordination between the client user and server admin. Use the following steps:

1. 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 `^[-\.\w]+$`. Let us assume they have agreed on 'bob'.

2. User generates a key with `pyzor genkey`, and puts an entry into their ~/.pyzor/accounts. Let us say that it generates the salt,key of: `227bfb58efaba7c582d9dcb66ab2063d38df2923,8da9f54058c34e383e997f45d6eb74837139f83b`. Assuming the server is at 127.0.0.1:9999, the user puts the following entry into ~/.pyzor/accounts:

       127.0.0.1 : 9999 : bob : 227bfb58efaba7c582d9dcb66ab2063d38df2923,8da9f54058c34e383e997f45d6eb74837139f83b

3. The user then sends the key (the part to the right-hand side of the comma) to the admin.

4. The admin adds the following to their ~/.pyzor/pyzord.passwd:

       bob : 8da9f54058c34e383e997f45d6eb74837139f83b

5. Assuming the admin wants to give the privilege of whitelisting (in addition to the normal permissions), the admin then adds the appropriate permissions to ~/.pyzor/pyzord.access:

       check report ping info whitelist : bob : allow

6. The server needs to be restarted in order for this to take effect.

## User-level Differences from Razor

This is a small list of user-recognizable differences between Pyzor and Razor that one might notice if coming from Razor to Pyzor.

- 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.
- Pyzor does not currently implement a web-of-trust system.

## Copyright

Copyright © 2002 Frank J. Tobin ftobin@neverending.org

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.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, visit the following URL: http://www.gnu.org/copyleft/gpl.html.