doc/manpages/man8/cnid_dbd.8.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <refentry id="cnid_dbd.8">
   3   <refmeta>
   4     <refentrytitle>cnid_dbd</refentrytitle>
   5
   6     <manvolnum>8</manvolnum>
   7
   8     <refmiscinfo class="date">01 Jan 2012</refmiscinfo>
   9
  10     <refmiscinfo class="source">@NETATALK_VERSION@</refmiscinfo>
  11   </refmeta>
  12
  13   <refnamediv>
  14     <refname>cnid_dbd</refname>
  15
  16     <refpurpose>implement access to CNID databases through a dedicated daemon
  17     process</refpurpose>
  18   </refnamediv>
  19
  20   <refsynopsisdiv>
  21     <cmdsynopsis>
  22       <command>cnid_dbd<indexterm>
  23           <primary>cnid_dbd</primary>
  24         </indexterm><indexterm>
  25           <primary>CNID backend</primary>
  26         </indexterm><indexterm>
  27           <primary>NFS</primary>
  28
  29           <secondary>Network File System</secondary>
  30         </indexterm></command>
  31
  32       <sbr />
  33
  34       <command>cnid_dbd<indexterm>
  35           <primary>cnid_dbd</primary>
  36         </indexterm></command>
  37
  38         <group choice="plain">
  39           <arg choice="plain">-v</arg>
  40           <arg choice="plain">-V</arg>
  41         </group>
  42     </cmdsynopsis>
  43   </refsynopsisdiv>
  44
  45   <refsect1>
  46     <title>DESCRIPTION</title>
  47
  48     <para><command>cnid_dbd</command> provides an interface for storage and
  49     retrieval of catalog node IDs (CNIDs) and related information to the
  50     <emphasis remap="B">afpd</emphasis> daemon. CNIDs are a component of
  51     Macintosh based file systems with semantics that map not easily onto Unix
  52     file systems. This makes separate storage in a database necessary.
  53     <command>cnid_dbd</command> is part of the <emphasis remap="B">CNID
  54     backend</emphasis> framework of <emphasis remap="B">afpd</emphasis> and
  55     implements the <emphasis remap="B">dbd</emphasis> backend.</para>
  56
  57     <para><command>cnid_dbd</command> is never started via the command line or
  58     system startup scripts but only by the <emphasis
  59     remap="B">cnid_metad</emphasis> daemon. There is one instance of
  60     <command>cnid_dbd</command> per netatalk volume.</para>
  61
  62     <para><command>cnid_dbd</command> uses the <emphasis remap="B">Berkeley
  63     DB</emphasis> database library and uses transactionally protected updates.
  64     The <emphasis remap="B">dbd</emphasis> backend with transactions will
  65     avoid corruption of the CNID database even if the system crashes
  66     unexpectedly.</para>
  67
  68     <para><command>cnid_dbd</command> inherits the effective userid and
  69     groupid from <emphasis remap="B">cnid_metad</emphasis> on startup, which
  70     is normally caused by <emphasis remap="B">afpd</emphasis> serving a
  71     netatalk volume to a client. It changes to the <emphasis
  72     remap="B">Berkeley DB</emphasis> database home directory <emphasis
  73     remap="I">dbdir</emphasis> that is associated with the volume. If the
  74     userid inherited from <emphasis remap="B">cnid_metad</emphasis> is 0
  75     (root), <command>cnid_dbd</command> will change userid and groupid to the
  76     owner and group of the database home directory. Otherwise, it will
  77     continue to use the inherited values. <command>cnid_dbd</command> will
  78     then attempt to open the database and start serving requests using
  79     filedescriptor <emphasis remap="I">clntfd</emphasis>. Subsequent instances
  80     of <emphasis remap="B">afpd</emphasis> that want to access the same volume
  81     are redirected to the running <command>cnid_dbd</command> process by
  82     <emphasis remap="B">cnid_metad</emphasis> via the filedescriptor <emphasis
  83     remap="I">ctrlfd</emphasis>.</para>
  84
  85     <para><command>cnid_dbd</command> can be configured to run forever or to
  86     exit after a period of inactivity. If <command>cnid_dbd</command> receives
  87     a TERM or an INT signal it will exit cleanly after flushing dirty database
  88     buffers to disk and closing <emphasis remap="B">Berkeley DB</emphasis>
  89     database environments. It is safe to terminate <command>cnid_dbd</command>
  90     this way, it will be restarted when necessary. Other signals are not
  91     handled and will cause an immediate exit, possibly leaving the CNID
  92     database in an inconsistent state (no transactions) or losing recent
  93     updates during recovery (transactions).</para>
  94
  95     <para>The <emphasis remap="B">Berkeley DB</emphasis> database subsystem
  96     will create files named log.xxxxxxxxxx in the database home directory
  97     <emphasis remap="I">dbdir</emphasis>, where xxxxxxxxxx is a monotonically
  98     increasing integer. These files contain the transactional database
  99     changes. They will be removed regularly, unless the <emphasis
 100     remap="B">logfile_autoremove</emphasis> option is specified in the
 101     <emphasis remap="I">db_param</emphasis> configuration file (see
 102     below) with a value of 0 (default 1).</para>
 103   </refsect1>
 104
 105   <refsect1>
 106     <title>OPTIONS</title>
 107
 108     <variablelist remap="TP">
 109       <varlistentry>
 110         <term><option>-v, -V</option></term>
 111
 112         <listitem>
 113           <para>Show version and exit.</para>
 114         </listitem>
 115       </varlistentry>
 116     </variablelist>
 117   </refsect1>
 118
 119   <refsect1>
 120     <title>CONFIGURATION</title>
 121
 122     <para><command>cnid_dbd</command> reads configuration information from the
 123     file <emphasis remap="I">db_param</emphasis> in the database directory
 124     <emphasis remap="I">dbdir</emphasis> on startup. If the file does not
 125     exist or a parameter is not listed, suitable default values are used. The
 126     format for a single parameter is the parameter name, followed by one or
 127     more spaces, followed by the parameter value, followed by a newline. The
 128     following parameters are currently recognized:</para>
 129
 130     <variablelist remap="TP">
 131       <varlistentry>
 132         <term><emphasis remap="B">logfile_autoremove</emphasis></term>
 133
 134         <listitem>
 135           <para>If set to 0, unused Berkeley DB transactional logfiles
 136           (log.xxxxxxxxxx in the database home directory) are not removed on
 137           startup of <command>cnid_dbd</command> and on a regular basis.
 138           Default: 1.</para>
 139         </listitem>
 140       </varlistentry>
 141
 142       <varlistentry>
 143         <term><emphasis remap="B">cachesize</emphasis></term>
 144
 145         <listitem>
 146           <para>Determines the size of the Berkeley DB cache in kilobytes.
 147           Default: 8192. Each <command>cnid_dbd</command> process grabs that
 148           much memory on top of its normal memory footprint. It can be used to
 149           tune database performance. The <emphasis
 150           remap="B">db_stat</emphasis> utility with the <option>-m</option>
 151           option that comes with Berkley DB can help you determine ether you
 152           need to change this value. The default is pretty conservative so
 153           that a large percentage of requests should be satisfied from the
 154           cache directly. If memory is not a bottleneck on your system you
 155           might want to leave it at that value. The <emphasis
 156           remap="B">Berkeley DB Tutorial and Reference Guide</emphasis> has a
 157           section <emphasis remap="B">Selecting a cache size</emphasis> that
 158           gives more detailed information.</para>
 159         </listitem>
 160       </varlistentry>
 161
 162       <varlistentry>
 163         <term><emphasis remap="B">flush_frequency</emphasis></term>
 164
 165         <term><emphasis remap="B">flush_interval</emphasis></term>
 166
 167         <listitem>
 168           <para><emphasis remap="I">flush_frequency</emphasis> (Default: 1000)
 169           and <emphasis remap="I">flush_interval</emphasis> (Default: 1800)
 170           control how often changes to the database are checkpointed. Both of
 171           these operations are performed if either i) more than <emphasis
 172           remap="I">flush_frequency</emphasis> requests have been received or
 173           ii) more than <emphasis remap="I">flush_interval</emphasis> seconds
 174           have elapsed since the last save/checkpoint. Be careful to check
 175           your harddisk configuration for on disk cache settings. Many IDE
 176           disks just cache writes as the default behaviour, so even flushing
 177           database files to disk will not have the desired effect.</para>
 178         </listitem>
 179       </varlistentry>
 180
 181       <varlistentry>
 182         <term><emphasis remap="B">fd_table_size</emphasis></term>
 183
 184         <listitem>
 185           <para>is the maximum number of connections (filedescriptors) that
 186           can be open for <emphasis remap="B">afpd</emphasis> client processes
 187           in <emphasis remap="B">cnid_dbd.</emphasis> Default: 512. If this
 188           number is exceeded, one of the existing connections is closed and
 189           reused. The affected <emphasis remap="B">afpd</emphasis> process
 190           will transparently reconnect later, which causes slight overhead. On
 191           the other hand, setting this parameter too high could affect
 192           performance in <command>cnid_dbd</command> since all descriptors
 193           have to be checked in a <function>select()</function> system call,
 194           or worse, you might exceed the per process limit of open file
 195           descriptors on your system. It is safe to set the value to 1 on
 196           volumes where only one <emphasis remap="B">afpd</emphasis> client
 197           process is expected to run, e.g. home directories.</para>
 198         </listitem>
 199       </varlistentry>
 200
 201       <varlistentry>
 202         <term><emphasis remap="B">idle_timeout</emphasis></term>
 203
 204         <listitem>
 205           <para>is the number of seconds of inactivity before an idle
 206           <command>cnid_dbd</command> exits. Default: 600. Set this to 0 to
 207           disable the timeout.</para>
 208         </listitem>
 209       </varlistentry>
 210     </variablelist>
 211   </refsect1>
 212
 213   <refsect1>
 214     <title>UPDATING</title>
 215
 216     <para>Note that the first version to appear <emphasis>after</emphasis>
 217     Netatalk 2.1 ie Netatalk 2.1.1, will support BerkeleyDB updates on the fly
 218     without manual intervention. In other words Netatalk 2.1 does contain code
 219     to prepare the BerkeleyDB database for upgrades and to upgrade it in case
 220     it has been prepared before. That means it can't upgrade a 2.0.x version
 221     because that one didn't prepare the database.</para>
 222
 223     <para>In order to update between older Netatalk releases using different
 224     BerkeleyDB library versions, follow this steps:</para>
 225
 226     <itemizedlist>
 227       <listitem>
 228         <para>Stop the to be upgraded old version of Netatalk</para>
 229       </listitem>
 230
 231       <listitem>
 232         <para>Using the old BerkeleyDB utilities run <command>db_recover -h
 233         &lt;path to .AppleDB&gt;</command></para>
 234       </listitem>
 235
 236       <listitem>
 237         <para>Using the new BerkeleyDB utilities run <command>db_upgrade -v -h
 238         &lt;path to .AppleDB&gt; -f cnid2.db</command></para>
 239       </listitem>
 240
 241       <listitem>
 242         <para>Again using the new BerkeleyDB utilities run
 243         <command>db_checkpoint -1 -h &lt;path to .AppleDB&gt;</command></para>
 244       </listitem>
 245
 246       <listitem>
 247         <para>Start the the new version of Netatalk</para>
 248       </listitem>
 249     </itemizedlist>
 250
 251   </refsect1>
 252
 253   <refsect1>
 254     <title>SEE ALSO</title>
 255
 256     <para><citerefentry>
 257         <refentrytitle>cnid_metad</refentrytitle>
 258
 259         <manvolnum>8</manvolnum>
 260       </citerefentry>, <citerefentry>
 261         <refentrytitle>afpd</refentrytitle>
 262
 263         <manvolnum>8</manvolnum>
 264       </citerefentry>, <citerefentry>
 265         <refentrytitle>dbd</refentrytitle>
 266
 267         <manvolnum>1</manvolnum>
 268       </citerefentry></para>
 269   </refsect1>
 270 </refentry>