=head1 SYNOPSIS
-B<rrdcached> [B<-l> I<address>] [B<-w> I<timeout>] [B<-z> I<delay>] [B<-f> I<timeout>] [B<-j> I<dir>]
+B<rrdcached>
+[B<-P>E<nbsp>I<permissions>]
+[B<-l>E<nbsp>I<address>]
+[B<-w>E<nbsp>I<timeout>]
+[B<-z>E<nbsp>I<delay>]
+[B<-f>E<nbsp>I<timeout>]
+[B<-p>E<nbsp>I<pid_file>]
+[B<-t>E<nbsp>I<write_threads>]
+[B<-j>E<nbsp>I<journal_dir>]
+[-F]
+[-g]
+[B<-b>E<nbsp>I<base_dir>E<nbsp>[B<-B>]]
=head1 DESCRIPTION
The daemon was written with big setups in mind. Those setups usually run into
IOE<nbsp>related 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<SECURITY CONSIDERATIONS> below before using this daemon! A detailed
description of how the daemon operates can be found in the L<HOW IT WORKS>
section below.
interpreted as the path to a UNIX domain socket. Otherwise the address or node
name are resolved using L<getaddrinfo>.
+For network sockets, a port may be specified by using the form
+C<B<[>I<address>B<]:>I<port>>. If the address is an IPv4 address or a fully
+qualified domain name (i.E<nbsp>e. the address contains at least one dot
+(C<.>)), the square brackets can be omitted, resulting in the (simpler)
+C<I<address>B<:>I<port>> pattern. The default port is B<42217/udp>. If you
+specify a network socket, it is mandatory to read the
+L</"SECURITY CONSIDERATIONS"> section.
+
+The following formats are accepted. Please note that the address of the UNIX
+domain socket B<must> start with a slash in the second case!
+
+ unix:</path/to/unix.sock>
+ /<path/to/unix.sock>
+ <hostname-or-ip>
+ [<hostname-or-ip>]:<port>
+ <hostname-or-ipv4>:<port>
+
If the B<-l> option is not specified the default address,
C<unix:/tmp/rrdcached.sock>, will be used.
+=item B<-P> I<command>[,I<command>[,...]]
+
+Specifies the commands accepted via a network socket. This allows
+administrators of I<RRDCacheD> 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<FLUSH> and C<PENDING> commands one could specify:
+
+ rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS
+
+The B<-P> option effects the I<following> 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<FLUSH> and C<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
+L</"Valid Commands"> below. There are two minor special exceptions:
+
+=over 4
+
+=item *
+
+The C<HELP> and C<QUIT> commands are always allowed.
+
+=item *
+
+If the C<BATCH> command is accepted, the B<.>E<nbsp>command will automatically
+be accepted, too.
+
+=back
+
+Please also read L</"SECURITY CONSIDERATIONS"> below.
+
=item B<-w> I<timeout>
Data is written to disk every I<timeout> seconds. If this option is not
Sets the name and location of the PID-file. If not specified, the default,
C<I<$localststedir>/run/rrdcached.pid> will be used.
+=item B<-t> I<write_threads>
+
+Specifies the number of threads used for writing RRD files. The default
+isE<nbsp>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 throughput.
+
=item B<-j> I<dir>
Write updates to a journal in I<dir>. In the event of a program or system
starts accepting new connections.
The journal will be rotated with the same frequency as the flush timer
-given by B<-f>. On clean shutdown, the journal files are removed.
+given by B<-f>.
+
+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 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> option.
+
+=item B<-F>
+
+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<dir>
updated by the daemon, assuming the base directory
"/tmp".
+B<WARNING:> The paths up to and including the base directory B<MUST NOT BE>
+symbolic links. In other words, if the base directory is
+specified as:
+
+ -b /base/dir/somewhere
+
+... then B<NONE> 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<NOT> detect symbolic links. Paths
+containing C<../> will also be blocked.
+
=back
-=head1 EFFECTED RRDTOOL COMMANDS
+=head1 AFFECTED RRDTOOL COMMANDS
The following commands may be made aware of the B<rrdcached> using the command
line argument B<--daemon> or the environment variable B<RRDCACHED_ADDRESS>:
the daemon before accessing the files, so they work with up-to-date data even
if the cache timeout is large.
+=head1 ERROR REPORTING
+
+The daemon reports errors in one of two ways: During startup, error messages
+are printed to C<STDERR>. One of the steps when starting up is to fork to the
+background and closing C<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 L<syslog(3)>. The facility used is
+C<LOG_DAEMON>.
+
=head1 HOW IT WORKS
When receiving an update, B<rrdcached> does not write to disk but looks for an
from the RRDE<nbsp>files. To get around this, the daemon provides the "flush
command" to flush specific files. This means that the file is inserted at the
B<head> of the update queue or moved there if it is already enqueued. The flush
-command will return after the update thread has dequeued the file, so there is
-a good chance that the file has been updated by the time the client receives
-the response from the daemon, but there is no guarantee.
+command will return only after the file's pending updates have been written
+to disk.
+------+ +------+ +------+
! head ! ! root ! ! tail !
+---+----+---+ +------+-----+ +---+----+---+
! 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 !
=head1 SECURITY CONSIDERATIONS
-This daemon is meant to improve IOE<nbsp>performance for setups with thousands
-of RRDE<nbsp>file to be updated. So security measures built into the daemon can
-be summarized easily: B<There is no security built in!>
+=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.
+
+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 C<FLUSH> command.
-There is no authentication and authorization, so B<you> 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.E<nbsp>e. 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.
+=head2 Encryption
-If you (want to) use the network capability, i.E<nbsp>e. let the daemon bind to
-an IPv4 or IPv6 socket, it is B<your> 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!
+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
(possibly moving it there if the node is already enqueued). The answer will be
sent B<after> the node has been dequeued.
+=item B<FLUSHALL>
+
+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<PENDING> I<filename>
+
+Shows any "pending" updates for a file, in order. The updates shown have
+not yet been written to the underlying RRD file.
+
+=item B<FORGET> I<filename>
+
+Removes I<filename> from the cache. Any pending updates B<WILL BE LOST>.
+
+=item B<QUEUE>
+
+Shows the files that are on the output queue. Returns zero or more lines
+in the following format, where E<lt>num_valsE<gt> is the number of values
+to be written for the E<lt>fileE<gt>:
+
+ <num_vals> <file>
+
=item B<HELP> [I<command>]
Returns a short usage message. If no command is given, or I<command> is
for, so describing the mechanism again is unnecessary. Read L<HOW IT WORKS>
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<WROTE> I<filename>
This command is written to the journal after a file is successfully
updates have already been applied. It is I<only> valid in the journal; it
is not accepted from the other command channels.
+=item B<BATCH>
+
+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<BATCH> 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<QUIT>
+
+Disconnect from rrdcached.
+
=back
=head2 Performance Values
=item B<DataSetsWritten> 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<UPDATE> command. For example:
-C<N: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.
+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<UPDATE>
+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<TreeNodesNumber> I<(unsigned 64bit integer)>
=back
+=head1 SIGNALS
+
+=over 4
+
+=item SIGINT and SIGTERM
+
+The daemon exits normally on receipt of either of these signals. Pending
+updates are handled in accordance with the B<-j> and B<-F> options.
+
+=item SIGUSR1
+
+The daemon exits AFTER flushing all updates out to disk. This may take a
+while.
+
+=item SIGUSR2
+
+The daemon exits immediately, without flushing updates out to disk.
+Pending updates will be replayed from the journal when the daemon starts
+up again. B<WARNING: if journaling (-j) is NOT enabled, any pending
+updates WILL BE LOST>.
+
+=back
+
=head1 BUGS
No known bugs at the moment.
projects / rrdtool.git / blobdiff