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