doc/DEVELOPER

   1 Information for Netatalk Developers
   2 ===================================
   3
   4 For basic installation instructions, see http://netatalk.sourceforge.net .
   5
   6 Netatalk is an implementation of "AFP over TCP".
   7 DSI is a session layer used to carry AFP over TCP.
   8 The complete stack looks like this:
   9
  10           AFP
  11            |
  12           DSI
  13            |
  14            | (port:548)
  15            |
  16    -+---------------------------+- (kernel boundary)
  17     |         Socket            |
  18     +------------+--------------+
  19     |     TCP    |    UDP       |
  20     +------------+--------------+
  21     |       IP v4 or v6         |
  22     +---------------------------+
  23     |     Network-Interface     |
  24     +---------------------------+
  25
  26 Compilation
  27 ===========
  28    The `configure' shell script attempts to guess correct values for
  29 various system-dependent variables used during compilation.  It uses
  30 those values to create a `Makefile' in each directory of the package.
  31 It may also create one or more `.h' files containing system-dependent
  32 definitions.  Finally, it creates a shell script `config.status' that
  33 you can run in the future to recreate the current configuration, a file
  34 `config.cache' that saves the results of its tests to speed up
  35 reconfiguring, and a file `config.log' containing compiler output
  36 (useful mainly for debugging `configure').
  37
  38    If you need to do unusual things to compile the package, please try
  39 to figure out how `configure' could check whether to do them, and mail
  40 diffs or instructions to the address given in the `README' so they can
  41 be considered for the next release.  If at some point `config.cache'
  42 contains results you don't want to keep, you may remove or edit it.
  43
  44    The file `configure.in' is used to create `configure' by a program
  45 called `autoconf'.  You only need `configure.in' if you want to change
  46 it or regenerate `configure' using a newer version of `autoconf'.
  47
  48
  49 Tools for Developers
  50 ====================
  51 1. Libtool
  52 Libtool encapsulates the platform specific dependencies for the
  53 creation of libraries. It determines if the local platform can support
  54 shared libraries or if it only supports static libraries.
  55
  56 Documentation: http://www.gnu.org/software/libtool/
  57
  58 2. GNU m4
  59 GNU m4 is an implementation of the Unix macro processor. It reads
  60 stdin and copies to stdout expanding defined macros as it processes
  61 the text.
  62
  63 Documentation: http://www.gnu.org/software/m4/
  64
  65 3. Autoconf
  66 Autoconf is a package of m4 macros that produce shell scripts to
  67 configure source code packages.
  68
  69 Documentation: http://www.gnu.org/software/autoconf/
  70
  71 4. Automake
  72 Automake is a tool that generates  'Makefile.in' files.
  73
  74 Documentation: http://www.gnu.org/software/automake/
  75
  76 Optional
  77 ========
  78 5. OpenSSL and/or Libgcrypt
  79 The OpenSSL Project is a collaborative effort to develop a robust,
  80 commercial-grade, full-featured, and Open Source toolkit implementing
  81 the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS
  82 v1) protocols as well as a full-strength general purpose cryptography
  83 library.
  84 This is required to enable DHX login support.
  85
  86 Get everything at http://www.openssl.org/
  87
  88 The Libgcrypt is a general purpose cryptographic library based on
  89 the code from GnuPG.
  90 This is required to enable DHX2 login support.
  91
  92 Get everything at http://directory.fsf.org/project/libgcrypt/
  93
  94 6. TCP Wrappers
  95 Wietse Venema's network logger, also known as TCPD or LOG_TCP. These
  96 programs log the client host name of incoming telnet, ftp, rsh,
  97 rlogin, finger etc. requests. Security options are: access control per
  98 host, domain and/or service; detection of host name spoofing or host
  99 address spoofing; booby traps to implement an early-warning system.
 100 TCP Wrappers can be gotten at ftp://ftp.porcupine.org/pub/security/
 101 Netatalk uses TCP Wrappers to authorize host access when using
 102 afpovertcp. It should be noted that if DDP is in use, the connection
 103 will still be allowed as TCP Wrappers do not impact DDP connections.
 104
 105 7. PAM (Pluggable Authentication Modules)
 106 PAM provides a flexible mechanism for authenticating
 107 users. PAM was invented by SUN Microsystems.
 108
 109 Author: Andrew Morgan <morgan@linux.kernel.org>
 110
 111 Linux-PAM is a suite of shared libraries that enable the local system
 112 administrator to choose how applications authenticate users.
 113 You can get the Linux PAM documentation and sources from
 114 http://www.kernel.org/pub/linux/libs/pam/
 115 Netatalk also supports other standard PAM implementations such as OpenPAM.
 116
 117 8. Berkeley DB
 118 Berkeley DB is a programmatic toolkit that provides fast, reliable,
 119 scalable, and mission-critical database support to software
 120 developers. BDB can downloaded from
 121 http://www.oracle.com/database/berkeley-db/index.html
 122 Netatalk's CNID database uses the library and header files from BDB.
 123 Currently, Netatalk supports BDB 4.6 and later.
 124
 125 Error checking and logging
 126 ==========================
 127 We wan't rigid error checking and concise log messages. This often leads
 128 to signifant code bloat where the relevant function call is buried in error
 129 checking and logging statements.
 130 In order to alleviate error checking and code readability, we provide a set
 131 of error checking macros in <atalk/errchk.h>. These macros compare the return
 132 value of statements againt 0, NULL, -1 (and maybe more, check it out).
 133 Every macro comes in four flavours: EC_CHECK, EC_CHECK_LOG, EC_CHECK_LOG_ERR
 134 and EC_CHECK_CUSTOM:
 135 - EC_CHECK just checks the CHECK
 136 - EC_CHECK_LOG additionally logs the stringified function call.
 137 - EC_CHECK_LOG_ERR allows specifying the return value
 138 - EC_CHECK_CUSTOM allows custom actions
 139 The macros EC_CHECK* unconditionally jump to a cleanup label where the
 140 neccessary cleanup can be done alongside controlling the return value.
 141 EC_CHECK_CUSTOM doesn't do that, so an extra "goto EC_CLEANUP" may be
 142 performed as appropiate.
 143
 144 Example:
 145 - stat() without EC macro:
 146   static int func(const char *name) {
 147     int ret = 0;
 148     ...
 149     if ((ret = stat(name, &some_struct_stat)) != 0) {
 150       LOG(...);
 151       ret = -1; /* often needed to explicitly set the error indicating return value */
 152       goto cleanup;
 153     }
 154
 155     return ret;
 156
 157   cleanup:
 158     ...
 159     return ret;
 160   }
 161
 162 - stat() with EC macro:
 163   static int func(const char *name) {
 164     EC_INIT; /* expands to int ret = 0; */
 165
 166     char *uppername = NULL
 167     EC_NULL(uppername = strdup(name));
 168     EC_ZERO(strtoupper(uppername));
 169
 170     EC_ZERO(stat(uppername, &some_struct_stat)); /* expands to complete if block from above */
 171
 172     EC_STATUS(0);
 173
 174 EC_CLEANUP:
 175     if (uppername) free(uppername);
 176     EC_EXIT;
 177   }
 178
 179 A boileplate function template is:
 180
 181 int func(void)
 182 {
 183     EC_INIT;
 184
 185     ...your code here...
 186
 187     EC_STATUS(0);
 188
 189 EC_CLEANUP:
 190     EC_EXIT;
 191 }
 192
 193 Ini Parser
 194 ==========
 195
 196 The ini parser is taken from <http://ndevilla.free.fr/iniparser/>.
 197 It has been slightly modified:
 198 - case-sensitive
 199 - "include" directive added
 200 - iniparser_getstrdup() to complemnt iniparser_getstring(), it return allocated strings
 201   which the caller must free as necessary
 202 - the API has been modifed such that all iniparser_get* funcs take a section and a parameter
 203   as sepereta args instead of one string of the form "section:parameter" in the original
 204   library
 205
 206 CNID Database Daemons
 207 =====================
 208
 209 The CNID database daemons cnid_metad and cnid_dbd are a implementation of
 210 the netatalk CNID database support that attempts to put all functionality
 211 into separate daemons.
 212 There is one cnid_dbd daemon per netatalk volume. The underlying database
 213 structure is based on Berkeley DB and the database format is the same
 214 as in the cdb CNID backend, so this can be used as a drop-in replacement.
 215
 216 Advantages:
 217
 218 - No locking issues or leftover locks due to crashed afpd daemons any
 219   more. Since there is only one thread of control accessing the
 220   database, no locking is needed and changes appear atomic.
 221
 222 - Berkeley DB transactions are difficult to get right with several
 223   processes attempting to access the CNID database simultanously. This
 224   is much easier with a single process and the database can be made nearly
 225   crashproof this way (at a performance cost).
 226
 227 - No problems with user permissions and access to underlying database
 228   files, the cnid_dbd process runs under a configurable user
 229   ID that normally also owns the underlying database
 230   and can be contacted by whatever afpd daemon accesses a volume.
 231
 232 - If an afpd process crashes, the CNID database is unaffected. If the
 233   process was making changes to the database at the time of the crash,
 234   those changes will be rolled back entirely (transactions).
 235   If the process was not using the database at the time of the crash,
 236   no corrective action is necessary. In any case, database consistency
 237   is assured.
 238
 239 Disadvantages:
 240
 241 - Performance in an environment of processes sharing the database
 242   (files) is potentially better for two reasons:
 243
 244   i)  IPC overhead.
 245   ii) r/o access to database pages is possible by more than one
 246       process at once, r/w access is possible for nonoverlapping regions.
 247
 248   The current implementation of cnid_dbd uses unix domain sockets as
 249   the IPC mechanism. While this is not the fastest possible method, it
 250   is very portable and the cnid_dbd IPC mechanisms can be extended to
 251   use faster IPC (like mmap) on architectures where it is
 252   supported. As a ballpark figure, 20000 requests/replies to the cnid_dbd
 253   daemon take about 0.6 seconds on a Pentium III 733 Mhz running Linux
 254   Kernel 2.4.18 using unix domain sockets. The requests are "empty"
 255   (no database lookups/changes), so this is just the IPC
 256   overhead.
 257
 258   I have not measured the effects of the advantages of simultanous
 259   database access.
 260
 261
 262 Installation and configuration
 263
 264 There are two executeables that will be built in etc/cnid_dbd and
 265 installed into the systems binaries directories of netatalk
 266 cnid_metad and cnid_dbd. cnid_metad should run all the
 267 time with root permissions. It will be notified when an instance of
 268 afpd starts up and will in turn make sure that a cnid_dbd daemon is
 269 started for the volume that afpd wishes to access. The cnid_dbd daemon runs as
 270 long as necessary and services any
 271 other instances of afpd that access the volume. You can safely kill it
 272 with SIGTERM, it will be restarted automatically by cnid_metad as soon
 273 as the volume is accessed again.
 274
 275 cnid_dbd changes to the Berkeley DB directory on startup and sets
 276 effective UID and GID to owner and group of that directory. Database and
 277 supporting files should therefore be writeable by that user/group.
 278
 279 Current shortcomings:
 280
 281 - The parameter file parsing of db_param is very simpleminded. It is
 282 easy to cause buffer overruns and the like.
 283 Also, there is no support for blanks (or weird characters) in
 284 filenames for the usock_file parameter.
 285
 286 - There is no protection against a malicious user connecting to the
 287 cnid_dbd socket and changing the database.