=head1 NAME

collectdctl - Control interface for collectd

=head1 SYNOPSIS

collectdctl I<[options]> I<E<lt>commandE<gt>> I<[command options]>

=head1 DESCRIPTION

collectdctl provides a control interface for collectd, which may be used to
interact with the daemon using the C<unixsock plugin>.

=head1 OPTIONS

collectdctl supports the following options:

=over 4

=item B<-s> I<socket>

Path to the UNIX socket opened by collectd's C<unixsock plugin>.
Default: /var/run/collectd-unixsock

=item B<-h>

Display usage information and exit.

=back

=head1 AVAILABLE COMMANDS

The following commands are supported:

=over 4

=item B<getval> I<E<lt>identifierE<gt>>

Query the latest collected value identified by the specified
I<E<lt>identifierE<gt>> (see below). The value-list associated with that
data-set is returned as a list of key-value-pairs, each on its own line. Keys
and values are separated by the equal sign (C<=>).

=item B<flush> [B<timeout=>I<E<lt>secondsE<gt>>] [B<plugin=>I<E<lt>nameE<gt>>]
[B<identifier=>I<E<lt>idE<gt>>]

Flush the daemon. This is useful, e.E<nbsp>g., to make sure that the latest
values have been written to the respective RRD file before graphing them or
copying them to somewhere else.

The following options are supported by the flush command:

=over 4

=item B<timeout=>I<E<lt>secondsE<gt>>

Flush values older than the specified timeout (in seconds) only.

=item B<plugin=>I<E<lt>nameE<gt>>

Flush the specified plugin only. I.E<nbsp>e., data cached by the specified
plugin is written to disk (or network or whatever), if the plugin supports
that operation.

Example: B<rrdtool>.

=item B<identifier=>I<E<lt>idE<gt>>

If this option is present, only the data specified by the specified identifier
(see below) will be flushed. Note that this option is not supported by all
plugins (e.E<nbsp>g., the C<network> plugin does not support this).

=back

In contrast to the plain-text protocol used by the C<unixsock> plugin, the
B<plugin> and B<identifier> options may only be specified once. If specified
multiple times, the last one overwrites the ones before.

=item B<listval>

Returns a list of all values (by their identifier) available to the
C<unixsock> plugin. Each value is printed on its own line. I.E<nbsp>e., this
command returns a list of valid identifiers that may be used with the other
commands.

=back

=head1 IDENTIFIERS

An identifier has the following format:

[I<hostname>/]I<plugin>[-I<plugin_instance>]/I<type>[-I<type_instance>]

Examples:
 somehost/cpu-0/cpu-idle
 uptime/uptime
 otherhost/memory/memory-used

Hostname defaults to the local (non-fully qualified) hostname if omitted. No
error is returned if the specified identifier does not exist (this is a
limitation in the C<libcollectdclient> library).

=head1 SEE ALSO

L<collectd(1)>
L<collectd.conf(5)>
L<collectd-unixsock(5)>

=head1 AUTHOR

collectd has been written by Florian Forster E<lt>octo at verplant.orgE<gt>
and many contributors (see `AUTHORS').

collectdctl has been written by
Håkon J Dugstad Johnsen E<lt>hakon-dugstad.johnsenE<nbsp>atE<nbsp>telenor.comE<gt>
and Sebastian Harl E<lt>sh at tokkee.orgE<gt>.

=cut