X-Git-Url: https://arthur.barton.de/cgi-bin/gitweb.cgi?p=netatalk.git;a=blobdiff_plain;f=man%2Fman8%2Fcnid_dbd.8.tmpl;h=c500ad2d3f7b1e96d68103494972d163a83792c3;hp=c751f270bd7745917c8e9a28e3511be7d0f20463;hb=e52ff73c65c963788839402baf925686ca0211d6;hpb=dce435c07bac5b4b368c2445f57e1f9a1f8b70b3 diff --git a/man/man8/cnid_dbd.8.tmpl b/man/man8/cnid_dbd.8.tmpl index c751f270..c500ad2d 100644 --- a/man/man8/cnid_dbd.8.tmpl +++ b/man/man8/cnid_dbd.8.tmpl @@ -1,158 +1,203 @@ -.TH cnid_dbd 8 "2 Dec 2003" 2.0.3 Netatalk -.SH NAME +'\" t +.\" Title: cnid_dbd +.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] +.\" Generator: DocBook XSL Stylesheets v1.74.3 +.\" Date: 2 Dec 2003 +.\" Manual: Netatalk 2.0.4 +.\" Source: Netatalk 2.0.4 +.\" Language: English +.\" +.TH "CNID_DBD" "8" "2 Dec 2003" "Netatalk 2\&.0\&.4" "Netatalk 2.0.4" +.\" ----------------------------------------------------------------- +.\" * set default formatting +.\" ----------------------------------------------------------------- +.\" disable hyphenation +.nh +.\" disable justification (adjust text to left margin only) +.ad l +.\" ----------------------------------------------------------------- +.\" * MAIN CONTENT STARTS HERE * +.\" ----------------------------------------------------------------- +.SH "NAME" cnid_dbd \- implement access to CNID databases through a dedicated daemon process -.SH SYNOPSIS -\fBcnid_dbd\fR \fBdbdir\fR \fBctrlfd\fR \fBclntfd\fR -.SH DESCRIPTION -cnid_dbd provides an interface for storage and -retrieval of catalog node IDs (CNIDs) and related information to the -\fIafpd\fR 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 \fICNID -backend\fR framework of \fIafpd\fR and -implements the \fIdbd\fR backend. -.PP -cnid_dbd is never started via the command line or -system startup scripts but only by the \fIcnid_metad\fR daemon. There is at most one instance of -cnid_dbd per netatalk volume. -.PP -cnid_dbd uses the \fIBerkleley -DB\fR database library and optionally supports transactionally -protected updates if the netatalk package is compiled with the appropriate -options. Using the \fIdbd\fR backend without -transactions will protect the CNID database against unexpected crashes of -the \fIafpd\fR daemon. Using the \fIdbd\fR backend with transactions will avoid corruption -of the CNID database even if the system crashes unexpectedly. -.PP -cnid_dbd uses the same on\-disk database format as -the \fIcdb\fR backend. It is therefore possible -to switch between the two backends as necessary. -.PP -cnid_dbd inherits the effective userid and -groupid from \fIcnid_metad\fR on startup, which -is normally caused by \fIafpd\fR serving a -netatalk volume to a client. It changes to the \fIBerkleley DB\fR database home directory \fIdbdir\fR that is associated with the volume. If the -userid inherited from \fIcnid_metad\fR 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 \fIclntfd\fR. Subsequent instances -of \fIafpd\fR that want to access the same volume -are redirected to the running cnid_dbd process by -\fIcnid_metad\fR via the filedescriptor \fIctrlfd\fR. -.PP -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 \fIBerkleley DB\fR -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). -.PP -If transactions are used the \fIBerkleley -DB\fR database subsystem will create files named log.xxxxxxxxxx in -the database home directory \fIdbdir\fR, where -xxxxxxxxxx is a monotonically increasing integer. These files contain -information to replay database changes and are not automatically removed, -unless the \fIlogfile_autoremove\fR option is -specified in the \fIdb_param\fR configuration -file (see below). Please see the sections \fIDatabase and -log file archival\fR, \fILog file -removal\fR and the documentation of the \fI -db_archive\fR command line utility in the Berkeley DB Tutorial and -Reference for information when and how it is safe to remove these files -manually. -.PP -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 -\fIAppleVolumes\fR configuration file to put the -database onto a local disk. -.SH CONFIGURATION -cnid_dbd reads configuration information from the -file \fIdb_param\fR in the database directory -\fIdbdir\fR 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: -.TP -\fIlogfile_autoremove\fR -This flag is ignored unless transactional support is enabled. -If set to 1, unused Berkeley DB transactional logfiles -(log.xxxxxxxxxx in the database home directory) are removed on -startup of cnid_dbd. This is usually safe if the -content of the database directory is backed up on a regular basis. -Default: 0. -.TP -\fIcachesize\fR -Determines the size of the Berkeley DB cache in kilobytes. -Default: 1024. Each cnid_dbd process grabs that -much memory on top of its normal memory footprint. It can be used to -tune database performance. The \fIdb_stat\fR utility with the \fB\-m\fR -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 \fIBerkeley DB Tutorial and Reference Guide\fR has a -section \fISelecting a cache size\fR that -gives more detailed information. -.TP +.SH "SYNOPSIS" +.HP \w'\fBcnid_dbd\fR\fB\fR\fB\fR\fB\fR\ 'u +\fBcnid_dbd\fR\fB\fR\fB\fR\fB\fR \fIdbdir\fR \fIctrlfd\fR \fIclntfd\fR +.SH "DESCRIPTION" +.PP +\fBcnid_dbd\fR +provides an interface for storage and retrieval of catalog node IDs (CNIDs) and related information to the +\fBafpd\fR +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\&. +\fBcnid_dbd\fR +is part of the +\fBCNID backend\fR +framework of +\fBafpd\fR +and implements the +\fBdbd\fR +backend\&. +.PP +\fBcnid_dbd\fR +is never started via the command line or system startup scripts but only by the +\fBcnid_metad\fR +daemon\&. There is at most one instance of +\fBcnid_dbd\fR +per netatalk volume\&. +.PP +\fBcnid_dbd\fR +uses the +\fBBerkleley DB\fR +database library and optionally supports transactionally protected updates if the netatalk package is compiled with the appropriate options\&. Using the +\fBdbd\fR +backend without transactions will protect the CNID database against unexpected crashes of the +\fBafpd\fR +daemon\&. Using the +\fBdbd\fR +backend with transactions will avoid corruption of the CNID database even if the system crashes unexpectedly\&. +.PP +\fBcnid_dbd\fR +uses the same on\-disk database format as the +\fBcdb\fR +backend\&. It is therefore possible to switch between the two backends as necessary\&. +.PP +\fBcnid_dbd\fR +inherits the effective userid and groupid from +\fBcnid_metad\fR +on startup, which is normally caused by +\fBafpd\fR +serving a netatalk volume to a client\&. It changes to the +\fBBerkleley DB\fR +database home directory +\fIdbdir\fR +that is associated with the volume\&. If the userid inherited from +\fBcnid_metad\fR +is 0 (root), +\fBcnid_dbd\fR +will change userid and groupid to the owner and group of the database home directory\&. Otherwise, it will continue to use the inherited values\&. +\fBcnid_dbd\fR +will then attempt to open the database and start serving requests using filedescriptor +\fIclntfd\fR\&. Subsequent instances of +\fBafpd\fR +that want to access the same volume are redirected to the running +\fBcnid_dbd\fR +process by +\fBcnid_metad\fR +via the filedescriptor +\fIctrlfd\fR\&. +.PP +\fBcnid_dbd\fR +can be configured to run forever or to exit after a period of inactivity\&. If +\fBcnid_dbd\fR +receives a TERM or an INT signal it will exit cleanly after flushing dirty database buffers to disk and closing +\fBBerkleley DB\fR +database environments\&. It is safe to terminate +\fBcnid_dbd\fR +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)\&. +.PP +If transactions are used the +\fBBerkleley DB\fR +database subsystem will create files named log\&.xxxxxxxxxx in the database home directory +\fIdbdir\fR, where xxxxxxxxxx is a monotonically increasing integer\&. These files contain information to replay database changes and are not automatically removed, unless the +\fBlogfile_autoremove\fR +option is specified in the +\fIdb_param\fR +configuration file (see below)\&. Please see the sections +\fBDatabase and log file archival\fR, +\fB Log file removal\fR +and the documentation of the +\fB db_archive\fR +command line utility in the Berkeley DB Tutorial and Reference for information when and how it is safe to remove these files manually\&. +.PP +Do not use +\fBcnid_dbd\fR +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 +\fBAppleVolumes\fR +configuration file to put the database onto a local disk\&. +.SH "CONFIGURATION" +.PP +\fBcnid_dbd\fR +reads configuration information from the file +\fIdb_param\fR +in the database directory +\fIdbdir\fR +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: +.PP +\fBlogfile_autoremove\fR +.RS 4 +This flag is ignored unless transactional support is enabled\&. If set to 1, unused Berkeley DB transactional logfiles (log\&.xxxxxxxxxx in the database home directory) are removed on startup of +\fBcnid_dbd\fR\&. This is usually safe if the content of the database directory is backed up on a regular basis\&. Default: 0\&. +.RE +.PP +\fBcachesize\fR +.RS 4 +Determines the size of the Berkeley DB cache in kilobytes\&. Default: 1024\&. Each +\fBcnid_dbd\fR +process grabs that much memory on top of its normal memory footprint\&. It can be used to tune database performance\&. The +\fBdb_stat\fR +utility with the +\fB\-m\fR +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 +\fBBerkeley DB Tutorial and Reference Guide\fR +has a section +\fBSelecting a cache size\fR +that gives more detailed information\&. +.RE +.PP +\fBnosync\fR +.RS 4 +This flag is ignored unless transactional support is enabled\&. If it is set to 1, transactional changes to the database are not synchronously written to disk when the transaction completes\&. This will increase performance considerably at the risk of recent changes getting lost in case of a crash\&. The database will still be consistent, though\&. See +\fBTransaction Throughput\fR +in the Berkeley DB Tutorial for more information\&. Default: 0\&. +.RE +.PP +\fBflush_frequency\fR, \fBflush_interval\fR +.RS 4 +\fIflush_frequency\fR +(Default: 100) and +\fIflush_interval\fR +(Default: 30) control how often changes to the database are written to the underlying database files if no transactions are used or how often the transaction system is checkpointed for transactions\&. Both of these operations are performed if either i) more than +\fIflush_frequency\fR +requests have been received or ii) more than +\fIflush_interval\fR +seconds have elapsed since the last save/checkpoint\&. If you use transactions with +\fInosync\fR +set to zero these parameters only influence how long recovery takes after a crash, there should never be any lost data\&. If \fInosync\fR -This flag is ignored unless transactional support is enabled. -If it is set to 1, transactional changes to the database are not -synchronously written to disk when the transaction completes. This -will increase performance considerably at the risk of recent changes -getting lost in case of a crash. The database will still be -consistent, though. See \fITransaction -Throughput\fR in the Berkeley DB Tutorial for more -information. Default: 0. -.TP -\fIflush_frequency\fR, \fIflush_interval\fR -\fIflush_frequency\fR (Default: 100) -and \fIflush_interval\fR (Default: 30) -control how often changes to the database are written to the -underlying database files if no transactions are used or how often -the transaction system is checkpointed for transactions. Both of -these operations are performed if either i) more than \fIflush_frequency\fR requests have been received or -ii) more than \fIflush_interval\fR seconds -have elapsed since the last save/checkpoint. If you use transactions -with \fInosync\fR set to zero these -parameters only influence how long recovery takes after a crash, -there should never be any lost data. If \fInosync\fR is 1, changes might be lost, but only -since the last 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. -.TP -\fIfd_table_size\fR -is the maximum number of connections (filedescriptors) that -can be open for \fIafpd\fR client processes -in \fIcnid_dbd.\fR Default: 16. If this -number is exceeded, one of the existing connections is closed and -reused. The affected \fIafpd\fR 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 \fIafpd\fR client -process is expected to run, e.g. home directories. -.TP -\fIidle_timeout\fR +is 1, changes might be lost, but only since the last 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\&. +.RE +.PP +\fBfd_table_size\fR +.RS 4 +is the maximum number of connections (filedescriptors) that can be open for +\fBafpd\fR +client processes in +\fBcnid_dbd\&.\fR +Default: 16\&. If this number is exceeded, one of the existing connections is closed and reused\&. The affected +\fBafpd\fR +process will transparently reconnect later, which causes slight overhead\&. On the other hand, setting this parameter too high could affect performance in +\fBcnid_dbd\fR +since all descriptors have to be checked in a +\fBselect()\fR +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 +\fBafpd\fR +client process is expected to run, e\&.g\&. home directories\&. +.RE +.PP +\fBidle_timeout\fR +.RS 4 is the number of seconds of inactivity before an idle -cnid_dbd exits. Default: 600. Set this to 0 to -disable the timeout. -.TP -\fIcheck\fR -is a flag value. If set cnid_dbd will -automatically check the database indexes. Default: 0. Set this -to 1 to enable checking. +\fBcnid_dbd\fR +exits\&. Default: 600\&. Set this to 0 to disable the timeout\&. +.RE +.PP +\fBcheck\fR +.RS 4 +is a flag value\&. If set +\fBcnid_dbd\fR +will automatically check the database indexes\&. Default: 0\&. Set this to 1 to enable checking\&. +.RE .SH "SEE ALSO" -\fBcnid_metad\fR(8), \fBafpd\fR(8) - +.PP +\fBcnid_metad\fR(8), +\fBafpd\fR(8)