![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdcached.1 b/doc/rrdcached.1
index 70ba28eac2d2b368bfc674844b4611f366f10e36..8c2324e8d9fa2bf90609e37ba13f6ce43a0a1509 100644 (file)
--- a/doc/rrdcached.1
+++ b/doc/rrdcached.1
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.14
+.\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
.\"
.\" Standard preamble:
.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.\" Set up some character translations and predefined strings. \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. | will give a
-.\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to
-.\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C'
-.\" expand to `' in nroff, nothing in troff, for use with C<>.
-.tr \(*W-|\(bv\*(Tr
+.\" double quote, and \*(R" will give a right double quote. \*(C+ will
+.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
+.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
+.\" nothing in troff, for use with C<>.
+.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds R" ''
'br\}
.\"
+.\" Escape single quotes in literal strings from groff's Unicode transform.
+.ie \n(.g .ds Aq \(aq
+.el .ds Aq '
+.\"
.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
+.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD. Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
-.if \nF \{\
+.ie \nF \{\
. de IX
. tm Index:\\$1\t\\n%\t"\\$2"
..
. nr % 0
. rr F
.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
+.el \{\
+. de IX
+..
+.\}
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear. Run. Save yourself. No user-serviceable parts.
.\" ========================================================================
.\"
.IX Title "RRDCACHED 1"
-.TH RRDCACHED 1 "2009-04-09" "1.3.99909060808" "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
+.nh
.SH "NAME"
rrdcached \- Data caching daemon for rrdtool
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBrrdcached\fR
-[\fB\-l/\-L\fR\ \fIaddress\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.
+\&\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
The following formats are accepted. Please note that the address of the \s-1UNIX\s0
domain socket \fBmust\fR start with a slash in the second case!
.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\-L\fR \fIaddress\fR" 4
-.IX Item "-L address"
-Same as \fB\-l\fR, except creates a low-privilege socket. See \fB\s-1SECURITY\s0
-\&\s-1CONSIDERATIONS\s0\fR for more information.
+.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
+administrators of \fIRRDCacheD\fR to control the actions accepted from various
+sources.
+.Sp
+The arguments given to the \fB\-P\fR option is a comma separated list of commands.
+For example, to allow the \f(CW\*(C`FLUSH\*(C'\fR and \f(CW\*(C`PENDING\*(C'\fR commands one could specify:
+.Sp
+.Vb 1
+\& rrdcached \-P FLUSH,PENDING $MORE_ARGUMENTS
+.Ve
+.Sp
+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
+\& rrdcached \-l unix:/some/path \-P FLUSH,PENDING \-l 10.0.0.1
+.Ve
+.Sp
+A complete list of available commands can be found in the section
+\&\*(L"Valid Commands\*(R" below. There are two minor special exceptions:
+.RS 4
+.IP "\(bu" 4
+The \f(CW\*(C`HELP\*(C'\fR and \f(CW\*(C`QUIT\*(C'\fR commands are always allowed.
+.IP "\(bu" 4
+If the \f(CW\*(C`BATCH\*(C'\fR command is accepted, the \fB.\fR\ command will automatically
+be accepted, too.
+.RE
+.RS 4
+.Sp
+Please also read \*(L"\s-1SECURITY\s0 \s-1CONSIDERATIONS\s0\*(R" below.
+.RE
.IP "\fB\-w\fR \fItimeout\fR" 4
.IX Item "-w timeout"
Data is written to disk every \fItimeout\fR seconds. If this option is not
cases. This timeout defaults to 3600\ seconds.
.IP "\fB\-p\fR \fIfile\fR" 4
.IX Item "-p file"
-Sets the name and location of the PID\-file. If not specified, the default,
+Sets the name and location of the PID-file. If not specified, the default,
\&\f(CW\*(C`\f(CI$localststedir\f(CW/run/rrdcached.pid\*(C'\fR will be used.
.IP "\fB\-t\fR \fIwrite_threads\fR" 4
.IX Item "-t write_threads"
When journaling is enabled, the daemon will use a fast shutdown procedure.
Rather than flushing all files to disk, it will make sure the journal is
properly written and exit immediately. Although the \s-1RRD\s0 data files are
-not fully up\-to\-date, no information is lost; all pending updates will be
+not fully up-to-date, no information is lost; all pending updates will be
replayed from the journal next time the daemon starts up.
.Sp
To disable fast shutdown, use the \fB\-F\fR option.
.IP "\fB\-B\fR" 4
.IX Item "-B"
Only permit writes into the base directory specified in \fB\-b\fR (and any
-sub\-directories). This does \fB\s-1NOT\s0\fR detect symbolic links. Paths
+sub-directories). This does \fB\s-1NOT\s0\fR detect symbolic links. Paths
containing \f(CW\*(C`../\*(C'\fR will also be blocked.
.SH "AFFECTED RRDTOOL COMMANDS"
.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
@@ -361,15 +428,15 @@ command\*(R" to flush specific files. This means that the file is inserted at th
command will return only after the file's pending updates have been written
to disk.
.PP
-.Vb 25
+.Vb 10
\& +\-\-\-\-\-\-+ +\-\-\-\-\-\-+ +\-\-\-\-\-\-+
\& ! head ! ! root ! ! tail !
\& +\-\-\-+\-\-+ +\-\-\-+\-\-+ +\-\-\-+\-\-+
\& ! /\e !
\& ! / \e !
\& ! /\e /\e !
-\& ! /\e/\e \e `\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- ... \-\-\-\-\-\-\-\-, !
-\& V / `\-\-\-\-\-\-\-, ! V
+\& ! /\e/\e \e \`\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- ... \-\-\-\-\-\-\-\-, !
+\& V / \`\-\-\-\-\-\-\-, ! V
\& +\-\-\-+\-\-\-\-+\-\-\-+ +\-\-\-\-\-\-+\-\-\-\-\-+ +\-\-\-+\-\-\-\-+\-\-\-+
\& ! File: foo ! ! File: bar ! ! File: qux !
\& ! First: 101 ! ! First: 119 ! ! First: 180 !
.IP "\(bu" 4
Tree nodes and entries in the update queue are the same data structure.
.IP "\(bu" 4
-The local time (\*(L"First\*(R") and the time specified in updates (\*(L"Time\*(R") may differ.
+The local time (\*(L"First\*(R") and the time specified in updates (\*(L"Time\*(R") may differ.
.IP "\(bu" 4
Timed out values are inserted at the \*(L"tail\*(R".
.IP "\(bu" 4
\&\s-1ASCII\s0 art rocks.
.SH "SECURITY CONSIDERATIONS"
.IX Header "SECURITY CONSIDERATIONS"
-The client/server protocol does not have any authentication or
-authorization mechanism. Therefore, take care to restrict which users can
-connect to the daemon.
+.SS "Authentication"
+.IX Subsection "Authentication"
+If your rrdtool installation was built without libwrap there is no form of
+authentication for clients connecting to the rrdcache daemon!
+.PP
+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
-Control sockets are divided into high-privilege (\fB\-l\fR) and low-privilege
-(\fB\-L\fR) sockets. High-privilege sockets accept all commands, whereas
-low-privilege sockets accept only \fB\s-1FLUSH\s0\fR, \fB\s-1STATS\s0\fR, and \fB\s-1HELP\s0\fR.
+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"
+.IX Subsection "Authorization"
+There is minimal per-socket authorization.
.PP
-For a multi-user environment where only certain users require read/write
-access, the recommended configuration uses two sockets as follows:
-.IP "\fB\-l\fR \fI/protected/dir/rrd.sock\fR" 4
-.IX Item "-l /protected/dir/rrd.sock"
-Create a high-privilege unix-domain socket. This should be protected with
-the same Unix permissions that are used to protect the \s-1RRD\s0 files. Updates
-should be directed to this socket.
-.IP "\fB\-L\fR \fI127.0.0.1\fR" 4
-.IX Item "-L 127.0.0.1"
-Create a low-privilege \s-1TCP\s0 socket listening on localhost. All users on
-the local system may use this to trigger \s-1FLUSH\s0 of individual files. Users
-with read-only access should be directed to this socket.
+Authorization is currently done on a per-socket basis. That means each socket
+has a list of commands it will accept and it will accept. It will accept only
+those commands explicitly listed but it will (currently) accept these commands
+from anyone reaching the socket.
.PP
-If you (want to) use the network capability, i.\ e. let the daemon bind to
-an IPv4 or IPv6 socket, it is \fByour\fR job 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 the network option is probably a bad idea!
+If the networking sockets are to be used, it is necessary to restrict the
+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 \f(CW\*(C`FLUSH\*(C'\fR command.
+.SS "Encryption"
+.IX Subsection "Encryption"
+There is no encryption.
+.PP
+Again, this may be added in the future, but for the time being it is your job
+to keep your private data private. Install a \s-1VPN\s0 or an encrypted tunnel if you
+statistics are confidential!
+.SS "Sanity checking"
+.IX Subsection "Sanity checking"
+There is no sanity checking.
.PP
The daemon will blindly write to any file it gets told, so you really should
create a separate user just for this daemon. Also it does not do any sanity
checks, so if it gets told to write values for a time far in the future, your
files will be messed up good!
-.PP
+.SS "Conclusion"
+.IX Subsection "Conclusion"
+.IP "\(bu" 4
+Security is the job of the administrator.
+.IP "\(bu" 4
+We recommend to allow write access via \s-1UNIX\s0 domain sockets only.
+.IP "\(bu" 4
You have been warned.
.SH "PROTOCOL"
.IX Header "PROTOCOL"
.PP
.Vb 1
\& 0 Success<LF>
-.Ve
-.PP
-.Vb 3
+\&
\& 2 Two lines follow<LF>
\& This is the first line<LF>
\& And this is the second line<LF>
.Ve
-.Sh "Valid Commands"
+.SS "Valid Commands"
.IX Subsection "Valid Commands"
The following commands are understood by the daemon:
.IP "\fB\s-1FLUSH\s0\fR \fIfilename\fR" 4
.Sp
.Vb 9
\& client: BATCH
-\& server: 0 Go ahead. End with dot '.' on its own line.
+\& server: 0 Go ahead. End with dot \*(Aq.\*(Aq on its own line.
\& client: UPDATE x.rrd 1223661439:1:2:3 <\-\-\- command #1
\& client: UPDATE y.rrd 1223661440:3:4:5 <\-\-\- command #2
\& client: and so on...
.IP "\fB\s-1QUIT\s0\fR" 4
.IX Item "QUIT"
Disconnect from rrdcached.
-.Sh "Performance Values"
+.SS "Performance Values"
.IX Subsection "Performance Values"
The following counters are returned by the \fB\s-1STATS\s0\fR command:
.IP "\fBQueueLength\fR \fI(unsigned 64bit integer)\fR" 4
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>