CNID_DBD

NAME

SYNOPSIS

cnid_dbddbdirctrlfdclntfdlogconfig_string

DESCRIPTION

cnid_dbd

provides an interface for storage and retrieval of catalog node IDs (CNIDs) and related information to the
afpd
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.
cnid_dbd
is part of the
CNID backend
framework of
afpd
and implements the
dbd
backend.

cnid_dbd
is never started via the command line or system startup scripts but only by the
cnid_metad
daemon. There is at most one instance of
cnid_dbd
per netatalk volume.

cnid_dbd
uses the
Berkleley DB
database library and uses transactionally protected updates. The
dbd
backend with transactions will avoid corruption of the CNID database even if the system crashes unexpectedly.

cnid_dbd
uses the same on-disk database format as the
cdb
backend. It is therefore possible to switch between the two backends as necessary.

cnid_dbd
inherits the effective userid and groupid from
cnid_metad
on startup, which is normally caused by
afpd
serving a netatalk volume to a client. It changes to the
Berkleley DB
database home directory
dbdir
that is associated with the volume. If the userid inherited from
cnid_metad
is 0 (root),
cnid_dbd
will change userid and groupid to the owner and group of the database home directory. Otherwise, it will continue to use the inherited values.
cnid_dbd
will then attempt to open the database and start serving requests using filedescriptor
clntfd. Subsequent instances of
afpd
that want to access the same volume are redirected to the running
cnid_dbd
process by
cnid_metad
via the filedescriptor
ctrlfd.

cnid_dbd
uses
logconfig_string
which is passed from
cnid_metad
to configure its logging output.

cnid_dbd
can be configured to run forever or to exit after a period of inactivity. If
cnid_dbd
receives a TERM or an INT signal it will exit cleanly after flushing dirty database buffers to disk and closing
Berkleley DB
database environments. It is safe to terminate
cnid_dbd
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).

The
Berkleley DB
database subsystem will create files named log.xxxxxxxxxx in the database home directory
dbdir, where xxxxxxxxxx is a monotonically increasing integer. These files contain ithe transactional database changes. They will be removed regularily, unless the
logfile_autoremove
option is specified in the
db_param
configuration file (see below).

Do not use
cnid_dbd
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
AppleVolumes
configuration file to put the database onto a local disk.

CONFIGURATION

cnid_dbd
reads configuration information from the file
db_param
in the database directory
dbdir
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:

logfile_autoremove

If set to 0, unused Berkeley DB transactional logfiles (log.xxxxxxxxxx in the database home directory) are not removed on startup of
cnid_dbd
and on a reqular basis. Default: 1.

cachesize

Determines the size of the Berkeley DB cache in kilobytes. Default: 8192. Each
cnid_dbd
process grabs that much memory on top of its normal memory footprint. It can be used to tune database performance. The
db_stat
utility with the
-m
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
Berkeley DB Tutorial and Reference Guide
has a section
Selecting a cache size
that gives more detailed information.

flush_frequency, flush_interval

flush_frequency
(Default: 1000) and
flush_interval
(Default: 1800) control how often changes to the database are checkpointed. Both of these operations are performed if either i) more than
flush_frequency
requests have been received or ii) more than
flush_interval
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.

fd_table_size

is the maximum number of connections (filedescriptors) that can be open for
afpd
client processes in
cnid_dbd.
Default: 512. If this number is exceeded, one of the existing connections is closed and reused. The affected
afpd
process will transparently reconnect later, which causes slight overhead. On the other hand, setting this parameter too high could affect performance in
cnid_dbd
since all descriptors have to be checked in a
select()
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
afpd
client process is expected to run, e.g. home directories.

idle_timeout

is the number of seconds of inactivity before an idle
cnid_dbd
exits. Default: 600. Set this to 0 to disable the timeout.

UPDATING

In order to update between Netatalk releases using different BerkeleyDB library versions, follow this steps:

•
Stop the to be upgraded old version of Netatalk

•
Using the old BerkeleyDB utilities run
db_recover -h <path to .AppleDB>

•
Using the new BerkeleyDB utilities run
db_upgrade -v -h <path to .AppleDB> -f cnid2.db

•
Again using the new BerkeleyDB utilities run
db_checkpoint -1 -h <path to .AppleDB>

•
Start the the new version of Netatalk

Note that the first version to appear
after
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.