1PERDITIONDB(5) File Formats Manual PERDITIONDB(5)
2
6 perditiondb - perdition modular popmap support
7
9 Perdition supports a dynamic library mechanism to access arbitrary
10 databases that resolve a user to a host and port.
11
13 If you are using the -s|--default server option then creating an empty
14 database will cause all users to use the default server. Alternatively,
15 setting no popmap by passing an empty string to the -m|--map_name
16 option will cause no map lookups to take place and only the default
17 server to be used.
18 E.g.: perdition -m ""
20 In this case, if no default server is set then perdition will still run
22 but users will not be able to connect to a real server.
23 GDBM
25 This is the default library used by perdition. The gdbm library reads
27 server and port information from a GDBM database. The database is
28 opened each time perdition looks up a server and port pair. The infor‐
29 mation for each lookup key is stored in a flat file, popmap with the
30 format:
31 <key>:[<username><domain_delimiter>]<host>[:<port>]
33 Where: host: hostname or ip address
35 port: port name or number
36 E.g.
38 horms:foo.bar:110
40 jain:jane@foo.bar
41 A domain_delimiter of "@" is used in the example above. For more
43 information on keys and the domain delimiter, see perdition(8).
44 If the -n|--no_lookup option is in effect, then ip addresses and port
46 names should be used as host and port names will not be resolved.
47 To build the flat file into a binary format the makegdbm utility, which
49 is provided as part of perdition should be used.
50 makegdbm popmap.gdbm.db < popmap
52 A makefile is provided and you can simply run make to rebuild the
54 popmap. This is installed into /etc/perdition/ in the RPM and Debian
55 distributions.
56 An alternate location for the popmap.gdbm.db can be specified using the
58 -m|--map_library_opt command line option or configuration file option.
59 E.g.
61 perdition -m /etc/my_popmap.gdbm.db
63 This map library is the default. It may also be used explicitly, used
65 by specifying the full path to the library using the -M|--map_library
66 command line option or configuration file option.
67 E.g.
69 perdition -M /usr/lib/libperditiondb_gdbm.so.0
71 Where /usr/lib is the directory in which the perdition libraries were
73 installed.
74 Berkeley DB
77 This is analogous to the GDBM library, except that a popmap.bdb.db
79 should be created using makebdb.
80 This library may be used by specifying the full path to the library
82 using the -M|--map_library command line option or configuration file
83 option.
84 E.g.
86 perdition -M /usr/lib/libperditiondb_bdb.so.0
88 Where /usr/lib is the directory in which the perdition libraries were
90 installed.
91 YP/NIS
94 The NIS library reads a YP/NIS map, the key is the userid, the value is
96 the servername.
97 The default map name is 'user_mail_server', and can be changed by spec‐
99 ifying the map name with the -m flag.
100 To use this library, you need to specify:
102 perdition -M /usr/lib/libperditiondb_nis.so.0
104 Where /usr/lib is the directory in which the perdition libraries were
106 installed. You will need to customise your yp server's Makefile to
107 actually get a new map on the server. This map library is intended for
108 sites that already have a significant infrastructure based around
109 YP/NIS.
110 POSIX REGULAR EXPRESSIONS
113 This library allows users to be looked matched against a list of regu‐
115 lar expressions.
116 This library can be used by specifying the full path to the library
118 using the -M|--map_library command line option or configuration file
119 option.
120 E.g.
122 perdition -M /usr/lib/libperditiondb_posix_regex.so.0
124 Where /usr/lib is the directory in which the perdition libraries were
126 installed.
127 The regular expression is kept in a flat file, by default /etc/perdi‐
129 tion/popmap.re . A sample map file is shipped with the source and can
130 be found in etc/perdition/popmap.re, this is installed into /etc/perdi‐
131 tion/popmap.re in the RPM and Debian distributions. The format for the
132 flat file is:
133 <regular expression>: [<username><domain_delimiter>]<server>[:<port>]
135 A single colon may follow a regular_expression Some amount of white
137 space must follow this colon or the regular_expression if the colon is
138 omitted. Blank lines are ignored, as is anything including and after a
139 # (hash) on a line. If a precedes a new line then the lines will be
140 concatenated. If a precedes any other character, including a # (hash)
141 it will be treated as a literal. Anything inside single quotes (') will
142 be treated as a literal. Anything other than a (') inside double quotes
143 (") will be treated as a literal. Whitespace in a regular_expression
144 must be escaped or quoted. Whitespace in a substitution need not be
145 escaped or quoted.
146 Information on setting the domain_delimiter is found in perdition(8),
148 "@" is used in this example.
149 E.g.
151 ^[a-k]: localhost
153 ^[^a-k]: localhost:110
154 ^user: user2@localhost
155 (.*)@(.*): $1_$2@localhost
156 The first matching regular expression will be used. The regular expres‐
158 sions are extended posix regular expressions. The last example illus‐
159 trates the ability to expand backreferances. Backreferences may be
160 used by inserting $n in the substitution where n is in the range 1..9.
161 The backreference substitution code in this library is courtesy of Wim
162 Bonis and in turn the PHP3 project.
163 E.g.
165 For the regex (.*)@(.*): $1_$2@localhost
167 user@x.y.z.de
168 would return
169 user_x.y.z.de@localhost
170 Note that there is no implicit ^ or $ around the regular expressions.
172 The popmap entry "flim: localhost" will match "flim", "flimstix", "its‐
173 flim" and "totallyflimless". To only match "flim" you need the popmap
174 entry "^flim$: localhost".
175 The map file is read once on startup and cached. This is to increase
177 performance as the regular expressions must be compiled internally
178 before they can be used. The map file can be re read by sending perdi‐
179 tion a SIGHUP. An alternate location for the popmap.re can be specified
180 using the -m|--map_library_opt command line option or configuration
181 file option.
182 E.g.
184 perdition -m /etc/perdition/my_popmap.re
186 MYSQL
189 This map library can be used by specifying the full path to the library
191 using the -M|--map_library command line option or configuration file
192 option.
193 E.g.
195 perdition -M /usr/lib/libperditiondb_mysql.so.0
197 Where /usr/lib is the directory in which the perdition libraries were
199 installed.
200 The library will connect to a MySQL database and do a query on a table
202 expected to have the columns:
203 +------------+--------------+------+-----+---------+-------+
205 | Field | Type | Null | Key | Default | Extra |
206 +------------+--------------+------+-----+---------+-------+
207 | user | varchar(128) | | PRI | | |
208 | servername | varchar(255) | | | | |
209 | port | varchar(8) | YES | | NULL | |
210 +------------+--------------+------+-----+---------+-------+
211 The fields may be in a different order and other, non-perdition fields
213 may also be present in this table. The names of the columns can be
214 other than their above defaults by using the library option string
215 described below. All fields must be literal character strings. The
216 allowed length of the strings is not important, however, it is recom‐
217 mended that the length of the user field be kept under 128 to avoid
218 exceeding perdition's internal query length limit, PERDI‐
219 TIONDB_MYSQL_QUERY_LENGTH which is 256 by default. This may be altered
220 by recompiling perdition. The user field must also be a unique index
221 as an exact match will be made of this field from the username supplied
222 by the user.
223 The servername is of the form.
225 [<username><domain_delimiter>]<host>[:<port>]
227 Where: host: hostname or ip address
229 port: port name or number
230 If the -n|--no_lookup option is in effect then ip addresses and port
232 numbers should be used as host and port names will not be resolved.
233 The port is the TCP port to use when connecting to the server. This
235 field can be specified if the back-end server answers on a non-standard
236 port (standard ports being 110 for POP3 and 143 for IMAP). Only specify
237 this field in the database if you intend to use POP3 or IMAP exclu‐
238 sively as it will try to use this port no matter what protocol is being
239 used. If POP3 and IMAP are both being used on non-standard back-end
240 server ports, those ports can be specified with the -p argument when
241 you invoke the perdition executable.
242 The database is accessed each time perdition needs to find the host and
244 port for a user. The default database values are as follows:
245 database host: localhost
247 database port: (MySQL Client Default: usually 3306)
248 database name: dbPerdition
249 database table: tblPerdition
250 database user: perdition
251 database password: perdition
252 user column: user
253 server column: servername
254 port column: port
255 A script, perditiondb_mysql_makedb, is provided to initialise such a
257 database. Alternate values can be set using the -m|--map_library_opt
258 command line option or configuration file option with an argument of
259 the following form. (N.B.: this example has been split over multiple
260 lines for ease of reading)
261 <dbhost>[:<dbport>[:<dbname>[:<dbtable>[:<dbuser>
263 [:<dbpwd>[:<dbservercol>[:<dbusercol>[:<dbportcol>]]]]]]]]
264 E.g.
266 perdition -m "some.host.com:3306:aDb:bTable:cUser:"\
268 "dPassword:eSrvCol:fUserCol:gPortCol"
269 Arguments may be omitted from the end of the option string with no con‐
271 sequence other than that the default value for any omitted argument
272 will be used. Arguments may not be omitted if any argument to its right
273 is defined. Someone seeking to set only the server and password to
274 something other than the default might attempt the following:
275 perdition -m some.host.com:::::OddPassword
277 This will not work. It will set the server and password to the values
279 shown, but all arguments in between will be set as NULL rather than the
280 default. In the author's opinion it is always best to specify all of
281 the arguments to avoid confusion.
282 Database servers may be grouped together for higher performance or high
284 availability by using ODBC and accessing them using the ODBC module.
285 Multiple MySQL Servers
287 It is possible to specify multiple MySQL servers by specifying them,
289 comma separated (without any space), in the dbhost column. In this
290 case all MySQL servers need to have an identical configuration, because
291 all other options are shared. If the first server is not reachable,
292 perdition will fall back to the second etc.
293 POSTGRESQL
295 This is a port of the MySQL library to PostgreSQL, The library can be
297 used by specifying the full path to the library using the
298 -M|--map_library command line option or configuration file option.
299 E.g.
301 perdition -M /usr/lib/libperditiondb_postgresql.so.0
303 Where /usr/lib is the directory in which the perdition libraries were
305 installed. A script, perditiondb_postgresql_makedb is provided to ini‐
306 tialise the database. For more information please see the MySQL docu‐
307 mentation above.
308 ODBC
311 This is a port of the MySQL library to ODBC. It may be used to access
313 databases that do not have a perditiondb module. It may also be used
314 to group database servers into clusters.
315 The library can be used by specifying the full path to the library
317 using the -M|--map_library command line option or configuration file
318 option.
319 E.g.
321 perdition -M /usr/lib/libperditiondb_odbc.so.0
323 Where /usr/lib is the directory in which the perdition libraries were
325 installed. A script, perditiondb_odbc_makedb is provided to seed the.
326 For more information please see the MySQL documentation above. The
327 database options passed using -m are the same as for MySQL except that
328 the database name (dbname) is the Data Source Name (DSN).
329 <dbhost>[:<dbport>[:<DSN>[:<dbtable>[:<dbuser>
331 [:<dbpwd>[:<dbsrvcol>[:<dbusercol>[:<dbportcol>]]]]]]]]
332 E.g.
334 perdition -m "some.host.com:3306:aDb:bTable:cUser:"\
336 "dPassword:eSrvCol:fUserCol:gPortCol"
337 As per the notes in the MySQL documentation above, please avoid omit‐
339 ting values.
340 LDAP
342 This library allows access to LDAP based popmaps. This library can be
344 used by specifying the full path to the library using the
345 -M|--map_library command line option or configuration file option.
346 E.g.
348 perdition -M /usr/lib/libperditiondb_ldap.so.0
350 Where /usr/lib is the directory in which the perdition libraries were
352 installed.
353 Options are parsed to this module using the -m|--map_library_opt com‐
355 mand line option or configuration file option. It has the form:
356 [ldap_version:][ldap_url]
358 The ldap_version is the version of the ldap procotol used. It should
360 be a numeric value. At the time of writing, OpenLdap supports 2 or 3,
361 and defaults to 2. This may vary between different ldap implementa‐
362 tions. If you inspect the local ldap.h file, the values of LDAP_VER‐
363 SION_MIN, LDAP_VERSION_MAX and LDAP_VERSION should reflect the minimum,
364 maximum and default ldap protocol versions respectively.
365 The ldap_url is the query made to the ldap server. The default URL is
367 as follows. Note that this has been split onto multiple lines for ease
368 of reading.
369 ldap://localhost/ou=mailbox,dc=nodomain?
371 username,mailhost,port?one?(uid=%s)
372 Perdition will replace any instance of %s with the key being used for
374 the lookup. Optionally, there may be an integer between the % and the
375 s, in which case the key will be white-space padded to this width, with
376 the key right justified.
377 The attribute names (username, mailhost and port) may be changed. But
379 the first attribute will be used as the username, the second attribute
380 as the host and the third atribute as the port. Any subsequent
381 attributes will be ignored. Trailing attributes may also be omitted.
382 So if there are only two attributes the port will not be read from the
383 database.
384 A script, perditiondb_ldap_makedb is provided to initialise LDAP.
386 x-bindpw bindname
388 Perdition can be configured to use use an alternate bind name, and the
390 non-standard "x-bindpw". In fact perdition can use any extensions that
391 are supported by openldap. (N.B.: these examples have been split over
392 multiple lines for ease or reading)
393 ldap://ldap.mydomain.com/o=domain.com?
395 uid,mailhost,port?sub?(uid=%s)?!bindname=uid=perdition%2co=domain.com
396 ldap://ldap.mydomain.com/o=domain.com?uid,mailhost,port?
398 sub?(uid=%s)?!BINDNAME=uid=perdition%2co=domain.com,X-BINDPW=secret
399 The first example does the usual LDAP lookup, but tries to bind to the
401 server with "uid=perdition,o=domain.com" rather than the usual anony‐
402 mous binding. Note: The commas inside the bind string itself must be
403 URL encoded, thus the %2c.
404 The second example is the same as the first, but in addition to speci‐
406 fying a bind string it also uses the non-standard "x-bindpw" extension
407 to specify a password, in this case "secret".
408 The "!" character is used to ensure Perdition supports the "bindname"
410 extension. If it didn't, the LDAP connection would be aborted. Right
411 now it isn't really needed, but it may become useful as other exten‐
412 sions appear. For full details of this, take a look at RFC2255.
413 Multiple LDAP Servers
415 It is possible to specify multiple LDAP servers by specifying them,
417 space delimited, in the LDAP UDL. If this is the case an attempt will
418 be made to open a connection to each host in order, the first host to
419 which a connection is successfully made will be used.
420 For example: (N.B.: this example has been split over multiple lines for
422 ease or reading)
423 ldap://host1 host2 host3/ou=mailbox,dc=nodomain?
425 username,mailhost,port?one?(uid=%s)
426 perdition.schema
428 A schema has been defined for perdition and is supplied as part of
430 perdition. To use this you should install it on the LDAP server in the
431 LDAP daemon's schema directory and include it in slapd.conf, after
432 other includes and before any database definitions.
433
435 The database is accessed using the dlopen(3) mechanism on a library.
436 The library should define the symbol dbserver_get with the following
437 semantics.
438 int (*dbserver_get)(char *, char *, char **, size_t *)
440 Find the server (value) given the user (key)
442 pre: key_str: Key as a null terminated string
444 options_str: Options string. The usage of this is implementation
446 dependent.
447 str_return: Value is returned here
449 len_return: Length of value is returned here
451 post: The str_key is looked up and the corresponding value is returned
453 in str_return and len_return.
454 return:
456 0 on success
457 -1 on db access error This includes file, connection and other
459 data access errors. It does not cover memory allocation prob‐
460 lems.
461 -2 if key cannot be found in map
463 -3 on other error
465 Note: The string returned in str_return should be in the following
467 form. Setting the domain_delimiter is discussed in the perdi‐
468 tion(8), "@" is used in this example.
469 [<username><domain_delimiter>]<servername>[:<port>]
471 E.g.:
473 localhost:110
475 user@localhost:110
476 user@localhost
477 localhost
478 As the library is opened using the dlopen(3) mechanism the library may
480 also export functions _init and _fini that will be executed when the
481 library is opened and closed respectively. In addition if the symbols
482 following symbols are defined then these are run when the library is
483 opened and closed respectively. If defined these symbols should have
484 the following semantics.
485 int *(*dbserver_init)(char *)
487 Initialise db as necessary
489 pre: options_str: Options string. The usage of this is implementation
491 dependent.
492 post: db is initialised
494 return:
496 0 on success
497 -1 on db access error This includes file, connection and other
499 data access errors. It does not cover memory allocation prob‐
500 lems.
501 -2 if key cannot be found in map
503 -3 on other error
505 int *(*dbserver_fini)(void)
507 Shut down db as necessary
509 pre: none
511 post: db is shut down
513 return:
515 0 on success
516 -1 on db access error This includes file, connection and other
518 data access errors. It does not cover memory allocation prob‐
519 lems.
520 -2 if key cannot be found in map
522 -3 on other error
524 In addition, if a SIGHUP is sent to a process then a signal handler
526 will call dbserver_fini if it is defined and then dbserver_init if it
527 is defined. Note: dbserver_init will be called if defined, even if
528 dbserver_fini is not defined.
529 In the case of the posix regular expressions library this will cause
531 popmap.re to be re-parsed, hence effecting any changes that have been
532 made to that file. For the GDBM library it will reopen the database and
533 for the other libraries it will reinitialise its connection to the
534 database, LDAP or NIS server.
535 The shared library has access to the following global symbols exported
537 by perdition.
538 struct utsname *system_uname
540 The uname information for the system as per uname(2)
541 struct sockaddr_in *peername
543 The sockaddr_in for address and port of the client end of the
544 connection.
545 struct sockaddr_in *sockname
547 The sockaddr_in for the local address and port that the client
548 connected to. Note: Under Solaris 7 and above, this is actually
549 the sockaddr_in bound to, not the address and port the connec‐
550 tion was accepted on.
551
553 perdition(8), makegdbm(1), makebdb(1), make(1), perdi‐
554 tiondb_mysql_makedb(8), perditiondb_postgresql_makedb(8) perdi‐
555 tiondb_ldap_makedb(8), perditiondb_odbc_makedb(8)
556
558 Lead
559 Horms <horms@vergenet.net>
560 Perditiondb Library Authors
562 Frederic Delchambre <dedel@freegates.be> (MySQL)
563 Chris Stratford: <chriss@uk.uu.net> (LDAP and BDB)
564 Nathan Neulinger <nneul@umr.edu> (NIS)
565 Contributing Authors
567 Daniel Roesen <droesen@entire-systems.com>
568 Clinton Work <work@scripty.com>
569 Youri <ya@linkline.be>
570 Jeremy Nelson <jnelson@optusnet.com.au>
571 Wim Bonis <bonis@solution-service.de>
572 Arvid Requate <arvid@Team.OWL-Online.DE>
573 Mikolaj J. Habryn <dichro@rcpt.to>
574 Ronny Cook <ronny@asiaonline.net>
575 Geoff Mitchell <g.mitchell@videonetworks.com>
576 Willi Langenberger <wlang@wu-wien.ac.at>
577 Matt Prigge <mprigge@pobox.com>
578 Wolfgang Breyha <wolfgang.breyha@uta.at>
579 6th August 2003 PERDITIONDB(5)