1=encoding UTF-8 2 3=head1 NAME 4 5collectd-unixsock - Documentation of collectd's C<unixsock plugin> 6 7=head1 SYNOPSIS 8 9 # See collectd.conf(5) 10 LoadPlugin unixsock 11 # ... 12 <Plugin unixsock> 13 SocketFile "/path/to/socket" 14 SocketGroup "collectd" 15 SocketPerms "0770" 16 DeleteSocket false 17 </Plugin> 18 19=head1 DESCRIPTION 20 21The C<unixsock plugin> opens an UNIX-socket over which one can interact with 22the daemon. This can be used to use the values collected by collectd in other 23applications, such as monitoring solutions, or submit externally collected 24values to collectd. 25 26For example, this plugin is used by L<collectd-nagios(1)> to check if some 27value is in a certain range and exit with a Nagios-compatible exit code. 28 29=head1 COMMANDS 30 31Upon start the C<unixsock plugin> opens a UNIX-socket and waits for 32connections. Once a connection is established the client can send commands to 33the daemon which it will answer, if it understand them. 34 35In general the plugin answers with a status line of the following form: 36 37I<Status> I<Message> 38 39If I<Status> is greater than or equal to zero the message indicates success, 40if I<Status> is less than zero the message indicates failure. I<Message> is a 41human-readable string that further describes the return value. 42 43On success, I<Status> furthermore indicates the number of subsequent lines of 44output (not including the status line). Each such lines usually contains a 45single return value. See the description of each command for details. 46 47The following commands are implemented: 48 49=over 4 50 51=item B<GETVAL> I<Identifier> 52 53If the value identified by I<Identifier> (see below) is found the complete 54value-list is returned. The response is a list of name-value-pairs, each pair 55on its own line (the number of lines is indicated by the status line - see 56above). Each name-value-pair is of the form I<name>B<=>I<value>. 57Counter-values are converted to a rate, e.E<nbsp>g. bytes per second. 58Undefined values are returned as B<NaN>. 59 60Example: 61 -> | GETVAL myhost/cpu-0/cpu-user 62 <- | 1 Value found 63 <- | value=1.260000e+00 64 65=item B<LISTVAL> 66 67Returns a list of the values available in the value cache together with the 68time of the last update, so that querying applications can issue a B<GETVAL> 69command for the values that have changed. Each return value consists of the 70update time as an epoch value and the identifier, separated by a space. The 71update time is the time of the last value, as provided by the collecting 72instance and may be very different from the time the server considers to be 73"now". 74 75Example: 76 -> | LISTVAL 77 <- | 69 Values found 78 <- | 1182204284 myhost/cpu-0/cpu-idle 79 <- | 1182204284 myhost/cpu-0/cpu-nice 80 <- | 1182204284 myhost/cpu-0/cpu-system 81 <- | 1182204284 myhost/cpu-0/cpu-user 82 ... 83 84=item B<PUTVAL> I<Identifier> [I<OptionList>] I<Valuelist> 85 86Submits one or more values (identified by I<Identifier>, see below) to the 87daemon which will dispatch it to all its write-plugins. 88 89An I<Identifier> is of the form 90C<I<host>B</>I<plugin>B<->I<instance>B</>I<type>B<->I<instance>> with both 91I<instance>-parts being optional. If they're omitted the hyphen must be 92omitted, too. I<plugin> and each I<instance>-part may be chosen freely as long 93as the tuple (plugin, plugin instance, type instance) uniquely identifies the 94plugin within collectd. I<type> identifies the type and number of values 95(i.E<nbsp>e. data-set) passed to collectd. A large list of predefined 96data-sets is available in the B<types.db> file. 97 98The I<OptionList> is an optional list of I<Options>, where each option is a 99key-value-pair. A list of currently understood options can be found below, all 100other options will be ignored. Values that contain spaces must be quoted with 101double quotes. 102 103I<Valuelist> is a colon-separated list of the time and the values, each either 104an integer if the data-source is a counter, or a double if the data-source is 105of type "gauge". You can submit an undefined gauge-value by using B<U>. When 106submitting B<U> to a counter the behavior is undefined. The time is given as 107epoch (i.E<nbsp>e. standard UNIX time). 108 109You can mix options and values, but the order is important: Options only 110effect following values, so specifying an option as last field is allowed, but 111useless. Also, an option applies to B<all> following values, so you don't need 112to re-set an option over and over again. 113 114The currently defined B<Options> are: 115 116=over 4 117 118=item B<interval=>I<seconds> 119 120Gives the interval in which the data identified by I<Identifier> is being 121collected. 122 123=item meta:B<key>=I<value> 124 125Add meta data with the key B<key> and the value I<value>. 126 127=back 128 129Please note that this is the same format as used in the B<exec plugin>, see 130L<collectd-exec(5)>. 131 132Example: 133 -> | PUTVAL testhost/interface/if_octets-test0 interval=10 1179574444:123:456 134 <- | 0 Success 135 136=item B<PUTNOTIF> [I<OptionList>] B<message=>I<Message> 137 138Submits a notification to the daemon which will then dispatch it to all plugins 139which have registered for receiving notifications. 140 141The B<PUTNOTIF> command is followed by a list of options which further describe 142the notification. The B<message> option is special in that it will consume the 143rest of the line as its value. The B<message>, B<severity>, and B<time> options 144are mandatory. 145 146Valid options are: 147 148=over 4 149 150=item B<message=>I<Message> (B<REQUIRED>) 151 152Sets the message of the notification. This is the message that will be made 153accessible to the user, so it should contain some useful information. As with 154all options: If the message includes spaces, it must be quoted with double 155quotes. This option is mandatory. 156 157=item B<severity=failure>|B<warning>|B<okay> (B<REQUIRED>) 158 159Sets the severity of the notification. This option is mandatory. 160 161=item B<time=>I<Time> (B<REQUIRED>) 162 163Sets the time of the notification. The time is given as "epoch", i.E<nbsp>e. as 164seconds since January 1st, 1970, 00:00:00. This option is mandatory. 165 166=item B<host=>I<Hostname> 167 168=item B<plugin=>I<Plugin> 169 170=item B<plugin_instance=>I<Plugin-Instance> 171 172=item B<type=>I<Type> 173 174=item B<type_instance=>I<Type-Instance> 175 176These "associative" options establish a relation between this notification and 177collected performance data. This connection is purely informal, i.E<nbsp>e. the 178daemon itself doesn't do anything with this information. However, websites or 179GUIs may use this information to place notifications near the affected graph or 180table. All the options are optional, but B<plugin_instance> without B<plugin> 181or B<type_instance> without B<type> doesn't make much sense and should be 182avoided. 183 184=item B<type:key=>I<value> 185 186Sets user defined meta information. The B<type> key is a single character 187defining the type of the meta information. 188 189The current supported types are: 190 191=over 8 192 193=item B<s> A string passed as-is. 194 195=back 196 197=back 198 199Please note that this is the same format as used in the B<exec plugin>, see 200L<collectd-exec(5)>. 201 202Example: 203 -> | PUTNOTIF type=temperature severity=warning time=1201094702 message=The roof is on fire! 204 <- | 0 Success 205 206=item B<FLUSH> [B<timeout=>I<Timeout>] [B<plugin=>I<Plugin> [...]] [B<identifier=>I<Ident> [...]] 207 208Flushes all cached data older than I<Timeout> seconds. If no timeout has been 209specified, it defaults to -1 which causes all data to be flushed. 210 211If the B<plugin> option has been specified, only the I<Plugin> plugin will be 212flushed. You can have multiple B<plugin> options to flush multiple plugins in 213one go. If the B<plugin> option is not given all plugins providing a flush 214callback will be flushed. 215 216If the B<identifier> option is given only the specified values will be flushed. 217This is meant to be used by graphing or displaying frontends which want to have 218the latest values for a specific graph. Again, you can specify the 219B<identifier> option multiple times to flush several values. If this option is 220not specified at all, all values will be flushed. 221 222Example: 223 -> | FLUSH plugin=rrdtool identifier=localhost/df/df-root identifier=localhost/df/df-var 224 <- | 0 Done: 2 successful, 0 errors 225 226=back 227 228=head2 Identifiers 229 230Value or value-lists are identified in a uniform fashion: 231 232I<Hostname>/I<Plugin>/I<Type> 233 234Where I<Plugin> and I<Type> are both either of type "I<Name>" or 235"I<Name>-I<Instance>". If the identifier includes spaces, it must be quoted 236using double quotes. This sounds more complicated than it is, so here are 237some examples: 238 239 myhost/cpu-0/cpu-user 240 myhost/load/load 241 myhost/memory/memory-used 242 myhost/disk-sda/disk_octets 243 "myups/snmp/temperature-Outlet 1" 244 245=head1 ABSTRACTION LAYER 246 247B<collectd> ships the Perl-Module L<Collectd::Unixsock> which 248provides an abstraction layer over the actual socket connection. It can be 249found in the directory F<bindings/perl/> in the source distribution or 250(usually) somewhere near F</usr/share/perl5/> if you're using a package. If 251you want to use Perl to communicate with the daemon, you're encouraged to use 252and expand this module. 253 254=head1 SEE ALSO 255 256L<collectd(1)>, 257L<collectd.conf(5)>, 258L<collectd-nagios(1)>, 259L<unix(7)> 260 261=head1 AUTHOR 262 263Florian Forster E<lt>octo@collectd.orgE<gt> 264 265=cut 266