$Id: README,v 1.37 2007-05-27 08:42:22 roland Exp $


               The Little Brother's Database
                
          Roland Rosenfeld <[email protected]> (current maintainer)
            Thomas Roessler <[email protected]> (initial author)

This package was inspired by the Big Brother Database package
available for various Emacs mailers, and by Brandon Long's "external
query" patch for the mutt mail user agent (Note that this patch has
been incorporated into the main-line mutt versions as of mutt 0.93.)

The package doesn't use any formal database libraries or languages,
although it should be quite easy to extend it to use, e.g., an
installed PostgreSQL server as it's backend.

For querying the Little Brother, just type "lbdbq <something>". lbdbq
will now attempt to invoke various modules to gather information about
persons matching "<something>". E.g., it may look at a list of
addresses from which you have received mail, it may look at YP maps,
or it may try to finger <something>@<various hosts>.

The behavior is configurable: Upon startup, lbdbq will source the
shell scripts

        /usr/local/etc/lbdb.rc (or where your @sysconfdir@ points to)
        $HOME/.lbdbrc
        $HOME/.lbdb/lbdbrc
        $HOME/.lbdb/rc

if they exist.

They can be used to set the following global variables:

- MODULES_PATH: Where lbdbq should look for modules

- METHODS: What modules to use.

