From: Florian Forster Date: Tue, 1 Jul 2008 08:02:42 +0000 (+0200) Subject: rrdcached(1): Added the `SECURITY CONSIDERATIONS' and `HOW IT WORKS' sections. X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=commitdiff_plain;h=3f16f00aae46836b4dbff29b3fa770718e992382 rrdcached(1): Added the `SECURITY CONSIDERATIONS' and `HOW IT WORKS' sections. --- diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod index 1429081..ab13ea7 100644 --- a/doc/rrdcached.pod +++ b/doc/rrdcached.pod @@ -16,6 +16,13 @@ passed, writes the updates to the RRD file. A I command may be used to 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 +IOErelated 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 below before using this daemon! A detailed +description of how the daemon operates can be found in the L +section below. + =head1 OPTIONS =over 4 @@ -67,6 +74,134 @@ used. =back +=head1 HOW IT WORKS + +When receiving an update, B 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 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= timeout>>, where C is the timeout specified +using the B<-w> option, see L. If the values are "old enough" they +will be enqueued in the "update queue", i.Ee. 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.Ee. 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 +3600Eseconds (one hour). + +The downside of caching values is that they won't show up in graphs generated +from the RRDEfiles. To get around this, the daemon provides the "flush +command" to flush specific files. This means that the file is inserted at the +B 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 IOEperformance for setups with thousands +of RRDEfile to be updated. So security measures built into the daemon can +be summarized easily: B + +There is no authentication and authorization, so B 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.Ee. 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.Ee. let the daemon bind to +an IPv4 or IPv6 socket, it is B 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 + =head1 SEE ALSO L, L