man/man8/cnid_dbd.8.in

   1 '\" t
   2 .\"     Title: cnid_dbd
   3 .\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
   4 .\" Generator: DocBook XSL Stylesheets v1.78.0 <http://docbook.sf.net/>
   5 .\"      Date: 01 Jan 2012
   6 .\"    Manual: @NETATALK_VERSION@
   7 .\"    Source: @NETATALK_VERSION@
   8 .\"  Language: English
   9 .\"
  10 .TH "CNID_DBD" "8" "01 Jan 2012" "@NETATALK_VERSION@" "@NETATALK_VERSION@"
  11 .\" -----------------------------------------------------------------
  12 .\" * Define some portability stuff
  13 .\" -----------------------------------------------------------------
  14 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15 .\" http://bugs.debian.org/507673
  16 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
  17 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  18 .ie \n(.g .ds Aq \(aq
  19 .el       .ds Aq '
  20 .\" -----------------------------------------------------------------
  21 .\" * set default formatting
  22 .\" -----------------------------------------------------------------
  23 .\" disable hyphenation
  24 .nh
  25 .\" disable justification (adjust text to left margin only)
  26 .ad l
  27 .\" -----------------------------------------------------------------
  28 .\" * MAIN CONTENT STARTS HERE *
  29 .\" -----------------------------------------------------------------
  30 .SH "NAME"
  31 cnid_dbd \- implement access to CNID databases through a dedicated daemon process
  32 .SH "SYNOPSIS"
  33 .HP \w'\fBcnid_dbd\fR\fB\fR\fB\fR\fB\fR\fBcnid_dbd\fR\fB\fR\ 'u
  34 \fBcnid_dbd\fR\fB\fR\fB\fR\fB\fR
  35 .br
  36 \fBcnid_dbd\fR\fB\fR \-v | \-V
  37 .SH "DESCRIPTION"
  38 .PP
  39 \fBcnid_dbd\fR
  40 provides an interface for storage and retrieval of catalog node IDs (CNIDs) and related information to the
  41 \fBafpd\fR
  42 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\&.
  43 \fBcnid_dbd\fR
  44 is part of the
  45 \fBCNID backend\fR
  46 framework of
  47 \fBafpd\fR
  48 and implements the
  49 \fBdbd\fR
  50 backend\&.
  51 .PP
  52 \fBcnid_dbd\fR
  53 is never started via the command line or system startup scripts but only by the
  54 \fBcnid_metad\fR
  55 daemon\&. There is one instance of
  56 \fBcnid_dbd\fR
  57 per netatalk volume\&.
  58 .PP
  59 \fBcnid_dbd\fR
  60 uses the
  61 \fBBerkeley DB\fR
  62 database library and uses transactionally protected updates\&. The
  63 \fBdbd\fR
  64 backend with transactions will avoid corruption of the CNID database even if the system crashes unexpectedly\&.
  65 .PP
  66 \fBcnid_dbd\fR
  67 inherits the effective userid and groupid from
  68 \fBcnid_metad\fR
  69 on startup, which is normally caused by
  70 \fBafpd\fR
  71 serving a netatalk volume to a client\&. It changes to the
  72 \fBBerkeley DB\fR
  73 database home directory
  74 \fIdbdir\fR
  75 that is associated with the volume\&. If the userid inherited from
  76 \fBcnid_metad\fR
  77 is 0 (root),
  78 \fBcnid_dbd\fR
  79 will change userid and groupid to the owner and group of the database home directory\&. Otherwise, it will continue to use the inherited values\&.
  80 \fBcnid_dbd\fR
  81 will then attempt to open the database and start serving requests using filedescriptor
  82 \fIclntfd\fR\&. Subsequent instances of
  83 \fBafpd\fR
  84 that want to access the same volume are redirected to the running
  85 \fBcnid_dbd\fR
  86 process by
  87 \fBcnid_metad\fR
  88 via the filedescriptor
  89 \fIctrlfd\fR\&.
  90 .PP
  91 \fBcnid_dbd\fR
  92 can be configured to run forever or to exit after a period of inactivity\&. If
  93 \fBcnid_dbd\fR
  94 receives a TERM or an INT signal it will exit cleanly after flushing dirty database buffers to disk and closing
  95 \fBBerkeley DB\fR
  96 database environments\&. It is safe to terminate
  97 \fBcnid_dbd\fR
  98 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)\&.
  99 .PP
 100 The
 101 \fBBerkeley DB\fR
 102 database subsystem will create files named log\&.xxxxxxxxxx in the database home directory
 103 \fIdbdir\fR, where xxxxxxxxxx is a monotonically increasing integer\&. These files contain the transactional database changes\&. They will be removed regularly, unless the
 104 \fBlogfile_autoremove\fR
 105 option is specified in the
 106 \fIdb_param\fR
 107 configuration file (see below) with a value of 0 (default 1)\&.
 108 .SH "OPTIONS"
 109 .PP
 110 \fB\-v, \-V\fR
 111 .RS 4
 112 Show version and exit\&.
 113 .RE
 114 .SH "CONFIGURATION"
 115 .PP
 116 \fBcnid_dbd\fR
 117 reads configuration information from the file
 118 \fIdb_param\fR
 119 in the database directory
 120 \fIdbdir\fR
 121 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:
 122 .PP
 123 \fBlogfile_autoremove\fR
 124 .RS 4
 125 If set to 0, unused Berkeley DB transactional logfiles (log\&.xxxxxxxxxx in the database home directory) are not removed on startup of
 126 \fBcnid_dbd\fR
 127 and on a regular basis\&. Default: 1\&.
 128 .RE
 129 .PP
 130 \fBcachesize\fR
 131 .RS 4
 132 Determines the size of the Berkeley DB cache in kilobytes\&. Default: 8192\&. Each
 133 \fBcnid_dbd\fR
 134 process grabs that much memory on top of its normal memory footprint\&. It can be used to tune database performance\&. The
 135 \fBdb_stat\fR
 136 utility with the
 137 \fB\-m\fR
 138 option that comes with Berkley DB can help you determine ether 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
 139 \fBBerkeley DB Tutorial and Reference Guide\fR
 140 has a section
 141 \fBSelecting a cache size\fR
 142 that gives more detailed information\&.
 143 .RE
 144 .PP
 145 \fBflush_frequency\fR, \fBflush_interval\fR
 146 .RS 4
 147 \fIflush_frequency\fR
 148 (Default: 1000) and
 149 \fIflush_interval\fR
 150 (Default: 1800) control how often changes to the database are checkpointed\&. Both of these operations are performed if either i) more than
 151 \fIflush_frequency\fR
 152 requests have been received or ii) more than
 153 \fIflush_interval\fR
 154 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\&.
 155 .RE
 156 .PP
 157 \fBfd_table_size\fR
 158 .RS 4
 159 is the maximum number of connections (filedescriptors) that can be open for
 160 \fBafpd\fR
 161 client processes in
 162 \fBcnid_dbd\&.\fR
 163 Default: 512\&. If this number is exceeded, one of the existing connections is closed and reused\&. The affected
 164 \fBafpd\fR
 165 process will transparently reconnect later, which causes slight overhead\&. On the other hand, setting this parameter too high could affect performance in
 166 \fBcnid_dbd\fR
 167 since all descriptors have to be checked in a
 168 \fBselect()\fR
 169 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
 170 \fBafpd\fR
 171 client process is expected to run, e\&.g\&. home directories\&.
 172 .RE
 173 .PP
 174 \fBidle_timeout\fR
 175 .RS 4
 176 is the number of seconds of inactivity before an idle
 177 \fBcnid_dbd\fR
 178 exits\&. Default: 600\&. Set this to 0 to disable the timeout\&.
 179 .RE
 180 .SH "UPDATING"
 181 .PP
 182 Note that the first version to appear
 183 \fIafter\fR
 184 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\*(Aqt upgrade a 2\&.0\&.x version because that one didn\*(Aqt prepare the database\&.
 185 .PP
 186 In order to update between older Netatalk releases using different BerkeleyDB library versions, follow this steps:
 187 .sp
 188 .RS 4
 189 .ie n \{\
 190 \h'-04'\(bu\h'+03'\c
 191 .\}
 192 .el \{\
 193 .sp -1
 194 .IP \(bu 2.3
 195 .\}
 196 Stop the to be upgraded old version of Netatalk
 197 .RE
 198 .sp
 199 .RS 4
 200 .ie n \{\
 201 \h'-04'\(bu\h'+03'\c
 202 .\}
 203 .el \{\
 204 .sp -1
 205 .IP \(bu 2.3
 206 .\}
 207 Using the old BerkeleyDB utilities run
 208 \fBdb_recover \-h <path to \&.AppleDB>\fR
 209 .RE
 210 .sp
 211 .RS 4
 212 .ie n \{\
 213 \h'-04'\(bu\h'+03'\c
 214 .\}
 215 .el \{\
 216 .sp -1
 217 .IP \(bu 2.3
 218 .\}
 219 Using the new BerkeleyDB utilities run
 220 \fBdb_upgrade \-v \-h <path to \&.AppleDB> \-f cnid2\&.db\fR
 221 .RE
 222 .sp
 223 .RS 4
 224 .ie n \{\
 225 \h'-04'\(bu\h'+03'\c
 226 .\}
 227 .el \{\
 228 .sp -1
 229 .IP \(bu 2.3
 230 .\}
 231 Again using the new BerkeleyDB utilities run
 232 \fBdb_checkpoint \-1 \-h <path to \&.AppleDB>\fR
 233 .RE
 234 .sp
 235 .RS 4
 236 .ie n \{\
 237 \h'-04'\(bu\h'+03'\c
 238 .\}
 239 .el \{\
 240 .sp -1
 241 .IP \(bu 2.3
 242 .\}
 243 Start the the new version of Netatalk
 244 .RE
 245 .SH "SEE ALSO"
 246 .PP
 247 \fBcnid_metad\fR(8),
 248 \fBafpd\fR(8),
 249 \fBdbd\fR(1)