man/man8/cnid_dbd.8.tmpl

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