head	1.2;
access;
symbols
	TIGRIS_1_1_0RC2:1.2
	TIGRIS_1_1_0RC1:1.2
	EB_WM:1.2
	TIGRIS_1_1:1.2.0.12
	TIGRIS_1_0_8:1.2
	TIGRIS_1_0_8RC3:1.2
	TIGRIS_1_0_8RC2:1.2
	TIGRIS_1_0_8RC1:1.2
	TIGRIS_1_0_7:1.2
	TIGRIS_1_0_7RC3:1.2
	TIGRIS_1_0_7RC2:1.2
	TIGRIS_1_0_7RC1:1.2
	TIGRIS_1_0_6:1.2
	TIGRIS_1_0_6RC5:1.2
	TIGRIS_1_0_6RC4:1.2
	TIGRIS_1_0_6RC3:1.2
	TIGRIS_1_0_6RC2:1.2
	TIGRIS_1_0_6RC1:1.2
	TIGRIS_1_0_5:1.2
	TIGRIS_1_0_5RC6:1.2
	TIGRIS_1_0_5RC5:1.2
	TIGRIS_1_0_5RC4:1.2
	TIGRIS_1_0_5RC3:1.2
	TIGRIS_1_0_5RC2:1.2
	TIGRIS_1_0_5RC1:1.2
	TIGRIS_1_0_4:1.2
	TIGRIS_1_0_3:1.2
	TIGRIS_1_0_2:1.2
	TIGRIS_1_0_1:1.2
	TIGRIS_1_0:1.2.0.14
	TIGRIS_1_0_0:1.2
	TIGRIS_1_0_0_RC1:1.2.0.10
	HELM_PEER_PORT_BRANCH:1.2.0.8
	TIGRIS_0_9_2_4:1.2
	TIGRIS_0_9_2_3:1.2
	TIGRIS_0_9_2:1.2.0.6
	TIGRIS_0_9_0:1.2.0.4
	TIGRIS_0_8_4:1.2.0.2
	EYEBROWSE_WM_0_89:1.2
	pre-joist:1.1;
locks; strict;
comment	@# @;


1.2
date	2000.10.12.17.46.24;	author ms;	state Exp;
branches;
next	1.1;

1.1
date	2000.09.08.01.36.53;	author ms;	state Exp;
branches;
next	;


desc
@@


1.2
log
@Added comments on the crons now being packaged with eyebrowse.
Submitted by:	Michael Salmon
@
text
@Using Eyebrowse
---------------

The primary interface for administering eyebrowse is through a perl
script called eyebrowse.  

Eyebrowse maintains a set of mailing lists, each of which can contain
one or more mailbox files.  Mailbox files are stored in standard unix
"mbox" format.  The mailbox files should be added to the list in
chronological order, and only the last file in a list is considered to
be active.  You could have one mailbox file per list, or one per
month, or one per year -- however your mailbox file are currently
stored will probably be fine.  Lists can also be indexed so that they
can be searched.

You will need to set up the lists through the eyebrowse command line
tool.  Periodically, you may need to add files to the lists (for
example, if messages are stored one list per month, each month, you'll
want to add the new file to the list at the beginning of each month.)
More often (daily, hourly, however often you want) you'll want to
update the lists and search indices so that the users will see the
most recent message data.  Packaged with eyebrowse in src/cron/ are
two example cron jobs you can use to run updateList once an hour and 
updateIndex once per day.  (For more information reference the crons themselves)

You can use the following commands to manage eyebrowse:

To add a new list to eyebrowse: 
% eyebrowse addlist list-name list-description

If you want the list to support text indexing (searching), also do this: 
% eyebrowse addindex list-name index-directory

where index-directory is a directory the indexer can use to store the text
index information.  The contents of that directory will be overwritten.  

To add a new mbox file to a list (files are added to the list in
chronological order; you could have one mbox per list, or you might
have one mbox per month.  Only the last mbox file in a list is
considered active at any time.)
% eyebrowse addlistfile list-name file-path

To update the database (add any new messages that have been received
since the last update), use the updatelist command.  This should be done
frequently.  Also, see the information on the "safeupdate" command for 
important warnings on mail file locking.
% eyebrowse updatelist list-name

If the list is indexed, also do this to update the text search index.  This
does not have to be done at the same time as the updatelist (or safeupdate.)  
% eyebrowse updateindex list-name

Alternately, you can update all lists and indices at once by: 
% eyebrowse update

The last (update) commands would likely be run periodically by a cron
job.


Important note -- File locking.  To prevent conflicts like the sendmail
programs trying to add new content to the end of a mailbox file while
UpdateList is reading it, you'll need to lock the mailbox files before
you run updatelist / update, or ensure that sendmail is not running at
the same time you'll be doing your eyebrowse updates.  Unfortunately,
there's no portable Java way to do file locking.  

In the eyebrowse (perl) script, there is a way to invoke updatelist in a
more safe manner (updateindex is not susceptible to file locking
problems).  You can invoke it as follows: 

% eyebrowse safeupdate list-name
% (optional) eyebrowse updateindex list-name

and it will run updatelist wrapped with the appropriate locks.

The perl locking doesn't work for mail files mounted across NFS, so in
that situation, you will have to fall back on the more primitive
"dotfile locking".  The widely-used procmail package contains a
program for locking mailbox files, which can be used for this purpose.
You could invoke it as follows (which would lock all mail files, update
all the lists, and unlock the files): 

  lockfile mail-dir/*.mbox 
  eyebrowse update
  rm -f mail-dir/*.mbox.lock


Eyebrowse Commands -- Summary
-----------------------------

% eyebrowse addlist list-name list-description
  Add a new list to the eyebrowse database

% eyebrowse addlistfile list-name file-path
  Add a new file to an existing list.  This new file becomes the active 
  mailbox file for that list.  Make sure that the previously active file
  (if any) has been fully updated (eyebrowse updatelist) before adding
  a new file to a list.  

% eyebrowse addindex list-name index-path
  Add a text search index to a list.  

% eyebrowse deletelist list-name
  Completely remove a list from the eyebrowse database

% eyebrowse deleteindex list-name
  Remove the text search index from a list.

% eyebrowse updatelist list-name
  Scan the active list file for new messages and add them to the database

% eyebrowse safeupdate list-name
  Perform an updatelist, using the perl-based mailbox file locking

% eyebrowse updateindex list-name
  Update the text search index associated with a list

% eyebrowse update
  Update all lists and indices.  Does NOT perform file locking

% eyebrowse getlists 
  Retrieve and print out all the lists managed by eyebrowse

% eyebrowse getlistfile list-name
  Get the path of the active mailbox file for the specified list

@


1.1
log
@Moved meta-files from eyebrowe/ to eyebrowse/docs
@
text
@d22 3
a24 1
most recent message data.
@

