X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdcached.pod;h=b01165e81437df6ffde8a41d1c4b7b8e8f3a8419;hp=09c89c3ed4384923be735768484d5c9f6e4d4e6e;hb=db9842391d7f238faf7b5ad1b01059115a4f2264;hpb=0f4b0029699613ec41194fe7696a6b10fdeb5c62

diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod
index 09c89c3..b01165e 100644
--- a/doc/rrdcached.pod
+++ b/doc/rrdcached.pod
@@ -6,7 +6,7 @@ rrdcached - Data caching daemon for rrdtool
 
 =head1 SYNOPSIS
 
-B<rrdcached> [B<-l> I<address>] [B<-w> I<timeout>] [B<-z> I<delay>] [B<-f> I<timeout>] [B<-j> I<dir>] [-F]
+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>]]
 
 =head1 DESCRIPTION
 
@@ -52,6 +52,11 @@ 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>
+
+Same as B<-l>, except creates a low-privilege socket.  See B<SECURITY
+CONSIDERATIONS> for more information.
+
 =item B<-w> I<timeout>
 
 Data is written to disk every I<timeout> seconds. If this option is not
@@ -120,6 +125,12 @@ used.
   updated by the daemon,  assuming the base directory
   "/tmp".
 
+=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 AFFECTED RRDTOOL COMMANDS
@@ -214,7 +225,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,15 +272,32 @@ ASCII art rocks.
 
 =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!>
+The client/server protocol does not have any authentication or
+authorization mechanism.  Therefore, take care to restrict which users can
+connect to the daemon.
+
+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>.
+
+For a multi-user environment where only certain users require read/write
+access, the recommended configuration uses two sockets as follows:
+
+=over
+
+=item B<-l> I</protected/dir/rrd.sock>
 
-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.
+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.
+
+=item B<-L> I<127.0.0.1>
+
+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.
+
+=back
 
 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
@@ -334,6 +363,15 @@ sent B<after> 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<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<HELP> [I<command>]
 
 Returns a short usage message. If no command is given, or I<command> is
@@ -378,6 +416,32 @@ written out to disk.  It is used during journal replay to determine which
 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 N:1:2:3            <--- command #1
+    client:  UPDATE y.rrd N: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
+
 =back
 
 =head2 Performance Values