From af0e35f99c0988c564067ae376253422ce215090 Mon Sep 17 00:00:00 2001
From: Florian Forster <octo@leeloo.lan.home.verplant.org>
Date: Sat, 19 May 2007 13:57:02 +0200
Subject: [PATCH] collectd-unixsock(5): Moved information about the `unixsock
 plugin' into an own manpage.

---
 src/Makefile.am           |   2 +-
 src/collectd-unixsock.pod | 102 ++++++++++++++++++++++++++++++++++++++++++++++
 src/collectd.pod          |   4 +-
 3 files changed, 106 insertions(+), 2 deletions(-)
 create mode 100644 src/collectd-unixsock.pod

diff --git a/src/Makefile.am b/src/Makefile.am
index 75d95d26..ea08a3e2 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -549,7 +549,7 @@ collectd_LDADD += "-dlopen" wireless.la
 collectd_DEPENDENCIES += wireless.la
 endif
 
-dist_man_MANS = collectd.1 collectd-nagios.1 collectd.conf.5 collectd-exec.5
+dist_man_MANS = collectd.1 collectd-nagios.1 collectd.conf.5 collectd-exec.5 collectd-unixsock.5
 #collectd_1_SOURCES = collectd.pod
 
 EXTRA_DIST = types.db
diff --git a/src/collectd-unixsock.pod b/src/collectd-unixsock.pod
new file mode 100644
index 00000000..68756949
--- /dev/null
+++ b/src/collectd-unixsock.pod
@@ -0,0 +1,102 @@
+=head1 NAME
+
+collectd-unixsock - Documentation of collectd's C<unixsock plugin>
+
+=head1 SYNOPSIS
+
+  # See collectd.conf(5)
+  LoadPlugin unixsock
+  # ...
+  <Plugin unixsock>
+    SocketFile "/path/to/socket"
+    SocketGroup "collectd"
+    SocketPerms "0770"
+  </Plugin>
+
+=head1 DESCRIPTION
+
+The C<unixsock plugin> 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, or submit externally collected values to
+collectd.
+
+=head1 COMMANDS
+
+Upon start the C<unixsock plugin> 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.
+
+The following commands are implemented:
+
+=over 4
+
+=item B<GETVAL> I<Identifier>
+
+If the value identified by I<Identifier> (see below) is found the complete
+value-list is returned. The response is a space seperated list of
+name-value-pairs:
+
+I<num> I<name>B<=>I<value>[ I<name>B<=>I<value>[ ...]]
+
+If I<num> is less then zero, an error occured. Otherwise it contains the
+number of values that follow. Each value is of the form I<name>B<=>I<value>.
+Counter-values are converted to a rate, e.E<nbsp>g. bytes per second.
+Undefined values are returned as B<NaN>.
+
+Example:
+  -> | GETVAL myhost/cpu-0/cpu-user
+  <- | 1 value=1.260000e+00
+
+=item B<PUTVAL> I<Identifier> I<Valuelist>
+
+Submits a value (identified by I<Identifier>, see below) to the daemon which
+will dispatch it to all it's write-plugins. The I<Valuelist> is a
+colon-seperated list of values, either an integer if the data-source is a
+counter, of a double if the data-source if of type "gauge". You can submit an
+undefined gauge-value by using B<U>. When submitting B<U> to a counter the
+behavior is undefined.
+
+Example:
+  -> | PUTVAL testhost/interface/if_octets-test0 1179574444:123:456
+  <- | 0 Success
+
+=back
+
+=head2 Identifiers
+
+Value or value-lists are identified in a uniform fassion:
+
+I<Hostname>/I<Plugin>/I<Type>
+
+Where I<Plugin> and I<Type> are both either of type "I<Name>" or
+"I<Name>-I<Instance>". This sounds more complicated than it is, so here are
+some examples:
+
+  myhost/cpu-0/cpu-user
+  myhost/load/load
+  myhost/memory/memory-used
+  myhost/disk-sda/disk_octets
+
+=head2 Return values
+
+Unless otherwise noted the plugin answers with a line of the following form:
+
+I<Num> I<Message>
+
+If I<Num> is zero the message indicates success, if I<Num> is non-zero the
+message indicates failure. I<Message> is a human-readable string that describes
+the return value further.
+
+Commands that return values may use I<Num> to return the number of values that
+follow, such as the B<GETVAL> command. These commands usually return a negative
+value on failure and never return zero.
+
+=head1 SEE ALSO
+
+L<collectd(1)>, L<collectd.conf(5)>, L<unix(7)>
+
+=head1 AUTHOR
+
+Florian Forster E<lt>octo@verplant.orgE<gt>
+
+=cut
diff --git a/src/collectd.pod b/src/collectd.pod
index 5449d0eb..85fddcb2 100644
--- a/src/collectd.pod
+++ b/src/collectd.pod
@@ -82,7 +82,8 @@ Several loglevels let you suppress uninteresting messages.
 
 Please note that some plugins, that provide other means of communicating with
 the daemon, have manpages of their own to describe their functionality in more
-detail. In particular those are L<collectd-exec(5)>, ...
+detail. In particular those are L<collectd-exec(5)>, L<collectd-unixsock(5)>,
+...
 
 =head1 SPECIAL PLUGINS
 
@@ -323,6 +324,7 @@ The B<VServer> homepage can be found at L<http://linux-vserver.org/>.
 
 L<collectd.conf(5)>,
 L<collectd-exec(5)>,
+L<collectd-unixsock(5)>,
 L<hddtemp(8)>,
 L<kstat(3KSTAT)>,
 L<mbmon(1)>,
-- 
2.11.0