git.sur5r.net Git - openldap/blob - contrib/slapd-modules/nssov/nss-ldapd/HACKING

   1
   2 This document tries to describe the software layout and design of the library.
   3 It should provide some help for contributing code to this package.
   4
   5 CONTRIBUTING TO NSS-LDAPD
   6 =========================
   7
   8 Contributions to nss-ldapd are most welcome. However not all contributions
   9 will be automatically integrated. Some notes:
  10
  11 * for large changes it is a good idea to send an email first
  12 * send your patches in unified diff (diff -u) format
  13 * try to use the svn version of the software to develop the patch
  14 * clearly state which problem you're trying to solve and how this is
  15   accomplished
  16 * please follow the existing coding conventions
  17 * patches will be integrated on a best-effort bases
  18 * please test the patch and include information on testing with the patch
  19   (platforms tested, etc)
  20 * contributions will be acknowledged in the AUTHORS file
  21 * include a copyright statement in the patched code if you feel the
  22   contribution is significant enough (e.g. more than a few lines)
  23 * when including third-party code, retain copyright information (copyright
  24   holder and license) and ensure that the license is LGPL compatible
  25
  26 Please contact Arthur de Jong <arthur@ch.tudelft.nl> if you want to
  27 contribute or use the Debian BTS if you're using the Debian package.
  28
  29
  30 BUILD DEPENDENCIES
  31 ==================
  32
  33 For building svn snapshots the following tools are needed:
  34
  35 * autoconf (2.61 is used but 2.59 is minimal)
  36 * automake (1.10 is used)
  37 * check (0.9.5 is used)
  38
  39 and of course the usual build tools (gcc/make/etc). Also see debian/control
  40 (Build-Depends field) for libraries you need.
  41
  42 To build the svn snapshot run the autogen.sh shell script to build the
  43 configure script. When developing patches please use --enable-warnings with
  44 configure and don't introduce too many new warnings. For building the manual
  45 pages docbook2x is used.
  46
  47
  48 RELEASE VERSIONING
  49 ==================
  50
  51 A new versioning scheme was chosen over the nss_ldap release scheme. The
  52 scheme is a simple major.minor numbering starting with 0.1. Until a 1.0
  53 release is made the code will be considered work in progress. The interfaces
  54 may change and features may be added and removed.
  55
  56
  57 GENERAL DESIGN
  58 ==============
  59
  60 The basic design splits the functionality in two parts. The NSS part
  61 interfaces with libc and translates the NSS requests into simple generic
  62 requests (e.g. "get user with name test", "get group with gid 101" or "get all
  63 shadow entries"). Translating these requests into LDAP requests is then the
  64 job of the daemon (nslcd) so that the NSS part won't have to know anything
  65 about LDAP (in fact replacing it with another lookup method is very simple).
  66
  67                 nslcd  -> OpenLDAP -> LDAP server
  68                   ^
  69     libc NSS -> libnss_ldap.so
  70
  71 design goals
  72 ------------
  73 * make it as simple as possible
  74 * design as specified above
  75 * simpler configuration and semantics
  76 * simpler, clearer and completer documentation
  77 * split source code into directories (src, src/hacks, src/aix, src/irs, etc)
  78 * get rid of unneeded code and complexity
  79 * split complexity in two parts (LDAP interface in server, NSS interface in
  80   library)
  81 * have a stable, easily maintainable piece of quality software
  82
  83
  84 NSS PART
  85 ========
  86
  87 The NSS part is implemented in files in the nss directory. The functions are
  88 split into files according to the database they support. All functions look
  89 like:
  90
  91 _nss_ldap_FUNCTION_r(...)
  92   This function opens the connection to the nslcd (with a time-out) builds the
  93   correct data structures and does a request (write()) to the nslcd waiting
  94   for an answer (again with a time-out)
  95
  96 Currently a number of macros are used to build most of the function bodies for
  97 these functions. A more elegant solution is welcome.
  98
  99 Some handy links:
 100 http://mirrors.usc.edu/pub/gnu/Manuals/glibc-2.2.3/html_chapter/libc_28.html#SEC596
 101 http://www.gnu.org/software/libc/manual/html_node/index.html
 102
 103
 104 THE COMMUNICATIONS PROTOCOL
 105 ===========================
 106
 107 The protocol used for communicating between the NSS library and the nslcd
 108 daemon is very simple and almost fully described in the nslcd.h header file.
 109 The nslcd-common.h header file defines some macros that are used for reading
 110 and writing protocol entities (strings, 32-bit integers, etc).
 111
 112 Some of the protocol handling code is automatically generated from the macros
 113 defined in nslcd.h. This cannot be done automatically in every case though so
 114 changing the protocol requires manual checking in the relevant source files in
 115 both the nss and the nslcd directories.
 116
 117 If the protocol is changed in an incompatible way the protocol version should
 118 be incremented in nslcd.h. There is currently no versioning scheme available
 119 for this.
 120
 121 A special module (common/tio.c) was made so we can define simpler semantics
 122 for time-out values and buffer sizes. Both tha NSS library and nslcd use this
 123 module which means that it includes functionality that is needed for both
 124 (e.g. large write buffers for the server part and large resettable read
 125 buffers for the NSS part). Maybe building two modules from the same source
 126 with different features in them is an option (e.g. the NSS part needs the
 127 read buffers and handling of SIGPIPE and the nslcd part needs the write
 128 buffers and possibly flushing in the background).
 129
 130
 131 SERVER PART
 132 ===========
 133
 134 At the server end a dispatcher picks up the request and delegates it to one of
 135 the database specific functions.
 136
 137 nslcd_FUNCION(...)
 138   This functions fills in the correct parameters from the request. This
 139   function should write responses to the stream. Almost all these functions
 140   are generated from a macro in common.h.
 141
 142
 143 SECURITY NOTES
 144 ==============
 145
 146 This design does open up the system to more potential security issues as there
 147 is now a local interface to a daemon with privileges. Before processes could
 148 only potentially exploit bugs in the library and gain the privileges of the
 149 process that was doing the name lookups. In this case the privileges of the
 150 daemon are potentially exposed.
 151
 152 The deamon should be changed to set a specific less-privileged user and
 153 group to minimize the riscs. Code for this is already in place. Configuration
 154 options should be added and the Debian packaging should use this.