=head1 SYNOPSIS
-B<rrdcached> [B<-l> I<address>] [B<-w> I<timeout>] [B<-f> I<timeout>]
+B<rrdcached> [B<-l> I<address>] [B<-w> I<timeout>] [B<-z> I<delay>] [B<-f> I<timeout>] [B<-j> I<dir>] [-F]
=head1 DESCRIPTION
interpreted as the path to a UNIX domain socket. Otherwise the address or node
name are resolved using L<getaddrinfo>.
+For network sockets, a port may be specified by using the form
+C<B<[>I<address>B<]:>I<port>>. If the address is an IPv4 address or a fully
+qualified domain name (i.E<nbsp>e. the address contains at least one dot
+(C<.>)), the square brackets can be omitted, resulting in the (simpler)
+C<I<address>B<:>I<port>> pattern.. The default port is B<42217/udp>.
+
+The following formats are accepted. Please note that the address of the UNIX
+domain socket B<must> start with a slash in the second case!
+
+ unix:</path/to/unix.sock>
+ /<path/to/unix.sock>
+ <hostname-or-ip>
+ [<hostname-or-ip>]:<port>
+ <hostname-or-ipv4>:<port>
+
If the B<-l> option is not specified the default address,
C<unix:/tmp/rrdcached.sock>, will be used.
Data is written to disk every I<timeout> seconds. If this option is not
specified the default interval of 300E<nbsp>seconds will be used.
+=item B<-z> I<delay>
+
+If specified, rrdcached will delay writing of each RRD for a random number
+of seconds in the rangeE<nbsp>[0,I<delay>). This will avoid too many
+writes being queued simultaneously. This value should be no greater than
+the value specified in B<-w>. By default, there is no delay.
+
=item B<-f> I<timeout>
Every I<timeout> seconds the entire cache is searched for old values which are
Sets the name and location of the PID-file. If not specified, the default,
C<I<$localststedir>/run/rrdcached.pid> will be used.
+=item B<-j> I<dir>
+
+Write updates to a journal in I<dir>. In the event of a program or system
+crash, this will allow the daemon to write any updates that were pending
+at the time of the crash.
+
+On startup, the daemon will check for journal files in this directory. If
+found, all updates therein will be read into memory before the daemon
+starts accepting new connections.
+
+The journal will be rotated with the same frequency as the flush timer
+given by B<-f>.
+
+When journaling is enabled, the daemon will use a fast shutdown procedure.
+Rather than flushing all files to disk, it will make sure the journal is
+properly written and exit immediately. Although the RRD data files are
+not fully up-to-date, no information is lost; all pending updates will be
+replayed from the journal next time the daemon starts up.
+
+To disable fast shutdown, use the B<-F> option.
+
+=item B<-F>
+
+ALWAYS flush all updates to the RRD data files when the daemon is shut
+down, regardless of journal setting.
+
=item B<-b> I<dir>
The daemon will change into a specific directory at startup. All files passed
the daemon before accessing the files, so they work with up-to-date data even
if the cache timeout is large.
+=head1 ERROR REPORTING
+
+The daemon reports errors in one of two ways: During startup, error messages
+are printed to C<STDERR>. One of the steps when starting up is to fork to the
+background and closing C<STDERR> - after this writing directly to the user is
+no longer possible. Once this has happened, the daemon will send log messages
+to the system logging daemon using L<syslog(3)>. The facility used it
+C<LOG_DAEMON>.
+
=head1 HOW IT WORKS
When receiving an update, B<rrdcached> does not write to disk but looks for an
from the RRDE<nbsp>files. To get around this, the daemon provides the "flush
command" to flush specific files. This means that the file is inserted at the
B<head> of the update queue or moved there if it is already enqueued. The flush
-command will return after the update thread has dequeued the file, so there is
-a good chance that the file has been updated by the time the client receives
-the response from the daemon, but there is no guarantee.
+command will return only after the file's pending updates have been written
+to disk.
+------+ +------+ +------+
! head ! ! root ! ! tail !
(possibly moving it there if the node is already enqueued). The answer will be
sent B<after> the node has been dequeued.
+=item B<FLUSHALL>
+
+Causes the daemon to start flushing ALL pending values to disk. This
+returns immediately, even though the writes may take a long time.
+
=item B<HELP> [I<command>]
Returns a short usage message. If no command is given, or I<command> is
Example:
- 5 Statistics follow
+ 9 Statistics follow
QueueLength: 0
+ UpdatesReceived: 30
+ FlushesReceived: 2
UpdatesWritten: 13
DataSetsWritten: 390
TreeNodesNumber: 13
TreeDepth: 4
+ JournalBytes: 190
+ JournalRotate: 0
=item B<UPDATE> I<filename> I<values> [I<values> ...]
for, so describing the mechanism again is unnecessary. Read L<HOW IT WORKS>
above for a detailed explanation.
+=item B<WROTE> I<filename>
+
+This command is written to the journal after a file is successfully
+written out to disk. It is used during journal replay to determine which
+updates have already been applied. It is I<only> valid in the journal; it
+is not accepted from the other command channels.
+
=back
=head2 Performance Values
Number of nodes currently enqueued in the update queue.
-=item B<TreeDepth> I<(unsigned 64bit integer)>
+=item B<UpdatesReceived> I<(unsigned 64bit integer)>
-Depth of the tree used for fast key lookup.
+Number of UPDATE commands received.
-=item B<TreeNodesNumber> I<(unsigned 64bit integer)>
+=item B<FlushesReceived> I<(unsigned 64bit integer)>
-Number of nodes in the cache.
+Number of FLUSH commands received.
=item B<UpdatesWritten> I<(unsigned 64bit integer)>
-Total number of updates, i.E<nbsp>e. calls to C<rrd_update_r>, since the daemon
-was started.
+Total number of updates, i.E<nbsp>e. calls to C<rrd_update_r>, since the
+daemon was started.
=item B<DataSetsWritten> I<(unsigned 64bit integer)>
C<N:123:456> is one data set with two values. The term "data set" is used to
prevent confusion whether individual values or groups of values are counted.
+=item B<TreeNodesNumber> I<(unsigned 64bit integer)>
+
+Number of nodes in the cache.
+
+=item B<TreeDepth> I<(unsigned 64bit integer)>
+
+Depth of the tree used for fast key lookup.
+
+=item B<JournalBytes> I<(unsigned 64bit integer)>
+
+Total number of bytes written to the journal since startup.
+
+=item B<JournalRotate> I<(unsigned 64bit integer)>
+
+Number of times the journal has been rotated since startup.
+
+=back
+
+=head1 SIGNALS
+
+=over 4
+
+=item SIGINT and SIGTERM
+
+The daemon exits normally on receipt of either of these signals. Pending
+updates are handled in accordance with the B<-j> and B<-F> options.
+
+=item SIGUSR1
+
+The daemon exits AFTER flushing all updates out to disk. This may take a
+while.
+
+=item SIGUSR2
+
+The daemon exits immediately, without flushing updates out to disk.
+Pending updates will be replayed from the journal when the daemon starts
+up again. B<WARNING: if journaling (-j) is NOT enabled, any pending
+updates WILL BE LOST>.
+
+=back
+
+=head1 SIGNALS
+
+=over 4
+
+=item SIGINT and SIGTERM
+
+The daemon exits normally on receipt of either of these signals.
+
=back
=head1 BUGS
L<rrdtool>, L<rrdgraph>
-=head1 AUHOR
+=head1 AUTHOR
B<rrdcached> and this manual page have been written by Florian Forster
E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>.
+
+=head1 CONTRIBUTORS
+
+kevin brintnall E<lt>kbrint@rufus.netE<gt>
+
+=cut
+