man/man8/cnid_dbd.8.tmpl

   1 .TH cnid_dbd 8  2\ Dec\ 2003 "Netatalk 2.0-alpha1"
   2 .SH NAME
   3 cnid_dbd \- implement access to CNID databases through a dedicated daemon  process
   4 .SH SYNOPSIS
   5 \fBcnid_dbd\fR \fBdbdir\fR \fBctrlfd\fR \fBclntfd\fR
   6 .SH DESCRIPTION
   7 cnid_dbd provides an interface for storage and
   8 retrieval of catalog node IDs (CNIDs) and related information to the
   9 \fIafpd\fR daemon. CNIDs are a component of
  10 Macintosh based file systems with semantics that map not easily onto Unix
  11 file systems. This makes separate storage in a database necessary.
  12 cnid_dbd is part of the \fICNID
  13 backend\fR framework of \fIafpd\fR and
  14 implements the \fIdbd\fR backend.
  15 .PP
  16 cnid_dbd is never started via the command line or
  17 system startup scripts but only by the \fIcnid_metad\fR
  18 daemon. There is at most one instance of cnid_dbd per
  19 netatalk volume.
  20 .PP
  21 cnid_dbd uses the \fIBerkleley
  22 DB\fR database library and optionally supports transactionally
  23 protected updates if the netatalk package is compiled with the appropriate
  24 options. Using the \fIdbd\fR backend without
  25 transactions will protect the CNID database against unexpected crashes of
  26 the \fIafpd\fR daemon. Using the \fIdbd\fR backend with transactions will avoid corruption
  27 of the CNID database even if the system crashes unexpectedly.
  28 .PP
  29 cnid_dbd uses the same on\-disk database format as
  30 the \fIcdb\fR backend. It is therefore possible
  31 to switch between the two backends as necessary.
  32 .PP
  33 cnid_dbd inherits the effective userid and
  34 groupid from \fIcnid_metad\fR on startup, which
  35 is normally caused by \fIafpd\fR serving a
  36 netatalk volume to a client. It changes to the \fIBerkleley
  37 DB\fR database home directory \fIdbdir\fR
  38 that is associated with the volume, opens the database and starts serving
  39 requests using the filedescriptor \fIclntfd\fR.
  40 Subsequent instances of \fIafpd\fR that
  41 want to access the same volume are redirected to the running
  42 cnid_dbd by \fIcnid_metad\fR
  43 via the filedescriptor \fIctrlfd\fR.
  44 .PP
  45 cnid_dbd can be configured to run forever or to
  46 exit after a period of inactivity. If cnid_dbd receives
  47 a TERM or an INT signal it will exit cleanly after flushing dirty database
  48 buffers to disk and closing \fIBerkleley DB\fR
  49 database environments. It is safe to terminate cnid_dbd
  50 this way, it will be restarted when necessary. Other signals are not
  51 handled and will cause an immediate exit, possibly leaving the CNID
  52 database in an inconsistent state (no transactions) or losing recent
  53 updates during recovery (transactions).
  54 .PP
  55 If transactions are used the \fIBerkleley DB\fR
  56 database subsystem will create files named log.xxxxxxxxxx in the
  57 database home directory \fIdbdir\fR, where xxxxxxxxxx
  58 is a monotonically increasing integer. These files contain information to
  59 replay database changes and are not automatically removed. Please see the sections
  60 \fIDatabase and log file archival\fR, \fI
  61 Log file removal\fR and the documentation of the \fI
  62 db_archive\fR command line utility in the Berkeley DB Tutorial and Reference
  63 for information when and how it is safe to remove these files.
  64 .SH CONFIGURATION
  65 cnid_dbd reads configuration information from the
  66 file \fIdb_param\fR in the database directory
  67 \fIdbdir\fR on startup. If the file does not
  68 exist or a parameter is not listed, suitable default values are used. The
  69 format for a single parameter is the parameter name, followed by one or
  70 more spaces, followed by the parameter value, followed by a newline. The
  71 following parameters are currently recognized:
  72 .TP
  73 \fIcachesize\fR
  74 Determines the size of the Berkeley DB cache in kilobytes.
  75 Default: 1024. Each cnid_dbd process grabs that
  76 much memory on top of its normal memory footprint. It can be used to
  77 tune database performance. The \fIdb_stat\fR
  78 utility with the \fB\-m\fR option that comes with Berkely
  79 DB can help you determine wether you need to change this value. The
  80 default is pretty conservative so that a large percentage of
  81 requests should be satisfied from the cache directly. If memory is
  82 not a bottleneck on your system you might want to leave it at that
  83 value. The \fIBerkeley DB Tutorial and Reference
  84 Guide\fR has a section \fISelecting a cache
  85 size\fR that gives more detailed information.
  86 .TP
  87 \fInosync\fR
  88 This flag is only valid if transactional support is enabled.
  89 If it is set to 1, transactional changes to the database are not
  90 synchronously written to disk when the transaction completes. This
  91 will increase performance considerably at the risk of recent changes
  92 getting lost in case of a crash. The database will still be
  93 consistent, though. See \fITransaction Throughput\fR
  94 in the Berkeley DB Tutorial for more information. Default: 0.
  95 .TP
  96 \fIflush_frequency\fR, \fIflush_interval\fR
  97 \fIflush_frequency\fR (Default: 100)
  98 and \fIflush_interval\fR (Default: 30)
  99 control how often changes to the database are written to the
 100 underlying database files if no transactions are used or how often
 101 the transaction system is checkpointed for transactions. Both of
 102 these operations are performed if either i) more than \fIflush_frequency\fR requests have been received or
 103 ii) more than \fIflush_interval\fR seconds
 104 have elapsed since the last save/checkpoint. If you use transactions
 105 with \fInosync\fR set to zero these
 106 parameters only influence how long recovery takes after a crash,
 107 there should never be any lost data. If \fInosync\fR
 108 is 1, changes might be lost, but only since the last checkpoint. Be
 109 careful to check your harddisk configuration for on disk cache
 110 settings. Many IDE disks just cache writes as the default behaviour,
 111 so even flushing database files to disk will not have the desired
 112 effect.
 113 .TP
 114 \fIfd_table_size\fR
 115 is the maximum number of connections (filedescriptors) that
 116 can be open for \fIafpd\fR client processes
 117 in \fIcnid_dbd.\fR Default: 16. If this
 118 number is exceeded, one of the existing connections is closed and
 119 reused. The affected \fIafpd\fR process
 120 will transparently reconnect later, which causes slight overhead. On
 121 the other hand, setting this parameter too high could affect
 122 performance in cnid_dbd since all descriptors
 123 have to be checked in a select() system call,
 124 or worse, you might exceed the per process limit of open file
 125 descriptors on your system. It is safe to set the value to 1 on
 126 volumes where only one \fIafpd\fR client
 127 process is expected to run, e.g. home directories.
 128 .TP
 129 \fIidle_timeout\fR
 130 is the number of seconds of inactivity before an idle
 131 cnid_dbd exits. Default: 600. Set this to 0 to
 132 disable the timeout.
 133 .SH SEE\ ALSO
 134 \fBcnid_metad\fR(1),
 135 \fBafpd\fR(8)
 136