- SORT_OUTPUT: Set this to "false" or "no" and lbdbq won't sort the
  addresses but returns them in reverse order (which means that the
  most recent address in m_inmail database is first).  If you set this
  to "name", lbdbq sorts the output by real name.  If you set this to
  "comment", it sort the output by the comment (for example the date
  in m_inmail). If you set this to "address", lbdbq sorts the output
  by addresses (that's the default).


Note that there _are_ defaults, so you should most probably modify
these variables using constructs like this:

        MODULES_PATH="MODULES_PATH $HOME/lbdb_modules"

Additionally, modules may have configuration variables of their own.

Currently the following modules are supplied with lbdb:

m_finger
       This module will use finger to find out something more about a
       person. The list of hosts do be asked is configurable; use the
       M_FINGER_HOSTS variable. Note that "localhost" will mean an
       invocation of your local finger(1) binary, and should thus work
       even if you don't provide the finger service to the network.
       m_finger tries to find out the machines mail domain name in
       /etc/mailname, by parsing a sendmail.cf file (if it finds one)
       and by reading /etc/hostname and /etc/HOSTNAME.

m_inmail
       This module will look up user name fragments in a list of mail
       addresses created by lbdb-fetchaddr(1).

m_passwd
       This module searches for matching entries in your local
       /etc/passwd file. It evaluates the local machine mail domain in
       the same way m_finger does.  If you set PASSWD_IGNORESYS=true,
       this module ignores all system accounts and only finds UIDs
       between 1000 and 29999 (all other UIDs are reserved on a Debian
       system).

m_yppasswd
       This module searches for matching entries in your NIS password
       file using the command "ypcat passwd".

m_nispasswd
       This module searches for matching entries in the NIS+ password
       database using the command ``niscat passwd.org_dir''.

m_getent
       This module searches for matching entries in whatever password
       database is configured using the command ``getent passwd''.

m_pgp2, m_pgp5, m_gpg
       These modules scan your PGP 2.*, PGP 5.* or GnuPG public key
       ring for data. They use the programs pgp(1), pgpk(1), or gpg(1)
       to get the data.

m_fido 
       This module searches your Fido nodelist, stored in
       $HOME/.lbdb/nodelist created by nodelist2lbdb(1).

m_abook
       This module uses the program abook
       (http://www.linuxstart.com/~jheinonen/abook/), a text based
       address book application to search for addresses.  You can
       define multiple abook address books by setting the variable
       ABOOK_FILES to a space separated list.

m_addr_email
       This module uses addr-email from the addressbook
       (http://red.roses.de/~clemens/addressbook/) Tk program to
       search for addresses.

m_muttalias
       This module searches the variable MUTTALIAS_FILES (a space
       separated list) of files in MUTT_DIRECTORY that contain mutt
       aliases.  File names without leading slash will have
       MUTT_DIRECTORY (defaults to $HOME/.mutt or $HOME, if
       $HOME/.mutt does not exist) prepended before the file name.
       Absolute file names (beginning with /) will be taken direct.

m_pine
       This  module searches pine(1) addressbook files for
       aliases. To realize this it first inspects the variable PINERC.
       If it isn't set, the default `/etc/pine.conf
       /etc/pine.conf.fixed .pinerc' is used. To suppress inspecting
       the PINERC variable, set it to "no". It than takes all
       address-book and global-address-book entries from these pinerc
       files and adds the contents of the variable PINE_ADDRESSBOOKS
       to the list, which defaults to `/etc/addressbook .addressbook'.
       Then these addressbooks are searched for aliases. All filenames
       without leading slash are searched in $HOME.

m_palm
       This module searches the Palm address database using the
       Palm::PDB and Palm::Address Perl modules from CPAN.  It
       searches in the variable PALM_ADDRESS_DATABASE or if this isn't
       set in $HOME/.jpilot/AddressDB.pdb.

m_gnomecard
       This module searches for addresses in your GnomeCard database
       files.  The variable GNOMECARD_FILES is a whitespace separated
       list of GnomeCard data files.  If this variable isn't defined,
       the module searches in $HOME/.gnome/GnomeCard for the GnomeCard
       database or at least falls back to $HOME/.gnome/GnomeCard.gcrd.
       If a filename does not start with a slash, it is prefixed with
       $HOME/.

m_bbdb
       This module searches for addresses in your (X)Emacs BBDB (big
       brother database).  It doesn't access ~/.bbdb directly (yet)
       but calls (x)emacs with a special mode to get the information
       (so don't expect too much performance in this module). You can
       configure the EMACS variable to tell this module which emacsen
       to use.  Otherwise it will fall back to emacs or xemacs.

m_ldap
       This module queries an LDAP server using the Net::LDAP Perl
       modules from CPAN.  It can be configured using an external
       resource file (for more details please refer to the
       mutt_ldap_query(1) manual page).

m_wanderlust
       This module searches for addresses stored in your
       $WANDERLUST_ADDRESSES (or by default in $HOME/.addresses) file,
       an addressbook of WanderLust.

m_osx_addressbook
       This module queries the OS X AddressBook.  It is only available
       on OS X systems.

m_evolution
       This module queries the Ximian Evolution address book using the
       evolution-addressbook-export application.

m_vcf
       This module uses libvformat to search for addresses from the
       space-separated set of vCard files defined in $VCF_FILES.


Feel free to create your own modules to query other kinds of
databases.  m_finger should be a good example of how to do it.

If you create your own modules or have other changes and feel that
they could be helpful for others, don't hesitate to submit them to me
for inclusion in later releases.

Finally, to use lbdbq from mutt, add the following line to your
~/.muttrc:

        set query_command="lbdbq %s"


CREDITS
-------

Most of the really interesting code of this program (namely, the RFC
822 address parser used by lbdb-fetchaddr) was stolen from Michael
Elkins' mutt mail user agent. Additional credits go to Brandon Long
for putting the query functionality into mutt.

Many thanks to the authors of the several modules and extensions:
- Ross Campbell <[email protected]>           (m_abook, m_yppasswd)
- Marc de Courville <[email protected]>           (m_ldap, mutt_ldap_query)
- Brendan Cully <[email protected]>               (m_osx_addressbook, m_vcf)
- Gabor Fleischer <[email protected]>                (m_pine)
- Rick Frankel <[email protected]>                 (m_gnomecard)
- Guido Guenther <[email protected]>                 (m_evolution)
- Utz-Uwe Haus <[email protected]>                    (m_bbdb, m_nispasswd)
- Torsten Jerzembeck <[email protected]> (m_addr_email)
- Gergely Nagy <[email protected]>               (m_wanderlust)
- Dave Pearson <[email protected]>                   (m_palm, lbdb.el)
- Brian Salter-Duke <[email protected]>        (m_muttalias)