fix rrd_getops use of external variables (optarg and friends) ... most

[rrdtool.git] / doc / rrdcached.pod

diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod
index a30f293..5113c2d 100644 (file)
--- a/doc/rrdcached.pod
+++ b/doc/rrdcached.pod
@@ -6,7 +6,17 @@ rrdcached - Data caching daemon for rrdtool
 
 =head1 SYNOPSIS
 
 
 =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<-l/-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
 
 
 =head1 DESCRIPTION
 


@@ -81,6 +91,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.
 
 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
 =item B<-j> I<dir>
 
 Write updates to a journal in I<dir>.  In the event of a program or system


@@ -107,6 +124,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.
 
 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
 =item B<-b> I<dir>
 
 The daemon will change into a specific directory at startup. All files passed


@@ -125,10 +146,23 @@ used.
   updated by the daemon,  assuming the base directory
   "/tmp".
 
   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>
 
 =item B<-B>
 

-Only permit writes into the base directory specified in B<-b>.  This does
-B<NOT> detect symbolic links.  Paths containing C<../> will also be blocked.
+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
 
 
 =back
 


@@ -172,7 +206,7 @@ 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
 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 it
+to the system logging daemon using L<syslog(3)>. The facility used is

 C<LOG_DAEMON>.
 
 =head1 HOW IT WORKS
 C<LOG_DAEMON>.
 
 =head1 HOW IT WORKS


@@ -362,6 +396,23 @@ 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.
 
 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
 =item B<HELP> [I<command>]
 
 Returns a short usage message. If no command is given, or I<command> is


@@ -399,6 +450,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.
 
 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
 =item B<WROTE> I<filename>
 
 This command is written to the journal after a file is successfully


@@ -406,6 +461,36 @@ 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.
 
 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
 =back
 
 =head2 Performance Values


@@ -433,10 +518,11 @@ daemon was started.
 
 =item B<DataSetsWritten> I<(unsigned 64bit integer)>
 
 
 =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)>
 
 
 =item B<TreeNodesNumber> I<(unsigned 64bit integer)>