documentation for syslog2psyc

2 files changed, 75 insertions, 27 deletions

diff --git a/Makefile b/Makefile
index 3fc5de2..748c727 100644
--- a/Makefile
+++ b/Makefile
@@ -15,6 +15,7 @@ manuals: htdocs $I
         perldoc -oman bin/psyccmd >$M/man1/psyccmd.1
         perldoc -oman bin/psycplay >$M/man1/psycplay.1
         perldoc -oman bin/psyclisten >$M/man1/psyclisten.1
+        perldoc -oman bin/syslog2psyc >$M/man1/syslog2psyc.1
 
 html: htdocs
         perldoc -ohtml bin/remotor >htdocs/remotor.html
@@ -23,6 +24,7 @@ html: htdocs
         perldoc -ohtml bin/psyccmd >htdocs/psyccmd.html
         perldoc -ohtml bin/psycplay >htdocs/psycplay.html
         perldoc -ohtml bin/psyclisten >htdocs/psyclisten.html
+        perldoc -ohtml bin/syslog2psyc >htdocs/syslog2psyc.html
 
 htdocs:
         mkdir -p $@ $M/man1 $M/man3
diff --git a/bin/syslog2psyc b/bin/syslog2psyc
index f4a1c83..7aef0c7 100755
--- a/bin/syslog2psyc
+++ b/bin/syslog2psyc
@@ -3,43 +3,32 @@
 # forwards syslog events to a PSYC target.      -lynX 2006
 #
 # had i known how easy it is, i would have done this 1997
-#
-# first set up a pipe where we can get syslog events from:
-#       mkfifo /dev/syslog2psyc
-#       chown <user> /dev/syslog2psyc
-#
-# then configure /dev/syslog2psyc as the destination for 
-# syslog messages. in syslog-ng.conf it may look like this:
-#       destination psyc { pipe("/dev/syslog2psyc"); };
-#       log { source(src); destination(psyc); };
-#
-# in syslog.conf it may look like this:
-#       *.warn;*.err                    |/dev/syslog2psyc
-#
-# finally run this script as <user>
-# you may later want to refine the type of messages that are
-# forwarded to you.
-#
-# If you don't own an always running PSYC server yet,
-# visit http://www.psyced.org. The psyced LPC sandbox
-# runtime has a syslog.c ready to use in the place/ folder.
 
-$target  = shift;
-$pipe  = shift;
+require 5.000;
+use Net::PSYC;
+use Pod::Usage qw( pod2usage );
+
+$target = shift;
+$pipe = shift;
 $pipe = '/dev/syslog2psyc' unless -r $pipe;
 $pipe = '/dev/console' unless -r $pipe;
 $pipe = '/dev/xconsole' unless -r $pipe;
 $pipe = 0 unless -r $pipe;
 
-die <<X unless $target and $pipe;
-please provide target and pipe as parameters, as in
-    $0 psyc://localhost/\@syslog /dev/syslog2psyc
+unless ($target and $pipe) {
+        print STDERR <<X unless $target and $pipe;
+Please provide target and pipe as parameters, as in
+     $0 psyc://localhost/\@syslog /dev/syslog2psyc
+
+See 'perldoc syslog2psyc' for an installation manual.
+
 X
+        pod2usage;
+        exit;
+}
 
 $mc = '_notice_system_event';
 
-use Net::PSYC;
-
 $user = $ENV{'USER'};
 $host = $ENV{'HOST'};
 
@@ -60,4 +49,61 @@ close IN;
 
 # we indeed get here when syslog gets restarted.
 # should we sleep and try again?
+sleep 2;
+exit;
+
+
+__END__
+
+=pod
+
+=head1 NAME
+
+syslog2psyc - a daemon that forwards syslog events to a PSYC entity
+
+=head1 SYNOPSIS
+
+ syslog2psyc <target> [<pipe>]
+
+ <target> is a PSYC uniform to send syslog notices to.
+ <pipe> is a non-standard path to the syslog2psyc fifo
+
+=head1 INSTALLATION
+
+First set up a pipe where we can get syslog events from:
+        mkfifo /dev/syslog2psyc
+        chown <user> /dev/syslog2psyc
+
+Then configure /dev/syslog2psyc as the destination for 
+syslog messages. In syslog-ng.conf it may look like this:
+        destination psyc { pipe("/dev/syslog2psyc"); };
+        log { source(src); destination(psyc); };
+
+In syslog.conf it may look like this:
+        *.warn;*.err                    |/dev/syslog2psyc
+
+Finally run this script as <user>.
+You may later want to refine the type of messages that are
+forwarded to you.
+
+If you don't own an always running PSYC server yet,
+visit http://www.psyced.org. The psyced LPC sandbox
+runtime has a syslog.c ready to use in the place/ folder.
+It is reachable at psyc://localhost/\@syslog while your
+PSYC client can enter it by means of /subscribe syslog.
+
+=head1 CAVEATS
+
+As long as Net::PSYC does not provide any encryption, you
+should use this within a trustworthy local network or
+as a localhost service.
+
+=head1 AUTHORS
+
+carlo von lynX.
+
+=head1 COPYRIGHT
 
+This program is free software, published under the Affero GNU Public
+License. A disclaimer isn't necessary in my country, nor do I need
+to mention the current year to assert a copyright.