Adding upstream version 2.18+dfsg.upstream/2.18+dfsgupstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 249 insertions, 0 deletions

diff --git a/irkerd.xml b/irkerd.xml
new file mode 100644
index 0000000..59b7dae
--- /dev/null
+++ b/irkerd.xml
@@ -0,0 +1,249 @@
+<!DOCTYPE refentry PUBLIC 
+   "-//OASIS//DTD DocBook XML V4.1.2//EN"
+   "docbook/docbookx.dtd">
+<refentry id='irkerd.8'>
+<refmeta>
+<refentrytitle>irkerd</refentrytitle>
+<manvolnum>8</manvolnum>
+<refmiscinfo class='date'>Aug 27 2012</refmiscinfo>
+<refmiscinfo class='source'>irker</refmiscinfo>
+<refmiscinfo class='product'>irker</refmiscinfo>
+<refmiscinfo class='manual'>Commands</refmiscinfo>
+</refmeta>
+<refnamediv id='name'>
+<refname>irkerd</refname>
+<refpurpose>relay for shipping notifications to IRC servers</refpurpose>
+</refnamediv>
+<refsynopsisdiv id='synopsis'>
+
+<cmdsynopsis>
+  <command>irkerd</command>
+     <arg>-c <replaceable>ca-file</replaceable></arg>
+     <arg>-d <replaceable>debuglevel</replaceable></arg>
+     <arg>-e <replaceable>cert-file</replaceable></arg>
+     <arg>-l <replaceable>logfile</replaceable></arg>
+     <arg>-H <replaceable>host</replaceable></arg>
+     <arg>-n <replaceable>nick</replaceable></arg>
+     <arg>-p <replaceable>password</replaceable></arg>
+     <arg>-i <replaceable>IRC-URL</replaceable></arg>
+     <arg>-V</arg>
+     <arg>-h</arg>
+     <arg choice='opt'><replaceable>message text</replaceable></arg>
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1 id='description'><title>DESCRIPTION</title>
+
+<para><application>irkerd</application> is a specialized write-only IRC
+client intended to be used for shipping notification messages to IRC
+channels. The use case in mind when it was designed was broadcasting
+notifications from commit hooks in version-control systems.</para>
+
+<para>The main advantage of relaying through this daemon over
+individual scripted sends from applications is that it can maintain
+connection state for multiple channels, rather than producing obnoxious
+join/leave channel spam on every message.</para>
+
+<para><application>irkerd</application> is a socket server that
+listens on for UDP or TCP packets on port 6659 for textual request
+lines containing JSON objects and terminated by a newline. Each JSON
+object must have two members: "to" specifying a destination or
+destination list, and "privmsg" specifying the message text.
+Examples:
+
+<programlisting>
+{"to":"irc://chat.freenode.net/git-ciabot", "privmsg":"Hello, world!"}
+{"to":["irc://chat.freenode.net/#git-ciabot","irc://chat.freenode.net/#gpsd"],"privmsg":"Multichannel test"}
+{"to":"irc://chat.hypothetical.net:6668/git-ciabot", "privmsg":"Hello, world!"}
+{"to":"ircs://chat.hypothetical.net/git-private?key=topsecret", "privmsg":"Keyed channel test"}
+{"to":"ircs://:topsecret@chat.example.net/git-private", "privmsg":"Password-protected server test"}
+</programlisting></para>
+
+<para>If the channel part of the URL does not have one of the prefix
+characters <quote>#</quote>, <quote>&amp;</quote>, or
+<quote>+</quote>, a <quote>#</quote> will be prepended to it before
+shipping - <emphasis>unless</emphasis> the channel part has the suffix
+",isnick" (which is unconditionally removed).</para>
+
+<para>The host part of the URL may have a port-number suffix separated by a
+colon, as shown in the third example; otherwise
+<application>irkerd</application> sends plaintext messages to the default
+6667 IRC port of each server, and SSL/TLS messages to 6697.</para>
+
+<para>The password for password-protected servers can be set using the
+usual <quote>[{username}:{password}@]{host}:{port}</quote> defined in
+RFC 3986, as shown in the fifth example.  Non-empty URL usernames
+override the default <quote>irker</quote> username.</para>
+
+<para>When the <quote>to</quote> URL uses the <quote>ircs</quote>
+scheme (as shown in the fourth and fifth examples), the connection to
+the IRC server is made via SSL/TLS (vs. a plaintext connection with the
+<quote>irc</quote> scheme).  To connect via SSL/TLS with Python 2.x,
+you need to explicitly declare the certificate authority file used to
+verify server certificates.  For example, <quote>-c
+/etc/ssl/certs/ca-certificates.crt</quote>.  In Python 3.2 and later,
+you can still set this option to declare a custom CA file, but
+<application>irkerd</application>; if you don't set it
+<application>irkerd</application> will use OpenSSL's default file
+(using Python's
+<quote>ssl.SSLContext.set_default_verify_paths</quote>).  In Python
+3.2 and later, <quote>ssl.match_hostname</quote> is used to ensure the
+server certificate belongs to the intended host, as well as being
+signed by a trusted CA.</para>
+
+<para>To join password-protected (mode +k) channels, the channel part of the
+URL may be followed with a query-string indicating the channel key, of the
+form <quote>?secret</quote> or <quote>?key=secret</quote>, where
+<quote>secret</quote> is the channel key.</para>
+
+<para>An empty message is legal and will cause
+<application>irkerd</application> to join or maintain a connection to
+the target channels without actually emitting a message.  This may be
+useful for advertising that an instance is up and running, or for
+joining a channel to log its traffic.</para>
+</refsect1>
+
+<refsect1 id='options'><title>OPTIONS</title>
+
+<para><application>irkerd</application> takes the following options:</para>
+
+<variablelist>
+<varlistentry>
+<term>-d</term>
+<listitem>
+  <para>
+    Takes a following value, setting the debugging level from it;
+    possible values are 'critical', 'error', 'warning', 'info',
+    'debug'. This option will generally only be of interest to
+    developers, as the logs are designed to help trace
+    <application>irkerd</application>'s internal state.  These tracing
+    logs are independent of the traffic logs controlled by
+    <quote>-l</quote>.
+  </para>
+  <para>
+    Logging will be to standard error (if
+    <application>irkerd</application> is running in the foreground) or
+    to <quote>/dev/syslog</quote> with facility "daemon" (if
+    <application>irkerd</application> is running in the background).
+    The background-ness of <application>irkerd</application> is
+    determined by comparing the process group id with the process
+    group associated with the terminal attached to stdout (with
+    non-matches for background processes).  We assume you aren't
+    running <application>irkerd</application> in Windows or another OS
+    that doesn't support <quote>os.getpgrp</quote> or
+    <quote>tcgetpgrp</quote>.  We assume that if stdout is attached to
+    a TTY associated with the same process group as
+    <application>irkerd</application>, you do intend to log to stderr
+    and not syslog.
+  </para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>-e</term>
+<listitem><para>Takes a following filename in pem format and uses it
+to authenticate to the IRC server.  You must be connecting to the IRC server
+over SSL for this to function properly.  This is commonly known as
+<quote>CertFP.</quote>
+</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>-e</term>
+<listitem><para>Takes a following filename in pem format and uses it
+to authenticate to the IRC server.  You must be connecting to the IRC
+server over SSL for this to function properly.  This is commonly known
+as <quote>CertFP.</quote></para>
+</listitem>
+</varlistentry>
+<varlistentry>
+<term>-l</term>
+<listitem><para>Takes a following filename, logs traffic to that file.
+Each log line consists of three |-separated fields; a numeric
+timestamp in Unix time, the FQDN of the sending server, and the
+message data.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>-H</term>
+<listitem><para>Takes a following hostname, and binds to that address
+when listening for messages.  <application>irkerd</application> binds
+to localhost by default, but you may want to use your host's public
+address to listen on a local network.  Listening on a public interface
+is not recommended, as it makes spamming IRC channels very
+easy.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>-n</term>
+<listitem><para>Takes a following value, setting the nick
+to be used. If the nick contains a numeric format element
+(such as %03d) it is used to generate suffixed fallback names
+in the event of a nick collision.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>-p</term>
+<listitem><para>Takes a following value, setting a nickserv
+password to be used. If given, this password is shipped to
+authenticate the nick on receipt of a welcome message.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>-i</term>
+<listitem><para>Immediate mode, to be run in foreground. Takes a following
+following value interpreted as a channel URL. May take a second
+argument giving a message string; if the second argument is absent the
+message is read from standard input (and may contain newlines). 
+Sends the message, then quits.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>-V</term>
+<listitem><para>Write the program version to stdout and
+terminate.</para></listitem>
+</varlistentry>
+<varlistentry>
+<term>-h</term>
+<listitem><para>Print usage instructions and terminate.</para></listitem>
+</varlistentry>
+</variablelist>
+</refsect1>
+
+<refsect1 id='limitations'><title>LIMITATIONS</title>
+<para>Requests via UDP optimizes for lowest latency and network load
+by avoiding TCP connection setup time; the cost is that delivery is
+not reliable in the face of packet loss.</para>
+
+<para>An <application>irkerd</application> instance with a
+publicly-accessible request socket could complicate blocking of IRC
+spam by making it easy for spammers to submit while hiding their IP
+addresses; the better way to deploy, then, is on places like
+project-hosting sites where the <application>irkerd</application>
+socket can be visible from commit-hook code but not exposed to the
+outside world. Priming your firewall with blocklists of IP addresses
+known to spew spam is always a good idea.</para>
+
+<para>The absence of any option to set the service port is deliberate.
+If you think you need to do that, you have a problem better solved at
+your firewall.</para>
+
+<para>IRC has a message length limit of 510 bytes; generate your
+privmsg attribute values with appropriate care.</para>
+
+<para>IRC ignores any text after an embedded newline. Be aware that
+<application>irkerd</application> will turn payload strings with
+embedded newlines into multiple IRC sends to avoid having message data
+discarded. </para>
+
+<para>Due to a bug in Python URL parsing, IRC urls with both a # and a
+key part may fail unexpectedly.  The workaround is to remove the #.</para>
+</refsect1>
+
+<refsect1 id='see_also'><title>SEE ALSO</title>
+<para>
+<citerefentry><refentrytitle>irkerhook</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
+</para>
+</refsect1>
+
+<refsect1 id='authors'><title>AUTHOR</title>
+<para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>.  See the
+project page at <ulink
+url='http://www.catb.org/~esr/irker'>http://www.catb.org/~esr/irker</ulink>
+for updates and other resources, including an installable repository
+hook script.</para>
+</refsect1>
+</refentry>