X-Git-Url: https://git.tokkee.org/?a=blobdiff_plain;f=doc%2Frrdcached.1;h=2a111870cee0a5c655bd48ed221ab5072be33315;hb=645054bac6187b0e83fd4125fd59e4feda216b64;hp=70ba28eac2d2b368bfc674844b4611f366f10e36;hpb=ffa00ac697dccce18dca8880ca7a14066521ac5c;p=pkg-rrdtool.git diff --git a/doc/rrdcached.1 b/doc/rrdcached.1 index 70ba28e..2a11187 100644 --- a/doc/rrdcached.1 +++ b/doc/rrdcached.1 @@ -1,15 +1,7 @@ -.\" 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 @@ -25,11 +17,11 @@ .. .\" 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- @@ -48,22 +40,25 @@ . 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. @@ -129,13 +124,18 @@ .\" ======================================================================== .\" .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] @@ -172,7 +172,9 @@ 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/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! @@ -187,10 +189,40 @@ 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 @@ -209,7 +241,7 @@ setting this to a high value, such as 3600\ seconds, is acceptable in most 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" @@ -233,7 +265,7 @@ given by \fB\-f\fR. 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. @@ -282,7 +314,7 @@ specified as: .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 ! @@ -395,7 +427,7 @@ Files/values are stored in a (balanced) tree. .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 @@ -404,37 +436,53 @@ Explicitly flushed values are inserted at the \*(L"head\*(R". \&\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" @@ -469,14 +517,12 @@ Examples: .PP .Vb 1 \& 0 Success -.Ve -.PP -.Vb 3 +\& \& 2 Two lines follow \& This is the first line \& And this is the second line .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 @@ -568,7 +614,7 @@ message itself. The first user command after \fB\s-1BATCH\s0\fR is command numb .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... @@ -580,7 +626,7 @@ message itself. The first user command after \fB\s-1BATCH\s0\fR is command numb .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