force writing of values to disk, so that graphing facilities and similar can
work with up-to-date data.
+The daemon was written with big setups in mind. Those setups usually run into
+IOE<nbsp>related problems sooner or later for reasons that are beyond the scope
+of this document. Check the wiki at the RRDTool homepage for details. Also
+check L<SECURITY CONSIDERATIONS> below before using this daemon! A detailed
+description of how the daemon operates can be found in the L<HOW IT WORKS>
+section below.
+
=head1 OPTIONS
=over 4
=item B<-l> I<address>
Tells the daemon to bind to I<address> and accept incoming connections on that
-socket. If I<address> begins with C<unix:>, everthing following that prefix is
+socket. If I<address> begins with C<unix:>, everything following that prefix is
interpreted as the path to a UNIX domain socket. Otherwise the address or node
name are resolved using L<getaddrinfo(3)>.
+If the B<-l> option is not specified the default address,
+C<unix:/tmp/rrdcached.sock>, will be used.
+
=item B<-w> I<timeout>
-Data is written to disk every I<timeout> seconds.
+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<-f> I<timeout>
Every I<timeout> seconds the entire cache is searched for old values which are
written to disk. This only concerns files to which updates have stopped, so
-setting this to a high value, such as 3600 seconds, is acceptable in most
-cases.
+setting this to a high value, such as 3600E<nbsp>seconds, is acceptable in most
+cases. This timeout defaults to 3600E<nbsp>seconds.
+
+=item B<-p> I<file>
+
+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<-b> I<dir>
+
+The daemon will change into a specific directory at startup. All files passed
+to the daemon, that are specified by a B<relative> path, will be interpreted
+to be relative to this directory. If not given the default, C</tmp>, will be
+used.
+
+ +------------------------+------------------------+
+ ! Command line ! File updated !
+ +------------------------+------------------------+
+ ! foo.rrd ! /tmp/foo.rrd !
+ ! foo/bar.rrd ! /tmp/foo/bar.rrd !
+ ! /var/lib/rrd/foo.rrd ! /var/lib/rrd/foo.rrd !
+ +------------------------+------------------------+
+ Paths given on the command line and paths actually
+ updated by the daemon, assuming the base directory
+ "/tmp".
=back
-=head1 BUGS
+=head1 HOW IT WORKS
+
+When receiving an update, B<rrdcached> does not write to disk but looks for an
+entry for that file in its internal tree. If not found, an entry is created
+including the current time (called "First" in the diagram below). This time is
+B<not> the time specified on the command line but the time the operating system
+considers to be "now". The value and time of the value (called "Time" in the
+diagram below) are appended to the tree node.
+
+When appending a value to a tree node, it is checked whether it's time to write
+the values to disk. Values are written to disk if
+S<C<now() - First E<gt>= timeout>>, where C<timeout> is the timeout specified
+using the B<-w> option, see L<OPTIONS>. If the values are "old enough" they
+will be enqueued in the "update queue", i.E<nbsp>e. they will be appended to
+the linked list shown below. Because the tree nodes and the elements of the
+linked list are the same data structures in memory, any update to a file that
+has already been enqueued will be written with the next write to the RRD file,
+too.
+
+A separate "update thread" constantly dequeues the first element in the update
+queue and writes all its values to the appropriate file. So as long as the
+update queue is not empty files are written at the highest possible rate.
+
+Since the timeout of files is checked only when new values are added to the
+file, "dead" files, i.E<nbsp>e. files that are not updated anymore, would never
+be written to disk. Therefore, every now and then, controlled by the B<-f>
+option, the entire tree is walked and all "old" values are enqueued. Since this
+only affects "dead" files and walking the tree is relatively expensive, you
+should set the "flush interval" to a reasonably high value. The default is
+3600E<nbsp>seconds (one hour).
+
+The downside of caching values is that they won't show up in graphs generated
+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.
+
+ +------+ +------+ +------+
+ ! head ! ! root ! ! tail !
+ +---+--+ +---+--+ +---+--+
+ ! /\ !
+ ! / \ !
+ ! /\ /\ !
+ ! /\/\ \ `----------------- ... --------, !
+ V / `-------, ! V
+ +---+----+---+ +------+-----+ +---+----+---+
+ ! File: foo ! ! File: bar ! ! File: qux !
+ ! First: 101 ! ! First: 119 ! ! First: 180 !
+ ! Next: ---+--->! Next: ---+---> ... --->! Next: - !
+ +============+ +============+ +============+
+ ! Time: 100 ! ! Time: 120 ! ! Time: 180 !
+ ! Value: 10 ! ! Value: 0.1 ! ! Value: 2,2 !
+ +------------+ +------------+ +------------+
+ ! Time: 110 ! ! Time: 130 ! ! Time: 190 !
+ ! Value: 26 ! ! Value: 0.1 ! ! Value: 7,3 !
+ +------------+ +------------+ +------------+
+ : : : : : :
+ +------------+ +------------+ +------------+
+ ! Time: 230 ! ! Time: 250 ! ! Time: 310 !
+ ! Value: 42 ! ! Value: 0.2 ! ! Value: 1,2 !
+ +------------+ +------------+ +------------+
+
+The above diagram demonstrates:
=over 4
=item
-Base directory is currently hard coded. The daemon will chdir to C</tmp/>.
+Files/values are stored in a (balanced) tree.
+
+=item
+
+Tree nodes and entries in the update queue are the same data structure.
+
+=item
+
+The local time ("First") and the time specified in updates ("Time") may differ.
+
+=item
+
+Timed out values are inserted at the "tail".
+
+=item
+
+Explicitely flushed values are inserted at the "head".
+
+=item
+
+ASCII art rocks.
=back
+=head1 SECURITY CONSIDERATIONS
+
+This daemon is meant to improve IOE<nbsp>performance for setups with thousands
+of RRDE<nbsp>file to be updated. So security measures built into the daemon can
+be summarized easily: B<There is no security built in!>
+
+There is no authentication and authorization, so B<you> will have to take care
+that only authorized clients can talk to the daemon. Since we assume that graph
+collection is done on a dedicated machine, i.E<nbsp>e. the box doesn't do
+anything else and especially does not have any interactive logins other than
+root, a UNIX domain socket should take care of that.
+
+If you (want to) use the network capability, i.E<nbsp>e. let the daemon bind to
+an IPv4 or IPv6 socket, it is B<your> job to install a packet filter or similar
+mechanism to prevent unauthorized connections. Unless you have a dedicated VLAN
+or VPN for this, using the network option is probably a bad idea!
+
+The daemon will blindly write to any file it gets told, so you really should
+create a separate user just for this daemon. Also it does not do any sanity
+checks, so if it gets told to write values for a time far in the future, your
+files will be messed up good!
+
+You have been warned.
+
+=head1 BUGS
+
+No known bugs at the moment.
+
=head1 SEE ALSO
L<rrdtool(1)>, L<rrdgraph(1)>