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 Required
  77 ========
  78 5. Berkeley DB
  79 Berkeley DB is a programmatic toolkit that provides fast, reliable,
  80 scalable, and mission-critical database support to software
  81 developers. BDB can downloaded from
  82 http://www.oracle.com/database/berkeley-db/index.html
  83 Netatalk's CNID database uses the library and header files from BDB.
  84 Currently, Netatalk supports BDB 4.6 and later.
  85
  86
  87 Optional
  88 ========
  89 6. OpenSSL and/or Libgcrypt
  90 The OpenSSL Project is a collaborative effort to develop a robust,
  91 commercial-grade, full-featured, and Open Source toolkit implementing
  92 the Secure Sockets Layer (SSL v2/v3) and Transport Layer Security (TLS
  93 v1) protocols as well as a full-strength general purpose cryptography
  94 library.
  95 This is required to enable DHX login support.
  96
  97 Get everything at http://www.openssl.org/
  98
  99 The Libgcrypt is a general purpose cryptographic library based on
 100 the code from GnuPG.
 101 This is required to enable DHX2 login support.
 102
 103 Get everything at http://directory.fsf.org/project/libgcrypt/
 104
 105 7. TCP Wrappers
 106 Wietse Venema's network logger, also known as TCPD or LOG_TCP. These
 107 programs log the client host name of incoming telnet, ftp, rsh,
 108 rlogin, finger etc. requests. Security options are: access control per
 109 host, domain and/or service; detection of host name spoofing or host
 110 address spoofing; booby traps to implement an early-warning system.
 111 TCP Wrappers can be gotten at ftp://ftp.porcupine.org/pub/security/
 112 Netatalk uses TCP Wrappers to authorize host access when using
 113 afpovertcp. It should be noted that if DDP is in use, the connection
 114 will still be allowed as TCP Wrappers do not impact DDP connections.
 115
 116 8. PAM (Pluggable Authentication Modules)
 117 PAM provides a flexible mechanism for authenticating
 118 users. PAM was invented by SUN Microsystems.
 119
 120 Author: Andrew Morgan <morgan@linux.kernel.org>
 121
 122 Linux-PAM is a suite of shared libraries that enable the local system
 123 administrator to choose how applications authenticate users.
 124 You can get the Linux PAM documentation and sources from
 125 http://www.kernel.org/pub/linux/libs/pam/
 126 Netatalk also supports other standard PAM implementations such as OpenPAM.
 127
 128 Error checking and logging
 129 ==========================
 130 We wan't rigid error checking and concise log messages. This often leads
 131 to signifant code bloat where the relevant function call is buried in error
 132 checking and logging statements.
 133 In order to alleviate error checking and code readability, we provide a set
 134 of error checking macros in <atalk/errchk.h>. These macros compare the return
 135 value of statements againt 0, NULL, -1 (and maybe more, check it out).
 136 Every macro comes in four flavours: EC_CHECK, EC_CHECK_LOG, EC_CHECK_LOG_ERR
 137 and EC_CHECK_CUSTOM:
 138 - EC_CHECK just checks the CHECK
 139 - EC_CHECK_LOG additionally logs the stringified function call.
 140 - EC_CHECK_LOG_ERR allows specifying the return value
 141 - EC_CHECK_CUSTOM allows custom actions
 142 The macros EC_CHECK* unconditionally jump to a cleanup label where the
 143 neccessary cleanup can be done alongside controlling the return value.
 144 EC_CHECK_CUSTOM doesn't do that, so an extra "goto EC_CLEANUP" may be
 145 performed as appropiate.
 146
 147 Example:
 148 - stat() without EC macro:
 149   static int func(const char *name) {
 150     int ret = 0;
 151     ...
 152     if ((ret = stat(name, &some_struct_stat)) != 0) {
 153       LOG(...);
 154       ret = -1; /* often needed to explicitly set the error indicating return value */
 155       goto cleanup;
 156     }
 157
 158     return ret;
 159
 160   cleanup:
 161     ...
 162     return ret;
 163   }
 164
 165 - stat() with EC macro:
 166   static int func(const char *name) {
 167     EC_INIT; /* expands to int ret = 0; */
 168
 169     char *uppername = NULL
 170     EC_NULL(uppername = strdup(name));
 171     EC_ZERO(strtoupper(uppername));
 172
 173     EC_ZERO(stat(uppername, &some_struct_stat)); /* expands to complete if block from above */
 174
 175     EC_STATUS(0);
 176
 177 EC_CLEANUP:
 178     if (uppername) free(uppername);
 179     EC_EXIT;
 180   }
 181
 182 A boileplate function template is:
 183
 184 int func(void)
 185 {
 186     EC_INIT;
 187
 188     ...your code here...
 189
 190     EC_STATUS(0);
 191
 192 EC_CLEANUP:
 193     EC_EXIT;
 194 }
 195
 196 Ini Parser
 197 ==========
 198
 199 The ini parser is taken from <http://ndevilla.free.fr/iniparser/>.
 200 It has been slightly modified:
 201 - case-sensitive
 202 - "include" directive added
 203 - iniparser_getstrdup() to complemnt iniparser_getstring(), it return allocated
 204   strings which the caller must free as necessary
 205 - the API has been modifed such that all iniparser_get* funcs take a section and
 206   a parameter as sepereta args instead of one string of the form "section:parameter"
 207   in the original library
 208
 209 CNID Database Daemons
 210 =====================
 211
 212 The CNID database daemons cnid_metad and cnid_dbd are a implementation of
 213 the netatalk CNID database support that attempts to put all functionality
 214 into separate daemons.
 215 There is one cnid_dbd daemon per netatalk volume. The underlying database
 216 structure is based on Berkeley DB and the database format is the same
 217 as in the cdb CNID backend, so this can be used as a drop-in replacement.
 218
 219 Advantages:
 220
 221 - No locking issues or leftover locks due to crashed afpd daemons any
 222   more. Since there is only one thread of control accessing the
 223   database, no locking is needed and changes appear atomic.
 224
 225 - Berkeley DB transactions are difficult to get right with several
 226   processes attempting to access the CNID database simultanously. This
 227   is much easier with a single process and the database can be made nearly
 228   crashproof this way (at a performance cost).
 229
 230 - No problems with user permissions and access to underlying database
 231   files, the cnid_dbd process runs under a configurable user
 232   ID that normally also owns the underlying database
 233   and can be contacted by whatever afpd daemon accesses a volume.
 234
 235 - If an afpd process crashes, the CNID database is unaffected. If the
 236   process was making changes to the database at the time of the crash,
 237   those changes will be rolled back entirely (transactions).
 238   If the process was not using the database at the time of the crash,
 239   no corrective action is necessary. In any case, database consistency
 240   is assured.
 241
 242 Disadvantages:
 243
 244 - Performance in an environment of processes sharing the database
 245   (files) is potentially better for two reasons:
 246
 247   i)  IPC overhead.
 248   ii) r/o access to database pages is possible by more than one
 249       process at once, r/w access is possible for nonoverlapping regions.
 250
 251   The current implementation of cnid_dbd uses unix domain sockets as
 252   the IPC mechanism. While this is not the fastest possible method, it
 253   is very portable and the cnid_dbd IPC mechanisms can be extended to
 254   use faster IPC (like mmap) on architectures where it is
 255   supported. As a ballpark figure, 20000 requests/replies to the cnid_dbd
 256   daemon take about 0.6 seconds on a Pentium III 733 Mhz running Linux
 257   Kernel 2.4.18 using unix domain sockets. The requests are "empty"
 258   (no database lookups/changes), so this is just the IPC
 259   overhead.
 260
 261   I have not measured the effects of the advantages of simultanous
 262   database access.
 263
 264
 265 Installation and configuration
 266
 267 There are two executeables that will be built in etc/cnid_dbd and
 268 installed into the systems binaries directories of netatalk
 269 cnid_metad and cnid_dbd. cnid_metad should run all the
 270 time with root permissions. It will be notified when an instance of
 271 afpd starts up and will in turn make sure that a cnid_dbd daemon is
 272 started for the volume that afpd wishes to access. The cnid_dbd daemon runs as
 273 long as necessary and services any
 274 other instances of afpd that access the volume. You can safely kill it
 275 with SIGTERM, it will be restarted automatically by cnid_metad as soon
 276 as the volume is accessed again.
 277
 278 cnid_dbd changes to the Berkeley DB directory on startup and sets
 279 effective UID and GID to owner and group of that directory. Database and
 280 supporting files should therefore be writeable by that user/group.
 281
 282 Current shortcomings:
 283
 284 - The parameter file parsing of db_param is very simpleminded. It is
 285 easy to cause buffer overruns and the like.
 286 Also, there is no support for blanks (or weird characters) in
 287 filenames for the usock_file parameter.
 288
 289 - There is no protection against a malicious user connecting to the
 290 cnid_dbd socket and changing the database.
 291
 292 Documentation
 293 =============
 294 Netatalk documentation is in Docbook XML format. In order to build manpages
 295 and the html documentation from the Docbook docs you need the following:
 296
 297 1. Install `xsltproc`
 298
 299 2. Get the latest Docbook XSL stylesheet distribution from:
 300    https://sourceforge.net/project/showfiles.php?group_id=21935
 301    Tested docbook-xsl stylesheet version is 1.75.2.
 302
 303 3. Fix indexterm bug in xsl stylesheet:
 304    inside the xsl stylesheet distribution in manpages/inline.xsl remove these lines:
 305
 306         <!-- * indexterm instances produce groff comments like this: -->
 307         <!-- * .\" primary: secondary: tertiary -->
 308         <xsl:template match="indexterm">
 309           <xsl:text>.\" </xsl:text>
 310           <xsl:apply-templates/>
 311           <xsl:text>&#10;</xsl:text>
 312         </xsl:template>
 313
 314         <xsl:template match="primary">
 315           <xsl:value-of select="normalize-space(.)"/>
 316         </xsl:template>
 317
 318         <xsl:template match="secondary|tertiary">
 319           <xsl:text>: </xsl:text>
 320           <xsl:value-of select="normalize-space(.)"/>
 321         </xsl:template>
 322
 323 4. Add the following argument to configure
 324    --with-docbook=PATH_TO_XML_STYLESHEET_DIR
 325
 326 5. The manpages and html documentation are now automatically built when running `make html`.
 327
 328 Editing Docbook Sources
 329 -----------------------
 330 Free WYSIWYG editor with only one minor drawback is XMLEditor from XMLmind:
 331 http://www.xmlmind.com/xmleditor/persoedition.html
 332
 333 Drawback: in order to be able to edit any of the  nested xml files, you have to
 334 "promote" them to valid Docbook files by referencing the Docbook DTD, insert as line 2+3:
 335
 336         <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 337         "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 338
 339 These changes will however prevent XMLeditor from opening the master xml file
 340 manual.xml. Before further processing can be done these changes then have to be
 341 reverted for any changed file.