irkerd.xml

   1 <!DOCTYPE refentry PUBLIC
   2    "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3    "docbook/docbookx.dtd">
   4 <refentry id='irkerd.1'>
   5 <refmeta>
   6 <refentrytitle>irkerd</refentrytitle>
   7 <manvolnum>1</manvolnum>
   8 <refmiscinfo class='date'>Aug 27 2012</refmiscinfo>
   9 <refmiscinfo class='source'>irkerd</refmiscinfo>
  10 <refmiscinfo class='product'>irkerd</refmiscinfo>
  11 <refmiscinfo class='manual'>Commands</refmiscinfo>
  12 </refmeta>
  13 <refnamediv id='name'>
  14 <refname>irkerd</refname>
  15 <refpurpose>relay for shipping notifications to IRC servers</refpurpose>
  16 </refnamediv>
  17 <refsynopsisdiv id='synopsis'>
  18
  19 <cmdsynopsis>
  20   <command>irkerd</command>
  21      <arg>-d <replaceable>debuglevel</replaceable></arg>
  22      <arg>-V</arg>
  23 </cmdsynopsis>
  24 </refsynopsisdiv>
  25
  26 <refsect1 id='description'><title>DESCRIPTION</title>
  27
  28 <para><application>irkerd</application> is a specialized write-only IRC
  29 client intended to be used for shipping notification messages to IRC
  30 channels. The use case in mind when it was designed was broadcasting
  31 notifications from commit hooks in version-control systems.</para>
  32
  33 <para><application>irkerd</application> is a socket server that
  34 listens on for UDP or TCP packets on port 6659 for textual request
  35 lines containing JSON objects and terminated by a newline. Each JSON
  36 object must have two members: "to" specifying a destination or
  37 destination list, and "privmsg" specifying the message test.
  38 Examples:
  39
  40 <programlisting>
  41 {"to":"irc://chat.freenode.net/git-ciabot", "privmsg":"Hello, world!"}
  42 {"to":["irc://chat.freenode.net/#git-ciabot","irc://chat.freenode.net/#gpsd"],"privmsg":"Multichannel test"}
  43 {"to":"irc://chat.hypothetical.net:6668/git-ciabot", "privmsg":"Hello, world!"}
  44 </programlisting></para>
  45
  46 <para>If the channel part of the URL does not have one of the prefix characters
  47 <quote>#</quote>, <quote>&amp;</quote>, or <quote>+</quote>, a <quote>#</quote>
  48 will be prepended to it before shipping.</para>
  49
  50 <para>The host part of the URL may have a port-number suffix separated by a
  51 colon, as shown in the third example; otherwise
  52 <application>irkerd</application> sends messages to the the default 6667 IRC
  53 port of each server.</para>
  54 </refsect1>
  55
  56 <refsect1 id='options'><title>OPTIONS</title>
  57
  58 <para><application>irkerd</application> takes the following options:</para>
  59
  60 <variablelist>
  61 <varlistentry>
  62 <term>-d</term>
  63 <listitem><para>Takes a following value, setting the debugging level from
  64 it. This option will generally only be of interest to developers;
  65 consult the source code for details.</para></listitem>
  66 </varlistentry>
  67 <varlistentry>
  68 <term>-V</term>
  69 <listitem><para>Write the program version to stdout and
  70 terminate.</para></listitem>
  71 </varlistentry>
  72 </variablelist>
  73
  74 </refsect1>
  75
  76 <refsect1 id='limitations'><title>LIMITATIONS</title>
  77 <para>Requests via UDP optimizes for lowest latency and network load
  78 by avoiding TCP connection setup time; the cost is that delivery is
  79 not reliable in the face of packet loss.</para>
  80
  81 <para>An <application>irkerd</application> instance with a
  82 publicly-accessible request socket could complicate blocking of IRC
  83 spam by making it easy for spammers to submit while hiding their IP
  84 addresses; the better way to deploy, then, is on places like
  85 project-hosting sites where the <application>irkerd</application>
  86 socket can be visible from commit-hook code but not exposed to the
  87 outside world. Priming your firewall with blocklists of IP addresses
  88 known to spew spam is always a good idea.</para>
  89
  90 <para>The absence of any option to set the service port is deliberate.
  91 If you think you need to do that, you have a problem better solved at
  92 your firewall.</para>
  93
  94 <para>IRC has a message length limit of 510 bytes and ignores any text
  95 after an embedded \n; generate your privmsg attribute values with
  96 appropriate care.</para>
  97 </refsect1>
  98
  99 <refsect1 id='authors'><title>AUTHOR</title>
 100 <para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>.  See the
 101 project page at <ulink
 102 url='http://www.catb.org/~esr/'>http://www.catb.org/~esr/irker</ulink>
 103 for updates and other resources, including an insrtallable repository
 104 hook script. The implementation uses the Python IRC library by Joe
 105 Rosdahl and Jason R. Coombs.</para>
 106 </refsect1>
 107 </refentry>
 108