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:
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}).
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.
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).
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):
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:
mailboxes=find_maildir(os.getenv("HOME").."/Mail")finds the maildirs that are inside ~/Mail/, and puts the list of theyr path in mailboxes.
mailboxes=find_mbox(os.getenv("HOME").."/Mail")finds the mboxes that are inside ~/Mail/, and puts the list of theyr path in mailboxes. Remember that is up to you to specify a directory containing only subdirectories or mbox files. All files beginning with . will be skipped.
{["securityfocus"] = "secfoc", ["sent-mail"] = "sent" }cmdgen is a command generator function, I use
function(s) return "xterm -e mutt -f "..s.."&" endinterval is the parameter used for creating all the mailboxes, and has the same meaning of the omonimous paramenter for a mailbox table.
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)
Sometimes you need to keep your mail on an host and being notified on another host.
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.
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.
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.