X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdcached.pod;h=7c0b30c6e2b33dd6fb12fd6c40748188a89c4cc0;hp=57eb6553720428b9959ed2481342eb426b020a99;hb=afcd0eb5b0e71964e9c5691b4a9794c2f4059928;hpb=9e2eb0abd095264f584490ede57ae5afe8beb748

diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod
index 57eb655..7c0b30c 100644
--- a/doc/rrdcached.pod
+++ b/doc/rrdcached.pod
@@ -19,7 +19,8 @@ B<rrdcached>
 [-F]
 [-g]
 [B<-b>E<nbsp>I<base_dir>E<nbsp>[B<-B>]]
-[B<-m>E<nbsp>I<alloc_size>]
+[B<-a>E<nbsp>I<alloc_size>]
+[-O]
 
 =head1 DESCRIPTION
 
@@ -51,7 +52,7 @@ 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
+C<I<address>B<:>I<port>> pattern. The default port is B<42217/tcp>. If you
 specify a network socket, it is mandatory to read the
 L</"SECURITY CONSIDERATIONS"> section.
 
@@ -78,7 +79,8 @@ user privileges (e.g. graph generating CGI scripts that typically run in the
 permission context of the web server).
 
 This option affects the I<following> UNIX socket addresses (the following
-B<-l> options), i.e., you may specify different settings for different
+B<-l> options) or the default socket (if no B<-l> options have been
+specified), i.e., you may specify different settings for different
 sockets.
 
 The default is not to change ownership or permissions of the socket and, thus,
@@ -96,7 +98,8 @@ BSD-derived systems ignore permissions for UNIX sockets. See L<unix(7)> for
 details.
 
 This option affects the I<following> UNIX socket addresses (the following
-B<-l> options), i.e., you may specify different settings for different
+B<-l> options) or the default socket (if no B<-l> options have been
+specified), i.e., you may specify different settings for different
 sockets.
 
 The default is not to change ownership or permissions of the socket and, thus,
@@ -114,7 +117,8 @@ For example, to allow the C<FLUSH> and C<PENDING> commands one could specify:
   rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS
 
 The B<-P> option affects the I<following> socket addresses (the following B<-l>
-options). In the following example, only the IPv4 network socket (address
+options) or the default socket (if no B<-l> options have been
+specified). 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
@@ -234,7 +238,7 @@ 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.
 
-=item B<-m> I<alloc_size>
+=item B<-a> I<alloc_size>
 
 Allocate value pointers in chunks of I<alloc_size>.  This may improve CPU
 utilization on machines with slow C<realloc()> implementations, in
@@ -242,6 +246,11 @@ exchange for slightly higher memory utilization.  The default isE<nbsp>1.
 Do not set this more than the B<-w> value divided by your average RRD step
 size.
 
+=item B<-O> 
+
+Preven the CREATE command from overwriting existing files, even when it is
+instructed to do so.  This is for added security.
+
 =back
 
 =head1 AFFECTED RRDTOOL COMMANDS
@@ -277,6 +286,10 @@ info
 
 =item *
 
+first
+
+=item *
+
 last
 
 =item *
@@ -291,6 +304,10 @@ update
 
 xport
 
+=item *
+
+create
+
 =back
 
 The B<update> command can send values to the daemon instead of writing them to
@@ -405,14 +422,15 @@ ASCII art rocks.
 
 =head2 Authentication
 
-There is no authentication.
+If your rrdtool installation was built without libwrap there is no form of 
+authentication for clients connecting to the rrdcache daemon!
 
-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!
+If your rrdtool installation was built with libwrap then you can use
+hosts_access to restrict client access to the rrdcache daemon (rrdcached).  For more
+information on how to use hosts_access to restrict access to the rrdcache
+daemon you should read the hosts_access(5) man pages. 
 
-It is highly recommended to install a packet filter or similar mechanism to
+It is still 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!
 
@@ -430,6 +448,8 @@ 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.
 
+Authorization does not work when rrcached is socket-activated by systemd. 
+
 =head2 Encryption
 
 There is no encryption.
@@ -522,6 +542,13 @@ returns immediately, even though the writes may take a long time.
 Shows any "pending" updates for a file, in order.  The updates shown have
 not yet been written to the underlying RRD file.
 
+=item B<FETCH> I<filename> I<CF> [I<start> [I<end>]]
+
+Calls C<rrd_fetch> with the specified arguments and returns the result in text
+form. If necessary, the file is flushed to disk first. The client side function
+C<rrdc_fetch> (declared in C<rrd_client.h>) parses the output and behaves just
+like C<rrd_fetch_r> for easy integration of remote queries.
+
 =item B<FORGET> I<filename>
 
 Removes I<filename> from the cache.  Any pending updates B<WILL BE LOST>.
@@ -582,6 +609,34 @@ 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<FIRST> I<filename> [I<rranum>]
+
+Return the timestamp for the first CDP in the specified RRA.  Default is to 
+use RRA zero if none is specified.
+
+=item B<LAST> I<filename> 
+
+Return the timestamp for the last update to the specified RRD. Note that the
+cache is I<not> flushed before checking, as the client is expected to request
+this separately if it is required.
+
+=item B<INFO> I<filename> 
+
+Return the configuration information for the specified RRD. Note that the
+cache is I<not> flushed before checking, as the client is expected to request
+this separately if it is required.
+
+The information is returned, one item per line, with the format:
+
+ I<keyname> I<type> I<value>
+
+=item B<CREATE> I<filename> [-s I<stepsize>] [-b I<begintime>] [-O] I<DSdefinitions> ... I<RRAdefinitions> ...
+
+This will create the RRD file according to the supplied parameters, provided
+the parameters are valid, and (if the -O option is given or if the rrdcached
+was started with the -O flag) the specified I<filename> does not already
+exist.
+
 =item B<BATCH>
 
 This command initiates the bulk load of multiple commands.  This is
@@ -703,6 +758,7 @@ Both B<rrdcached> and this manual page have been written by Florian.
 =head1 CONTRIBUTORS
 
 kevin brintnall E<lt>kbrint@rufus.netE<gt>
+Steve Shipway E<lt>steve@steveshipway.orgE<gt> 
 
 =cut