doc/rrdcached.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 rrdcached - Data caching daemon for rrdtool
   6
   7 =head1 SYNOPSIS
   8
   9 B<rrdcached>
  10 [B<-l/-L>E<nbsp>I<address>]
  11 [B<-w>E<nbsp>I<timeout>]
  12 [B<-z>E<nbsp>I<delay>]
  13 [B<-f>E<nbsp>I<timeout>]
  14 [B<-p>E<nbsp>I<pid_file>]
  15 [B<-t>E<nbsp>I<write_threads>]
  16 [B<-j>E<nbsp>I<journal_dir>]
  17 [-F]
  18 [-g]
  19 [B<-b>E<nbsp>I<base_dir>E<nbsp>[B<-B>]]
  20
  21 =head1 DESCRIPTION
  22
  23 B<rrdcached> is a daemon that receives updates to existing RRD files,
  24 accumulates them and, if enough have been received or a defined time has
  25 passed, writes the updates to the RRD file. A I<flush> command may be used to
  26 force writing of values to disk, so that graphing facilities and similar can
  27 work with up-to-date data.
  28
  29 The daemon was written with big setups in mind. Those setups usually run into
  30 IOE<nbsp>related problems sooner or later for reasons that are beyond the scope
  31 of this document. Check the wiki at the RRDTool homepage for details. Also
  32 check L<SECURITY CONSIDERATIONS> below before using this daemon! A detailed
  33 description of how the daemon operates can be found in the L<HOW IT WORKS>
  34 section below.
  35
  36 =head1 OPTIONS
  37
  38 =over 4
  39
  40 =item B<-l> I<address>
  41
  42 Tells the daemon to bind to I<address> and accept incoming connections on that
  43 socket. If I<address> begins with C<unix:>, everything following that prefix is
  44 interpreted as the path to a UNIX domain socket. Otherwise the address or node
  45 name are resolved using L<getaddrinfo>.
  46
  47 For network sockets, a port may be specified by using the form
  48 C<B<[>I<address>B<]:>I<port>>. If the address is an IPv4 address or a fully
  49 qualified domain name (i.E<nbsp>e. the address contains at least one dot
  50 (C<.>)), the square brackets can be omitted, resulting in the (simpler)
  51 C<I<address>B<:>I<port>> pattern.. The default port is B<42217/udp>.
  52
  53 The following formats are accepted. Please note that the address of the UNIX
  54 domain socket B<must> start with a slash in the second case!
  55
  56    unix:</path/to/unix.sock>
  57    /<path/to/unix.sock>
  58    <hostname-or-ip>
  59    [<hostname-or-ip>]:<port>
  60    <hostname-or-ipv4>:<port>
  61
  62 If the B<-l> option is not specified the default address,
  63 C<unix:/tmp/rrdcached.sock>, will be used.
  64
  65 =item B<-L> I<address>
  66
  67 Same as B<-l>, except creates a low-privilege socket.  See B<SECURITY
  68 CONSIDERATIONS> for more information.
  69
  70 =item B<-w> I<timeout>
  71
  72 Data is written to disk every I<timeout> seconds. If this option is not
  73 specified the default interval of 300E<nbsp>seconds will be used.
  74
  75 =item B<-z> I<delay>
  76
  77 If specified, rrdcached will delay writing of each RRD for a random number
  78 of seconds in the rangeE<nbsp>[0,I<delay>).  This will avoid too many
  79 writes being queued simultaneously.  This value should be no greater than
  80 the value specified in B<-w>.  By default, there is no delay.
  81
  82 =item B<-f> I<timeout>
  83
  84 Every I<timeout> seconds the entire cache is searched for old values which are
  85 written to disk. This only concerns files to which updates have stopped, so
  86 setting this to a high value, such as 3600E<nbsp>seconds, is acceptable in most
  87 cases. This timeout defaults to 3600E<nbsp>seconds.
  88
  89 =item B<-p> I<file>
  90
  91 Sets the name and location of the PID-file. If not specified, the default,
  92 C<I<$localststedir>/run/rrdcached.pid> will be used.
  93
  94 =item B<-t> I<write_threads>
  95
  96 Specifies the number of threads used for writing RRD files.  The default
  97 isE<nbsp>4.  Increasing this number will allow rrdcached to have more
  98 simultaneous I/O requests into the kernel.  This may allow the kernel to
  99 re-order disk writes, resulting in better disk throughput.
 100
 101 =item B<-j> I<dir>
 102
 103 Write updates to a journal in I<dir>.  In the event of a program or system
 104 crash, this will allow the daemon to write any updates that were pending
 105 at the time of the crash.
 106
 107 On startup, the daemon will check for journal files in this directory.  If
 108 found, all updates therein will be read into memory before the daemon
 109 starts accepting new connections.
 110
 111 The journal will be rotated with the same frequency as the flush timer
 112 given by B<-f>.
 113
 114 When journaling is enabled, the daemon will use a fast shutdown procedure.
 115 Rather than flushing all files to disk, it will make sure the journal is
 116 properly written and exit immediately.  Although the RRD data files are
 117 not fully up-to-date, no information is lost; all pending updates will be
 118 replayed from the journal next time the daemon starts up.
 119
 120 To disable fast shutdown, use the B<-F> option.
 121
 122 =item B<-F>
 123
 124 ALWAYS flush all updates to the RRD data files when the daemon is shut
 125 down, regardless of journal setting.
 126
 127 =item B<-g>
 128
 129 Run in the foreground.  The daemon will not fork().
 130
 131 =item B<-b> I<dir>
 132
 133 The daemon will change into a specific directory at startup. All files passed
 134 to the daemon, that are specified by a B<relative> path, will be interpreted
 135 to be relative to this directory. If not given the default, C</tmp>, will be
 136 used.
 137
 138   +------------------------+------------------------+
 139   ! Command line           ! File updated           !
 140   +------------------------+------------------------+
 141   ! foo.rrd                ! /tmp/foo.rrd           !
 142   ! foo/bar.rrd            ! /tmp/foo/bar.rrd       !
 143   ! /var/lib/rrd/foo.rrd   ! /var/lib/rrd/foo.rrd   !
 144   +------------------------+------------------------+
 145   Paths given on the command  line and paths actually
 146   updated by the daemon,  assuming the base directory
 147   "/tmp".
 148
 149 B<WARNING:> The paths up to and including the base directory B<MUST NOT BE>
 150 symbolic links.  In other words, if the base directory is
 151 specified as:
 152
 153     -b /base/dir/somewhere
 154
 155 ... then B<NONE> of the following should be symbolic links:
 156
 157     /base
 158     /base/dir
 159     /base/dir/somewhere
 160
 161 =item B<-B>
 162
 163 Only permit writes into the base directory specified in B<-b> (and any
 164 sub-directories).  This does B<NOT> detect symbolic links.  Paths
 165 containing C<../> will also be blocked.
 166
 167 =back
 168
 169 =head1 AFFECTED RRDTOOL COMMANDS
 170
 171 The following commands may be made aware of the B<rrdcached> using the command
 172 line argument B<--daemon> or the environment variable B<RRDCACHED_ADDRESS>:
 173
 174 =over 4
 175
 176 =item B<dump>
 177
 178 =item B<fetch>
 179
 180 =item B<flush>
 181
 182 =item B<graph>
 183
 184 =item B<graphv>
 185
 186 =item B<info>
 187
 188 =item B<last>
 189
 190 =item B<lastupdate>
 191
 192 =item B<update>
 193
 194 =item B<xport>
 195
 196 =back
 197
 198 The B<update> command can send values to the daemon instead of writing them to
 199 the disk itself. All other commands can send a B<FLUSH> command (see below) to
 200 the daemon before accessing the files, so they work with up-to-date data even
 201 if the cache timeout is large.
 202
 203 =head1 ERROR REPORTING
 204
 205 The daemon reports errors in one of two ways: During startup, error messages
 206 are printed to C<STDERR>. One of the steps when starting up is to fork to the
 207 background and closing C<STDERR> - after this writing directly to the user is
 208 no longer possible. Once this has happened, the daemon will send log messages
 209 to the system logging daemon using L<syslog(3)>. The facility used is
 210 C<LOG_DAEMON>.
 211
 212 =head1 HOW IT WORKS
 213
 214 When receiving an update, B<rrdcached> does not write to disk but looks for an
 215 entry for that file in its internal tree. If not found, an entry is created
 216 including the current time (called "First" in the diagram below). This time is
 217 B<not> the time specified on the command line but the time the operating system
 218 considers to be "now". The value and time of the value (called "Time" in the
 219 diagram below) are appended to the tree node.
 220
 221 When appending a value to a tree node, it is checked whether it's time to write
 222 the values to disk. Values are written to disk if
 223 S<C<now() - First E<gt>= timeout>>, where C<timeout> is the timeout specified
 224 using the B<-w> option, see L<OPTIONS>. If the values are "old enough" they
 225 will be enqueued in the "update queue", i.E<nbsp>e. they will be appended to
 226 the linked list shown below.  Because the tree nodes and the elements of the
 227 linked list are the same data structures in memory, any update to a file that
 228 has already been enqueued will be written with the next write to the RRD file,
 229 too.
 230
 231 A separate "update thread" constantly dequeues the first element in the update
 232 queue and writes all its values to the appropriate file. So as long as the
 233 update queue is not empty files are written at the highest possible rate.
 234
 235 Since the timeout of files is checked only when new values are added to the
 236 file, "dead" files, i.E<nbsp>e. files that are not updated anymore, would never
 237 be written to disk. Therefore, every now and then, controlled by the B<-f>
 238 option, the entire tree is walked and all "old" values are enqueued. Since this
 239 only affects "dead" files and walking the tree is relatively expensive, you
 240 should set the "flush interval" to a reasonably high value. The default is
 241 3600E<nbsp>seconds (one hour).
 242
 243 The downside of caching values is that they won't show up in graphs generated
 244 from the RRDE<nbsp>files. To get around this, the daemon provides the "flush
 245 command" to flush specific files. This means that the file is inserted at the
 246 B<head> of the update queue or moved there if it is already enqueued. The flush
 247 command will return only after the file's pending updates have been written
 248 to disk.
 249
 250  +------+   +------+                               +------+
 251  ! head !   ! root !                               ! tail !
 252  +---+--+   +---+--+                               +---+--+
 253      !         /\                                      !
 254      !        /  \                                     !
 255      !       /\  /\                                    !
 256      !      /\/\ \ `----------------- ... --------,    !
 257      V     /      `-------,                       !    V
 258  +---+----+---+    +------+-----+             +---+----+---+
 259  ! File:  foo !    ! File:  bar !             ! File:  qux !
 260  ! First: 101 !    ! First: 119 !             ! First: 180 !
 261  ! Next:&bar -+--->! Next:&... -+---> ... --->! Next:NULL  !
 262  | Prev:NULL  !<---+-Prev:&foo  !<--- ... ----+-Prev: &... !
 263  +============+    +============+             +============+
 264  ! Time:  100 !    ! Time:  120 !             ! Time:  180 !
 265  ! Value:  10 !    ! Value: 0.1 !             ! Value: 2,2 !
 266  +------------+    +------------+             +------------+
 267  ! Time:  110 !    ! Time:  130 !             ! Time:  190 !
 268  ! Value:  26 !    ! Value: 0.1 !             ! Value: 7,3 !
 269  +------------+    +------------+             +------------+
 270  :            :    :            :             :            :
 271  +------------+    +------------+             +------------+
 272  ! Time:  230 !    ! Time:  250 !             ! Time:  310 !
 273  ! Value:  42 !    ! Value: 0.2 !             ! Value: 1,2 !
 274  +------------+    +------------+             +------------+
 275
 276 The above diagram demonstrates:
 277
 278 =over
 279
 280 =item *
 281
 282 Files/values are stored in a (balanced) tree.
 283
 284 =item *
 285
 286 Tree nodes and entries in the update queue are the same data structure.
 287
 288 =item *
 289
 290 The local time ("First") and the time specified in updates ("Time") may differ.
 291
 292 =item *
 293
 294 Timed out values are inserted at the "tail".
 295
 296 =item *
 297
 298 Explicitly flushed values are inserted at the "head".
 299
 300 =item *
 301
 302 ASCII art rocks.
 303
 304 =back
 305
 306 =head1 SECURITY CONSIDERATIONS
 307
 308 The client/server protocol does not have any authentication or
 309 authorization mechanism.  Therefore, take care to restrict which users can
 310 connect to the daemon.
 311
 312 Control sockets are divided into high-privilege (B<-l>) and low-privilege
 313 (B<-L>) sockets.  High-privilege sockets accept all commands, whereas
 314 low-privilege sockets accept only B<FLUSH>, B<STATS>, and B<HELP>.
 315
 316 For a multi-user environment where only certain users require read/write
 317 access, the recommended configuration uses two sockets as follows:
 318
 319 =over
 320
 321 =item B<-l> I</protected/dir/rrd.sock>
 322
 323 Create a high-privilege unix-domain socket.  This should be protected with
 324 the same Unix permissions that are used to protect the RRD files.  Updates
 325 should be directed to this socket.
 326
 327 =item B<-L> I<127.0.0.1>
 328
 329 Create a low-privilege TCP socket listening on localhost.  All users on
 330 the local system may use this to trigger FLUSH of individual files.  Users
 331 with read-only access should be directed to this socket.
 332
 333 =back
 334
 335 If you (want to) use the network capability, i.E<nbsp>e. let the daemon bind to
 336 an IPv4 or IPv6 socket, it is B<your> job to install a packet filter or similar
 337 mechanism to prevent unauthorized connections. Unless you have a dedicated VLAN
 338 or VPN for this, using the network option is probably a bad idea!
 339
 340 The daemon will blindly write to any file it gets told, so you really should
 341 create a separate user just for this daemon. Also it does not do any sanity
 342 checks, so if it gets told to write values for a time far in the future, your
 343 files will be messed up good!
 344
 345 You have been warned.
 346
 347 =head1 PROTOCOL
 348
 349 The daemon communicates with clients using a line based ASCII protocol which is
 350 easy to read and easy to type. This makes it easy for scripts to implement the
 351 protocol and possible for users to use L<telnet> to connect to the daemon
 352 and test stuff "by hand".
 353
 354 The protocol is line based, this means that each record consists of one or more
 355 lines. A line is terminated by the line feed character C<0x0A>, commonly
 356 written as C<\n>. In the examples below, this character will be written as
 357 C<E<lt>LFE<gt>> ("line feed").
 358
 359 After the connection has been established, the client is expected to send a
 360 "command". A command consists of the command keyword, possibly some arguments,
 361 and a terminating newline character. For a list of commands, see
 362 L<Valid Commands> below.
 363
 364 Example:
 365
 366   FLUSH /tmp/foo.rrd<LF>
 367
 368 The daemon answers with a line consisting of a status code and a short status
 369 message, separated by one or more space characters. A negative status code
 370 signals an error, a positive status code or zero signal success. If the status
 371 code is greater than zero, it indicates the number of lines that follow the
 372 status line.
 373
 374 Examples:
 375
 376  0 Success<LF>
 377
 378  2 Two lines follow<LF>
 379  This is the first line<LF>
 380  And this is the second line<LF>
 381
 382 =head2 Valid Commands
 383
 384 The following commands are understood by the daemon:
 385
 386 =over 4
 387
 388 =item B<FLUSH> I<filename>
 389
 390 Causes the daemon to put I<filename> to the B<head> of the update queue
 391 (possibly moving it there if the node is already enqueued). The answer will be
 392 sent B<after> the node has been dequeued.
 393
 394 =item B<FLUSHALL>
 395
 396 Causes the daemon to start flushing ALL pending values to disk.  This
 397 returns immediately, even though the writes may take a long time.
 398
 399 =item B<PENDING> I<filename>
 400
 401 Shows any "pending" updates for a file, in order.  The updates shown have
 402 not yet been written to the underlying RRD file.
 403
 404 =item B<FORGET> I<filename>
 405
 406 Removes I<filename> from the cache.  Any pending updates B<WILL BE LOST>.
 407
 408 =item B<QUEUE>
 409
 410 Shows the files that are on the output queue.  Returns zero or more lines
 411 in the following format, where E<lt>num_valsE<gt> is the number of values
 412 to be written for the E<lt>fileE<gt>:
 413
 414     <num_vals> <file>
 415
 416 =item B<HELP> [I<command>]
 417
 418 Returns a short usage message. If no command is given, or I<command> is
 419 B<HELP>, a list of commands supported by the daemon is returned. Otherwise a
 420 short description, possibly containing a pointer to a manual page, is returned.
 421 Obviously, this is meant for interactive usage and the format in which the
 422 commands and usage summaries are returned is not well defined.
 423
 424 =item B<STATS>
 425
 426 Returns a list of metrics which can be used to measure the daemons performance
 427 and check its status. For a description of the values returned, see
 428 L<Performance Values> below.
 429
 430 The format in which the values are returned is similar to many other line based
 431 protocols: Each value is printed on a separate line, each consisting of the
 432 name of the value, a colon, one or more spaces and the actual value.
 433
 434 Example:
 435
 436  9 Statistics follow
 437  QueueLength: 0
 438  UpdatesReceived: 30
 439  FlushesReceived: 2
 440  UpdatesWritten: 13
 441  DataSetsWritten: 390
 442  TreeNodesNumber: 13
 443  TreeDepth: 4
 444  JournalBytes: 190
 445  JournalRotate: 0
 446
 447 =item B<UPDATE> I<filename> I<values> [I<values> ...]
 448
 449 Adds more data to a filename. This is B<the> operation the daemon was designed
 450 for, so describing the mechanism again is unnecessary. Read L<HOW IT WORKS>
 451 above for a detailed explanation.
 452
 453 Note that rrdcached only accepts absolute timestamps in the update values.
 454 Updates strings like "N:1:2:3" are automatically converted to absolute
 455 time by the RRD client library before sending to rrdcached.
 456
 457 =item B<WROTE> I<filename>
 458
 459 This command is written to the journal after a file is successfully
 460 written out to disk.  It is used during journal replay to determine which
 461 updates have already been applied.  It is I<only> valid in the journal; it
 462 is not accepted from the other command channels.
 463
 464 =item B<BATCH>
 465
 466 This command initiates the bulk load of multiple commands.  This is
 467 designed for installations with extremely high update rates, since it
 468 permits more than one command to be issued per read() and write().
 469
 470 All commands are executed just as they would be if given individually,
 471 except for output to the user.  Messages indicating success are
 472 suppressed, and error messages are delayed until the client is finished.
 473
 474 Command processing is finished when the client sends a dot (".") on its
 475 own line.  After the client has finished, the server responds with an
 476 error count and the list of error messages (if any).  Each error messages
 477 indicates the number of the command to which it corresponds, and the error
 478 message itself.  The first user command after B<BATCH> is command number one.
 479
 480     client:  BATCH
 481     server:  0 Go ahead.  End with dot '.' on its own line.
 482     client:  UPDATE x.rrd 1223661439:1:2:3            <--- command #1
 483     client:  UPDATE y.rrd 1223661440:3:4:5            <--- command #2
 484     client:  and so on...
 485     client:  .
 486     server:  2 Errors
 487     server:  1 message for command 1
 488     server:  12 message for command 12
 489
 490 =item B<QUIT>
 491
 492 Disconnect from rrdcached.
 493
 494 =back
 495
 496 =head2 Performance Values
 497
 498 The following counters are returned by the B<STATS> command:
 499
 500 =over 4
 501
 502 =item B<QueueLength> I<(unsigned 64bit integer)>
 503
 504 Number of nodes currently enqueued in the update queue.
 505
 506 =item B<UpdatesReceived> I<(unsigned 64bit integer)>
 507
 508 Number of UPDATE commands received.
 509
 510 =item B<FlushesReceived> I<(unsigned 64bit integer)>
 511
 512 Number of FLUSH commands received.
 513
 514 =item B<UpdatesWritten> I<(unsigned 64bit integer)>
 515
 516 Total number of updates, i.E<nbsp>e. calls to C<rrd_update_r>, since the
 517 daemon was started.
 518
 519 =item B<DataSetsWritten> I<(unsigned 64bit integer)>
 520
 521 Total number of "data sets" written to disk since the daemon was
 522 started. A data set is one or more values passed to the B<UPDATE>
 523 command. For example: C<1223661439:123:456> is one data set with two
 524 values. The term "data set" is used to prevent confusion whether
 525 individual values or groups of values are counted.
 526
 527 =item B<TreeNodesNumber> I<(unsigned 64bit integer)>
 528
 529 Number of nodes in the cache.
 530
 531 =item B<TreeDepth> I<(unsigned 64bit integer)>
 532
 533 Depth of the tree used for fast key lookup.
 534
 535 =item B<JournalBytes> I<(unsigned 64bit integer)>
 536
 537 Total number of bytes written to the journal since startup.
 538
 539 =item B<JournalRotate> I<(unsigned 64bit integer)>
 540
 541 Number of times the journal has been rotated since startup.
 542
 543 =back
 544
 545 =head1 SIGNALS
 546
 547 =over 4
 548
 549 =item SIGINT and SIGTERM
 550
 551 The daemon exits normally on receipt of either of these signals.  Pending
 552 updates are handled in accordance with the B<-j> and B<-F> options.
 553
 554 =item SIGUSR1
 555
 556 The daemon exits AFTER flushing all updates out to disk.  This may take a
 557 while.
 558
 559 =item SIGUSR2
 560
 561 The daemon exits immediately, without flushing updates out to disk.
 562 Pending updates will be replayed from the journal when the daemon starts
 563 up again.  B<WARNING: if journaling (-j) is NOT enabled, any pending
 564 updates WILL BE LOST>.
 565
 566 =back
 567
 568 =head1 BUGS
 569
 570 No known bugs at the moment.
 571
 572 =head1 SEE ALSO
 573
 574 L<rrdtool>, L<rrdgraph>
 575
 576 =head1 AUTHOR
 577
 578 B<rrdcached> and this manual page have been written by Florian Forster
 579 E<lt>octoE<nbsp>atE<nbsp>verplant.orgE<gt>.
 580
 581 =head1 CONTRIBUTORS
 582
 583 kevin brintnall E<lt>kbrint@rufus.netE<gt>
 584
 585 =cut
 586