Provided by: perdition_1.17-5build1_i386 bug

NAME

       perditiondb - perdition modular popmap support

DESCRIPTION

       Perdition  supports  a  dynamic  library  mechanism to access arbitrary
       databases that resolve a user to a host and port.

DATABASE ACCESS LIBRARIES

       If you are using the -s|--default server option then creating an  empty
       database will cause all users to use the default server. Alternatively,
       setting no popmap by passing  an  empty  string  to  the  -m|--map_name
       option  will  cause  no  map lookups to take place and only the default
       server to be used.

       E.g.: perdition -m ""

       In this case, if no default server is set then perdition will still run
       but users will not be able to connect to a real server.

       GDBM

       This  is the default library used by perdition.  The gdbm library reads
       server and port information from  a  GDBM  database.  The  database  is
       opened  each  time  perdition  looks  up  a  server and port pair.  The
       information for each lookup key is stored in a flat file,  popmap  with
       the format:

       <key>:[<username><domain_delimiter>]<host>[:<port>]

       Where: host: hostname or ip address
              port: port name or number

       E.g.

       horms:foo.bar:110
       jain:jane@foo.bar

       A  domain_delimiter  of  "@"  is  used  in the example above.  For more
       information on keys and the domain delimiter, see perdition(8).

       If the -n|--no_lookup option is in effect, then ip addresses  and  port
       names should be used as host and port names will not be resolved.

       To build the flat file into a binary format the makegdbm utility, which
       is provided as part of perdition should be used.

       makegdbm popmap.gdbm.db < popmap

       A makefile is provided and you can  simply  run  make  to  rebuild  the
       popmap.  This  is  installed into /etc/perdition/ in the RPM and Debian
       distributions.

       An alternate location for the popmap.gdbm.db can be specified using the
       -m|--map_library_opt  command line option or configuration file option.

       E.g.

       perdition -m /etc/my_popmap.gdbm.db

       This map library is the default. It may also be used  explicitly,  used
       by  specifying  the full path to the library using the -M|--map_library
       command line option or configuration file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_gdbm.so.0

       Where /usr/lib is the directory in which the perdition  libraries  were
       installed.

       Berkeley DB

       This  is  analogous  to  the  GDBM library, except that a popmap.bdb.db
       should be created using makebdb.

       This library may be used by specifying the full  path  to  the  library
       using  the  -M|--map_library  command line option or configuration file
       option.

       E.g.

       perdition -M /usr/lib/libperditiondb_bdb.so.0

       Where /usr/lib is the directory in which the perdition  libraries  were
       installed.

       YP/NIS

       The NIS library reads a YP/NIS map, the key is the userid, the value is
       the servername.

       The default map name is  ’user_mail_server’,  and  can  be  changed  by
       specifying the map name with the -m flag.

       To use this library, you need to specify:

       perdition -M /usr/lib/libperditiondb_nis.so.0

       Where  /usr/lib  is the directory in which the perdition libraries were
       installed.  You will need to customise your  yp  server’s  Makefile  to
       actually  get a new map on the server. This map library is intended for
       sites that already  have  a  significant  infrastructure  based  around
       YP/NIS.

       POSIX REGULAR EXPRESSIONS

       This  library  allows  users  to  be  looked  matched against a list of
       regular expressions.

       This library can be used by specifying the full  path  to  the  library
       using  the  -M|--map_library  command line option or configuration file
       option.

       E.g.

       perdition -M /usr/lib/libperditiondb_posix_regex.so.0

       Where /usr/lib is the directory in which the perdition  libraries  were
       installed.

       The   regular   expression   is   kept  in  a  flat  file,  by  default
       /etc/perdition/popmap.re .  A sample  map  file  is  shipped  with  the
       source  and  can be found in etc/perdition/popmap.re, this is installed
       into /etc/perdition/popmap.re in the RPM and Debian distributions.  The
       format for the flat file is:

       <regular expression>: [<username><domain_delimiter>]<server>[:<port>]

       A  single  colon  may  follow a regular_expression Some amount of white
       space must follow this colon or the regular_expression if the colon  is
       omitted.  Blank lines are ignored, as is anything including and after a
       # (hash) on a line. If a  precedes a new line then the  lines  will  be
       concatenated.  If a  precedes any other character, including a # (hash)
       it will be treated as a literal. Anything inside single quotes (’) will
       be treated as a literal. Anything other than a (’) inside double quotes
       (") will be treated as a literal. Whitespace  in  a  regular_expression
       must  be  escaped  or  quoted. Whitespace in a substitution need not be
       escaped or quoted.

       Information on setting the domain_delimiter is found  in  perdition(8),
       "@" is used in this example.

       E.g.

       ^[a-k]: localhost
       ^[^a-k]: localhost:110
       ^user: user2@localhost
       (.*)@(.*): $1_$2@localhost

       The  first  matching  regular  expression  will  be  used.  The regular
       expressions are extended posix regular expressions.  The  last  example
       illustrates  the  ability to expand backreferances.  Backreferences may
       be used by inserting $n in the substitution where n  is  in  the  range
       1..9.   The backreference substitution code in this library is courtesy
       of Wim Bonis <bonis@solution-service.de> and in turn the PHP3  project.

       E.g.

       For the regex (.*)@(.*): $1_$2@localhost
       bonis@solution-service.de
       would return
       bonis_solution-service.de@localhost

       Note  that  there is no implicit ^ or $ around the regular expressions.
       The popmap entry  "flim:  localhost"  will  match  "flim",  "flimstix",
       "itsflim"  and  "totallyflimless".  To  only  match "flim" you need the
       popmap entry "^flim$: localhost".

       The map file is read once on startup and cached. This  is  to  increase
       performance  as  the  regular  expressions  must be compiled internally
       before they can be used. The  map  file  can  be  re  read  by  sending
       perdition  a  SIGHUP.  An  alternate  location for the popmap.re can be
       specified  using  the  -m|--map_library_opt  command  line  option   or
       configuration file option.

       E.g.

       perdition -m /etc/perdition/my_popmap.re

       MYSQL

       This map library can be used by specifying the full path to the library
       using the -M|--map_library command line option  or  configuration  file
       option.

       E.g.

       perdition -M /usr/lib/libperditiondb_mysql.so.0

       Where  /usr/lib  is the directory in which the perdition libraries were
       installed.

       The library will connect to a MySQL database and do a query on a  table
       expected to have the columns:

       +------------+--------------+------+-----+---------+-------+
       | Field      | Type         | Null | Key | Default | Extra |
       +------------+--------------+------+-----+---------+-------+
       | user       | varchar(128) |      | PRI |         |       |
       | servername | varchar(255) |      |     |         |       |
       | port       | varchar(8)   | YES  |     | NULL    |       |
       +------------+--------------+------+-----+---------+-------+

       The  fields may be in a different order and other, non-perdition fields
       may also be present in this table. The names  of  the  columns  can  be
       other  than  their  above  defaults  by using the library option string
       described below.  All fields must be  literal  character  strings.  The
       allowed  length  of  the  strings  is  not  important,  however,  it is
       recommended that the length of the user field  be  kept  under  128  to
       avoid    exceeding    perdition’s    internal   query   length   limit,
       PERDITIONDB_MYSQL_QUERY_LENGTH which is 256 by  default.  This  may  be
       altered by recompiling perdition.  The user field must also be a unique
       index as an exact match will be made of this field  from  the  username
       supplied by the user.

       The servername is of the form.

       [<username><domain_delimiter>]<host>[:<port>]

       Where: host: hostname or ip address
              port: port name or number

       If  the  -n|--no_lookup  option is in effect then ip addresses and port
       numbers should be used as host and port names will not be resolved.

       The port is the TCP port to use when connecting  to  the  server.  This
       field can be specified if the back-end server answers on a non-standard
       port (standard ports being 110 for POP3 and 143 for IMAP). Only specify
       this  field  in  the  database  if  you  intend  to  use  POP3  or IMAP
       exclusively as it will try to use this port no matter what protocol  is
       being  used. If POP3 and IMAP are both being used on non-standard back-
       end server ports, those ports can be specified  with  the  -p  argument
       when you invoke the perdition executable.

       The database is accessed each time perdition needs to find the host and
       port for a user.  The default database values are as follows:

       database host:     localhost
       database port:     (MySQL Client Default: usually 3306)
       database name:     dbPerdition
       database table:    tblPerdition
       database user:     perdition
       database password: perdition
       user column:       user
       server column:     servername
       port column:       port

       A script, perditiondb_mysql_makedb, is provided to  initialise  such  a
       database.   Alternate  values can be set using the -m|--map_library_opt
       command line option or configuration file option with  an  argument  of
       the  following  form.  (N.B.: this example has been split over multiple
       lines for ease of reading)

       <dbhost>[:<dbport>[:<dbname>[:<dbtable>[:<dbuser>
       [:<dbpwd>[:<dbsrvcol>[:<dbusercol>[:<dbportcol>]]]]]]]]

       E.g.

       perdition -m "some.host.com:3306:aDb:bTable:cUser:"\
       "dPassword:eSrvCol:fUserCol:gPortCol"

       Arguments may be omitted from the end of  the  option  string  with  no
       consequence  other than that the default value for any omitted argument
       will be used. Arguments may not be omitted if any argument to its right
       is  defined.  Someone  seeking  to  set only the server and password to
       something other than the default might attempt the following:

       perdition -m some.host.com:::::OddPassword

       This will not work. It will set the server and password to  the  values
       shown, but all arguments in between will be set as NULL rather than the
       default. In the author’s opinion it is always best to  specify  all  of
       the arguments to avoid confusion.

       Database servers may be grouped together for higher performance or high
       availability by using ODBC and accessing them using the ODBC module.

       POSTGRESQL

       This is a port of the MySQL library to PostgreSQL, The library  can  be
       used   by   specifying   the   full  path  to  the  library  using  the
       -M|--map_library command line option or configuration file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_mysql.so.0

       Where /usr/lib is the directory in which the perdition  libraries  were
       installed.   A  script,  perditiondb_postgresql_makedb  is  provided to
       initialise the database.  For more information  please  see  the  MySQL
       documentation above.

       ODBC

       This  is  a port of the MySQL library to ODBC. It may be used to access
       databases that do not have a perditiondb module.  It may also  be  used
       to group database servers into clusters.

       The  library  can  be  used  by specifying the full path to the library
       using the -M|--map_library command line option  or  configuration  file
       option.

       E.g.

       perdition -M /usr/lib/libperditiondb_odbc.so.0

       Where  /usr/lib  is the directory in which the perdition libraries were
       installed.  A script, perditiondb_odbc_makedb is provided to seed  the.
       For  more  information  please  see the MySQL documentation above.  The
       database options passed using -m are the same as for MySQL except  that
       the database name (dbname) is the Data Source Name (DSN).

       <dbhost>[:<dbport>[:<DSN>[:<dbtable>[:<dbuser>
       [:<dbpwd>[:<dbsrvcol>[:<dbusercol>[:<dbportcol>]]]]]]]]

       E.g.

       perdition -m "some.host.com:3306:aDb:bTable:cUser:"\
       "dPassword:eSrvCol:fUserCol:gPortCol"

       As  per  the  notes  in  the  MySQL  documentation  above, please avoid
       omitting values.

       LDAP

       This library allows access to LDAP based popmaps. This library  can  be
       used   by   specifying   the   full  path  to  the  library  using  the
       -M|--map_library command line option or configuration file option.

       E.g.

       perdition -M /usr/lib/libperditiondb_ldap.so.0

       Where /usr/lib is the directory in which the perdition  libraries  were
       installed.

       The  search  is  done  using  an LDAP URL.  An alternate URL can be set
       using the -m|--map_library_opt command  line  option  or  configuration
       file  option.   The  default URL is as follows. Note that this has been
       split onto multiple lines for ease of reading.

       ldap://localhost/ou=mailbox,dc=nodomain?
       username,mailhost,port?one?(uid=%s)

       Perdition will replace any instance of %s with the key being  used  for
       the  lookup.  Optionally, there may be an integer between the % and the
       s, in which case the key will be white-space padded to this width, with
       the key right justified.

       The  attribute names (username, mailhost and port) may be changed.  But
       the first attribute will be used as the username, the second  attribute
       as  the  host  and  the  third  atribute  as  the  port. Any subsequent
       attributes will be ignored.  Trailing attributes may also  be  omitted.
       So  if there are only two attributes the port will not be read from the
       database.

       A script, perditiondb_ldap_makedb is provided to initialise LDAP.

       x-bindpw bindname

       Perdition can be configured to use use an alternate bind name, and  the
       non-standard  "x-bindpw". In fact perdition can use any extensions that
       are supported by openldap. (N.B.: these examples have been  split  over
       multiple lines for ease or reading)

       ldap://ldap.mydomain.com/o=domain.com?
       uid,mailhost,port?sub?(uid=%s)?!bindname=uid=perdition%2co=domain.com

       ldap://ldap.mydomain.com/o=domain.com?uid,mailhost,port?
       sub?(uid=%s)?!BINDNAME=uid=perdition%2co=domain.com,X-BINDPW=secret

       The  first example does the usual LDAP lookup, but tries to bind to the
       server  with  "uid=perdition,o=domain.com"  rather   than   the   usual
       anonymous binding.  Note: The commas inside the bind string itself must
       be URL encoded, thus the %2c.

       The second example is the  same  as  the  first,  but  in  addition  to
       specifying  a  bind  string  it  also  uses the non-standard "x-bindpw"
       extension to specify a password, in this case "secret".

       The "!" character is used to ensure Perdition supports  the  "bindname"
       extension.   If it didn’t, the LDAP connection would be aborted.  Right
       now it  isn’t  really  needed,  but  it  may  become  useful  as  other
       extensions appear.  For full details of this, take a look at RFC2255.

       Multiple LDAP Servers

       It  is  possible  to  specify multiple LDAP servers by specifying them,
       space delimited, in the LDAP UDL. If this is the case an  attempt  will
       be  made  to open a connection to each host in order, the first host to
       which a connection is successfully made will be used.

       For example: (N.B.: this example has been split over multiple lines for
       ease or reading)

       ldap://host1 host2 host3/ou=mailbox,dc=nodomain?
       username,mailhost,port?one?(uid=%s)

       perdition.schema

       A  schema  has  been  defined  for perdition and is supplied as part of
       perdition. To use this you should install it on the LDAP server in  the
       LDAP  daemon’s  schema  directory  and  include it in slapd.conf, after
       other includes and before any database definitions.

LIBRARY FUNCTIONS

       The database is accessed using the dlopen(3) mechanism  on  a  library.
       The  library  should  define the symbol dbserver_get with the following
       semantics.

       int (*dbserver_get)(char *, char *, char **, size_t *)

       Find the server (value) given the user (key)

       pre:   key_str: Key as a null terminated string

              options_str: Options string. The usage of this is implementation
              dependent.

              str_return: Value is returned here

              len_return: Length of value is returned here

       post:  The str_key is looked up and the corresponding value is returned
              in str_return and len_return.

       return:
              0 on success

              -1 on db access error This includes file, connection  and  other
              data   access  errors.  It  does  not  cover  memory  allocation
              problems.

              -2 if key cannot be found in map

              -3 on other error

       Note:  The string returned in str_return should  be  in  the  following
              form.    Setting   the  domain_delimiter  is  discussed  in  the
              perdition(8), "@" is used in this example.

              [<username><domain_delimiter>]<servername>[:<port>]

              E.g.:

              localhost:110
              user@localhost:110
              user@localhost
              localhost

       As the library is opened using the dlopen(3) mechanism the library  may
       also  export  functions  _init and _fini that will be executed when the
       library is opened and closed respectively.  In addition if the  symbols
       following   symbols  are defined then these are run when the library is
       opened and closed respectively.  If defined these symbols  should  have
       the following semantics.

       int *(*dbserver_init)(char *)

       Initialise db as necessary

       pre:   options_str: Options string. The usage of this is implementation
              dependent.

       post:  db is initialised

       return:
              0 on success

              -1 on db access error This includes file, connection  and  other
              data   access  errors.  It  does  not  cover  memory  allocation
              problems.

              -2 if key cannot be found in map

              -3 on other error

       int *(*dbserver_fini)(void)

       Shut down db as necessary

       pre:   none

       post:  db is shut down

       return:
              0 on success

              -1 on db access error This includes file, connection  and  other
              data   access  errors.  It  does  not  cover  memory  allocation
              problems.

              -2 if key cannot be found in map

              -3 on other error

       In addition, if a SIGHUP is sent to a process  then  a  signal  handler
       will  call  dbserver_fini if it is defined and then dbserver_init if it
       is defined. Note: dbserver_init will be  called  if  defined,  even  if
       dbserver_fini is not defined.

       In  the  case  of the posix regular expressions library this will cause
       popmap.re to be re-parsed, hence effecting any changes that  have  been
       made to that file. For the GDBM library it will reopen the database and
       for the other libraries it will  reinitialise  its  connection  to  the
       database, LDAP or NIS server.

       The  shared library has access to the following global symbols exported
       by perdition.

       struct utsname *system_uname
              The uname information for the system as per uname(2)

       struct sockaddr_in *peername
              The sockaddr_in for address and port of the client  end  of  the
              connection.

       struct sockaddr_in *sockname
              The  sockaddr_in  for the local address and port that the client
              connected to.  Note: Under Solaris 7 and above, this is actually
              the   sockaddr_in  bound  to,  not  the  address  and  port  the
              connection was accepted on.

SEE ALSO

       perdition(8),         makegdbm(1),         makebdb(1),         make(1),
       perditiondb_mysql_makedb(8),           perditiondb_postgresql_makedb(8)
       perditiondb_ldap_makedb(8), perditiondb_odbc_makedb(8)

AUTHORS

       Lead
       Horms <horms@vergenet.net>

       Perditiondb Library Authors
       Frederic Delchambre <dedel@freegates.be>      (MySQL)
       Chris Stratford: <chriss@uk.uu.net>           (LDAP and BDB)
       Nathan Neulinger <nneul@umr.edu>              (NIS)

       Contributing Authors
       Daniel Roesen <droesen@entire-systems.com>
       Clinton Work <work@scripty.com>
       Youri <ya@linkline.be>
       Jeremy Nelson <jnelson@optusnet.com.au>
       Wim Bonis <bonis@solution-service.de>
       Arvid Requate <arvid@Team.OWL-Online.DE>
       Mikolaj J. Habryn <dichro@rcpt.to>
       Ronny Cook <ronny@asiaonline.net>
       Geoff Mitchell <g.mitchell@videonetworks.com>
       Willi Langenberger <wlang@wu-wien.ac.at>
       Matt Prigge <mprigge@pobox.com>
       Wolfgang Breyha <wolfgang.breyha@uta.at>

                                6th August 2003                 PERDITIONDB(5)