X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdcached.pod;h=7c0b30c6e2b33dd6fb12fd6c40748188a89c4cc0;hp=22a74e9e1344a6afad6f2b42fb0f40fbc1f91774;hb=afcd0eb5b0e71964e9c5691b4a9794c2f4059928;hpb=732528deae5d3d282ef07e2fbb9372f2270c3668 diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod index 22a74e9..7c0b30c 100644 --- a/doc/rrdcached.pod +++ b/doc/rrdcached.pod @@ -19,6 +19,8 @@ B [-F] [-g] [B<-b>EIE[B<-B>]] +[B<-a>EI] +[-O] =head1 DESCRIPTION @@ -44,13 +46,13 @@ section below. Tells the daemon to bind to I
and accept incoming connections on that socket. If I
begins with C, 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. For network sockets, a port may be specified by using the form CI
B<]:>I>. If the address is an IPv4 address or a fully qualified domain name (i.Ee. the address contains at least one dot (C<.>)), the square brackets can be omitted, resulting in the (simpler) -CB<:>I> pattern. The default port is B<42217/udp>. If you +CB<:>I> pattern. The default port is B<42217/tcp>. If you specify a network socket, it is mandatory to read the L section. @@ -66,15 +68,43 @@ domain socket B start with a slash in the second case! If the B<-l> option is not specified the default address, C, will be used. -=item B<-s> I +=item B<-s> I|I -Set the group permissions of the UNIX domain socket. The option accepts either +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 to the socket and therefore able to send commands to the daemon. This +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 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 + +Set the file permissions of a UNIX domain socket. The option accepts an octal +number representing the bit pattern for the mode (see L 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 for +details. + +This option affects the I 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[,I[,...]] Specifies the commands accepted via a network socket. This allows @@ -86,8 +116,9 @@ For example, to allow the C and C commands one could specify: rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS -The B<-P> option effects the I socket addresses (the following B<-l> -options). In the following example, only the IPv4 network socket (address +The B<-P> option affects the I 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 and C commands: rrdcached -l unix:/some/path -P FLUSH,PENDING -l 10.0.0.1 @@ -207,6 +238,19 @@ Only permit writes into the base directory specified in B<-b> (and any sub-directories). This does B detect symbolic links. Paths containing C<../> will also be blocked. +=item B<-a> I + +Allocate value pointers in chunks of I. This may improve CPU +utilization on machines with slow C implementations, in +exchange for slightly higher memory utilization. The default isE1. +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 @@ -242,6 +286,10 @@ info =item * +first + +=item * + last =item * @@ -256,6 +304,10 @@ update xport +=item * + +create + =back The B command can send values to the daemon instead of writing them to @@ -370,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! @@ -395,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 command. +Authorization does not work when rrcached is socket-activated by systemd. + =head2 Encryption There is no encryption. @@ -487,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 I I [I [I]] + +Calls C 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 (declared in C) parses the output and behaves just +like C for easy integration of remote queries. + =item B I Removes I from the cache. Any pending updates B. @@ -547,6 +609,34 @@ written out to disk. It is used during journal replay to determine which updates have already been applied. It is I valid in the journal; it is not accepted from the other command channels. +=item B I [I] + +Return the timestamp for the first CDP in the specified RRA. Default is to +use RRA zero if none is specified. + +=item B I + +Return the timestamp for the last update to the specified RRD. Note that the +cache is I flushed before checking, as the client is expected to request +this separately if it is required. + +=item B I + +Return the configuration information for the specified RRD. Note that the +cache is I 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 I I + +=item B I [-s I] [-b I] [-O] I ... I ... + +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 does not already +exist. + =item B This command initiates the bulk load of multiple commands. This is @@ -668,6 +758,7 @@ Both B and this manual page have been written by Florian. =head1 CONTRIBUTORS kevin brintnall Ekbrint@rufus.netE +Steve Shipway Esteve@steveshipway.orgE =cut