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.75.2 <http://docbook.sf.net/>
   5 .\"      Date: 01 Jan 2012
   6 .\"    Manual: Netatalk 2.2
   7 .\"    Source: Netatalk 2.2
   8 .\"  Language: English
   9 .\"
  10 .TH "CNID_DBD" "8" "01 Jan 2012" "Netatalk 2.2" "Netatalk 2.2"
  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\fBcnid_dbd\fR\fB\fR\ 'u
  25 \fBcnid_dbd\fR\fB\fR\fB\fR\fB\fR \fIvolpath\fR \fIctrlfd\fR \fIclntfd\fR \fIlogconfig_string\fR
  26 .br
  27 \fBcnid_dbd\fR\fB\fR \-v | \-V
  28 .SH "DESCRIPTION"
  29 .PP
  30 \fBcnid_dbd\fR
  31 provides an interface for storage and retrieval of catalog node IDs (CNIDs) and related information to the
  32 \fBafpd\fR
  33 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\&.
  34 \fBcnid_dbd\fR
  35 is part of the
  36 \fBCNID backend\fR
  37 framework of
  38 \fBafpd\fR
  39 and implements the
  40 \fBdbd\fR
  41 backend\&.
  42 .PP
  43 \fBcnid_dbd\fR
  44 is never started via the command line or system startup scripts but only by the
  45 \fBcnid_metad\fR
  46 daemon\&. There is one instance of
  47 \fBcnid_dbd\fR
  48 per netatalk volume\&.
  49 .PP
  50 \fBcnid_dbd\fR
  51 uses the
  52 \fBBerkleley DB\fR
  53 database library and uses transactionally protected updates\&. The
  54 \fBdbd\fR
  55 backend with transactions will avoid corruption of the CNID database even if the system crashes unexpectedly\&.
  56 .PP
  57 \fBcnid_dbd\fR
  58 inherits the effective userid and groupid from
  59 \fBcnid_metad\fR
  60 on startup, which is normally caused by
  61 \fBafpd\fR
  62 serving a netatalk volume to a client\&. It changes to the
  63 \fBBerkleley DB\fR
  64 database home directory
  65 \fIdbdir\fR
  66 that is associated with the volume\&. If the userid inherited from
  67 \fBcnid_metad\fR
  68 is 0 (root),
  69 \fBcnid_dbd\fR
  70 will change userid and groupid to the owner and group of the database home directory\&. Otherwise, it will continue to use the inherited values\&.
  71 \fBcnid_dbd\fR
  72 will then attempt to open the database and start serving requests using filedescriptor
  73 \fIclntfd\fR\&. Subsequent instances of
  74 \fBafpd\fR
  75 that want to access the same volume are redirected to the running
  76 \fBcnid_dbd\fR
  77 process by
  78 \fBcnid_metad\fR
  79 via the filedescriptor
  80 \fIctrlfd\fR\&.
  81 .PP
  82 \fBcnid_dbd\fR
  83 uses
  84 \fBlogconfig_string\fR
  85 which is passed from
  86 \fBcnid_metad\fR
  87 to configure its logging output\&.
  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 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 ithe transactional database changes\&. They will be removed regularily, unless the
 102 \fBlogfile_autoremove\fR
 103 option is specified in the
 104 \fIdb_param\fR
 105 configuration file (see below) with a value of 0 (default 1)\&.
 106 .PP
 107 Do not use
 108 \fBcnid_dbd\fR
 109 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
 110 \fBAppleVolumes\fR
 111 configuration file to put the database onto a local disk\&.
 112 .SH "OPTIONS"
 113 .PP
 114 \fB\-v, \-V\fR
 115 .RS 4
 116 Show version and exit\&.
 117 .RE
 118 .SH "CONFIGURATION"
 119 .PP
 120 \fBcnid_dbd\fR
 121 reads configuration information from the file
 122 \fIdb_param\fR
 123 in the database directory
 124 \fIdbdir\fR
 125 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:
 126 .PP
 127 \fBlogfile_autoremove\fR
 128 .RS 4
 129 If set to 0, unused Berkeley DB transactional logfiles (log\&.xxxxxxxxxx in the database home directory) are not removed on startup of
 130 \fBcnid_dbd\fR
 131 and on a reqular basis\&. Default: 1\&.
 132 .RE
 133 .PP
 134 \fBcachesize\fR
 135 .RS 4
 136 Determines the size of the Berkeley DB cache in kilobytes\&. Default: 8192\&. Each
 137 \fBcnid_dbd\fR
 138 process grabs that much memory on top of its normal memory footprint\&. It can be used to tune database performance\&. The
 139 \fBdb_stat\fR
 140 utility with the
 141 \fB\-m\fR
 142 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
 143 \fBBerkeley DB Tutorial and Reference Guide\fR
 144 has a section
 145 \fBSelecting a cache size\fR
 146 that gives more detailed information\&.
 147 .RE
 148 .PP
 149 \fBflush_frequency\fR, \fBflush_interval\fR
 150 .RS 4
 151 \fIflush_frequency\fR
 152 (Default: 1000) and
 153 \fIflush_interval\fR
 154 (Default: 1800) control how often changes to the database are checkpointed\&. Both of these operations are performed if either i) more than
 155 \fIflush_frequency\fR
 156 requests have been received or ii) more than
 157 \fIflush_interval\fR
 158 seconds have elapsed since the last save/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\&.
 159 .RE
 160 .PP
 161 \fBfd_table_size\fR
 162 .RS 4
 163 is the maximum number of connections (filedescriptors) that can be open for
 164 \fBafpd\fR
 165 client processes in
 166 \fBcnid_dbd\&.\fR
 167 Default: 512\&. If this number is exceeded, one of the existing connections is closed and reused\&. The affected
 168 \fBafpd\fR
 169 process will transparently reconnect later, which causes slight overhead\&. On the other hand, setting this parameter too high could affect performance in
 170 \fBcnid_dbd\fR
 171 since all descriptors have to be checked in a
 172 \fBselect()\fR
 173 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
 174 \fBafpd\fR
 175 client process is expected to run, e\&.g\&. home directories\&.
 176 .RE
 177 .PP
 178 \fBidle_timeout\fR
 179 .RS 4
 180 is the number of seconds of inactivity before an idle
 181 \fBcnid_dbd\fR
 182 exits\&. Default: 600\&. Set this to 0 to disable the timeout\&.
 183 .RE
 184 .SH "UPDATING"
 185 .PP
 186 Note that the first version to appear
 187 \fIafter\fR
 188 Netatalk 2\&.1 ie Netatalk 2\&.1\&.1, will support BerkeleyDB updates on the fly without manual intervention\&. In other words Netatalk 2\&.1 does contain code to prepare the BerkeleyDB database for upgrades and to upgrade it in case it has been prepared before\&. That means it can\'t upgrade a 2\&.0\&.x version because that one didn\'t prepare the database\&.
 189 .PP
 190 In order to update between older Netatalk releases using different BerkeleyDB library versions, follow this steps:
 191 .sp
 192 .RS 4
 193 .ie n \{\
 194 \h'-04'\(bu\h'+03'\c
 195 .\}
 196 .el \{\
 197 .sp -1
 198 .IP \(bu 2.3
 199 .\}
 200 Stop the to be upgraded old version of Netatalk
 201 .RE
 202 .sp
 203 .RS 4
 204 .ie n \{\
 205 \h'-04'\(bu\h'+03'\c
 206 .\}
 207 .el \{\
 208 .sp -1
 209 .IP \(bu 2.3
 210 .\}
 211 Using the old BerkeleyDB utilities run
 212 \fBdb_recover \-h <path to \&.AppleDB>\fR
 213 .RE
 214 .sp
 215 .RS 4
 216 .ie n \{\
 217 \h'-04'\(bu\h'+03'\c
 218 .\}
 219 .el \{\
 220 .sp -1
 221 .IP \(bu 2.3
 222 .\}
 223 Using the new BerkeleyDB utilities run
 224 \fBdb_upgrade \-v \-h <path to \&.AppleDB> \-f cnid2\&.db\fR
 225 .RE
 226 .sp
 227 .RS 4
 228 .ie n \{\
 229 \h'-04'\(bu\h'+03'\c
 230 .\}
 231 .el \{\
 232 .sp -1
 233 .IP \(bu 2.3
 234 .\}
 235 Again using the new BerkeleyDB utilities run
 236 \fBdb_checkpoint \-1 \-h <path to \&.AppleDB>\fR
 237 .RE
 238 .sp
 239 .RS 4
 240 .ie n \{\
 241 \h'-04'\(bu\h'+03'\c
 242 .\}
 243 .el \{\
 244 .sp -1
 245 .IP \(bu 2.3
 246 .\}
 247 Start the the new version of Netatalk
 248 .RE
 249 .SH "SEE ALSO"
 250 .PP
 251 \fBcnid_metad\fR(8),
 252 \fBafpd\fR(8),
 253 \fBdbd\fR(1)