X-Git-Url: https://git.octo.it/?a=blobdiff_plain;f=doc%2Frrdcached.pod;h=043e020a30760214da0130b3d3731ac1c5b84991;hb=6a0490ebd1433e810f3f68a2493207a8bd882314;hp=09c89c3ed4384923be735768484d5c9f6e4d4e6e;hpb=0f4b0029699613ec41194fe7696a6b10fdeb5c62;p=rrdtool.git diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod index 09c89c3..043e020 100644 --- a/doc/rrdcached.pod +++ b/doc/rrdcached.pod @@ -6,7 +6,18 @@ rrdcached - Data caching daemon for rrdtool =head1 SYNOPSIS -B [B<-l> I
] [B<-w> I] [B<-z> I] [B<-f> I] [B<-j> I] [-F] +B +[B<-P>EI] +[B<-l>EI
] +[B<-w>EI] +[B<-z>EI] +[B<-f>EI] +[B<-p>EI] +[B<-t>EI] +[B<-j>EI] +[-F] +[-g] +[B<-b>EIE[B<-B>]] =head1 DESCRIPTION @@ -18,7 +29,7 @@ work with up-to-date data. The daemon was written with big setups in mind. Those setups usually run into IOErelated problems sooner or later for reasons that are beyond the scope -of this document. Check the wiki at the RRDTool homepage for details. Also +of this document. Check the wiki at the RRDtool homepage for details. Also check L below before using this daemon! A detailed description of how the daemon operates can be found in the L section below. @@ -38,7 +49,9 @@ For network sockets, a port may be specified by using the form CI
B<]:>I>. If the address is an IPv4 address or a fully qualified domain name (i.Ee. the address contains at least one dot (C<.>)), the square brackets can be omitted, resulting in the (simpler) -CB<:>I> pattern.. The default port is B<42217/udp>. +CB<:>I> pattern. The default port is B<42217/udp>. If you +specify a network socket, it is mandatory to read the +L section. The following formats are accepted. Please note that the address of the UNIX domain socket B start with a slash in the second case! @@ -52,6 +65,41 @@ domain socket B start with a slash in the second case! If the B<-l> option is not specified the default address, C, will be used. +=item B<-P> I[,I[,...]] + +Specifies the commands accepted via a network socket. This allows +administrators of I to control the actions accepted from various +sources. + +The arguments given to the B<-P> option is a comma separated list of commands. +For example, to allow the C and C commands one could specify: + + rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS + +The B<-P> option effects the I socket addresses (the following B<-l> +options). In the following example, only the IPv4 network socket (address +C<10.0.0.1>) will be restricted to the C and C 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 +L below. There are two minor special exceptions: + +=over 4 + +=item * + +The C and C commands are always allowed. + +=item * + +If the C command is accepted, the B<.>Ecommand will automatically +be accepted, too. + +=back + +Please also read L below. + =item B<-w> I Data is written to disk every I seconds. If this option is not @@ -76,6 +124,13 @@ cases. This timeout defaults to 3600Eseconds. Sets the name and location of the PID-file. If not specified, the default, C/run/rrdcached.pid> will be used. +=item B<-t> I + +Specifies the number of threads used for writing RRD files. The default +isE4. 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 throughput. + =item B<-j> I Write updates to a journal in I. In the event of a program or system @@ -102,6 +157,10 @@ To disable fast shutdown, use the B<-F> option. ALWAYS flush all updates to the RRD data files when the daemon is shut down, regardless of journal setting. +=item B<-g> + +Run in the foreground. The daemon will not fork(). + =item B<-b> I The daemon will change into a specific directory at startup. All files passed @@ -120,6 +179,24 @@ used. updated by the daemon, assuming the base directory "/tmp". +B The paths up to and including the base directory B +symbolic links. In other words, if the base directory is +specified as: + + -b /base/dir/somewhere + +... then B of the following should be symbolic links: + + /base + /base/dir + /base/dir/somewhere + +=item B<-B> + +Only permit writes into the base directory specified in B<-b> (and any +sub-directories). This does B detect symbolic links. Paths +containing C<../> will also be blocked. + =back =head1 AFFECTED RRDTOOL COMMANDS @@ -162,7 +239,7 @@ The daemon reports errors in one of two ways: During startup, error messages are printed to C. One of the steps when starting up is to fork to the background and closing C - 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 L. The facility used it +to the system logging daemon using L. The facility used is C. =head1 HOW IT WORKS @@ -214,7 +291,8 @@ to disk. +---+----+---+ +------+-----+ +---+----+---+ ! File: foo ! ! File: bar ! ! File: qux ! ! First: 101 ! ! First: 119 ! ! First: 180 ! - ! Next: ---+--->! Next: ---+---> ... --->! Next: - ! + ! Next:&bar -+--->! Next:&... -+---> ... --->! Next:NULL ! + | Prev:NULL !<---+-Prev:&foo !<--- ... ----+-Prev: &... ! +============+ +============+ +============+ ! Time: 100 ! ! Time: 120 ! ! Time: 180 ! ! Value: 10 ! ! Value: 0.1 ! ! Value: 2,2 ! @@ -260,28 +338,68 @@ ASCII art rocks. =head1 SECURITY CONSIDERATIONS -This daemon is meant to improve IOEperformance for setups with thousands -of RRDEfile to be updated. So security measures built into the daemon can -be summarized easily: B +=head2 Authentication + +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! + +=head2 Authorization + +There is minimal per-socket authorization. -There is no authentication and authorization, so B will have to take care -that only authorized clients can talk to the daemon. Since we assume that graph -collection is done on a dedicated machine, i.Ee. the box doesn't do -anything else and especially does not have any interactive logins other than -root, a UNIX domain socket should take care of that. +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 you (want to) use the network capability, i.Ee. let the daemon bind to -an IPv4 or IPv6 socket, it is B 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! +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 C command. + +=head2 Encryption + +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! + +=head2 Sanity checking + +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! +=head2 Conclusion + +=over 4 + +=item * + +Security is the job of the administrator. + +=item * + +We recommend to allow write access via UNIX domain sockets only. + +=item * + You have been warned. +=back + =head1 PROTOCOL The daemon communicates with clients using a line based ASCII protocol which is @@ -334,6 +452,23 @@ sent B the node has been dequeued. Causes the daemon to start flushing ALL pending values to disk. This returns immediately, even though the writes may take a long time. +=item B I + +Shows any "pending" updates for a file, in order. The updates shown have +not yet been written to the underlying RRD file. + +=item B I + +Removes I from the cache. Any pending updates B. + +=item B + +Shows the files that are on the output queue. Returns zero or more lines +in the following format, where Enum_valsE is the number of values +to be written for the EfileE: + + + =item B [I] Returns a short usage message. If no command is given, or I is @@ -371,6 +506,10 @@ Adds more data to a filename. This is B operation the daemon was designed for, so describing the mechanism again is unnecessary. Read L above for a detailed explanation. +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 rrdcached. + =item B I This command is written to the journal after a file is successfully @@ -378,6 +517,36 @@ written out to disk. It is used during journal replay to determine which updates have already been applied. It is I valid in the journal; it is not accepted from the other command channels. +=item B + +This command initiates the bulk load of multiple commands. This is +designed for installations with extremely high update rates, since it +permits more than one command to be issued per read() and write(). + +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 corresponds, and the error +message itself. The first user command after B is command number one. + + client: BATCH + server: 0 Go ahead. End with dot '.' on its own line. + client: UPDATE x.rrd 1223661439:1:2:3 <--- command #1 + client: UPDATE y.rrd 1223661440:3:4:5 <--- command #2 + client: and so on... + client: . + server: 2 Errors + server: 1 message for command 1 + server: 12 message for command 12 + +=item B + +Disconnect from rrdcached. + =back =head2 Performance Values @@ -405,10 +574,11 @@ daemon was started. =item B I<(unsigned 64bit integer)> -Total number of "data sets" written to disk since the daemon was started. A -data set is one or more values passed to the B command. For example: -C 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. +Total number of "data sets" written to disk since the daemon was +started. A data set is one or more values passed to the B +command. For example: C<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. =item B I<(unsigned 64bit integer)>