![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdcached.1 b/doc/rrdcached.1
index 2a111870cee0a5c655bd48ed221ab5072be33315..8c2324e8d9fa2bf90609e37ba13f6ce43a0a1509 100644 (file)
--- a/doc/rrdcached.1
+++ b/doc/rrdcached.1
-.\" Automatically generated by Pod::Man 2.1801 (Pod::Simple 3.08)
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
.\" ========================================================================
.\"
.IX Title "RRDCACHED 1"
-.TH RRDCACHED 1 "2009-09-24" "1.3.999" "rrdtool"
+.TH RRDCACHED 1 "2011-03-15" "1.4.7" "rrdtool"
.\" For nroff, turn off justification. Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
\&\fBrrdcached\fR
[\fB\-P\fR\ \fIpermissions\fR]
[\fB\-l\fR\ \fIaddress\fR]
+[\fB\-s\fR\ \fIgroup\fR]
[\fB\-w\fR\ \fItimeout\fR]
[\fB\-z\fR\ \fIdelay\fR]
[\fB\-f\fR\ \fItimeout\fR]
.PP
The daemon was written with big setups in mind. Those setups usually run into
\&\s-1IO\s0\ related problems sooner or later for reasons that are beyond the scope
-of this document. Check the wiki at the RRDTool homepage for details. Also
+of this document. Check the wiki at the RRDtool homepage for details. Also
check \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" below before using this daemon! A detailed
description of how the daemon operates can be found in the \*(L"\s-1HOW\s0 \s-1IT\s0 \s-1WORKS\s0\*(R"
section below.
Tells the daemon to bind to \fIaddress\fR and accept incoming connections on that
socket. If \fIaddress\fR begins with \f(CW\*(C`unix:\*(C'\fR, everything following that prefix is
interpreted as the path to a \s-1UNIX\s0 domain socket. Otherwise the address or node
-name are resolved using getaddrinfo.
+name are resolved using \f(CW\*(C`getaddrinfo()\*(C'\fR.
.Sp
For network sockets, a port may be specified by using the form
\&\f(CW\*(C`\f(CB[\f(CW\f(CIaddress\f(CW\f(CB]:\f(CW\f(CIport\f(CW\*(C'\fR. If the address is an IPv4 address or a fully
qualified domain name (i.\ e. the address contains at least one dot
(\f(CW\*(C`.\*(C'\fR)), the square brackets can be omitted, resulting in the (simpler)
-\&\f(CW\*(C`\f(CIaddress\f(CW\f(CB:\f(CW\f(CIport\f(CW\*(C'\fR pattern. The default port is \fB42217/udp\fR. If you
+\&\f(CW\*(C`\f(CIaddress\f(CW\f(CB:\f(CW\f(CIport\f(CW\*(C'\fR pattern. The default port is \fB42217/tcp\fR. If you
specify a network socket, it is mandatory to read the
\&\*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" section.
.Sp
.Sp
If the \fB\-l\fR option is not specified the default address,
\&\f(CW\*(C`unix:/tmp/rrdcached.sock\*(C'\fR, will be used.
+.IP "\fB\-s\fR \fIgroup_name\fR|\fIgid\fR" 4
+.IX Item "-s group_name|gid"
+Set the group permissions of a \s-1UNIX\s0 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 \s-1RRD\s0 processes with the same
+user privileges (e.g. graph generating \s-1CGI\s0 scripts that typically run in the
+permission context of the web server).
+.Sp
+This option affects the \fIfollowing\fR \s-1UNIX\s0 socket addresses (the following
+\&\fB\-l\fR options) or the default socket (if no \fB\-l\fR options have been
+specified), i.e., you may specify different settings for different
+sockets.
+.Sp
+The default is not to change ownership or permissions of the socket and, thus,
+use the system default.
+.IP "\fB\-m\fR \fImode\fR" 4
+.IX Item "-m mode"
+Set the file permissions of a \s-1UNIX\s0 domain socket. The option accepts an octal
+number representing the bit pattern for the mode (see \fIchmod\fR\|(1) for
+details).
+.Sp
+Please note that not all systems honor this setting. On Linux, read/write
+permissions are required to connect to a \s-1UNIX\s0 socket. However, many
+BSD-derived systems ignore permissions for \s-1UNIX\s0 sockets. See \fIunix\fR\|(7) for
+details.
+.Sp
+This option affects the \fIfollowing\fR \s-1UNIX\s0 socket addresses (the following
+\&\fB\-l\fR options) or the default socket (if no \fB\-l\fR options have been
+specified), i.e., you may specify different settings for different
+sockets.
+.Sp
+The default is not to change ownership or permissions of the socket and, thus,
+use the system default.
.IP "\fB\-P\fR \fIcommand\fR[,\fIcommand\fR[,...]]" 4
.IX Item "-P command[,command[,...]]"
Specifies the commands accepted via a network socket. This allows
\& rrdcached \-P FLUSH,PENDING $MORE_ARGUMENTS
.Ve
.Sp
-The \fB\-P\fR option effects the \fIfollowing\fR socket addresses (the following \fB\-l\fR
-options). In the following example, only the IPv4 network socket (address
+The \fB\-P\fR option affects the \fIfollowing\fR socket addresses (the following \fB\-l\fR
+options) or the default socket (if no \fB\-l\fR options have been
+specified). In the following example, only the IPv4 network socket (address
\&\f(CW10.0.0.1\fR) will be restricted to the \f(CW\*(C`FLUSH\*(C'\fR and \f(CW\*(C`PENDING\*(C'\fR commands:
.Sp
.Vb 1
.IX Header "AFFECTED RRDTOOL COMMANDS"
The following commands may be made aware of the \fBrrdcached\fR using the command
line argument \fB\-\-daemon\fR or the environment variable \fB\s-1RRDCACHED_ADDRESS\s0\fR:
-.IP "\fBdump\fR" 4
-.IX Item "dump"
-.PD 0
-.IP "\fBfetch\fR" 4
-.IX Item "fetch"
-.IP "\fBflush\fR" 4
-.IX Item "flush"
-.IP "\fBgraph\fR" 4
-.IX Item "graph"
-.IP "\fBgraphv\fR" 4
-.IX Item "graphv"
-.IP "\fBinfo\fR" 4
-.IX Item "info"
-.IP "\fBlast\fR" 4
-.IX Item "last"
-.IP "\fBlastupdate\fR" 4
-.IX Item "lastupdate"
-.IP "\fBupdate\fR" 4
-.IX Item "update"
-.IP "\fBxport\fR" 4
-.IX Item "xport"
-.PD
+.IP "\(bu" 4
+dump
+.IP "\(bu" 4
+fetch
+.IP "\(bu" 4
+flush
+.IP "\(bu" 4
+graph
+.IP "\(bu" 4
+graphv
+.IP "\(bu" 4
+info
+.IP "\(bu" 4
+last
+.IP "\(bu" 4
+lastupdate
+.IP "\(bu" 4
+update
+.IP "\(bu" 4
+xport
.PP
The \fBupdate\fR command can send values to the daemon instead of writing them to
the disk itself. All other commands can send a \fB\s-1FLUSH\s0\fR command (see below) to
When appending a value to a tree node, it is checked whether it's time to write
the values to disk. Values are written to disk if
\&\f(CW\*(C`now()\ \-\ First\ >=\ timeout\*(C'\fR, where \f(CW\*(C`timeout\*(C'\fR is the timeout specified
-using the \fB\-w\fR option, see \s-1OPTIONS\s0. If the values are \*(L"old enough\*(R" they
+using the \fB\-w\fR option, see \*(L"\s-1OPTIONS\s0\*(R". If the values are \*(L"old enough\*(R" they
will be enqueued in the \*(L"update queue\*(R", i.\ e. they will be appended to
the linked list shown below. Because the tree nodes and the elements of the
linked list are the same data structures in memory, any update to a file that
.IX Header "SECURITY CONSIDERATIONS"
.SS "Authentication"
.IX Subsection "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!
.PP
-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 \fIhosts_access\fR\|(5) man pages.
.PP
-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 \s-1VLAN\s0 or \s-1VPN\s0 for
this, using network sockets is probably a bad idea!
.SS "Authorization"
rrdtool, rrdgraph
.SH "AUTHOR"
.IX Header "AUTHOR"
-\&\fBrrdcached\fR and this manual page have been written by Florian Forster
-<octo\ at\ verplant.org>.
+Florian Forster <octo\ at\ verplant.org>
+.PP
+Both \fBrrdcached\fR and this manual page have been written by Florian.
.SH "CONTRIBUTORS"
.IX Header "CONTRIBUTORS"
kevin brintnall <kbrint@rufus.net>