man/man8/cnid_dbd.8.tmpl

   1 '\" t
   2 .\"     Title: cnid_dbd
   3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.74.3 <http://docbook.sf.net/>
   5 .\"      Date: 2 Dec 2003
   6 .\"    Manual: Netatalk 2.0.4
   7 .\"    Source: Netatalk 2.0.4
   8 .\"  Language: English
   9 .\"
  10 .TH "CNID_DBD" "8" "2 Dec 2003" "Netatalk 2\&.0\&.4" "Netatalk 2.0.4"
  11 .\" -----------------------------------------------------------------
  12 .\" * set default formatting
  13 .\" -----------------------------------------------------------------
  14 .\" disable hyphenation
  15 .nh
  16 .\" disable justification (adjust text to left margin only)
  17 .ad l
  18 .\" -----------------------------------------------------------------
  19 .\" * MAIN CONTENT STARTS HERE *
  20 .\" -----------------------------------------------------------------
  21 .SH "NAME"
  22 cnid_dbd \- implement access to CNID databases through a dedicated daemon process
  23 .SH "SYNOPSIS"
  24 .HP \w'\fBcnid_dbd\fR\fB\fR\fB\fR\fB\fR\ 'u
  25 \fBcnid_dbd\fR\fB\fR\fB\fR\fB\fR \fIdbdir\fR \fIctrlfd\fR \fIclntfd\fR
  26 .SH "DESCRIPTION"
  27 .PP
  28 \fBcnid_dbd\fR
  29 provides an interface for storage and retrieval of catalog node IDs (CNIDs) and related information to the
  30 \fBafpd\fR
  31 daemon\&. CNIDs are a component of Macintosh based file systems with semantics that map not easily onto Unix file systems\&. This makes separate storage in a database necessary\&.
  32 \fBcnid_dbd\fR
  33 is part of the
  34 \fBCNID backend\fR
  35 framework of
  36 \fBafpd\fR
  37 and implements the
  38 \fBdbd\fR
  39 backend\&.
  40 .PP
  41 \fBcnid_dbd\fR
  42 is never started via the command line or system startup scripts but only by the
  43 \fBcnid_metad\fR
  44 daemon\&. There is at most one instance of
  45 \fBcnid_dbd\fR
  46 per netatalk volume\&.
  47 .PP
  48 \fBcnid_dbd\fR
  49 uses the
  50 \fBBerkleley DB\fR
  51 database library and optionally supports transactionally protected updates if the netatalk package is compiled with the appropriate options\&. Using the
  52 \fBdbd\fR
  53 backend without transactions will protect the CNID database against unexpected crashes of the
  54 \fBafpd\fR
  55 daemon\&. Using the
  56 \fBdbd\fR
  57 backend with transactions will avoid corruption of the CNID database even if the system crashes unexpectedly\&.
  58 .PP
  59 \fBcnid_dbd\fR
  60 uses the same on\-disk database format as the
  61 \fBcdb\fR
  62 backend\&. It is therefore possible to switch between the two backends as necessary\&.
  63 .PP
  64 \fBcnid_dbd\fR
  65 inherits the effective userid and groupid from
  66 \fBcnid_metad\fR
  67 on startup, which is normally caused by
  68 \fBafpd\fR
  69 serving a netatalk volume to a client\&. It changes to the
  70 \fBBerkleley DB\fR
  71 database home directory
  72 \fIdbdir\fR
  73 that is associated with the volume\&. If the userid inherited from
  74 \fBcnid_metad\fR
  75 is 0 (root),
  76 \fBcnid_dbd\fR
  77 will change userid and groupid to the owner and group of the database home directory\&. Otherwise, it will continue to use the inherited values\&.
  78 \fBcnid_dbd\fR
  79 will then attempt to open the database and start serving requests using filedescriptor
  80 \fIclntfd\fR\&. Subsequent instances of
  81 \fBafpd\fR
  82 that want to access the same volume are redirected to the running
  83 \fBcnid_dbd\fR
  84 process by
  85 \fBcnid_metad\fR
  86 via the filedescriptor
  87 \fIctrlfd\fR\&.
  88 .PP
  89 \fBcnid_dbd\fR
  90 can be configured to run forever or to exit after a period of inactivity\&. If
  91 \fBcnid_dbd\fR
  92 receives a TERM or an INT signal it will exit cleanly after flushing dirty database buffers to disk and closing
  93 \fBBerkleley DB\fR
  94 database environments\&. It is safe to terminate
  95 \fBcnid_dbd\fR
  96 this way, it will be restarted when necessary\&. Other signals are not handled and will cause an immediate exit, possibly leaving the CNID database in an inconsistent state (no transactions) or losing recent updates during recovery (transactions)\&.
  97 .PP
  98 If transactions are used the
  99 \fBBerkleley DB\fR
 100 database subsystem will create files named log\&.xxxxxxxxxx in the database home directory
 101 \fIdbdir\fR, where xxxxxxxxxx is a monotonically increasing integer\&. These files contain information to replay database changes and are not automatically removed, unless the
 102 \fBlogfile_autoremove\fR
 103 option is specified in the
 104 \fIdb_param\fR
 105 configuration file (see below)\&. Please see the sections
 106 \fBDatabase and log file archival\fR,
 107 \fB Log file removal\fR
 108 and the documentation of the
 109 \fB db_archive\fR
 110 command line utility in the Berkeley DB Tutorial and Reference for information when and how it is safe to remove these files manually\&.
 111 .PP
 112 Do not use
 113 \fBcnid_dbd\fR
 114 for databases on NFS mounted file systems\&. It makes the whole point of securing database changes properly moot\&. Use the dbdir: Option in the appropriate
 115 \fBAppleVolumes\fR
 116 configuration file to put the database onto a local disk\&.
 117 .SH "CONFIGURATION"
 118 .PP
 119 \fBcnid_dbd\fR
 120 reads configuration information from the file
 121 \fIdb_param\fR
 122 in the database directory
 123 \fIdbdir\fR
 124 on startup\&. If the file does not exist or a parameter is not listed, suitable default values are used\&. The format for a single parameter is the parameter name, followed by one or more spaces, followed by the parameter value, followed by a newline\&. The following parameters are currently recognized:
 125 .PP
 126 \fBlogfile_autoremove\fR
 127 .RS 4
 128 This flag is ignored unless transactional support is enabled\&. If set to 1, unused Berkeley DB transactional logfiles (log\&.xxxxxxxxxx in the database home directory) are removed on startup of
 129 \fBcnid_dbd\fR\&. This is usually safe if the content of the database directory is backed up on a regular basis\&. Default: 0\&.
 130 .RE
 131 .PP
 132 \fBcachesize\fR
 133 .RS 4
 134 Determines the size of the Berkeley DB cache in kilobytes\&. Default: 1024\&. Each
 135 \fBcnid_dbd\fR
 136 process grabs that much memory on top of its normal memory footprint\&. It can be used to tune database performance\&. The
 137 \fBdb_stat\fR
 138 utility with the
 139 \fB\-m\fR
 140 option that comes with Berkely DB can help you determine wether you need to change this value\&. The default is pretty conservative so that a large percentage of requests should be satisfied from the cache directly\&. If memory is not a bottleneck on your system you might want to leave it at that value\&. The
 141 \fBBerkeley DB Tutorial and Reference Guide\fR
 142 has a section
 143 \fBSelecting a cache size\fR
 144 that gives more detailed information\&.
 145 .RE
 146 .PP
 147 \fBnosync\fR
 148 .RS 4
 149 This flag is ignored unless transactional support is enabled\&. If it is set to 1, transactional changes to the database are not synchronously written to disk when the transaction completes\&. This will increase performance considerably at the risk of recent changes getting lost in case of a crash\&. The database will still be consistent, though\&. See
 150 \fBTransaction Throughput\fR
 151 in the Berkeley DB Tutorial for more information\&. Default: 0\&.
 152 .RE
 153 .PP
 154 \fBflush_frequency\fR, \fBflush_interval\fR
 155 .RS 4
 156 \fIflush_frequency\fR
 157 (Default: 100) and
 158 \fIflush_interval\fR
 159 (Default: 30) control how often changes to the database are written to the underlying database files if no transactions are used or how often the transaction system is checkpointed for transactions\&. Both of these operations are performed if either i) more than
 160 \fIflush_frequency\fR
 161 requests have been received or ii) more than
 162 \fIflush_interval\fR
 163 seconds have elapsed since the last save/checkpoint\&. If you use transactions with
 164 \fInosync\fR
 165 set to zero these parameters only influence how long recovery takes after a crash, there should never be any lost data\&. If
 166 \fInosync\fR
 167 is 1, changes might be lost, but only since the last checkpoint\&. Be careful to check your harddisk configuration for on disk cache settings\&. Many IDE disks just cache writes as the default behaviour, so even flushing database files to disk will not have the desired effect\&.
 168 .RE
 169 .PP
 170 \fBfd_table_size\fR
 171 .RS 4
 172 is the maximum number of connections (filedescriptors) that can be open for
 173 \fBafpd\fR
 174 client processes in
 175 \fBcnid_dbd\&.\fR
 176 Default: 16\&. If this number is exceeded, one of the existing connections is closed and reused\&. The affected
 177 \fBafpd\fR
 178 process will transparently reconnect later, which causes slight overhead\&. On the other hand, setting this parameter too high could affect performance in
 179 \fBcnid_dbd\fR
 180 since all descriptors have to be checked in a
 181 \fBselect()\fR
 182 system call, or worse, you might exceed the per process limit of open file descriptors on your system\&. It is safe to set the value to 1 on volumes where only one
 183 \fBafpd\fR
 184 client process is expected to run, e\&.g\&. home directories\&.
 185 .RE
 186 .PP
 187 \fBidle_timeout\fR
 188 .RS 4
 189 is the number of seconds of inactivity before an idle
 190 \fBcnid_dbd\fR
 191 exits\&. Default: 600\&. Set this to 0 to disable the timeout\&.
 192 .RE
 193 .PP
 194 \fBcheck\fR
 195 .RS 4
 196 is a flag value\&. If set
 197 \fBcnid_dbd\fR
 198 will automatically check the database indexes\&. Default: 0\&. Set this to 1 to enable checking\&.
 199 .RE
 200 .SH "SEE ALSO"
 201 .PP
 202 \fBcnid_metad\fR(8),
 203 \fBafpd\fR(8)