1 RRDCACHED(1) rrdtool RRDCACHED(1)
6 rrdcached - Data caching daemon for rrdtool
9 r\brr\brd\bdc\bca\bac\bch\bhe\bed\bd [-\b-P\bP _\bp_\be_\br_\bm_\bi_\bs_\bs_\bi_\bo_\bn_\bs] [-\b-l\bl _\ba_\bd_\bd_\br_\be_\bs_\bs] [-\b-w\bw _\bt_\bi_\bm_\be_\bo_\bu_\bt] [-\b-z\bz _\bd_\be_\bl_\ba_\by]
10 [-\b-f\bf _\bt_\bi_\bm_\be_\bo_\bu_\bt] [-\b-p\bp _\bp_\bi_\bd_\b__\bf_\bi_\bl_\be] [-\b-t\bt _\bw_\br_\bi_\bt_\be_\b__\bt_\bh_\br_\be_\ba_\bd_\bs] [-\b-j\bj _\bj_\bo_\bu_\br_\bn_\ba_\bl_\b__\bd_\bi_\br] [-F]
15 accumulates them and, if enough have been received or a defined time
17 used to force writing of values to disk, so that graphing facilities
18 and similar can work with up-to-date data.
20 The daemon was written with big setups in mind. Those setups usually
21 run into IO related problems sooner or later for reasons that are
22 beyond the scope of this document. Check the wiki at the RRDtool
23 homepage for details. Also check "SECURITY CONSIDERATIONS" below before
24 using this daemon! A detailed description of how the daemon operates
25 can be found in the "HOW IT WORKS" section below.
31 following that prefix is interpreted as the path to a UNIX domain
32 socket. Otherwise the address or node name are resolved using
33 getaddrinfo.
35 For network sockets, a port may be specified by using the form
36 "[\b[_\ba_\bd_\bd_\br_\be_\bs_\bs]\b]:\b:_\bp_\bo_\br_\bt_\b". If the address is an IPv4 address or a fully
37 qualified domain name (i. e. the address contains at least one dot
38 (".")), the square brackets can be omitted, resulting in the
39 (simpler) "_\ba_\bd_\bd_\br_\be_\bs_\bs:\b:_\bp_\bo_\br_\bt_\b" pattern. The default port is 4\b42\b22\b21\b17\b7/\b/u\bud\bdp\bp. If
40 you specify a network socket, it is mandatory to read the "SECURITY
41 CONSIDERATIONS" section.
43 The following formats are accepted. Please note that the address of
46 unix:</path/to/unix.sock>
47 /<path/to/unix.sock>
48 <hostname-or-ip>
49 [<hostname-or-ip>]:<port>
50 <hostname-or-ipv4>:<port>
53 "unix:/tmp/rrdcached.sock", will be used.
56 Specifies the commands accepted via a network socket. This allows
58 various sources.
61 commands. For example, to allow the "FLUSH" and "PENDING" commands
62 one could specify:
64 rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS
66 The -\b-P\bP option effects the _\bf_\bo_\bl_\bl_\bo_\bw_\bi_\bn_\bg socket addresses (the following
68 (address 10.0.0.1) will be restricted to the "FLUSH" and "PENDING"
69 commands:
71 rrdcached -l unix:/some/path -P FLUSH,PENDING -l 10.0.0.1
73 A complete list of available commands can be found in the section
74 "Valid Commands" below. There are two minor special exceptions:
76 · The "HELP" and "QUIT" commands are always allowed.
78 · If the "BATCH" command is accepted, the .\b. command will
79 automatically be accepted, too.
81 Please also read "SECURITY CONSIDERATIONS" below.
85 not specified the default interval of 300 seconds will be used.
88 If specified, rrdcached will delay writing of each RRD for a random
90 writes being queued simultaneously. This value should be no
92 delay.
96 which are written to disk. This only concerns files to which
97 updates have stopped, so setting this to a high value, such as
98 3600 seconds, is acceptable in most cases. This timeout defaults to
99 3600 seconds.
102 Sets the name and location of the PID-file. If not specified, the
103 default, "_\b$_\bl_\bo_\bc_\ba_\bl_\bs_\bt_\bs_\bt_\be_\bd_\bi_\br_\b/_\br_\bu_\bn_\b/_\br_\br_\bd_\bc_\ba_\bc_\bh_\be_\bd_\b._\bp_\bi_\bd_\b" will be used.
106 Specifies the number of threads used for writing RRD files. The
107 default is 4. Increasing this number will allow rrdcached to have
108 more simultaneous I/O requests into the kernel. This may allow the
109 kernel to re-order disk writes, resulting in better disk
110 throughput.
114 system crash, this will allow the daemon to write any updates that
115 were pending at the time of the crash.
117 On startup, the daemon will check for journal files in this
118 directory. If found, all updates therein will be read into memory
119 before the daemon starts accepting new connections.
121 The journal will be rotated with the same frequency as the flush
124 When journaling is enabled, the daemon will use a fast shutdown
125 procedure. Rather than flushing all files to disk, it will make
126 sure the journal is properly written and exit immediately.
127 Although the RRD data files are not fully up-to-date, no
128 information is lost; all pending updates will be replayed from the
129 journal next time the daemon starts up.
134 shut down, regardless of journal setting.
139 The daemon will change into a specific directory at startup. All
141 will be interpreted to be relative to this directory. If not given
142 the default, "/tmp", will be used.
144 +------------------------+------------------------+
145 ! Command line ! File updated !
146 +------------------------+------------------------+
147 ! foo.rrd ! /tmp/foo.rrd !
148 ! foo/bar.rrd ! /tmp/foo/bar.rrd !
149 ! /var/lib/rrd/foo.rrd ! /var/lib/rrd/foo.rrd !
150 +------------------------+------------------------+
151 Paths given on the command line and paths actually
152 updated by the daemon, assuming the base directory
153 "/tmp".
155 W\bWA\bAR\bRN\bNI\bIN\bNG\bG:\b: The paths up to and including the base directory M\bMU\bUS\bST\bT N\bNO\bOT\bT
157 specified as:
159 -b /base/dir/somewhere
163 /base
164 /base/dir
165 /base/dir/somewhere
169 containing "../" will also be blocked.
176 · dump
178 · fetch
180 · flush
182 · graph
184 · graphv
186 · info
188 · last
190 · lastupdate
192 · update
194 · xport
198 (see below) to the daemon before accessing the files, so they work with
199 up-to-date data even if the cache timeout is large.
202 The daemon reports errors in one of two ways: During startup, error
203 messages are printed to "STDERR". One of the steps when starting up is
204 to fork to the background and closing "STDERR" - after this writing
205 directly to the user is no longer possible. Once this has happened, the
206 daemon will send log messages to the system logging daemon using
211 for an entry for that file in its internal tree. If not found, an entry
212 is created including the current time (called "First" in the diagram
214 time the operating system considers to be "now". The value and time of
215 the value (called "Time" in the diagram below) are appended to the tree
216 node.
218 When appending a value to a tree node, it is checked whether it's time
219 to write the values to disk. Values are written to disk if
220 "now() - First >= timeout", where "timeout" is the timeout specified
222 will be enqueued in the "update queue", i. e. they will be appended to
223 the linked list shown below. Because the tree nodes and the elements
224 of the linked list are the same data structures in memory, any update
225 to a file that has already been enqueued will be written with the next
226 write to the RRD file, too.
228 A separate "update thread" constantly dequeues the first element in the
229 update queue and writes all its values to the appropriate file. So as
230 long as the update queue is not empty files are written at the highest
231 possible rate.
233 Since the timeout of files is checked only when new values are added to
234 the file, "dead" files, i. e. files that are not updated anymore, would
235 never be written to disk. Therefore, every now and then, controlled by
237 enqueued. Since this only affects "dead" files and walking the tree is
238 relatively expensive, you should set the "flush interval" to a
239 reasonably high value. The default is 3600 seconds (one hour).
241 The downside of caching values is that they won't show up in graphs
242 generated from the RRD files. To get around this, the daemon provides
243 the "flush command" to flush specific files. This means that the file
245 already enqueued. The flush command will return only after the file's
246 pending updates have been written to disk.
248 +------+ +------+ +------+
249 ! head ! ! root ! ! tail !
250 +---+--+ +---+--+ +---+--+
251 ! /\ !
252 ! / \ !
253 ! /\ /\ !
254 ! /\/\ \ `----------------- ... --------, !
255 V / `-------, ! V
256 +---+----+---+ +------+-----+ +---+----+---+
257 ! File: foo ! ! File: bar ! ! File: qux !
258 ! First: 101 ! ! First: 119 ! ! First: 180 !
259 ! Next:&bar -+--->! Next:&... -+---> ... --->! Next:NULL !
260 | Prev:NULL !<---+-Prev:&foo !<--- ... ----+-Prev: &... !
261 +============+ +============+ +============+
262 ! Time: 100 ! ! Time: 120 ! ! Time: 180 !
263 ! Value: 10 ! ! Value: 0.1 ! ! Value: 2,2 !
264 +------------+ +------------+ +------------+
265 ! Time: 110 ! ! Time: 130 ! ! Time: 190 !
266 ! Value: 26 ! ! Value: 0.1 ! ! Value: 7,3 !
267 +------------+ +------------+ +------------+
268 : : : : : :
269 +------------+ +------------+ +------------+
270 ! Time: 230 ! ! Time: 250 ! ! Time: 310 !
271 ! Value: 42 ! ! Value: 0.2 ! ! Value: 1,2 !
272 +------------+ +------------+ +------------+
274 The above diagram demonstrates:
276 · Files/values are stored in a (balanced) tree.
278 · Tree nodes and entries in the update queue are the same data
279 structure.
281 · The local time ("First") and the time specified in updates ("Time")
282 may differ.
284 · Timed out values are inserted at the "tail".
286 · Explicitly flushed values are inserted at the "head".
288 · ASCII art rocks.
292 There is no authentication.
294 The client/server protocol does not yet have any authentication
295 mechanism. It is likely that authentication and encryption will be
296 added in a future version, but for the time being it is the
297 administrator's responsibility to secure the traffic from/to the
298 daemon!
300 It is highly recommended to install a packet filter or similar
301 mechanism to prevent unauthorized connections. Unless you have a
302 dedicated VLAN or VPN for this, using network sockets is probably a bad
303 idea!
306 There is minimal per-socket authorization.
308 Authorization is currently done on a per-socket basis. That means each
309 socket has a list of commands it will accept and it will accept. It
310 will accept only those commands explicitly listed but it will
311 (currently) accept these commands from anyone reaching the socket.
313 If the networking sockets are to be used, it is necessary to restrict
314 the accepted commands to those needed by external clients. If, for
315 example, external clients want to draw graphs of the cached data, they
316 should only be allowed to use the "FLUSH" command.
319 There is no encryption.
321 Again, this may be added in the future, but for the time being it is
322 your job to keep your private data private. Install a VPN or an
323 encrypted tunnel if you statistics are confidential!
326 There is no sanity checking.
328 The daemon will blindly write to any file it gets told, so you really
329 should create a separate user just for this daemon. Also it does not do
330 any sanity checks, so if it gets told to write values for a time far in
331 the future, your files will be messed up good!
334 · Security is the job of the administrator.
336 · We recommend to allow write access via UNIX domain sockets only.
338 · You have been warned.
341 The daemon communicates with clients using a line based ASCII protocol
342 which is easy to read and easy to type. This makes it easy for scripts
343 to implement the protocol and possible for users to use telnet to
344 connect to the daemon and test stuff "by hand".
346 The protocol is line based, this means that each record consists of one
347 or more lines. A line is terminated by the line feed character 0x0A,
348 commonly written as "\n". In the examples below, this character will be
349 written as "<LF>" ("line feed").
351 After the connection has been established, the client is expected to
352 send a "command". A command consists of the command keyword, possibly
353 some arguments, and a terminating newline character. For a list of
354 commands, see "Valid Commands" below.
356 Example:
358 FLUSH /tmp/foo.rrd<LF>
360 The daemon answers with a line consisting of a status code and a short
361 status message, separated by one or more space characters. A negative
362 status code signals an error, a positive status code or zero signal
363 success. If the status code is greater than zero, it indicates the
364 number of lines that follow the status line.
366 Examples:
368 0 Success<LF>
370 2 Two lines follow<LF>
371 This is the first line<LF>
372 And this is the second line<LF>
375 The following commands are understood by the daemon:
378 Causes the daemon to put _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be to the h\bhe\bea\bad\bd of the update queue
379 (possibly moving it there if the node is already enqueued). The
383 Causes the daemon to start flushing ALL pending values to disk.
384 This returns immediately, even though the writes may take a long
385 time.
388 Shows any "pending" updates for a file, in order. The updates
389 shown have not yet been written to the underlying RRD file.
392 Removes _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be from the cache. Any pending updates W\bWI\bIL\bLL\bL B\bBE\bE L\bLO\bOS\bST\bT.
395 Shows the files that are on the output queue. Returns zero or more
396 lines in the following format, where <num_vals> is the number of
397 values to be written for the <file>:
399 <num_vals> <file>
404 Otherwise a short description, possibly containing a pointer to a
405 manual page, is returned. Obviously, this is meant for interactive
406 usage and the format in which the commands and usage summaries are
407 returned is not well defined.
410 Returns a list of metrics which can be used to measure the daemons
411 performance and check its status. For a description of the values
412 returned, see "Performance Values" below.
414 The format in which the values are returned is similar to many
415 other line based protocols: Each value is printed on a separate
416 line, each consisting of the name of the value, a colon, one or
417 more spaces and the actual value.
419 Example:
421 9 Statistics follow
422 QueueLength: 0
423 UpdatesReceived: 30
424 FlushesReceived: 2
425 UpdatesWritten: 13
426 DataSetsWritten: 390
427 TreeNodesNumber: 13
428 TreeDepth: 4
429 JournalBytes: 190
430 JournalRotate: 0
432 U\bUP\bPD\bDA\bAT\bTE\bE _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be _\bv_\ba_\bl_\bu_\be_\bs [_\bv_\ba_\bl_\bu_\be_\bs ...]
434 designed for, so describing the mechanism again is unnecessary.
435 Read "HOW IT WORKS" above for a detailed explanation.
437 Note that rrdcached only accepts absolute timestamps in the update
438 values. Updates strings like "N:1:2:3" are automatically converted
439 to absolute time by the RRD client library before sending to
440 rrdcached.
443 This command is written to the journal after a file is successfully
444 written out to disk. It is used during journal replay to determine
446 journal; it is not accepted from the other command channels.
449 This command initiates the bulk load of multiple commands. This is
450 designed for installations with extremely high update rates, since
454 All commands are executed just as they would be if given
455 individually, except for output to the user. Messages indicating
456 success are suppressed, and error messages are delayed until the
457 client is finished.
459 Command processing is finished when the client sends a dot (".") on
460 its own line. After the client has finished, the server responds
461 with an error count and the list of error messages (if any). Each
462 error messages indicates the number of the command to which it
463 corresponds, and the error message itself. The first user command
466 client: BATCH
467 server: 0 Go ahead. End with dot '.' on its own line.
468 client: UPDATE x.rrd 1223661439:1:2:3 <--- command #1
469 client: UPDATE y.rrd 1223661440:3:4:5 <--- command #2
470 client: and so on...
471 client: .
472 server: 2 Errors
473 server: 1 message for command 1
474 server: 12 message for command 12
477 Disconnect from rrdcached.
482 Q\bQu\bue\beu\bue\beL\bLe\ben\bng\bgt\bth\bh _\b(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\b6_\b4_\bb_\bi_\bt _\bi_\bn_\bt_\be_\bg_\be_\br_\b)
483 Number of nodes currently enqueued in the update queue.
485 U\bUp\bpd\bda\bat\bte\bes\bsR\bRe\bec\bce\bei\biv\bve\bed\bd _\b(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\b6_\b4_\bb_\bi_\bt _\bi_\bn_\bt_\be_\bg_\be_\br_\b)
486 Number of UPDATE commands received.
488 F\bFl\blu\bus\bsh\bhe\bes\bsR\bRe\bec\bce\bei\biv\bve\bed\bd _\b(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\b6_\b4_\bb_\bi_\bt _\bi_\bn_\bt_\be_\bg_\be_\br_\b)
489 Number of FLUSH commands received.
491 U\bUp\bpd\bda\bat\bte\bes\bsW\bWr\bri\bit\btt\bte\ben\bn _\b(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\b6_\b4_\bb_\bi_\bt _\bi_\bn_\bt_\be_\bg_\be_\br_\b)
492 Total number of updates, i. e. calls to "rrd_update_r", since the
493 daemon was started.
495 D\bDa\bat\bta\baS\bSe\bet\bts\bsW\bWr\bri\bit\btt\bte\ben\bn _\b(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\b6_\b4_\bb_\bi_\bt _\bi_\bn_\bt_\be_\bg_\be_\br_\b)
496 Total number of "data sets" written to disk since the daemon was
498 command. For example: "1223661439:123:456" is one data set with two
499 values. The term "data set" is used to prevent confusion whether
500 individual values or groups of values are counted.
502 T\bTr\bre\bee\beN\bNo\bod\bde\bes\bsN\bNu\bum\bmb\bbe\ber\br _\b(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\b6_\b4_\bb_\bi_\bt _\bi_\bn_\bt_\be_\bg_\be_\br_\b)
503 Number of nodes in the cache.
505 T\bTr\bre\bee\beD\bDe\bep\bpt\bth\bh _\b(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\b6_\b4_\bb_\bi_\bt _\bi_\bn_\bt_\be_\bg_\be_\br_\b)
506 Depth of the tree used for fast key lookup.
508 J\bJo\bou\bur\brn\bna\bal\blB\bBy\byt\bte\bes\bs _\b(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\b6_\b4_\bb_\bi_\bt _\bi_\bn_\bt_\be_\bg_\be_\br_\b)
509 Total number of bytes written to the journal since startup.
511 J\bJo\bou\bur\brn\bna\bal\blR\bRo\bot\bta\bat\bte\be _\b(_\bu_\bn_\bs_\bi_\bg_\bn_\be_\bd _\b6_\b4_\bb_\bi_\bt _\bi_\bn_\bt_\be_\bg_\be_\br_\b)
512 Number of times the journal has been rotated since startup.
515 SIGINT and SIGTERM
516 The daemon exits normally on receipt of either of these signals.
518 options.
520 SIGUSR1
521 The daemon exits AFTER flushing all updates out to disk. This may
522 take a while.
524 SIGUSR2
525 The daemon exits immediately, without flushing updates out to disk.
526 Pending updates will be replayed from the journal when the daemon
527 starts up again. W\bWA\bAR\bRN\bNI\bIN\bNG\bG:\b: i\bif\bf j\bjo\bou\bur\brn\bna\bal\bli\bin\bng\bg (\b(-\b-j\bj)\b) i\bis\bs N\bNO\bOT\bT e\ben\bna\bab\bbl\ble\bed\bd,\b, a\ban\bny\by
528 p\bpe\ben\bnd\bdi\bin\bng\bg u\bup\bpd\bda\bat\bte\bes\bs W\bWI\bIL\bLL\bL B\bBE\bE L\bLO\bOS\bST\bT.
531 No known bugs at the moment.
534 rrdtool, rrdgraph
537 Florian Forster <octo at verplant.org>
542 kevin brintnall <kbrint@rufus.net>
546 1.4.2 2009-11-15 RRDCACHED(1)