![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/rrdcached.1 b/doc/rrdcached.1
index 70ba28eac2d2b368bfc674844b4611f366f10e36..2a111870cee0a5c655bd48ed221ab5072be33315 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.1801 (Pod::Simple 3.08)
.\"
.\" 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 "2009-09-24" "1.3.999" "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\-w\fR\ \fItimeout\fR]
[\fB\-z\fR\ \fIdelay\fR]
[\fB\-f\fR\ \fItimeout\fR]
\&\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/udp\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\-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 effects the \fIfollowing\fR socket addresses (the following \fB\-l\fR
+options). 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"
@@ -361,15 +393,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"
+There is no authentication.
+.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!
.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 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