Configuration file documentation

The only purpose of the configuration file is to say ebiff to check mailbox x for new mail and notify the user with y.
Supported mailbox drivers are: maildir, mbox, netin.
Supported notifier drivers are: stdout, gtk2, xosd, flite, sox, utmp, netout, wm.
Sections:

  1. Introduction
  2. Simple example
  3. Some words about LUA
  4. The plugins options
  5. functions.lua
  6. Complex example
  7. Network transparent notification

Introduction

The function call bind(mailbox,notifier) creates a new relation , and adds it to the relation list used by ebiff.
An alternative way of calling bind is to pass a mailbox list or a notifier list instead of a single element. The right syntax to do this is bind({box1,box2,..,boxn},{not1,not2,...,notm}).

Simple example

This is a short example of a configuration file (longer and more complex examples are in /usr/share/doc/ebiff/samples/ in the debian system): 

--
-- This is a sample configuration file for ebiff
--

-- create a mailbox
b_inbox = new{
	type = "mailbox";
	name = "Inbox";
	command = "mutt.sh -f =inbox &";
	driver = {
		type="maildir";
		path = "/home/me/Mail/inbox";
		};
	interval=10;
	}
	
-- create a gtk2 notifier
n_gtk2 = new{
	type = "notifier";
	driver= {
		type="gtk2";
		position="right";
		showall=true;
		}
	}

-- create a xosd notifier
n_osd = new{
	type = "notifier";
	driver= {
		type="xosd";
		}
	}

-- bind them
bind(b_inbox,{n_gtk2,n_osd})

In the example the mailbox b_inbox will be inspected every 10 seconds and eventually both n_gtk2 and n_osd will be used to notify the user.

Some words about LUA

Comments starts with --, strings can be queted with single ' or double " quotes, boolean values are true and false. The syntax and functionalities you can use are really more than these, since the configuration file is a real LUA script (see lua-users for a tutorial). Some syntax peculiarity follow:

The last important thing you must know is that you must use the new function (ok, in the example it has no (), but it is automatically understood by LUA) to create a new mailbox or notifier instance (calling new also adds the id field, this is why it is a required field but not used in the sample configuration).

The plugins options

A relation has the following fields (notice that the tables mailbox and notifier that must be passed to bind are subtables of relation and theys fields are listed here):

functions.lua

In the samples/ directory there are some usefull example of configuration files, and a support file you can cut&paste in your configuration file to make your life easyer. The documentation of functions.lua follows (remember that you can use these support functions also adding a line like: 

dofile("/usr/share/doc/ebiff/samples/functions.lua")

at the beginning of your configuration file, the path used in the example is peculiar to the debian system).

These are the functions defined in functions.lua:

Complex example

This is a more complex example of an auto-updating configuration file that uses the prevoius functions:

-- create a notifier
xosd = new {
	type="notifier";
	driver={
		type="xosd";
		outlineoffset=0;
		shoadowoffset=3;
		color="#00FF00";
		timeout=6;
		align="right";
		pos="bottom";
		voffset=100;
		};

-- create anothe notifier
sox = new {
	type="notifier";
	driver={
		type="sox";
		file="/usr/share/licq/sounds/fun/Online.wav";
		};
}
		
-- get the list of maildirs in ~/Mail
-- os.getenv(name) has the meaning of the omonimous getenv function
-- .. is the string concatenation operator
boxes = find_maildir( os.getenv("HOME") .. "/Mail" )

-- create the name map
map = {	
	["securityfocus"] = "secfoc", 
	["sent-mail"] = "sent",
	["sourceforge"] = "sf.net",
	["lp-forum"] = "lp-frm"
}

-- create the command generator
cmd = function(s) 
	return "xterm -e mutt -f "..s.."&" 
end

-- create a list of mailboxes based on boxes
mailboxes = maildirs2mailboxes(boxes,map,cmd,10)

-- bind all togheter
bind(mailboxes,xosd)

-- bind some mailboex to the sox notifier
bind(selectmailbox(mailboxes,"sf.net"),sox)
bind(selectmailbox(mailboxes,"friends"),sox)

Network transparent notification

Sometimes you need to keep your mail on an host and being notified on another host.

Introduction

ebiff can check mailbox on a computer A and notify the user on a computer B.
To do this the simplest approach is to use the netout/netin plugins. The netout plugin sends notification request, the netin plugin receives notification requests.
You can see the netout plugin as a notifier and the netin plugin as a mailbox.

Configuration

The simplest configuration is to have only the netout notifier on host A and only the netin mailbox on host B. This allows you to have all the mailboxes on A seen as one mailbox on B.

The most complex one is to have one netout notifier for each mailbox on A and a corresponding number of netin mailboxes on B.

The first solution is simpler, but is not enough powerful to allow you to remotely notify different mailboxes with different notifiers. The best solution is to tailor the configuration file on your needs, defining a netout notifier for each set of mailboxes you want to notify with the same notifier.

Security

All network traffic is in clear. If your hosts are conneted by an untrusted network you can user an ssh tunnel to solve the problem.
Consider the example on which you have one netout plugin on host A and port 12345. From B you can simply configure the netin plugin to use localhost as the host and port 12345 and start an ssh tunnel with
ssh -C -L 12345:A:12345 A
To protect your privacy even more it would be easy to patch ebiff netout to accept incoming connection only from localhost or a trusted number of computers, but since now it is not implemented.

$Id: doc.xslt,v 1.13 2004/12/05 17:06:13 gareuselesinge Exp $