+=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
+
+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
+
+=over 4
+
+=item
+
+Tree nodes are never deleted.
+
+=back
+
projects / rrdtool.git / commitdiff