irkerd.xml: Cleanup syslog docs and shift 'os' import

[irker.git] / irkerd.xml

<!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>-l <replaceable>logfile</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> or <quote>.  We also assume that you have
    stdout attached to a TTY (and haven't closed or redirected it).
    We also 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>
</refsect1>
</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>-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 two
following values interpreted as a channel URL and a message
string. 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 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>
</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>