Code

Imported upstream version 1.4.2.
[pkg-rrdtool.git] / doc / rrdcached.pod
1 =pod
3 =head1 NAME
5 rrdcached - Data caching daemon for rrdtool
7 =head1 SYNOPSIS
9 B<rrdcached>
10 [B<-P>E<nbsp>I<permissions>]
11 [B<-l>E<nbsp>I<address>]
12 [B<-w>E<nbsp>I<timeout>]
13 [B<-z>E<nbsp>I<delay>]
14 [B<-f>E<nbsp>I<timeout>]
15 [B<-p>E<nbsp>I<pid_file>]
16 [B<-t>E<nbsp>I<write_threads>]
17 [B<-j>E<nbsp>I<journal_dir>]
18 [-F]
19 [-g]
20 [B<-b>E<nbsp>I<base_dir>E<nbsp>[B<-B>]]
22 =head1 DESCRIPTION
24 B<rrdcached> is a daemon that receives updates to existing RRD files,
25 accumulates them and, if enough have been received or a defined time has
26 passed, writes the updates to the RRD file. A I<flush> command may be used to
27 force writing of values to disk, so that graphing facilities and similar can
28 work with up-to-date data.
30 The daemon was written with big setups in mind. Those setups usually run into
31 IOE<nbsp>related problems sooner or later for reasons that are beyond the scope
32 of this document. Check the wiki at the RRDtool homepage for details. Also
33 check L</"SECURITY CONSIDERATIONS"> below before using this daemon! A detailed
34 description of how the daemon operates can be found in the L</"HOW IT WORKS">
35 section below.
37 =head1 OPTIONS
39 =over 4
41 =item B<-l> I<address>
43 Tells the daemon to bind to I<address> and accept incoming connections on that
44 socket. If I<address> begins with C<unix:>, everything following that prefix is
45 interpreted as the path to a UNIX domain socket. Otherwise the address or node
46 name are resolved using getaddrinfo.
48 For network sockets, a port may be specified by using the form
49 C<B<[>I<address>B<]:>I<port>>. If the address is an IPv4 address or a fully
50 qualified domain name (i.E<nbsp>e. the address contains at least one dot
51 (C<.>)), the square brackets can be omitted, resulting in the (simpler)
52 C<I<address>B<:>I<port>> pattern. The default port is B<42217/udp>. If you
53 specify a network socket, it is mandatory to read the
54 L</"SECURITY CONSIDERATIONS"> section.
56 The following formats are accepted. Please note that the address of the UNIX
57 domain socket B<must> start with a slash in the second case!
59    unix:</path/to/unix.sock>
60    /<path/to/unix.sock>
61    <hostname-or-ip>
62    [<hostname-or-ip>]:<port>
63    <hostname-or-ipv4>:<port>
65 If the B<-l> option is not specified the default address,
66 C<unix:/tmp/rrdcached.sock>, will be used.
68 =item B<-P> I<command>[,I<command>[,...]]
70 Specifies the commands accepted via a network socket. This allows
71 administrators of I<RRDCacheD> to control the actions accepted from various
72 sources.
74 The arguments given to the B<-P> option is a comma separated list of commands.
75 For example, to allow the C<FLUSH> and C<PENDING> commands one could specify:
77   rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS
79 The B<-P> option effects the I<following> socket addresses (the following B<-l>
80 options). In the following example, only the IPv4 network socket (address
81 C<10.0.0.1>) will be restricted to the C<FLUSH> and C<PENDING> commands:
83   rrdcached -l unix:/some/path -P FLUSH,PENDING -l 10.0.0.1
85 A complete list of available commands can be found in the section
86 L</"Valid Commands"> below. There are two minor special exceptions:
88 =over 4
90 =item *
92 The C<HELP> and C<QUIT> commands are always allowed.
94 =item *
96 If the C<BATCH> command is accepted, the B<.>E<nbsp>command will automatically
97 be accepted, too.
99 =back
101 Please also read L</"SECURITY CONSIDERATIONS"> below.
103 =item B<-w> I<timeout>
105 Data is written to disk every I<timeout> seconds. If this option is not
106 specified the default interval of 300E<nbsp>seconds will be used.
108 =item B<-z> I<delay>
110 If specified, rrdcached will delay writing of each RRD for a random number
111 of seconds in the rangeE<nbsp>[0,I<delay>).  This will avoid too many
112 writes being queued simultaneously.  This value should be no greater than
113 the value specified in B<-w>.  By default, there is no delay.
115 =item B<-f> I<timeout>
117 Every I<timeout> seconds the entire cache is searched for old values which are
118 written to disk. This only concerns files to which updates have stopped, so
119 setting this to a high value, such as 3600E<nbsp>seconds, is acceptable in most
120 cases. This timeout defaults to 3600E<nbsp>seconds.
122 =item B<-p> I<file>
124 Sets the name and location of the PID-file. If not specified, the default,
125 C<I<$localststedir>/run/rrdcached.pid> will be used.
127 =item B<-t> I<write_threads>
129 Specifies the number of threads used for writing RRD files.  The default
130 isE<nbsp>4.  Increasing this number will allow rrdcached to have more
131 simultaneous I/O requests into the kernel.  This may allow the kernel to
132 re-order disk writes, resulting in better disk throughput.
134 =item B<-j> I<dir>
136 Write updates to a journal in I<dir>.  In the event of a program or system
137 crash, this will allow the daemon to write any updates that were pending
138 at the time of the crash.
140 On startup, the daemon will check for journal files in this directory.  If
141 found, all updates therein will be read into memory before the daemon
142 starts accepting new connections.
144 The journal will be rotated with the same frequency as the flush timer
145 given by B<-f>.
147 When journaling is enabled, the daemon will use a fast shutdown procedure.
148 Rather than flushing all files to disk, it will make sure the journal is
149 properly written and exit immediately.  Although the RRD data files are
150 not fully up-to-date, no information is lost; all pending updates will be
151 replayed from the journal next time the daemon starts up.
153 To disable fast shutdown, use the B<-F> option.
155 =item B<-F>
157 ALWAYS flush all updates to the RRD data files when the daemon is shut
158 down, regardless of journal setting.
160 =item B<-g>
162 Run in the foreground.  The daemon will not fork().
164 =item B<-b> I<dir>
166 The daemon will change into a specific directory at startup. All files passed
167 to the daemon, that are specified by a B<relative> path, will be interpreted
168 to be relative to this directory. If not given the default, C</tmp>, will be
169 used.
171   +------------------------+------------------------+
172   ! Command line           ! File updated           !
173   +------------------------+------------------------+
174   ! foo.rrd                ! /tmp/foo.rrd           !
175   ! foo/bar.rrd            ! /tmp/foo/bar.rrd       !
176   ! /var/lib/rrd/foo.rrd   ! /var/lib/rrd/foo.rrd   !
177   +------------------------+------------------------+
178   Paths given on the command  line and paths actually
179   updated by the daemon,  assuming the base directory
180   "/tmp".
182 B<WARNING:> The paths up to and including the base directory B<MUST NOT BE>
183 symbolic links.  In other words, if the base directory is
184 specified as:
186     -b /base/dir/somewhere
188 ... then B<NONE> of the following should be symbolic links:
190     /base
191     /base/dir
192     /base/dir/somewhere
194 =item B<-B>
196 Only permit writes into the base directory specified in B<-b> (and any
197 sub-directories).  This does B<NOT> detect symbolic links.  Paths
198 containing C<../> will also be blocked.
200 =back
202 =head1 AFFECTED RRDTOOL COMMANDS
204 The following commands may be made aware of the B<rrdcached> using the command
205 line argument B<--daemon> or the environment variable B<RRDCACHED_ADDRESS>:
207 =over
209 =item *
211 dump
213 =item *
215 fetch
217 =item *
219 flush
221 =item *
223 graph
225 =item *
227 graphv
229 =item *
231 info
233 =item *
235 last
237 =item *
239 lastupdate
241 =item *
243 update
245 =item *
247 xport
249 =back
251 The B<update> command can send values to the daemon instead of writing them to
252 the disk itself. All other commands can send a B<FLUSH> command (see below) to
253 the daemon before accessing the files, so they work with up-to-date data even
254 if the cache timeout is large.
256 =head1 ERROR REPORTING
258 The daemon reports errors in one of two ways: During startup, error messages
259 are printed to C<STDERR>. One of the steps when starting up is to fork to the
260 background and closing C<STDERR> - after this writing directly to the user is
261 no longer possible. Once this has happened, the daemon will send log messages
262 to the system logging daemon using syslog(3). The facility used is
263 C<LOG_DAEMON>.
265 =head1 HOW IT WORKS
267 When receiving an update, B<rrdcached> does not write to disk but looks for an
268 entry for that file in its internal tree. If not found, an entry is created
269 including the current time (called "First" in the diagram below). This time is
270 B<not> the time specified on the command line but the time the operating system
271 considers to be "now". The value and time of the value (called "Time" in the
272 diagram below) are appended to the tree node.
274 When appending a value to a tree node, it is checked whether it's time to write
275 the values to disk. Values are written to disk if
276 S<C<now() - First E<gt>= timeout>>, where C<timeout> is the timeout specified
277 using the B<-w> option, see L</OPTIONS>. If the values are "old enough" they
278 will be enqueued in the "update queue", i.E<nbsp>e. they will be appended to
279 the linked list shown below.  Because the tree nodes and the elements of the
280 linked list are the same data structures in memory, any update to a file that
281 has already been enqueued will be written with the next write to the RRD file,
282 too.
284 A separate "update thread" constantly dequeues the first element in the update
285 queue and writes all its values to the appropriate file. So as long as the
286 update queue is not empty files are written at the highest possible rate.
288 Since the timeout of files is checked only when new values are added to the
289 file, "dead" files, i.E<nbsp>e. files that are not updated anymore, would never
290 be written to disk. Therefore, every now and then, controlled by the B<-f>
291 option, the entire tree is walked and all "old" values are enqueued. Since this
292 only affects "dead" files and walking the tree is relatively expensive, you
293 should set the "flush interval" to a reasonably high value. The default is
294 3600E<nbsp>seconds (one hour).
296 The downside of caching values is that they won't show up in graphs generated
297 from the RRDE<nbsp>files. To get around this, the daemon provides the "flush
298 command" to flush specific files. This means that the file is inserted at the
299 B<head> of the update queue or moved there if it is already enqueued. The flush
300 command will return only after the file's pending updates have been written
301 to disk.
303  +------+   +------+                               +------+
304  ! head !   ! root !                               ! tail !
305  +---+--+   +---+--+                               +---+--+
306      !         /\                                      !
307      !        /  \                                     !
308      !       /\  /\                                    !
309      !      /\/\ \ `----------------- ... --------,    !
310      V     /      `-------,                       !    V
311  +---+----+---+    +------+-----+             +---+----+---+
312  ! File:  foo !    ! File:  bar !             ! File:  qux !
313  ! First: 101 !    ! First: 119 !             ! First: 180 !
314  ! Next:&bar -+--->! Next:&... -+---> ... --->! Next:NULL  !
315  | Prev:NULL  !<---+-Prev:&foo  !<--- ... ----+-Prev: &... !
316  +============+    +============+             +============+
317  ! Time:  100 !    ! Time:  120 !             ! Time:  180 !
318  ! Value:  10 !    ! Value: 0.1 !             ! Value: 2,2 !
319  +------------+    +------------+             +------------+
320  ! Time:  110 !    ! Time:  130 !             ! Time:  190 !
321  ! Value:  26 !    ! Value: 0.1 !             ! Value: 7,3 !
322  +------------+    +------------+             +------------+
323  :            :    :            :             :            :
324  +------------+    +------------+             +------------+
325  ! Time:  230 !    ! Time:  250 !             ! Time:  310 !
326  ! Value:  42 !    ! Value: 0.2 !             ! Value: 1,2 !
327  +------------+    +------------+             +------------+
329 The above diagram demonstrates:
331 =over
333 =item *
335 Files/values are stored in a (balanced) tree.
337 =item *
339 Tree nodes and entries in the update queue are the same data structure.
341 =item *
343 The local time ("First") and the time specified in updates ("Time") may differ.  
345 =item *
347 Timed out values are inserted at the "tail".
349 =item *
351 Explicitly flushed values are inserted at the "head".
353 =item *
355 ASCII art rocks.
357 =back
359 =head1 SECURITY CONSIDERATIONS
361 =head2 Authentication
363 There is no authentication.
365 The client/server protocol does not yet have any authentication mechanism. It
366 is likely that authentication and encryption will be added in a future version,
367 but for the time being it is the administrator's responsibility to secure the
368 traffic from/to the daemon!
370 It is highly recommended to install a packet filter or similar mechanism to
371 prevent unauthorized connections. Unless you have a dedicated VLAN or VPN for
372 this, using network sockets is probably a bad idea!
374 =head2 Authorization
376 There is minimal per-socket authorization.
378 Authorization is currently done on a per-socket basis. That means each socket
379 has a list of commands it will accept and it will accept. It will accept only
380 those commands explicitly listed but it will (currently) accept these commands
381 from anyone reaching the socket.
383 If the networking sockets are to be used, it is necessary to restrict the
384 accepted commands to those needed by external clients. If, for example,
385 external clients want to draw graphs of the cached data, they should only be
386 allowed to use the C<FLUSH> command.
388 =head2 Encryption
390 There is no encryption.
392 Again, this may be added in the future, but for the time being it is your job
393 to keep your private data private. Install a VPN or an encrypted tunnel if you
394 statistics are confidential!
396 =head2 Sanity checking
398 There is no sanity checking.
400 The daemon will blindly write to any file it gets told, so you really should
401 create a separate user just for this daemon. Also it does not do any sanity
402 checks, so if it gets told to write values for a time far in the future, your
403 files will be messed up good!
405 =head2 Conclusion
407 =over 4
409 =item *
411 Security is the job of the administrator.
413 =item *
415 We recommend to allow write access via UNIX domain sockets only.
417 =item *
419 You have been warned.
421 =back
423 =head1 PROTOCOL
425 The daemon communicates with clients using a line based ASCII protocol which is
426 easy to read and easy to type. This makes it easy for scripts to implement the
427 protocol and possible for users to use telnet to connect to the daemon
428 and test stuff "by hand".
430 The protocol is line based, this means that each record consists of one or more
431 lines. A line is terminated by the line feed character C<0x0A>, commonly
432 written as C<\n>. In the examples below, this character will be written as
433 C<E<lt>LFE<gt>> ("line feed").
435 After the connection has been established, the client is expected to send a
436 "command". A command consists of the command keyword, possibly some arguments,
437 and a terminating newline character. For a list of commands, see
438 L</"Valid Commands"> below.
440 Example:
442   FLUSH /tmp/foo.rrd<LF>
444 The daemon answers with a line consisting of a status code and a short status
445 message, separated by one or more space characters. A negative status code
446 signals an error, a positive status code or zero signal success. If the status
447 code is greater than zero, it indicates the number of lines that follow the
448 status line.
450 Examples:
452  0 Success<LF>
454  2 Two lines follow<LF>
455  This is the first line<LF>
456  And this is the second line<LF>
458 =head2 Valid Commands
460 The following commands are understood by the daemon:
462 =over 4
464 =item B<FLUSH> I<filename>
466 Causes the daemon to put I<filename> to the B<head> of the update queue
467 (possibly moving it there if the node is already enqueued). The answer will be
468 sent B<after> the node has been dequeued.
470 =item B<FLUSHALL>
472 Causes the daemon to start flushing ALL pending values to disk.  This
473 returns immediately, even though the writes may take a long time.
475 =item B<PENDING> I<filename>
477 Shows any "pending" updates for a file, in order.  The updates shown have
478 not yet been written to the underlying RRD file.
480 =item B<FORGET> I<filename>
482 Removes I<filename> from the cache.  Any pending updates B<WILL BE LOST>.
484 =item B<QUEUE>
486 Shows the files that are on the output queue.  Returns zero or more lines
487 in the following format, where E<lt>num_valsE<gt> is the number of values
488 to be written for the E<lt>fileE<gt>:
490     <num_vals> <file>
492 =item B<HELP> [I<command>]
494 Returns a short usage message. If no command is given, or I<command> is
495 B<HELP>, a list of commands supported by the daemon is returned. Otherwise a
496 short description, possibly containing a pointer to a manual page, is returned.
497 Obviously, this is meant for interactive usage and the format in which the
498 commands and usage summaries are returned is not well defined.
500 =item B<STATS>
502 Returns a list of metrics which can be used to measure the daemons performance
503 and check its status. For a description of the values returned, see
504 L</"Performance Values"> below.
506 The format in which the values are returned is similar to many other line based
507 protocols: Each value is printed on a separate line, each consisting of the
508 name of the value, a colon, one or more spaces and the actual value.
510 Example:
512  9 Statistics follow
513  QueueLength: 0
514  UpdatesReceived: 30
515  FlushesReceived: 2
516  UpdatesWritten: 13
517  DataSetsWritten: 390
518  TreeNodesNumber: 13
519  TreeDepth: 4
520  JournalBytes: 190
521  JournalRotate: 0
523 =item B<UPDATE> I<filename> I<values> [I<values> ...]
525 Adds more data to a filename. This is B<the> operation the daemon was designed
526 for, so describing the mechanism again is unnecessary. Read L</"HOW IT WORKS">
527 above for a detailed explanation.
529 Note that rrdcached only accepts absolute timestamps in the update values.
530 Updates strings like "N:1:2:3" are automatically converted to absolute
531 time by the RRD client library before sending to rrdcached.
533 =item B<WROTE> I<filename>
535 This command is written to the journal after a file is successfully
536 written out to disk.  It is used during journal replay to determine which
537 updates have already been applied.  It is I<only> valid in the journal; it
538 is not accepted from the other command channels.
540 =item B<BATCH>
542 This command initiates the bulk load of multiple commands.  This is
543 designed for installations with extremely high update rates, since it
544 permits more than one command to be issued per read() and write().
546 All commands are executed just as they would be if given individually,
547 except for output to the user.  Messages indicating success are
548 suppressed, and error messages are delayed until the client is finished.
550 Command processing is finished when the client sends a dot (".") on its
551 own line.  After the client has finished, the server responds with an
552 error count and the list of error messages (if any).  Each error messages
553 indicates the number of the command to which it corresponds, and the error
554 message itself.  The first user command after B<BATCH> is command number one.
556     client:  BATCH
557     server:  0 Go ahead.  End with dot '.' on its own line.
558     client:  UPDATE x.rrd 1223661439:1:2:3            <--- command #1
559     client:  UPDATE y.rrd 1223661440:3:4:5            <--- command #2
560     client:  and so on...
561     client:  .
562     server:  2 Errors
563     server:  1 message for command 1
564     server:  12 message for command 12
566 =item B<QUIT>
568 Disconnect from rrdcached.
570 =back
572 =head2 Performance Values
574 The following counters are returned by the B<STATS> command:
576 =over 4
578 =item B<QueueLength> I<(unsigned 64bit integer)>
580 Number of nodes currently enqueued in the update queue.
582 =item B<UpdatesReceived> I<(unsigned 64bit integer)>
584 Number of UPDATE commands received.
586 =item B<FlushesReceived> I<(unsigned 64bit integer)>
588 Number of FLUSH commands received.
590 =item B<UpdatesWritten> I<(unsigned 64bit integer)>
592 Total number of updates, i.E<nbsp>e. calls to C<rrd_update_r>, since the
593 daemon was started.
595 =item B<DataSetsWritten> I<(unsigned 64bit integer)>
597 Total number of "data sets" written to disk since the daemon was
598 started. A data set is one or more values passed to the B<UPDATE>
599 command. For example: C<1223661439:123:456> is one data set with two
600 values. The term "data set" is used to prevent confusion whether
601 individual values or groups of values are counted.
603 =item B<TreeNodesNumber> I<(unsigned 64bit integer)>
605 Number of nodes in the cache.
607 =item B<TreeDepth> I<(unsigned 64bit integer)>
609 Depth of the tree used for fast key lookup.
611 =item B<JournalBytes> I<(unsigned 64bit integer)>
613 Total number of bytes written to the journal since startup.
615 =item B<JournalRotate> I<(unsigned 64bit integer)>
617 Number of times the journal has been rotated since startup.
619 =back
621 =head1 SIGNALS
623 =over 4
625 =item SIGINT and SIGTERM
627 The daemon exits normally on receipt of either of these signals.  Pending
628 updates are handled in accordance with the B<-j> and B<-F> options.
630 =item SIGUSR1
632 The daemon exits AFTER flushing all updates out to disk.  This may take a
633 while.
635 =item SIGUSR2
637 The daemon exits immediately, without flushing updates out to disk.
638 Pending updates will be replayed from the journal when the daemon starts
639 up again.  B<WARNING: if journaling (-j) is NOT enabled, any pending
640 updates WILL BE LOST>.
642 =back
644 =head1 BUGS
646 No known bugs at the moment.
648 =head1 SEE ALSO
650 L<rrdtool>, L<rrdgraph>
652 =head1 AUTHOR
654 Florian Forster E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>
656 Both B<rrdcached> and this manual page have been written by Florian.
658 =head1 CONTRIBUTORS
660 kevin brintnall E<lt>kbrint@rufus.netE<gt>
662 =cut