irkerd.xml

   1 <!DOCTYPE refentry PUBLIC
   2    "-//OASIS//DTD DocBook XML V4.1.2//EN"
   3    "docbook/docbookx.dtd">
   4 <refentry id='irkerd.8'>
   5 <refmeta>
   6 <refentrytitle>irkerd</refentrytitle>
   7 <manvolnum>8</manvolnum>
   8 <refmiscinfo class='date'>Aug 27 2012</refmiscinfo>
   9 <refmiscinfo class='source'>irker</refmiscinfo>
  10 <refmiscinfo class='product'>irker</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>-l <replaceable>logfile</replaceable></arg>
  23      <arg>-V</arg>
  24 </cmdsynopsis>
  25 </refsynopsisdiv>
  26
  27 <refsect1 id='description'><title>DESCRIPTION</title>
  28
  29 <para><application>irkerd</application> is a specialized write-only IRC
  30 client intended to be used for shipping notification messages to IRC
  31 channels. The use case in mind when it was designed was broadcasting
  32 notifications from commit hooks in version-control systems.</para>
  33
  34 <para><application>irkerd</application> is a socket server that
  35 listens on for UDP or TCP packets on port 6659 for textual request
  36 lines containing JSON objects and terminated by a newline. Each JSON
  37 object must have two members: "to" specifying a destination or
  38 destination list, and "privmsg" specifying the message text.
  39 Examples:
  40
  41 <programlisting>
  42 {"to":"irc://chat.freenode.net/git-ciabot", "privmsg":"Hello, world!"}
  43 {"to":["irc://chat.freenode.net/#git-ciabot","irc://chat.freenode.net/#gpsd"],"privmsg":"Multichannel test"}
  44 {"to":"irc://chat.hypothetical.net:6668/git-ciabot", "privmsg":"Hello, world!"}
  45 </programlisting></para>
  46
  47 <para>If the channel part of the URL does not have one of the prefix
  48 characters <quote>#</quote>, <quote>&amp;</quote>, or
  49 <quote>+</quote>, a <quote>#</quote> will be prepended to it before
  50 shipping - <emphasis>unless</emphasis>the channel part has the suffix
  51 ",isnick" (which is unconditionally removed).</para>
  52
  53 <para>The host part of the URL may have a port-number suffix separated by a
  54 colon, as shown in the third example; otherwise
  55 <application>irkerd</application> sends messages to the the default 6667 IRC
  56 port of each server.</para>
  57
  58 <para>An empty message is legal and will cause
  59 <application>irkerd</application> to join the target channels without
  60 actually emitting a message.  This may be useful for advertising that
  61 an instance is up and running.</para>
  62 </refsect1>
  63
  64 <refsect1 id='options'><title>OPTIONS</title>
  65
  66 <para><application>irkerd</application> takes the following options:</para>
  67
  68 <variablelist>
  69 <varlistentry>
  70 <term>-d</term>
  71 <listitem><para>Takes a following value, setting the debugging level from
  72 it. This option will generally only be of interest to developers;
  73 consult the source code for details.</para></listitem>
  74 </varlistentry>
  75 <varlistentry>
  76 <term>-l</term>
  77 <listitem><para>Takes a following filename, logs traffic to that file.
  78 Each log line consists of three |-separated fields; a numeric
  79 timestamp in Unix time, the fqdn of the sending server, and the
  80 message data.</para></listitem>
  81 </varlistentry>
  82 <varlistentry>
  83 <term>-V</term>
  84 <listitem><para>Write the program version to stdout and
  85 terminate.</para></listitem>
  86 </varlistentry>
  87 </variablelist>
  88
  89 </refsect1>
  90
  91 <refsect1 id='limitations'><title>LIMITATIONS</title>
  92 <para>Requests via UDP optimizes for lowest latency and network load
  93 by avoiding TCP connection setup time; the cost is that delivery is
  94 not reliable in the face of packet loss.</para>
  95
  96 <para>An <application>irkerd</application> instance with a
  97 publicly-accessible request socket could complicate blocking of IRC
  98 spam by making it easy for spammers to submit while hiding their IP
  99 addresses; the better way to deploy, then, is on places like
 100 project-hosting sites where the <application>irkerd</application>
 101 socket can be visible from commit-hook code but not exposed to the
 102 outside world. Priming your firewall with blocklists of IP addresses
 103 known to spew spam is always a good idea.</para>
 104
 105 <para>The absence of any option to set the service port is deliberate.
 106 If you think you need to do that, you have a problem better solved at
 107 your firewall.</para>
 108
 109 <para>IRC has a message length limit of 510 bytes; generate your
 110 privmsg attribute values with appropriate care.</para>
 111
 112 <para>IRC ignores any text after an embedded newline. Be aware that
 113 <application>irkerd</application> will turn payload strings with
 114 embedded newlines into multiple IRC sends to avoid having message data
 115 discarded. </para>
 116 </refsect1>
 117
 118 <refsect1 id='see_also'><title>SEE ALSO</title>
 119 <para>
 120 <citerefentry><refentrytitle>irkerhook</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 121 </para>
 122 </refsect1>
 123
 124 <refsect1 id='authors'><title>AUTHOR</title>
 125 <para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>.  See the
 126 project page at <ulink
 127 url='http://www.catb.org/~esr/irker'>http://www.catb.org/~esr/irker</ulink>
 128 for updates and other resources, including an installable repository
 129 hook script. The implementation uses the Python IRC library by Joe
 130 Rosdahl and Jason R. Coombs.</para>
 131 </refsect1>
 132 </refentry>
 133