X-Git-Url: https://git.tokkee.org/?p=pkg-rrdtool.git;a=blobdiff_plain;f=doc%2Frrdcached.txt;h=fdacd186880328a23acaf738bed73492233e0f1e;hp=32d3674e88fa98cff6d2d2f279d2d7f04da50203;hb=645054bac6187b0e83fd4125fd59e4feda216b64;hpb=ffa00ac697dccce18dca8880ca7a14066521ac5c diff --git a/doc/rrdcached.txt b/doc/rrdcached.txt index 32d3674..fdacd18 100644 --- a/doc/rrdcached.txt +++ b/doc/rrdcached.txt @@ -6,9 +6,9 @@ NNAAMMEE rrdcached - Data caching daemon for rrdtool SSYYNNOOPPSSIISS - rrrrddccaacchheedd [--ll//--LL _a_d_d_r_e_s_s] [--ww _t_i_m_e_o_u_t] [--zz _d_e_l_a_y] [--ff _t_i_m_e_o_u_t] - [--pp _p_i_d___f_i_l_e] [--tt _w_r_i_t_e___t_h_r_e_a_d_s] [--jj _j_o_u_r_n_a_l___d_i_r] [-F] [-g] - [--bb _b_a_s_e___d_i_r [--BB]] + rrrrddccaacchheedd [--PP _p_e_r_m_i_s_s_i_o_n_s] [--ll _a_d_d_r_e_s_s] [--ww _t_i_m_e_o_u_t] [--zz _d_e_l_a_y] + [--ff _t_i_m_e_o_u_t] [--pp _p_i_d___f_i_l_e] [--tt _w_r_i_t_e___t_h_r_e_a_d_s] [--jj _j_o_u_r_n_a_l___d_i_r] [-F] + [-g] [--bb _b_a_s_e___d_i_r [--BB]] DDEESSCCRRIIPPTTIIOONN rrrrddccaacchheedd is a daemon that receives updates to existing RRD files, @@ -19,23 +19,26 @@ DDEESSCCRRIIPPTTIIOONN The daemon was written with big setups in mind. Those setups usually run into IO related problems sooner or later for reasons that are - beyond the scope of this document. Check the wiki at the RRDTool home- - page for details. Also check "SECURITY CONSIDERATIONS" below before + beyond the scope of this document. Check the wiki at the RRDTool + homepage for details. Also check "SECURITY CONSIDERATIONS" below before using this daemon! A detailed description of how the daemon operates can be found in the "HOW IT WORKS" section below. OOPPTTIIOONNSS --ll _a_d_d_r_e_s_s Tells the daemon to bind to _a_d_d_r_e_s_s and accept incoming connections - on that socket. If _a_d_d_r_e_s_s begins with "unix:", everything follow- - ing that prefix is interpreted as the path to a UNIX domain socket. - Otherwise the address or node name are resolved using getaddrinfo. + on that socket. If _a_d_d_r_e_s_s begins with "unix:", everything + following that prefix is interpreted as the path to a UNIX domain + socket. Otherwise the address or node name are resolved using + getaddrinfo. For network sockets, a port may be specified by using the form - "[address]:port". If the address is an IPv4 address or a fully + "[[_a_d_d_r_e_s_s]]::_p_o_r_t_". If the address is an IPv4 address or a fully qualified domain name (i. e. the address contains at least one dot - (".")), the square brackets can be omitted, resulting in the (sim- - pler) "address:port" pattern.. The default port is 4422221177//uuddpp. + (".")), the square brackets can be omitted, resulting in the + (simpler) "_a_d_d_r_e_s_s::_p_o_r_t_" pattern. The default port is 4422221177//uuddpp. If + you specify a network socket, it is mandatory to read the "SECURITY + CONSIDERATIONS" section. The following formats are accepted. Please note that the address of the UNIX domain socket mmuusstt start with a slash in the second case! @@ -49,9 +52,33 @@ OOPPTTIIOONNSS If the --ll option is not specified the default address, "unix:/tmp/rrdcached.sock", will be used. - --LL _a_d_d_r_e_s_s - Same as --ll, except creates a low-privilege socket. See SSEECCUURRIITTYY - CCOONNSSIIDDEERRAATTIIOONNSS for more information. + --PP _c_o_m_m_a_n_d[,_c_o_m_m_a_n_d[,...]] + Specifies the commands accepted via a network socket. This allows + administrators of _R_R_D_C_a_c_h_e_D to control the actions accepted from + various sources. + + The arguments given to the --PP option is a comma separated list of + commands. For example, to allow the "FLUSH" and "PENDING" commands + one could specify: + + rrdcached -P FLUSH,PENDING $MORE_ARGUMENTS + + The --PP option effects the _f_o_l_l_o_w_i_n_g socket addresses (the following + --ll options). In the following example, only the IPv4 network socket + (address 10.0.0.1) will be restricted to the "FLUSH" and "PENDING" + commands: + + rrdcached -l unix:/some/path -P FLUSH,PENDING -l 10.0.0.1 + + A complete list of available commands can be found in the section + "Valid Commands" below. There are two minor special exceptions: + + · The "HELP" and "QUIT" commands are always allowed. + + · If the "BATCH" command is accepted, the .. command will + automatically be accepted, too. + + Please also read "SECURITY CONSIDERATIONS" below. --ww _t_i_m_e_o_u_t Data is written to disk every _t_i_m_e_o_u_t seconds. If this option is @@ -73,22 +100,22 @@ OOPPTTIIOONNSS --pp _f_i_l_e Sets the name and location of the PID-file. If not specified, the - default, "$localststedir/run/rrdcached.pid" will be used. + default, "_$_l_o_c_a_l_s_t_s_t_e_d_i_r_/_r_u_n_/_r_r_d_c_a_c_h_e_d_._p_i_d_" will be used. --tt _w_r_i_t_e___t_h_r_e_a_d_s Specifies the number of threads used for writing RRD files. The default is 4. Increasing this number will allow rrdcached to have more simultaneous I/O requests into the kernel. This may allow the - kernel to re-order disk writes, resulting in better disk through- - put. + kernel to re-order disk writes, resulting in better disk + throughput. --jj _d_i_r Write updates to a journal in _d_i_r. In the event of a program or system crash, this will allow the daemon to write any updates that were pending at the time of the crash. - On startup, the daemon will check for journal files in this direc- - tory. If found, all updates therein will be read into memory + On startup, the daemon will check for journal files in this + directory. If found, all updates therein will be read into memory before the daemon starts accepting new connections. The journal will be rotated with the same frequency as the flush @@ -97,9 +124,9 @@ OOPPTTIIOONNSS 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 RRD data files are not fully up-to-date, no informa- - tion is lost; all pending updates will be replayed from the journal - next time the daemon starts up. + Although the RRD data files are not fully up-to-date, no + information is lost; all pending updates will be replayed from the + journal next time the daemon starts up. To disable fast shutdown, use the --FF option. @@ -126,8 +153,8 @@ OOPPTTIIOONNSS "/tmp". WWAARRNNIINNGG:: The paths up to and including the base directory MMUUSSTT NNOOTT - BBEE symbolic links. In other words, if the base directory is speci- - fied as: + BBEE symbolic links. In other words, if the base directory is + specified as: -b /base/dir/somewhere @@ -138,13 +165,13 @@ OOPPTTIIOONNSS /base/dir/somewhere --BB Only permit writes into the base directory specified in --bb (and any - sub-directories). This does NNOOTT detect symbolic links. Paths con- - taining "../" will also be blocked. + sub-directories). This does NNOOTT detect symbolic links. Paths + containing "../" will also be blocked. AAFFFFEECCTTEEDD RRRRDDTTOOOOLL CCOOMMMMAANNDDSS The following commands may be made aware of the rrrrddccaacchheedd using the - command line argument ----ddaaeemmoonn or the environment variable RRRRDD-- - CCAACCHHEEDD__AADDDDRREESSSS: + command line argument ----ddaaeemmoonn or the environment variable + RRRRDDCCAACCHHEEDD__AADDDDRREESSSS: dduummpp ffeettcchh @@ -167,8 +194,8 @@ EERRRROORR RREEPPOORRTTIINNGG messages are printed to "STDERR". One of the steps when starting up is to fork to the background and closing "STDERR" - after this writing directly to the user is no longer possible. Once this has happened, the - daemon will send log messages to the system logging daemon using _s_y_s_- - _l_o_g(3). The facility used is "LOG_DAEMON". + daemon will send log messages to the system logging daemon using + _s_y_s_l_o_g(3). The facility used is "LOG_DAEMON". HHOOWW IITT WWOORRKKSS When receiving an update, rrrrddccaacchheedd does not write to disk but looks @@ -199,8 +226,8 @@ HHOOWW IITT WWOORRKKSS never be written to disk. Therefore, every now and then, controlled by the --ff option, the entire tree is walked and all "old" values are enqueued. Since this only affects "dead" files and walking the tree is - relatively expensive, you should set the "flush interval" to a reason- - ably high value. The default is 3600 seconds (one hour). + relatively expensive, you should set the "flush interval" to a + reasonably high value. The default is 3600 seconds (one hour). The downside of caching values is that they won't show up in graphs generated from the RRD files. To get around this, the daemon provides @@ -237,62 +264,75 @@ HHOOWW IITT WWOORRKKSS The above diagram demonstrates: - · Files/values are stored in a (balanced) tree. + · Files/values are stored in a (balanced) tree. - · Tree nodes and entries in the update queue are the same data struc- - ture. + · Tree nodes and entries in the update queue are the same data + structure. - · The local time ("First") and the time specified in updates ("Time") + · The local time ("First") and the time specified in updates ("Time") may differ. - · Timed out values are inserted at the "tail". + · Timed out values are inserted at the "tail". - · Explicitly flushed values are inserted at the "head". + · Explicitly flushed values are inserted at the "head". - · ASCII art rocks. + · ASCII art rocks. SSEECCUURRIITTYY CCOONNSSIIDDEERRAATTIIOONNSS - The client/server protocol does not have any authentication or autho- - rization mechanism. Therefore, take care to restrict which users can - connect to the daemon. - - Control sockets are divided into high-privilege (--ll) and low-privilege - (--LL) sockets. High-privilege sockets accept all commands, whereas low- - privilege sockets accept only FFLLUUSSHH, SSTTAATTSS, and HHEELLPP. - - For a multi-user environment where only certain users require - read/write access, the recommended configuration uses two sockets as - follows: - - --ll _/_p_r_o_t_e_c_t_e_d_/_d_i_r_/_r_r_d_._s_o_c_k - Create a high-privilege unix-domain socket. This should be pro- - tected with the same Unix permissions that are used to protect the - RRD files. Updates should be directed to this socket. - - --LL _1_2_7_._0_._0_._1 - Create a low-privilege TCP socket listening on localhost. All - users on the local system may use this to trigger FLUSH of individ- - ual files. Users with read-only access should be directed to this - socket. - - If you (want to) use the network capability, i. e. let the daemon bind - to an IPv4 or IPv6 socket, it is yyoouurr job to install a packet filter or - similar mechanism to prevent unauthorized connections. Unless you have - a dedicated VLAN or VPN for this, using the network option is probably - a bad idea! + AAuutthheennttiiccaattiioonn + There is no authentication. + + 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! + + It is highly recommended to install a packet filter or similar + mechanism to prevent unauthorized connections. Unless you have a + dedicated VLAN or VPN for this, using network sockets is probably a bad + idea! + + AAuutthhoorriizzaattiioonn + There is minimal per-socket authorization. + + 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. + + 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 "FLUSH" command. + + EEnnccrryyppttiioonn + There is no encryption. + + 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 VPN or an + encrypted tunnel if you statistics are confidential! + + SSaanniittyy cchheecckkiinngg + There is no sanity checking. 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! - You have been warned. + CCoonncclluussiioonn + · Security is the job of the administrator. + + · We recommend to allow write access via UNIX domain sockets only. + + · You have been warned. PPRROOTTOOCCOOLL The daemon communicates with clients using a line based ASCII protocol which is easy to read and easy to type. This makes it easy for scripts - to implement the protocol and possible for users to use telnet to con- - nect to the daemon and test stuff "by hand". + to implement the protocol and possible for users to use telnet to + connect to the daemon and test stuff "by hand". The protocol is line based, this means that each record consists of one or more lines. A line is terminated by the line feed character 0x0A, @@ -301,8 +341,8 @@ PPRROOTTOOCCOOLL After the connection has been established, the client is expected to send a "command". A command consists of the command keyword, possibly - some arguments, and a terminating newline character. For a list of com- - mands, see "Valid Commands" below. + some arguments, and a terminating newline character. For a list of + commands, see "Valid Commands" below. Example: @@ -311,8 +351,8 @@ PPRROOTTOOCCOOLL The daemon answers with a line consisting of a status code and a short status message, separated by one or more space characters. A negative status code signals an error, a positive status code or zero signal - success. If the status code is greater than zero, it indicates the num- - ber of lines that follow the status line. + success. If the status code is greater than zero, it indicates the + number of lines that follow the status line. Examples: @@ -322,8 +362,7 @@ PPRROOTTOOCCOOLL This is the first line And this is the second line - VVaalliidd CCoommmmaannddss - + VVaalliidd CCoommmmaannddss The following commands are understood by the daemon: FFLLUUSSHH _f_i_l_e_n_a_m_e @@ -388,8 +427,8 @@ PPRROOTTOOCCOOLL Note that rrdcached only accepts absolute timestamps in the update values. Updates strings like "N:1:2:3" are automatically converted - to absolute time by the RRD client library before sending to rrd- - cached. + to absolute time by the RRD client library before sending to + rrdcached. WWRROOTTEE _f_i_l_e_n_a_m_e This command is written to the journal after a file is successfully @@ -403,16 +442,16 @@ PPRROOTTOOCCOOLL it permits more than one command to be issued per _r_e_a_d_(_) and _w_r_i_t_e_(_). - All commands are executed just as they would be if given individu- - ally, except for output to the user. Messages indicating success - are suppressed, and error messages are delayed until the client is - finished. + All commands are executed just as they would be if given + individually, except for output to the user. Messages indicating + success are suppressed, and error messages are delayed until the + client is finished. Command processing is finished when the client sends a dot (".") on its own line. After the client has finished, the server responds with an error count and the list of error messages (if any). Each - error messages indicates the number of the command to which it cor- - responds, and the error message itself. The first user command + error messages indicates the number of the command to which it + corresponds, and the error message itself. The first user command after BBAATTCCHH is command number one. client: BATCH @@ -428,8 +467,7 @@ PPRROOTTOOCCOOLL QQUUIITT Disconnect from rrdcached. - PPeerrffoorrmmaannccee VVaalluueess - + PPeerrffoorrmmaannccee VVaalluueess The following counters are returned by the SSTTAATTSS command: QQuueeuueeLLeennggtthh _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_) @@ -447,8 +485,8 @@ PPRROOTTOOCCOOLL DDaattaaSSeettssWWrriitttteenn _(_u_n_s_i_g_n_e_d _6_4_b_i_t _i_n_t_e_g_e_r_) Total number of "data sets" written to disk since the daemon was - started. A data set is one or more values passed to the UUPPDDAATTEE com- - mand. For example: "1223661439:123:456" is one data set with two + started. A data set is one or more values passed to the UUPPDDAATTEE + command. For example: "1223661439:123:456" is one data set with two values. The term "data set" is used to prevent confusion whether individual values or groups of values are counted. @@ -495,4 +533,4 @@ CCOONNTTRRIIBBUUTTOORRSS -1.3.99909060808 2009-04-09 RRDCACHED(1) +1.3.999 2009-09-24 RRDCACHED(1)