1cnid_dbd(8)                        Netatalk                        cnid_dbd(8)
2
3
4

NAME

6       cnid_dbd  - implement access to CNID databases through a dedicated dae‐
7       mon process
8

SYNOPSIS

10       cnid_dbd dbdir ctrlfd clntfd
11

DESCRIPTION

13       cnid_dbd provides an interface for storage  and  retrieval  of  catalog
14       node  IDs (CNIDs) and related information to the afpd daemon. CNIDs are
15       a component of Macintosh based file systems with semantics that map not
16       easily  onto  Unix file systems. This makes separate storage in a data‐
17       base necessary.  cnid_dbd is part of the CNID backend framework of afpd
18       and implements the dbd backend.
19
20       cnid_dbd  is  never  started  via  the  command  line or system startup
21       scripts but only by  the  cnid_metad  daemon.  There  is  at  most  one
22       instance of cnid_dbd per netatalk volume.
23
24       cnid_dbd uses the Berkleley DB database library and optionally supports
25       transactionally protected updates if the netatalk package  is  compiled
26       with  the  appropriate  options. Using the dbd backend without transac‐
27       tions will protect the CNID database against unexpected crashes of  the
28       afpd daemon. Using the dbd backend with transactions will avoid corrup‐
29       tion of the CNID database even if the system crashes unexpectedly.
30
31       cnid_dbd uses the same on-disk database format as the cdb  backend.  It
32       is therefore possible to switch between the two backends as necessary.
33
34       cnid_dbd  inherits  the effective userid and groupid from cnid_metad on
35       startup, which is normally caused by afpd serving a netatalk volume  to
36       a  client. It changes to the Berkleley DB database home directory dbdir
37       that is associated with  the  volume.  If  the  userid  inherited  from
38       cnid_metad  is 0 (root), cnid_dbd will change userid and groupid to the
39       owner and group of the database home directory. Otherwise, it will con‐
40       tinue  to  use the inherited values. cnid_dbd will then attempt to open
41       the database and start serving requests  using  filedescriptor  clntfd.
42       Subsequent  instances  of  afpd that want to access the same volume are
43       redirected to the  running  cnid_dbd  process  by  cnid_metad  via  the
44       filedescriptor ctrlfd.
45
46       cnid_dbd  can be configured to run forever or to exit after a period of
47       inactivity. If cnid_dbd receives a TERM or an INT signal it  will  exit
48       cleanly  after  flushing  dirty  database  buffers  to disk and closing
49       Berkleley DB database environments. It is safe  to  terminate  cnid_dbd
50       this  way,  it  will be restarted when necessary. Other signals are not
51       handled and will cause an immediate exit,  possibly  leaving  the  CNID
52       database  in  an  inconsistent state (no transactions) or losing recent
53       updates during recovery (transactions).
54
55       If transactions are used the Berkleley DB database subsystem will  cre‐
56       ate  files  named  log.xxxxxxxxxx in the database home directory dbdir,
57       where xxxxxxxxxx is a monotonically  increasing  integer.  These  files
58       contain  information  to  replay database changes and are not automati‐
59       cally removed, unless the logfile_autoremove option is specified in the
60       db_param  configuration file (see below). Please see the sections Data‐
61       base and log file archival, Log file removal and the  documentation  of
62       the  db_archive  command  line  utility in the Berkeley DB Tutorial and
63       Reference for information when and how it is safe to remove these files
64       manually.
65
66       Do not use cnid_dbd for databases on NFS mounted file systems. It makes
67       the whole point of securing database changes  properly  moot.  Use  the
68       dbdir: Option in the appropriate AppleVolumes configuration file to put
69       the database onto a local disk.
70

CONFIGURATION

72       cnid_dbd reads configuration information from the file db_param in  the
73       database  directory  dbdir  on startup. If the file does not exist or a
74       parameter is not listed, suitable default values are used.  The  format
75       for  a  single parameter is the parameter name, followed by one or more
76       spaces, followed by the parameter value, followed  by  a  newline.  The
77       following parameters are currently recognized:
78
79       logfile_autoremove
80              This  flag  is  ignored unless transactional support is enabled.
81              If  set  to  1,  unused  Berkeley  DB   transactional   logfiles
82              (log.xxxxxxxxxx  in  the database home directory) are removed on
83              startup of cnid_dbd. This is usually safe if the content of  the
84              database directory is backed up on a regular basis.  Default: 0.
85
86       cachesize
87              Determines  the  size  of  the  Berkeley  DB cache in kilobytes.
88              Default: 1024. Each cnid_dbd process grabs that much  memory  on
89              top of its normal memory footprint. It can be used to tune data‐
90              base performance. The db_stat utility with the  -m  option  that
91              comes  with Berkely DB can help you determine wether you need to
92              change this value. The default is pretty conservative so that  a
93              large  percentage of requests should be satisfied from the cache
94              directly. If memory is not a bottleneck on your system you might
95              want  to  leave  it  at that value. The Berkeley DB Tutorial and
96              Reference Guide has a section Selecting a cache size that  gives
97              more detailed information.
98
99       nosync This  flag  is  ignored unless transactional support is enabled.
100              If it is set to 1, transactional changes to the database are not
101              synchronously  written  to  disk when the transaction completes.
102              This will increase  performance  considerably  at  the  risk  of
103              recent  changes  getting  lost  in case of a crash. The database
104              will still be consistent, though. See Transaction Throughput  in
105              the Berkeley DB Tutorial for more information. Default: 0.
106
107       flush_frequency, flush_interval
108              flush_frequency  (Default: 100) and flush_interval (Default: 30)
109              control how often changes to the database  are  written  to  the
110              underlying  database  files  if  no transactions are used or how
111              often the transaction system is checkpointed  for  transactions.
112              Both  of  these  operations are performed if either i) more than
113              flush_frequency requests have been received  or  ii)  more  than
114              flush_interval  seconds  have elapsed since the last save/check‐
115              point. If you use transactions with nosync  set  to  zero  these
116              parameters only influence how long recovery takes after a crash,
117              there should never be any lost data. If  nosync  is  1,  changes
118              might be lost, but only since the last checkpoint. Be careful to
119              check your harddisk configuration for on  disk  cache  settings.
120              Many  IDE  disks  just cache writes as the default behaviour, so
121              even flushing database files to disk will not have  the  desired
122              effect.
123
124       fd_table_size
125              is  the maximum number of connections (filedescriptors) that can
126              be open for afpd client processes in cnid_dbd. Default:  16.  If
127              this  number  is  exceeded,  one  of the existing connections is
128              closed and reused. The affected afpd process will  transparently
129              reconnect  later,  which  causes  slight  overhead. On the other
130              hand, setting this parameter too high could  affect  performance
131              in  cnid_dbd  since  all  descriptors  have  to  be checked in a
132              select() system call, or worse, you might exceed the per process
133              limit of open file descriptors on your system. It is safe to set
134              the value to 1 on volumes where only one afpd client process  is
135              expected to run, e.g. home directories.
136
137       idle_timeout
138              is  the  number of seconds of inactivity before an idle cnid_dbd
139              exits. Default: 600. Set this to 0 to disable the timeout.
140
141       check  is a flag value. If set cnid_dbd will  automatically  check  the
142              database indexes. Default: 0. Set this to 1 to enable checking.
143

SEE ALSO

145       cnid_metad(8), afpd(8)
146
147
148
149
1502.0.3                             2 Dec 2003                       cnid_dbd(8)
Impressum