![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdcached.txt b/doc/rrdcached.txt
index 32d3674e88fa98cff6d2d2f279d2d7f04da50203..fdacd186880328a23acaf738bed73492233e0f1e 100644 (file)
--- a/doc/rrdcached.txt
+++ b/doc/rrdcached.txt
rrdcached - Data caching daemon for rrdtool
S\bSY\bYN\bNO\bOP\bPS\bSI\bIS\bS
- r\brr\brd\bdc\bca\bac\bch\bhe\bed\bd [-\b-l\bl/\b/-\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] [-\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] [-g]
- [-\b-b\bb _\bb_\ba_\bs_\be_\b__\bd_\bi_\br [-\b-B\bB]]
+ 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]
+ [-\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]
+ [-g] [-\b-b\bb _\bb_\ba_\bs_\be_\b__\bd_\bi_\br [-\b-B\bB]]
D\bDE\bES\bSC\bCR\bRI\bIP\bPT\bTI\bIO\bON\bN
r\brr\brd\bdc\bca\bac\bch\bhe\bed\bd is a daemon that receives updates to existing RRD files,
The daemon was written with big setups in mind. Those setups usually
run into IO related problems sooner or later for reasons that are
- beyond the scope of this document. Check the wiki at the RRDTool home-
- page for details. Also check "SECURITY CONSIDERATIONS" below before
+ beyond the scope of this document. Check the wiki at the RRDTool
+ homepage for details. Also check "SECURITY CONSIDERATIONS" below before
using this daemon! A detailed description of how the daemon operates
can be found in the "HOW IT WORKS" section below.
O\bOP\bPT\bTI\bIO\bON\bNS\bS
-\b-l\bl _\ba_\bd_\bd_\br_\be_\bs_\bs
Tells the daemon to bind to _\ba_\bd_\bd_\br_\be_\bs_\bs and accept incoming connections
- on that socket. If _\ba_\bd_\bd_\br_\be_\bs_\bs begins with "unix:", everything follow-
- ing that prefix is interpreted as the path to a UNIX domain socket.
- Otherwise the address or node name are resolved using getaddrinfo.
+ on that socket. If _\ba_\bd_\bd_\br_\be_\bs_\bs begins with "unix:", everything
+ following that prefix is interpreted as the path to a UNIX domain
+ socket. Otherwise the address or node name are resolved using
+ getaddrinfo.
For network sockets, a port may be specified by using the form
- "[address]:port". If the address is an IPv4 address or a fully
+ "[\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
qualified domain name (i. e. the address contains at least one dot
- (".")), the square brackets can be omitted, resulting in the (sim-
- pler) "address:port" pattern.. The default port is 4\b42\b22\b21\b17\b7/\b/u\bud\bdp\bp.
+ (".")), the square brackets can be omitted, resulting in the
+ (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
+ you specify a network socket, it is mandatory to read the "SECURITY
+ CONSIDERATIONS" section.
The following formats are accepted. Please note that the address of
the UNIX domain socket m\bmu\bus\bst\bt start with a slash in the second case!
If the -\b-l\bl option is not specified the default address,
"unix:/tmp/rrdcached.sock", will be used.
- -\b-L\bL _\ba_\bd_\bd_\br_\be_\bs_\bs
- Same as -\b-l\bl, except creates a low-privilege socket. See S\bSE\bEC\bCU\bUR\bRI\bIT\bTY\bY
- C\bCO\bON\bNS\bSI\bID\bDE\bER\bRA\bAT\bTI\bIO\bON\bNS\bS for more information.
+ -\b-P\bP _\bc_\bo_\bm_\bm_\ba_\bn_\bd[,_\bc_\bo_\bm_\bm_\ba_\bn_\bd[,...]]
+ Specifies the commands accepted via a network socket. This allows
+ administrators of _\bR_\bR_\bD_\bC_\ba_\bc_\bh_\be_\bD to control the actions accepted from
+ various sources.
+
+ The arguments given to the -\b-P\bP option is a comma separated list of
+ commands. For example, to allow the "FLUSH" and "PENDING" commands
+ one could specify:
+
+ rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS
+
+ The -\b-P\bP option effects the _\bf_\bo_\bl_\bl_\bo_\bw_\bi_\bn_\bg socket addresses (the following
+ -\b-l\bl options). In the following example, only the IPv4 network socket
+ (address 10.0.0.1) will be restricted to the "FLUSH" and "PENDING"
+ commands:
+
+ rrdcached -l unix:/some/path -P FLUSH,PENDING -l 10.0.0.1
+
+ A complete list of available commands can be found in the section
+ "Valid Commands" below. There are two minor special exceptions:
+
+ · The "HELP" and "QUIT" commands are always allowed.
+
+ · If the "BATCH" command is accepted, the .\b. command will
+ automatically be accepted, too.
+
+ Please also read "SECURITY CONSIDERATIONS" below.
-\b-w\bw _\bt_\bi_\bm_\be_\bo_\bu_\bt
Data is written to disk every _\bt_\bi_\bm_\be_\bo_\bu_\bt seconds. If this option is
-\b-p\bp _\bf_\bi_\bl_\be
Sets the name and location of the PID-file. If not specified, the
- default, "$localststedir/run/rrdcached.pid" will be used.
+ 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.
-\b-t\bt _\bw_\br_\bi_\bt_\be_\b__\bt_\bh_\br_\be_\ba_\bd_\bs
Specifies the number of threads used for writing RRD files. The
default is 4. Increasing this number will allow rrdcached to have
more simultaneous I/O requests into the kernel. This may allow the
- kernel to re-order disk writes, resulting in better disk through-
- put.
+ kernel to re-order disk writes, resulting in better disk
+ throughput.
-\b-j\bj _\bd_\bi_\br
Write updates to a journal in _\bd_\bi_\br. In the event of a program or
system crash, this will allow the daemon to write any updates that
were pending at the time of the crash.
- On startup, the daemon will check for journal files in this direc-
- tory. If found, all updates therein will be read into memory
+ On startup, the daemon will check for journal files in this
+ directory. If found, all updates therein will be read into memory
before the daemon starts accepting new connections.
The journal will be rotated with the same frequency as the flush
When journaling is enabled, the daemon will use a fast shutdown
procedure. Rather than flushing all files to disk, it will make
sure the journal is properly written and exit immediately.
- Although the RRD data files are not fully up-to-date, no informa-
- tion is lost; all pending updates will be replayed from the journal
- next time the daemon starts up.
+ Although the RRD data files are not fully up-to-date, no
+ information is lost; all pending updates will be replayed from the
+ journal next time the daemon starts up.
To disable fast shutdown, use the -\b-F\bF option.
"/tmp".
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
- B\bBE\bE symbolic links. In other words, if the base directory is speci-
- fied as:
+ B\bBE\bE symbolic links. In other words, if the base directory is
+ specified as:
-b /base/dir/somewhere
/base/dir/somewhere
-\b-B\bB Only permit writes into the base directory specified in -\b-b\bb (and any
- sub-directories). This does N\bNO\bOT\bT detect symbolic links. Paths con-
- taining "../" will also be blocked.
+ sub-directories). This does N\bNO\bOT\bT detect symbolic links. Paths
+ containing "../" will also be blocked.
A\bAF\bFF\bFE\bEC\bCT\bTE\bED\bD R\bRR\bRD\bDT\bTO\bOO\bOL\bL C\bCO\bOM\bMM\bMA\bAN\bND\bDS\bS
The following commands may be made aware of the r\brr\brd\bdc\bca\bac\bch\bhe\bed\bd using the
- command line argument -\b--\b-d\bda\bae\bem\bmo\bon\bn or the environment variable R\bRR\bRD\bD-\b-
- C\bCA\bAC\bCH\bHE\bED\bD_\b_A\bAD\bDD\bDR\bRE\bES\bSS\bS:
+ command line argument -\b--\b-d\bda\bae\bem\bmo\bon\bn or the environment variable
+ R\bRR\bRD\bDC\bCA\bAC\bCH\bHE\bED\bD_\b_A\bAD\bDD\bDR\bRE\bES\bSS\bS:
d\bdu\bum\bmp\bp
f\bfe\bet\btc\bch\bh
messages are printed to "STDERR". One of the steps when starting up is
to fork to the background and closing "STDERR" - after this writing
directly to the user is no longer possible. Once this has happened, the
- daemon will send log messages to the system logging daemon using _\bs_\by_\bs_\b-
- _\bl_\bo_\bg(3). The facility used is "LOG_DAEMON".
+ daemon will send log messages to the system logging daemon using
+ _\bs_\by_\bs_\bl_\bo_\bg(3). The facility used is "LOG_DAEMON".
H\bHO\bOW\bW I\bIT\bT W\bWO\bOR\bRK\bKS\bS
When receiving an update, r\brr\brd\bdc\bca\bac\bch\bhe\bed\bd does not write to disk but looks
never be written to disk. Therefore, every now and then, controlled by
the -\b-f\bf 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 reason-
- ably high value. The default is 3600 seconds (one hour).
+ relatively expensive, you should set the "flush interval" to a
+ reasonably high value. The default is 3600 seconds (one hour).
The downside of caching values is that they won't show up in graphs
generated from the RRD files. To get around this, the daemon provides
The above diagram demonstrates:
- · Files/values are stored in a (balanced) tree.
+ · Files/values are stored in a (balanced) tree.
- · Tree nodes and entries in the update queue are the same data struc-
- ture.
+ · Tree nodes and entries in the update queue are the same data
+ structure.
- · The local time ("First") and the time specified in updates ("Time")
+ · The local time ("First") and the time specified in updates ("Time")
may differ.
- · Timed out values are inserted at the "tail".
+ · Timed out values are inserted at the "tail".
- · Explicitly flushed values are inserted at the "head".
+ · Explicitly flushed values are inserted at the "head".
- · ASCII art rocks.
+ · ASCII art rocks.
S\bSE\bEC\bCU\bUR\bRI\bIT\bTY\bY C\bCO\bON\bNS\bSI\bID\bDE\bER\bRA\bAT\bTI\bIO\bON\bNS\bS
- The client/server protocol does not have any authentication or autho-
- rization mechanism. Therefore, take care to restrict which users can
- connect to the daemon.
-
- Control sockets are divided into high-privilege (-\b-l\bl) and low-privilege
- (-\b-L\bL) sockets. High-privilege sockets accept all commands, whereas low-
- privilege sockets accept only F\bFL\bLU\bUS\bSH\bH, S\bST\bTA\bAT\bTS\bS, and H\bHE\bEL\bLP\bP.
-
- For a multi-user environment where only certain users require
- read/write access, the recommended configuration uses two sockets as
- follows:
-
- -\b-l\bl _\b/_\bp_\br_\bo_\bt_\be_\bc_\bt_\be_\bd_\b/_\bd_\bi_\br_\b/_\br_\br_\bd_\b._\bs_\bo_\bc_\bk
- Create a high-privilege unix-domain socket. This should be pro-
- tected with the same Unix permissions that are used to protect the
- RRD files. Updates should be directed to this socket.
-
- -\b-L\bL _\b1_\b2_\b7_\b._\b0_\b._\b0_\b._\b1
- Create a low-privilege TCP socket listening on localhost. All
- users on the local system may use this to trigger FLUSH of individ-
- ual files. Users with read-only access should be directed to this
- socket.
-
- If you (want to) use the network capability, i. e. let the daemon bind
- to an IPv4 or IPv6 socket, it is y\byo\bou\bur\br 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!
+ A\bAu\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn
+ There is no authentication.
+
+ The client/server protocol does not yet have any authentication
+ mechanism. It is likely that authentication and encryption will be
+ added in a future version, but for the time being it is the
+ administrator's responsibility to secure the traffic from/to the
+ daemon!
+
+ It is highly recommended to install a packet filter or similar
+ mechanism to prevent unauthorized connections. Unless you have a
+ dedicated VLAN or VPN for this, using network sockets is probably a bad
+ idea!
+
+ A\bAu\but\bth\bho\bor\bri\biz\bza\bat\bti\bio\bon\bn
+ There is minimal per-socket authorization.
+
+ Authorization is currently done on a per-socket basis. That means each
+ socket has a list of commands it will accept and it will accept. It
+ will accept only those commands explicitly listed but it will
+ (currently) accept these commands from anyone reaching the socket.
+
+ If the networking sockets are to be used, it is necessary to restrict
+ the accepted commands to those needed by external clients. If, for
+ example, external clients want to draw graphs of the cached data, they
+ should only be allowed to use the "FLUSH" command.
+
+ E\bEn\bnc\bcr\bry\byp\bpt\bti\bio\bon\bn
+ There is no encryption.
+
+ Again, this may be added in the future, but for the time being it is
+ your job to keep your private data private. Install a VPN or an
+ encrypted tunnel if you statistics are confidential!
+
+ S\bSa\ban\bni\bit\bty\by c\bch\bhe\bec\bck\bki\bin\bng\bg
+ There is no sanity checking.
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.
+ C\bCo\bon\bnc\bcl\blu\bus\bsi\bio\bon\bn
+ · Security is the job of the administrator.
+
+ · We recommend to allow write access via UNIX domain sockets only.
+
+ · You have been warned.
P\bPR\bRO\bOT\bTO\bOC\bCO\bOL\bL
The daemon communicates with clients using a line based ASCII protocol
which is easy to read and easy to type. This makes it easy for scripts
- to implement the protocol and possible for users to use telnet to con-
- nect to the daemon and test stuff "by hand".
+ to implement the protocol and possible for users to use telnet to
+ connect to the daemon and test stuff "by hand".
The protocol is line based, this means that each record consists of one
or more lines. A line is terminated by the line feed character 0x0A,
After the connection has been established, the client is expected to
send a "command". A command consists of the command keyword, possibly
- some arguments, and a terminating newline character. For a list of com-
- mands, see "Valid Commands" below.
+ some arguments, and a terminating newline character. For a list of
+ commands, see "Valid Commands" below.
Example:
The daemon answers with a line consisting of a status code and a short
status message, separated by one or more space characters. A negative
status code signals an error, a positive status code or zero signal
- success. If the status code is greater than zero, it indicates the num-
- ber of lines that follow the status line.
+ success. If the status code is greater than zero, it indicates the
+ number of lines that follow the status line.
Examples:
This is the first line<LF>
And this is the second line<LF>
- V\bVa\bal\bli\bid\bd C\bCo\bom\bmm\bma\ban\bnd\bds\bs
-
+ V\bVa\bal\bli\bid\bd C\bCo\bom\bmm\bma\ban\bnd\bds\bs
The following commands are understood by the daemon:
F\bFL\bLU\bUS\bSH\bH _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
Note that rrdcached only accepts absolute timestamps in the update
values. Updates strings like "N:1:2:3" are automatically converted
- to absolute time by the RRD client library before sending to rrd-
- cached.
+ to absolute time by the RRD client library before sending to
+ rrdcached.
W\bWR\bRO\bOT\bTE\bE _\bf_\bi_\bl_\be_\bn_\ba_\bm_\be
This command is written to the journal after a file is successfully
it permits more than one command to be issued per _\br_\be_\ba_\bd_\b(_\b) and
_\bw_\br_\bi_\bt_\be_\b(_\b).
- All commands are executed just as they would be if given individu-
- ally, except for output to the user. Messages indicating success
- are suppressed, and error messages are delayed until the client is
- finished.
+ All commands are executed just as they would be if given
+ individually, except for output to the user. Messages indicating
+ success are suppressed, and error messages are delayed until the
+ client is finished.
Command processing is finished when the client sends a dot (".") on
its own line. After the client has finished, the server responds
with an error count and the list of error messages (if any). Each
- error messages indicates the number of the command to which it cor-
- responds, and the error message itself. The first user command
+ error messages indicates the number of the command to which it
+ corresponds, and the error message itself. The first user command
after B\bBA\bAT\bTC\bCH\bH is command number one.
client: BATCH
Q\bQU\bUI\bIT\bT
Disconnect from rrdcached.
- P\bPe\ber\brf\bfo\bor\brm\bma\ban\bnc\bce\be V\bVa\bal\blu\bue\bes\bs
-
+ P\bPe\ber\brf\bfo\bor\brm\bma\ban\bnc\bce\be V\bVa\bal\blu\bue\bes\bs
The following counters are returned by the S\bST\bTA\bAT\bTS\bS command:
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)
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)
Total number of "data sets" written to disk since the daemon was
- started. A data set is one or more values passed to the U\bUP\bPD\bDA\bAT\bTE\bE com-
- mand. For example: "1223661439:123:456" is one data set with two
+ started. A data set is one or more values passed to the U\bUP\bPD\bDA\bAT\bTE\bE
+ command. For example: "1223661439:123:456" is one data set with two
values. The term "data set" is used to prevent confusion whether
individual values or groups of values are counted.
-1.3.99909060808 2009-04-09 RRDCACHED(1)
+1.3.999 2009-09-24 RRDCACHED(1)