doc/DEVELOPER

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