![[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:
.\" ========================================================================
.\"
.\" 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
.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
..
.\" 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 C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
. ds -- \(*W-
. ds R" ''
'br\}
.\"
. 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
.\" 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.
.\" 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
.\}
. 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.
.\"
.\" 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"
.\" ========================================================================
.\"
.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
.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]
[\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(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
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.
.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
.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"
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"
\&\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
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.
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
.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"
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
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 !
\& +\-\-\-\-\-\-+ +\-\-\-\-\-\-+ +\-\-\-\-\-\-+
\& ! 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 !
\& +\-\-\-+\-\-\-\-+\-\-\-+ +\-\-\-\-\-\-+\-\-\-\-\-+ +\-\-\-+\-\-\-\-+\-\-\-+
\& ! 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
.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
.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"
\&\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
.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
.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
.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
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"
You have been warned.
.SH "PROTOCOL"
.IX Header "PROTOCOL"
.PP
.Vb 1
\& 0 Success<LF>
.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
\& 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
.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
.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...
\& 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.
.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
.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