B<rrdcached>
[B<-P>E<nbsp>I<permissions>]
[B<-l>E<nbsp>I<address>]
+[B<-s>E<nbsp>I<group>]
[B<-w>E<nbsp>I<timeout>]
[B<-z>E<nbsp>I<delay>]
[B<-f>E<nbsp>I<timeout>]
[-F]
[-g]
[B<-b>E<nbsp>I<base_dir>E<nbsp>[B<-B>]]
+[B<-a>E<nbsp>I<alloc_size>]
+[-O]
=head1 DESCRIPTION
Tells the daemon to bind to I<address> and accept incoming connections on that
socket. If I<address> begins with C<unix:>, everything following that prefix is
interpreted as the path to a UNIX domain socket. Otherwise the address or node
-name are resolved using getaddrinfo.
+name are resolved using C<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
+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.
If the B<-l> option is not specified the default address,
C<unix:/tmp/rrdcached.sock>, will be used.
+=item B<-s> I<group_name>|I<gid>
+
+Set the group permissions of a UNIX domain socket. The option accepts either
+a numeric group id or group name. That group will then have both read and write
+permissions (the socket will have file permissions 0750) for the socket and,
+therefore, is able to send commands to the daemon. This
+may be useful in cases where you cannot easily run all RRD processes with the same
+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) 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,
+use the system default.
+
+=item B<-m> I<mode>
+
+Set the file permissions of a UNIX domain socket. The option accepts an octal
+number representing the bit pattern for the mode (see L<chmod(1)> for
+details).
+
+Please note that not all systems honor this setting. On Linux, read/write
+permissions are required to connect to a UNIX socket. However, many
+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) 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,
+use the system default.
+
=item B<-P> I<command>[,I<command>[,...]]
Specifies the commands accepted via a network socket. This allows
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
+The B<-P> option affects the I<following> socket addresses (the following B<-l>
+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
sub-directories). This does B<NOT> detect symbolic links. Paths
containing C<../> will also be blocked.
+=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
+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
=item *
+first
+
+=item *
+
last
=item *
xport
+=item *
+
+create
+
=back
The B<update> command can send values to the daemon instead of writing them to
=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!
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.
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>.
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
=head1 CONTRIBUTORS
kevin brintnall E<lt>kbrint@rufus.netE<gt>
+Steve Shipway E<lt>steve@steveshipway.orgE<gt>
=cut
projects / rrdtool.git / blobdiff