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