1
RRDCACHED(1) rrdtool RRDCACHED(1)
6
rrdcached - Data caching daemon for rrdtool
9
rrrrddccaacchheedd [--PP _p_e_r_m_i_s_s_i_o_n_s] [--ll _a_d_d_r_e_s_s] [--ss _g_r_o_u_p] [--ww _t_i_m_e_o_u_t]
10
[--zz _d_e_l_a_y] [--ff _t_i_m_e_o_u_t] [--pp _p_i_d___f_i_l_e] [--tt _w_r_i_t_e___t_h_r_e_a_d_s]
11
[--jj _j_o_u_r_n_a_l___d_i_r] [-F] [-g] [--bb _b_a_s_e___d_i_r [--BB]]
13
DDEESSCCRRIIPPTTIIOONN
14
rrrrddccaacchheedd is a daemon that receives updates to existing RRD files,
15
accumulates them and, if enough have been received or a defined time
16
has passed, writes the updates to the RRD file. A _f_l_u_s_h command may be
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.
29
Tells the daemon to bind to _a_d_d_r_e_s_s and accept incoming connections
30
on that socket. If _a_d_d_r_e_s_s begins with "unix:", everything
31
following that prefix is interpreted as the path to a UNIX domain
32
socket. Otherwise the address or node name are resolved using
35
For network sockets, a port may be specified by using the form
36
"[[_a_d_d_r_e_s_s]]::_p_o_r_t_". 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) "_a_d_d_r_e_s_s::_p_o_r_t_" pattern. The default port is 4422221177//uuddpp. 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
44
the UNIX domain socket mmuusstt start with a slash in the second case!
46
unix:</path/to/unix.sock>
49
[<hostname-or-ip>]:<port>
50
<hostname-or-ipv4>:<port>
52
If the --ll option is not specified the default address,
53
"unix:/tmp/rrdcached.sock", will be used.
55
--ss _g_r_o_u_p___n_a_m_e|_g_i_d
56
Set the group permissions of a UNIX domain socket. The option
57
accepts either a numeric group id or group name. That group will
58
then have both read and write permissions (the socket will have
59
file permissions 0750) for the socket and, therefore, is able to
60
send commands to the daemon. This may be useful in cases where you
61
cannot easily run all RRD processes with the same user privileges
62
(e.g. graph generating CGI scripts that typically run in the
63
permission context of the web server).
65
This option affects the _f_o_l_l_o_w_i_n_g UNIX socket addresses (the
66
following --ll options), i.e., you may specify different settings for
69
The default is not to change ownership or permissions of the socket
70
and, thus, use the system default.
73
Set the file permissions of a UNIX domain socket. The option
74
accepts an octal number representing the bit pattern for the mode
75
(see _c_h_m_o_d(1) for details).
77
Please note that not all systems honor this setting. On Linux,
78
read/write permissions are required to connect to a UNIX socket.
79
However, many BSD-derived systems ignore permissions for UNIX
80
sockets. See _u_n_i_x(7) for details.
82
This option affects the _f_o_l_l_o_w_i_n_g UNIX socket addresses (the
83
following --ll options), i.e., you may specify different settings for
86
The default is not to change ownership or permissions of the socket
87
and, thus, use the system default.
89
--PP _c_o_m_m_a_n_d[,_c_o_m_m_a_n_d[,...]]
90
Specifies the commands accepted via a network socket. This allows
91
administrators of _R_R_D_C_a_c_h_e_D to control the actions accepted from
94
The arguments given to the --PP option is a comma separated list of
95
commands. For example, to allow the "FLUSH" and "PENDING" commands
98
rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS
100
The --PP option affects the _f_o_l_l_o_w_i_n_g socket addresses (the following
101
--ll options). In the following example, only the IPv4 network socket
102
(address 10.0.0.1) will be restricted to the "FLUSH" and "PENDING"
105
rrdcached -l unix:/some/path -P FLUSH,PENDING -l 10.0.0.1
107
A complete list of available commands can be found in the section
108
"Valid Commands" below. There are two minor special exceptions:
110
� The "HELP" and "QUIT" commands are always allowed.
112
� If the "BATCH" command is accepted, the .. command will
113
automatically be accepted, too.
115
Please also read "SECURITY CONSIDERATIONS" below.
118
Data is written to disk every _t_i_m_e_o_u_t seconds. If this option is
119
not specified the default interval of 300 seconds will be used.
122
If specified, rrdcached will delay writing of each RRD for a random
123
number of seconds in the range [0,_d_e_l_a_y). This will avoid too many
124
writes being queued simultaneously. This value should be no
125
greater than the value specified in --ww. By default, there is no
129
Every _t_i_m_e_o_u_t seconds the entire cache is searched for old values
130
which are written to disk. This only concerns files to which
131
updates have stopped, so setting this to a high value, such as
132
3600 seconds, is acceptable in most cases. This timeout defaults to
136
Sets the name and location of the PID-file. If not specified, the
137
default, "_$_l_o_c_a_l_s_t_s_t_e_d_i_r_/_r_u_n_/_r_r_d_c_a_c_h_e_d_._p_i_d_" will be used.
139
--tt _w_r_i_t_e___t_h_r_e_a_d_s
140
Specifies the number of threads used for writing RRD files. The
141
default is 4. Increasing this number will allow rrdcached to have
142
more simultaneous I/O requests into the kernel. This may allow the
143
kernel to re-order disk writes, resulting in better disk
147
Write updates to a journal in _d_i_r. In the event of a program or
148
system crash, this will allow the daemon to write any updates that
149
were pending at the time of the crash.
151
On startup, the daemon will check for journal files in this
152
directory. If found, all updates therein will be read into memory
153
before the daemon starts accepting new connections.
155
The journal will be rotated with the same frequency as the flush
158
When journaling is enabled, the daemon will use a fast shutdown
159
procedure. Rather than flushing all files to disk, it will make
160
sure the journal is properly written and exit immediately.
161
Although the RRD data files are not fully up-to-date, no
162
information is lost; all pending updates will be replayed from the
163
journal next time the daemon starts up.
165
To disable fast shutdown, use the --FF option.
167
--FF ALWAYS flush all updates to the RRD data files when the daemon is
168
shut down, regardless of journal setting.
170
--gg Run in the foreground. The daemon will not _f_o_r_k_(_).
173
The daemon will change into a specific directory at startup. All
174
files passed to the daemon, that are specified by a rreellaattiivvee path,
175
will be interpreted to be relative to this directory. If not given
176
the default, "/tmp", will be used.
178
+------------------------+------------------------+
179
! Command line ! File updated !
180
+------------------------+------------------------+
181
! foo.rrd ! /tmp/foo.rrd !
182
! foo/bar.rrd ! /tmp/foo/bar.rrd !
183
! /var/lib/rrd/foo.rrd ! /var/lib/rrd/foo.rrd !
184
+------------------------+------------------------+
185
Paths given on the command line and paths actually
186
updated by the daemon, assuming the base directory
189
WWAARRNNIINNGG:: The paths up to and including the base directory MMUUSSTT NNOOTT
190
BBEE symbolic links. In other words, if the base directory is
193
-b /base/dir/somewhere
195
... then NNOONNEE of the following should be symbolic links:
201
--BB Only permit writes into the base directory specified in --bb (and any
202
sub-directories). This does NNOOTT detect symbolic links. Paths
203
containing "../" will also be blocked.
205
AAFFFFEECCTTEEDD RRRRDDTTOOOOLL CCOOMMMMAANNDDSS
206
The following commands may be made aware of the rrrrddccaacchheedd using the
207
command line argument ----ddaaeemmoonn or the environment variable
208
RRRRDDCCAACCHHEEDD__AADDDDRREESSSS:
230
The uuppddaattee command can send values to the daemon instead of writing
231
them to the disk itself. All other commands can send a FFLLUUSSHH command
232
(see below) to the daemon before accessing the files, so they work with
233
up-to-date data even if the cache timeout is large.
235
EERRRROORR RREEPPOORRTTIINNGG
236
The daemon reports errors in one of two ways: During startup, error
237
messages are printed to "STDERR". One of the steps when starting up is
238
to fork to the background and closing "STDERR" - after this writing
239
directly to the user is no longer possible. Once this has happened, the
240
daemon will send log messages to the system logging daemon using
241
_s_y_s_l_o_g(3). The facility used is "LOG_DAEMON".
243
HHOOWW IITT WWOORRKKSS
244
When receiving an update, rrrrddccaacchheedd does not write to disk but looks
245
for an entry for that file in its internal tree. If not found, an entry
246
is created including the current time (called "First" in the diagram
247
below). This time is nnoott the time specified on the command line but the
248
time the operating system considers to be "now". The value and time of
249
the value (called "Time" in the diagram below) are appended to the tree
252
When appending a value to a tree node, it is checked whether it's time
253
to write the values to disk. Values are written to disk if
254
"now() - First >= timeout", where "timeout" is the timeout specified
255
using the --ww option, see "OPTIONS". If the values are "old enough" they
256
will be enqueued in the "update queue", i. e. they will be appended to
257
the linked list shown below. Because the tree nodes and the elements
258
of the linked list are the same data structures in memory, any update
259
to a file that has already been enqueued will be written with the next
260
write to the RRD file, too.
262
A separate "update thread" constantly dequeues the first element in the
263
update queue and writes all its values to the appropriate file. So as
264
long as the update queue is not empty files are written at the highest
267
Since the timeout of files is checked only when new values are added to
268
the file, "dead" files, i. e. files that are not updated anymore, would
269
never be written to disk. Therefore, every now and then, controlled by
270
the --ff option, the entire tree is walked and all "old" values are
271
enqueued. Since this only affects "dead" files and walking the tree is
272
relatively expensive, you should set the "flush interval" to a
273
reasonably high value. The default is 3600 seconds (one hour).
275
The downside of caching values is that they won't show up in graphs
276
generated from the RRD files. To get around this, the daemon provides
277
the "flush command" to flush specific files. This means that the file
278
is inserted at the hheeaadd of the update queue or moved there if it is
279
already enqueued. The flush command will return only after the file's
280
pending updates have been written to disk.
282
+------+ +------+ +------+
283
! head ! ! root ! ! tail !
284
+---+--+ +---+--+ +---+--+
288
! /\/\ \ `----------------- ... --------, !
290
+---+----+---+ +------+-----+ +---+----+---+
291
! File: foo ! ! File: bar ! ! File: qux !
292
! First: 101 ! ! First: 119 ! ! First: 180 !
293
! Next:&bar -+--->! Next:&... -+---> ... --->! Next:NULL !
294
| Prev:NULL !<---+-Prev:&foo !<--- ... ----+-Prev: &... !
295
+============+ +============+ +============+
296
! Time: 100 ! ! Time: 120 ! ! Time: 180 !
297
! Value: 10 ! ! Value: 0.1 ! ! Value: 2,2 !
298
+------------+ +------------+ +------------+
299
! Time: 110 ! ! Time: 130 ! ! Time: 190 !
300
! Value: 26 ! ! Value: 0.1 ! ! Value: 7,3 !
301
+------------+ +------------+ +------------+
303
+------------+ +------------+ +------------+
304
! Time: 230 ! ! Time: 250 ! ! Time: 310 !
305
! Value: 42 ! ! Value: 0.2 ! ! Value: 1,2 !
306
+------------+ +------------+ +------------+
308
The above diagram demonstrates:
310
� Files/values are stored in a (balanced) tree.
312
� Tree nodes and entries in the update queue are the same data
315
� The local time ("First") and the time specified in updates ("Time")
318
� Timed out values are inserted at the "tail".
320
� Explicitly flushed values are inserted at the "head".
324
SSEECCUURRIITTYY CCOONNSSIIDDEERRAATTIIOONNSS
325
AAuutthheennttiiccaattiioonn
326
There is no authentication.
328
The client/server protocol does not yet have any authentication
329
mechanism. It is likely that authentication and encryption will be
330
added in a future version, but for the time being it is the
331
administrator's responsibility to secure the traffic from/to the
334
It is highly recommended to install a packet filter or similar
335
mechanism to prevent unauthorized connections. Unless you have a
336
dedicated VLAN or VPN for this, using network sockets is probably a bad
339
AAuutthhoorriizzaattiioonn
340
There is minimal per-socket authorization.
342
Authorization is currently done on a per-socket basis. That means each
343
socket has a list of commands it will accept and it will accept. It
344
will accept only those commands explicitly listed but it will
345
(currently) accept these commands from anyone reaching the socket.
347
If the networking sockets are to be used, it is necessary to restrict
348
the accepted commands to those needed by external clients. If, for
349
example, external clients want to draw graphs of the cached data, they
350
should only be allowed to use the "FLUSH" command.
353
There is no encryption.
355
Again, this may be added in the future, but for the time being it is
356
your job to keep your private data private. Install a VPN or an
357
encrypted tunnel if you statistics are confidential!
359
SSaanniittyy cchheecckkiinngg
360
There is no sanity checking.
362
The daemon will blindly write to any file it gets told, so you really
363
should create a separate user just for this daemon. Also it does not do
364
any sanity checks, so if it gets told to write values for a time far in
365
the future, your files will be messed up good!
368
� Security is the job of the administrator.
370
� We recommend to allow write access via UNIX domain sockets only.
372
� You have been warned.
375
The daemon communicates with clients using a line based ASCII protocol
376
which is easy to read and easy to type. This makes it easy for scripts
377
to implement the protocol and possible for users to use telnet to
378
connect to the daemon and test stuff "by hand".
380
The protocol is line based, this means that each record consists of one
381
or more lines. A line is terminated by the line feed character 0x0A,
382
commonly written as "\n". In the examples below, this character will be
383
written as "<LF>" ("line feed").
385
After the connection has been established, the client is expected to
386
send a "command". A command consists of the command keyword, possibly
387
some arguments, and a terminating newline character. For a list of
388
commands, see "Valid Commands" below.
392
FLUSH /tmp/foo.rrd<LF>
394
The daemon answers with a line consisting of a status code and a short
395
status message, separated by one or more space characters. A negative
396
status code signals an error, a positive status code or zero signal
397
success. If the status code is greater than zero, it indicates the
398
number of lines that follow the status line.
404
2 Two lines follow<LF>
405
This is the first line<LF>
406
And this is the second line<LF>
408
VVaalliidd CCoommmmaannddss
409
The following commands are understood by the daemon:
411
FFLLUUSSHH _f_i_l_e_n_a_m_e
412
Causes the daemon to put _f_i_l_e_n_a_m_e to the hheeaadd of the update queue
413
(possibly moving it there if the node is already enqueued). The
414
answer will be sent aafftteerr the node has been dequeued.
417
Causes the daemon to start flushing ALL pending values to disk.
418
This returns immediately, even though the writes may take a long
421
PPEENNDDIINNGG _f_i_l_e_n_a_m_e
422
Shows any "pending" updates for a file, in order. The updates
423
shown have not yet been written to the underlying RRD file.
425
FFOORRGGEETT _f_i_l_e_n_a_m_e
426
Removes _f_i_l_e_n_a_m_e from the cache. Any pending updates WWIILLLL BBEE LLOOSSTT.
429
Shows the files that are on the output queue. Returns zero or more
430
lines in the following format, where <num_vals> is the number of
431
values to be written for the <file>:
435
HHEELLPP [_c_o_m_m_a_n_d]
436
Returns a short usage message. If no command is given, or _c_o_m_m_a_n_d
437
is HHEELLPP, a list of commands supported by the daemon is returned.
438
Otherwise a short description, possibly containing a pointer to a
439
manual page, is returned. Obviously, this is meant for interactive
440
usage and the format in which the commands and usage summaries are
441
returned is not well defined.
444
Returns a list of metrics which can be used to measure the daemons
445
performance and check its status. For a description of the values
446
returned, see "Performance Values" below.
448
The format in which the values are returned is similar to many
449
other line based protocols: Each value is printed on a separate
450
line, each consisting of the name of the value, a colon, one or
451
more spaces and the actual value.
466
UUPPDDAATTEE _f_i_l_e_n_a_m_e _v_a_l_u_e_s [_v_a_l_u_e_s ...]
467
Adds more data to a filename. This is tthhee operation the daemon was
468
designed for, so describing the mechanism again is unnecessary.
469
Read "HOW IT WORKS" above for a detailed explanation.
471
Note that rrdcached only accepts absolute timestamps in the update
472
values. Updates strings like "N:1:2:3" are automatically converted
473
to absolute time by the RRD client library before sending to
476
WWRROOTTEE _f_i_l_e_n_a_m_e
477
This command is written to the journal after a file is successfully
478
written out to disk. It is used during journal replay to determine
479
which updates have already been applied. It is _o_n_l_y valid in the
480
journal; it is not accepted from the other command channels.
483
This command initiates the bulk load of multiple commands. This is
484
designed for installations with extremely high update rates, since
485
it permits more than one command to be issued per _r_e_a_d_(_) and
488
All commands are executed just as they would be if given
489
individually, except for output to the user. Messages indicating
490
success are suppressed, and error messages are delayed until the
493
Command processing is finished when the client sends a dot (".") on
494
its own line. After the client has finished, the server responds
495
with an error count and the list of error messages (if any). Each
496
error messages indicates the number of the command to which it
497
corresponds, and the error message itself. The first user command
498
after BBAATTCCHH is command number one.
501
server: 0 Go ahead. End with dot '.' on its own line.
502
client: UPDATE x.rrd 1223661439:1:2:3 <--- command #1
503
client: UPDATE y.rrd 1223661440:3:4:5 <--- command #2
507
server: 1 message for command 1
508
server: 12 message for command 12
511
Disconnect from rrdcached.
513
PPeerrffoorrmmaannccee VVaalluueess
514
The following counters are returned by the SSTTAATTSS command:
516
QQuueeuueeLLeennggtthh _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_)
517
Number of nodes currently enqueued in the update queue.
519
UUppddaatteessRReecceeiivveedd _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_)
520
Number of UPDATE commands received.
522
FFlluusshheessRReecceeiivveedd _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_)
523
Number of FLUSH commands received.
525
UUppddaatteessWWrriitttteenn _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_)
526
Total number of updates, i. e. calls to "rrd_update_r", since the
529
DDaattaaSSeettssWWrriitttteenn _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_)
530
Total number of "data sets" written to disk since the daemon was
531
started. A data set is one or more values passed to the UUPPDDAATTEE
532
command. For example: "1223661439:123:456" is one data set with two
533
values. The term "data set" is used to prevent confusion whether
534
individual values or groups of values are counted.
536
TTrreeeeNNooddeessNNuummbbeerr _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_)
537
Number of nodes in the cache.
539
TTrreeeeDDeepptthh _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_)
540
Depth of the tree used for fast key lookup.
542
JJoouurrnnaallBByytteess _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_)
543
Total number of bytes written to the journal since startup.
545
JJoouurrnnaallRRoottaattee _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_)
546
Number of times the journal has been rotated since startup.
550
The daemon exits normally on receipt of either of these signals.
551
Pending updates are handled in accordance with the --jj and --FF
555
The daemon exits AFTER flushing all updates out to disk. This may
559
The daemon exits immediately, without flushing updates out to disk.
560
Pending updates will be replayed from the journal when the daemon
561
starts up again. WWAARRNNIINNGG:: iiff jjoouurrnnaalliinngg ((--jj)) iiss NNOOTT eennaabblleedd,, aannyy
562
ppeennddiinngg uuppddaatteess WWIILLLL BBEE LLOOSSTT.
565
No known bugs at the moment.
571
Florian Forster <octo at verplant.org>
573
Both rrrrddccaacchheedd and this manual page have been written by Florian.
575
CCOONNTTRRIIBBUUTTOORRSS
576
kevin brintnall <kbrint@rufus.net>
580
1.4.3 2010-03-22 RRDCACHED(1)
added
removed
doc/rrdcached.txt
