PROXY-HOWTO

This file describes how to use OmniBiff as a proxy for other biff
programs. The reason for this is because most desktop environments
have some notion of "applets": the WindowMaker dockapp, BlackBox slit,
Gnome panel, KDE kicker, Enlightenment epplets, and even the tray in MS
Windows. For all of these environments there are existing programs that
check for new email. The proxy mode of OmniBiff adds the ability to
monitor web-based email accounts to these existing programs.

Be aware that OmniBiff only checks for the presence of new email -- it
does not count the number of new messages, examine the headers to see who
the mail is from, clip the first few lines of the mail, or any else like
that. This is because OmniBiff has to work at the least common denominator
of all the servers it supports. If you are using a biff program that
uses these "extra features", they will not work correctly when using
OmniBiff as a proxy. Any account with new mail will be perceived by the
biff program as having one new message of length 100 bytes.


General Procedure
=================

In general, the procedure is to configure OmniBiff to use POP3Skin by
selecting "proxy mode" when configuring it, and then defining any number
of mailboxes to be monitored. Keep the check interval at the default
10 minutes -- it will be ignored by POP3Skin anyway.

The default port number used by POP3Skin is 9000, whereas POP3 servers
normally use port 110. On most UNIX systems, 110 is a priviledged port
and requires root access to run a server on it. I do not recommend running
OmniBiff as root, for security reasons.  Unfortunately some biff programs
are hardwired to use port 110; this can be circumvented by forwarding
port 110 to 9000, either at the kernel-level via ipchains or by running
a user-level program like ssh or zeebeedee with root priviledges. If all
else fails you can run POP3Skin on 110 as root, but be aware that it is
quite likely "exploitable", and you may be putting your system at risk.

After OmniBiff is configured, start it with:

java -jar omnibiff.jar [-p /path/to/config/file]

Let's suppose one of the mailboxes you configured was a Hotmail account
with the name "hotmail". To have a biff program monitor this account,
configure it to check a POP3 account on localhost port 9000, username
"hotmail", and password "hotmail". Set the check interval to to whatever
you wish -- the interval you specify will control OmniBiff, regardless
of the period specified when hotmail was defined to OmniBiff (unlike
the other skins, POP3Skin suspends each bifflet between queries). You
can repeat this for each mailbox you wish to monitor, assuming you have
a biff program that supports multiple accounts.


Specific Examples
=================

These examples assume that you have defined a mailbox in OmniBiff for
monitoring Hotmail, and the name of the mailbox is "hotmail". The proxy
port is 9000.


KBiff
-----
  Define a profile called Hotmail. In the "Mailbox" tab, set:

  o  Protocol --> POP3
  o  Server   --> localhost
  o  Password --> hotmail
  o  Select "Store password"
  o  User     --> hotmail
  o  Click the "Advanced" button and enter 9000 for the port

  For some types of accounts, you may need to suspend KBiff while you
  are reading your email in order to keep your session from getting
  clobbered by subsequent biff checks. You can do this by selecting
  "Stop" and "Start" in the KBiff popup menu.


Gkrellm
-------
  To use the builtin POP3 feature, you will need to either forward
  port 110 to 9000, or run Omnibiff as root with the proxy on port 110.
  Alternatively, you can use omnifetch as a fetchmail replacement, but
  then you won't be able to monitor multiple accounts.  Both methods
  are described below.
  
  Note that you can temporarily suspend email checking by "muting"
  the mail krell.

  Builtin
  -------
  Bring up the configuration tool for the "Mail" builtin. In the
  "Mailboxes" tab, add a mailbox with the line:

  localhost hotmail hotmail

  Under the "Options" tab, set:

  o  Message Counting --> do not count
  o  Mute mode inhibits all mail checking, not just notify (sound) program
  o  List mailboxes containing new mail in a tooltip

  Fetchmail
  ---------
  **NOTE  This method uses Omnibiff in "external client" mode rather than
          proxy mode.

  In the "Setup" tab, enter:

  o  Mail fetch/check program --> /usr/local/bin/omnifetch -d hotmail
  
  In the "Mailboxes" tab, add a mailbox with the line:

  localhost hotmail hotmail

  In the "Options" tab, set:

  o  Message Counting --> do not count
  o  Fetch/check program checks messages only
  o  Mute mode inhibits all mail checking, not just notify (sound) program


gbiff
-----
  This program is hardcoded to use port 110 for POP3, so you will have
  to either forward port 110 to 9000 or else run POP3Skin as root on
  port 110.

  In the "Mailbox" tab of the properties dialog, enter:

  o  Protocol --> pop3
  o  Address  --> localhost
  o  User     --> hotmail
  o  Password --> hotmail
  o  Options: --> No title, No date (or No popup)

  Gbiff doesn't appear to have any way to temporarily suspend checking,
  which may cause problems with session-oriented web email accounts. Note
  that you can run multiple instances of gbiff to monitor more than
  one account.