X-Git-Url: https://git.octo.it/?p=rrdtool.git;a=blobdiff_plain;f=doc%2Frrdcached.pod;h=7c0b30c6e2b33dd6fb12fd6c40748188a89c4cc0;hp=0fa12caca9f945b99f1b584df6cb1f9d979b6a44;hb=afcd0eb5b0e71964e9c5691b4a9794c2f4059928;hpb=4be0f003298ec0cb9a251abfeb67d8f439b6d1f3 diff --git a/doc/rrdcached.pod b/doc/rrdcached.pod index 0fa12ca..7c0b30c 100644 --- a/doc/rrdcached.pod +++ b/doc/rrdcached.pod @@ -9,6 +9,7 @@ rrdcached - Data caching daemon for rrdtool B [B<-P>EI] [B<-l>EI
] +[B<-s>EI] [B<-w>EI] [B<-z>EI] [B<-f>EI] @@ -18,6 +19,8 @@ B [-F] [-g] [B<-b>EIE[B<-B>]] +[B<-a>EI] +[-O] =head1 DESCRIPTION @@ -43,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. @@ -65,6 +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|I + +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 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 @@ -76,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 @@ -197,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 @@ -232,6 +286,10 @@ info =item * +first + +=item * + last =item * @@ -246,6 +304,10 @@ update xport +=item * + +create + =back The B command can send values to the daemon instead of writing them to @@ -360,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! @@ -385,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. @@ -477,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. @@ -537,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 @@ -658,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