=encoding UTF-8 =head1 NAME collectd-unixsock - Documentation of collectd's C =head1 SYNOPSIS # See collectd.conf(5) LoadPlugin unixsock # ... SocketFile "/path/to/socket" SocketGroup "collectd" SocketPerms "0770" DeleteSocket false =head1 DESCRIPTION The C opens an UNIX-socket over which one can interact with the daemon. This can be used to use the values collected by collectd in other applications, such as monitoring solutions, or submit externally collected values to collectd. For example, this plugin is used by L to check if some value is in a certain range and exit with a Nagios-compatible exit code. =head1 COMMANDS Upon start the C opens a UNIX-socket and waits for connections. Once a connection is established the client can send commands to the daemon which it will answer, if it understand them. In general the plugin answers with a status line of the following form: I I If I is greater than or equal to zero the message indicates success, if I is less than zero the message indicates failure. I is a human-readable string that further describes the return value. On success, I furthermore indicates the number of subsequent lines of output (not including the status line). Each such lines usually contains a single return value. See the description of each command for details. The following commands are implemented: =over 4 =item B I If the value identified by I (see below) is found the complete value-list is returned. The response is a list of name-value-pairs, each pair on its own line (the number of lines is indicated by the status line - see above). Each name-value-pair is of the form IB<=>I. Counter-values are converted to a rate, e.Eg. bytes per second. Undefined values are returned as B. Example: -> | GETVAL myhost/cpu-0/cpu-user <- | 1 Value found <- | value=1.260000e+00 =item B Returns a list of the values available in the value cache together with the time of the last update, so that querying applications can issue a B command for the values that have changed. Each return value consists of the update time as an epoch value and the identifier, separated by a space. The update time is the time of the last value, as provided by the collecting instance and may be very different from the time the server considers to be "now". Example: -> | LISTVAL <- | 69 Values found <- | 1182204284 myhost/cpu-0/cpu-idle <- | 1182204284 myhost/cpu-0/cpu-nice <- | 1182204284 myhost/cpu-0/cpu-system <- | 1182204284 myhost/cpu-0/cpu-user ... =item B I [I] I Submits one or more values (identified by I, see below) to the daemon which will dispatch it to all its write-plugins. An I is of the form CBIB<->IBIB<->I> with both I-parts being optional. If they're omitted the hyphen must be omitted, too. I and each I-part may be chosen freely as long as the tuple (plugin, plugin instance, type instance) uniquely identifies the plugin within collectd. I identifies the type and number of values (i.Ee. data-set) passed to collectd. A large list of predefined data-sets is available in the B file. The I is an optional list of I, where each option is a key-value-pair. A list of currently understood options can be found below, all other options will be ignored. Values that contain spaces must be quoted with double quotes. I is a colon-separated list of the time and the values, each either an integer if the data-source is a counter, or a double if the data-source is of type "gauge". You can submit an undefined gauge-value by using B. When submitting B to a counter the behavior is undefined. The time is given as epoch (i.Ee. standard UNIX time). You can mix options and values, but the order is important: Options only effect following values, so specifying an option as last field is allowed, but useless. Also, an option applies to B following values, so you don't need to re-set an option over and over again. The currently defined B are: =over 4 =item BI Gives the interval in which the data identified by I is being collected. =back Please note that this is the same format as used in the B, see L. Example: -> | PUTVAL testhost/interface/if_octets-test0 interval=10 1179574444:123:456 <- | 0 Success =item B [I] BI Submits a notification to the daemon which will then dispatch it to all plugins which have registered for receiving notifications. The B command is followed by a list of options which further describe the notification. The B option is special in that it will consume the rest of the line as its value. The B, B, and B