X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdcached.pod;h=460899c0df22086c3a913e7d783006000af87947;hp=fd565239845be1bca72f1e6636022ff451f20ffa;hb=45fb79dd5d7871bc7a80821ad198bc70d43fdf2e;hpb=273a1b83ea752d385159b02977e5157a9fe09aa1

diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod
index fd56523..460899c 100644
--- a/doc/rrdcached.pod
+++ b/doc/rrdcached.pod
@@ -6,7 +6,18 @@ rrdcached - Data caching daemon for rrdtool
 
 =head1 SYNOPSIS
 
-B<rrdcached> [B<-l/-L> I<address>] [B<-w> I<timeout>] [B<-z> I<delay>] [B<-f> I<timeout>] [B<-j> I<dir>] [-F] [B<-b> I<dir> [B<-B>]]
+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
 
@@ -38,7 +49,9 @@ 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>.
+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!
@@ -52,10 +65,40 @@ domain socket B<must> start with a slash in the second case!
 If the B<-l> option is not specified the default address,
 C<unix:/tmp/rrdcached.sock>, will be used.
 
-=item B<-L> I<address>
+=item B<-P> I<command>[,I<command>[,...]]
 
-Same as B<-l>, except creates a low-privilege socket.  See B<SECURITY
-CONSIDERATIONS> for more information.
+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>
 
@@ -81,6 +124,13 @@ cases. This timeout defaults to 3600E<nbsp>seconds.
 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
@@ -107,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<dir>
 
 The daemon will change into a specific directory at startup. All files passed
@@ -125,6 +179,18 @@ used.
   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
@@ -272,45 +338,68 @@ ASCII art rocks.
 
 =head1 SECURITY CONSIDERATIONS
 
-The client/server protocol does not have any authentication or
-authorization mechanism.  Therefore, take care to restrict which users can
-connect to the daemon.
+=head2 Authentication
 
-Control sockets are divided into high-privilege (B<-l>) and low-privilege
-(B<-L>) sockets.  High-privilege sockets accept all commands, whereas
-low-privilege sockets accept only B<FLUSH>, B<STATS>, and B<HELP>.
+There is no authentication.
 
-For a multi-user environment where only certain users require read/write
-access, the recommended configuration uses two sockets as follows:
+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!
 
-=over
+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!
 
-=item B<-l> I</protected/dir/rrd.sock>
+=head2 Authorization
 
-Create a high-privilege unix-domain socket.  This should be protected with
-the same Unix permissions that are used to protect the RRD files.  Updates
-should be directed to this socket.
+There is minimal per-socket authorization.
 
-=item B<-L> I<127.0.0.1>
+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.
 
-Create a low-privilege TCP socket listening on localhost.  All users on
-the local system may use this to trigger FLUSH of individual files.  Users
-with read-only access should be directed to this 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.
 
-=back
+=head2 Encryption
+
+There is no 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!
+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
@@ -372,6 +461,14 @@ not yet been written to the underlying RRD file.
 
 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
@@ -409,6 +506,10 @@ Adds more data to a filename. This is B<the> operation the daemon was designed
 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
@@ -434,14 +535,18 @@ 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 N:1:2:3            <--- command #1
-    client:  UPDATE y.rrd N:3:4:5            <--- command #2
+    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
@@ -469,10 +574,11 @@ daemon was started.
 
 =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)>