What is UDB ? ------------- UDB consists of a library and some simple utilities for creating and maintaining a shared-memory database associating users with IP addresses, or users with established TCP connections. It was written primarily to allow an IRC proxy (tircproxy) to communicate with a modified identd on the system, with as little overhead and latency as possible. It could be useful for any other proxy system which could benefit from knowing what users to associate with dynamic IP addresses. Although written with IP addresses and TCP/IP connections in mind, the library is easily extendable to handle other user-related data, which is why this is UDB - a User Database, not just an IP-User Database. Future releases may include API-level support for such extensions. The database is persistant (it is deliberately never deleted), to allow short lived processes (e.g. spawned by inetd) to communicate with each other reliably. Included are the following utilities: udb_ls - Displays the current contents of the tables udb_rm - Deletes an entry from one of the tables udb_ipuser - Creates a static IP<->user mapping udb_init - Initialize the database to a given size These programs serve as simple examples of how to use some of the library's basic features and as basic administrative tools. Each of them (except for udb_ls) will print a "usage" summary if called w/o arguments. One example of how to make use of them would be to call "udb_ipuser" from the /etc/ppp/ip-up script, to tell the system who just "logged on". This would allow dial-up users to be correctly identified when they connect to the IRC (or anything else for that matter). In addition, a sample RedHat compatible startup script is included, which will read the initial UDB table from /etc/udb.conf, if the file exists. An example of how to create udb.conf is also included. Platforms --------- This version of UDB has been verified to work on: HP-UX 10.20 RedHat Linux 6.0 (w/ kernel 2.2.13) It doesn't work on: (please help me fix this!) Solaris 2.6 Other platforms are untested. Please let me know how UDB works on your system. Installation instructions ------------------------- This should work for everybody: ./configure make su -c "make install" The "make install" process will leave a file named INSTALLED in the UDB source directory, which lists the files installed in your system. You can do a "make uninstall" to get rid of them. This should work for RedHat users (instead of the above): su make rpm ln -s /etc/rc.d/init.d/udb.init /etc/rc.d/rc5.d/S99udb ln -s /etc/rc.d/init.d/udb.init /etc/rc.d/rc3.d/S99udb This has the added bonuses of using rpm to install the package and ensuring that the UDB database will be initialized on system startup (assuming you put something in the file /etc/udb.conf). If you encounter difficulties (and/or find solutions) please let the UDB mailing list (udb@bre.klaki.net) know about it. Configuration ------------- First of all, if you aren't familiar with System V IPC, read the man pages for ipcs(8) and ipcrm(8). These tools will allow you to examine the size of the UDB tables and delete them if you so choose. Before building the library, it may be a good idea to edit udb.h and lower UDB_IP_USER_SIZE and UDB_CONN_USER_SIZE to more reasonable values - the defaults are somewhat wasteful of memory (they use approximately 400kb). Alternately, you can use the udb_init to set the table sizes on system startup. Aside from table sizes, the only thing you will need to configure is who has access to the tables themselves. The first process that calls udb_init will own the UDB tables. The tables are created with mode ug+rw,o-rw (user and group can read and write, others can't do anything). This means that all processes that wish to make use of the UDB tables must either belong to the same group as the user who created the tables in the first place, run with the same user ID or run as root. Since running things as root is generally considered a bad idea, the best way to avoid permission-related problems is to create a special group (e.g. "udb") for UDB access, and create the tables as soon as possible after system boot using the udb_init program. This could be done by adding the following command to one of the system startup scripts: echo udb_init 1031 5023 | newgrp udb (This also sets the sizes of the IP and TCP tables to 1031 and 5023 entries, respectively). The RedHat initialization script, udb.init, makes the tables available to the 'nobody' group by default. WARNING: Although there are at the moment no known bugs in the UDB library itself, malicious applications could still trash the shared memory tables (bypass the API) and cause other UDB-enabled applications to crash (or worse). Therefore it is important to limit access to the tables as much as possible, as you would for any other configuration file in your system. For these reasons, using the "nobody" group (which many other applications have access to) may not be a very good idea. Comments -------- If you port this package to a new OS, or use it for anything at all, I'd like to hear about it. :-) GNU autoconf and libtool are cool! Links ----- http://bre.klaki.net/programs/udb/ - UDB home page http://bre.klaki.net/programs/tircproxy/ - tircproxy home page Please see the UDB home page for information about the project's mailing list and a list of applications that use UDB. Authors ------- This program is (C) Copyright January 2000 by Bjarni R. Einarsson and Multimedia Consumer Services, Iceland . This program is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License or the GNU General Public License as published by the Free Software Foundation; either version 2 of the License (GPL), or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License (at http://www.gnu.org/) for more details.