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>-c <replaceable>ca-file</replaceable></arg>
  22      <arg>-d <replaceable>debuglevel</replaceable></arg>
  23      <arg>--syslog</arg>
  24      <arg>-l <replaceable>logfile</replaceable></arg>
  25      <arg>-H <replaceable>host</replaceable></arg>
  26      <arg>-P <replaceable>port</replaceable></arg>
  27      <arg>-n <replaceable>nick</replaceable></arg>
  28      <arg>-p <replaceable>password</replaceable></arg>
  29      <arg>-i <replaceable>IRC-URL</replaceable></arg>
  30      <arg>-V</arg>
  31      <arg>-h</arg>
  32      <arg choice='opt'><replaceable>message text</replaceable></arg>
  33 </cmdsynopsis>
  34 </refsynopsisdiv>
  35
  36 <refsect1 id='description'><title>DESCRIPTION</title>
  37
  38 <para><application>irkerd</application> is a specialized write-only IRC
  39 client intended to be used for shipping notification messages to IRC
  40 channels. The use case in mind when it was designed was broadcasting
  41 notifications from commit hooks in version-control systems.</para>
  42
  43 <para>The main advantage of relaying through this daemon over
  44 individual scripted sends from applications is that it can maintain
  45 connection state for multiple channels, rather than producing obnoxious
  46 join/leave channel spam on every message.</para>
  47
  48 <para><application>irkerd</application> is a socket server that
  49 listens on for UDP or TCP packets on port 6659 for textual request
  50 lines containing JSON objects and terminated by a newline. Each JSON
  51 object must have two members: "to" specifying a destination or
  52 destination list, and "privmsg" specifying the message text.
  53 Examples:
  54
  55 <programlisting>
  56 {"to":"irc://chat.freenode.net/git-ciabot", "privmsg":"Hello, world!"}
  57 {"to":["irc://chat.freenode.net/#git-ciabot","irc://chat.freenode.net/#gpsd"],"privmsg":"Multichannel test"}
  58 {"to":"irc://chat.hypothetical.net:6668/git-ciabot", "privmsg":"Hello, world!"}
  59 {"to":"ircs://chat.hypothetical.net/git-private?key=topsecret", "privmsg":"Keyed channel test"}
  60 {"to":"ircs://:topsecret@chat.example.net/git-private", "privmsg":"Password-protected server test"}
  61 </programlisting></para>
  62
  63 <para>If the channel part of the URL does not have one of the prefix
  64 characters <quote>#</quote>, <quote>&amp;</quote>, or
  65 <quote>+</quote>, a <quote>#</quote> will be prepended to it before
  66 shipping - <emphasis>unless</emphasis>the channel part has the suffix
  67 ",isnick" (which is unconditionally removed).</para>
  68
  69 <para>The host part of the URL may have a port-number suffix separated by a
  70 colon, as shown in the third example; otherwise
  71 <application>irkerd</application> sends plaintext messages to the default
  72 6667 IRC port of each server, and SSL/TLS messages to 6697.</para>
  73
  74 <para>The password for password-protected servers can be set using the
  75 usual <quote>[{username}:{password}@]{host}:{port}</quote> defined in
  76 RFC 3986, as shown in the fifth example.  Non-empty URL usernames
  77 override the default <quote>irker</quote> username.</para>
  78
  79 <para>When the <quote>to</quote> URL uses the <quote>ircs</quote>
  80 scheme (as shown in the fourth and fifth examples), the connection to
  81 the IRC server is made via SSL/TLS (vs. a plaintext connection with the
  82 <quote>irc</quote> scheme).  To connect via SSL/TLS with Python 2.x,
  83 you need to explicitly declare the certificate authority file used to
  84 verify server certificates.  For example, <quote>-c
  85 /etc/ssl/certs/ca-certificates.crt</quote>.  In Python 3.2 and later,
  86 you can still set this option to declare a custom CA file, but
  87 <application>irkerd</application>; if you don't set it
  88 <application>irkerd</application> will use OpenSSL's default file
  89 (using Python's
  90 <quote>ssl.SSLContext.set_default_verify_paths</quote>).  In Python
  91 3.2 and later, <quote>ssl.match_hostname</quote> is used to ensure the
  92 server certificate belongs to the intended host, as well as being
  93 signed by a trusted CA.</para>
  94
  95 <para>To join password-protected (mode +k) channels, the channel part of the
  96 URL may be followed with a query-string indicating the channel key, of the
  97 form <quote>?secret</quote> or <quote>?key=secret</quote>, where
  98 <quote>secret</quote> is the channel key.</para>
  99
 100 <para>An empty message is legal and will cause
 101 <application>irkerd</application> to join or maintain a connection to
 102 the target channels without actually emitting a message.  This may be
 103 useful for advertising that an instance is up and running, or for
 104 joining a channel to log its traffic.</para>
 105 </refsect1>
 106
 107 <refsect1 id='options'><title>OPTIONS</title>
 108
 109 <para><application>irkerd</application> takes the following options:</para>
 110
 111 <variablelist>
 112 <varlistentry>
 113 <term>-d</term>
 114 <listitem><para>Takes a following value, setting the debugging level from
 115 it. This option will generally only be of interest to developers;
 116 consult the source code for details.</para></listitem>
 117 </varlistentry>
 118 <varlistentry>
 119 <term>--syslog</term>
 120 <listitem><para>Writes debugging ouput to syslog (via /dev/log)
 121 instead of printing to stderr.</para></listitem>
 122 </varlistentry>
 123 <varlistentry>
 124 <term>-l</term>
 125 <listitem><para>Takes a following filename, logs traffic to that file.
 126 Each log line consists of three |-separated fields; a numeric
 127 timestamp in Unix time, the FQDN of the sending server, and the
 128 message data.</para></listitem>
 129 </varlistentry>
 130 <varlistentry>
 131 <term>-H</term>
 132 <listitem><para>Takes a following hostname, and binds to that address
 133 when listening for messages.  <application>irkerd</application> binds
 134 to localhost by default, but you may want to use your host's public
 135 address to listen on a local network.  Listening on a public interface
 136 is not recommended, as it makes spamming IRC channels very
 137 easy.</para></listitem>
 138 </varlistentry>
 139 <varlistentry>
 140 <term>-P</term>
 141 <listitem><para>Takes a following port number, and binds to that port
 142 when listening for messages.  <application>irkerd</application> binds
 143 to port 6659 by default.</para></listitem>
 144 </varlistentry>
 145 <varlistentry>
 146 <term>-n</term>
 147 <listitem><para>Takes a following value, setting the nick
 148 to be used. If the nick contains a numeric format element
 149 (such as %03d) it is used to generate suffixed fallback names
 150 in the event of a nick collision.</para></listitem>
 151 </varlistentry>
 152 <varlistentry>
 153 <term>-p</term>
 154 <listitem><para>Takes a following value, setting a nickserv
 155 password to be used. If given, this password is shipped to
 156 authenticate the nick on receipt of a welcome message.</para></listitem>
 157 </varlistentry>
 158 <varlistentry>
 159 <term>-i</term>
 160 <listitem><para>Immediate mode, to be run in foreground. Takes two
 161 following values interpreted as a channel URL and a message
 162 string. Sends the message, then quits.</para></listitem>
 163 </varlistentry>
 164 <varlistentry>
 165 <term>-V</term>
 166 <listitem><para>Write the program version to stdout and
 167 terminate.</para></listitem>
 168 </varlistentry>
 169 <varlistentry>
 170 <term>-h</term>
 171 <listitem><para>Print usage instructions and terminate.</para></listitem>
 172 </varlistentry>
 173 </variablelist>
 174
 175 </refsect1>
 176
 177 <refsect1 id='limitations'><title>LIMITATIONS</title>
 178 <para>Requests via UDP optimizes for lowest latency and network load
 179 by avoiding TCP connection setup time; the cost is that delivery is
 180 not reliable in the face of packet loss.</para>
 181
 182 <para>An <application>irkerd</application> instance with a
 183 publicly-accessible request socket could complicate blocking of IRC
 184 spam by making it easy for spammers to submit while hiding their IP
 185 addresses; the better way to deploy, then, is on places like
 186 project-hosting sites where the <application>irkerd</application>
 187 socket can be visible from commit-hook code but not exposed to the
 188 outside world. Priming your firewall with blocklists of IP addresses
 189 known to spew spam is always a good idea.</para>
 190
 191 <para>IRC has a message length limit of 510 bytes; generate your
 192 privmsg attribute values with appropriate care.</para>
 193
 194 <para>IRC ignores any text after an embedded newline. Be aware that
 195 <application>irkerd</application> will turn payload strings with
 196 embedded newlines into multiple IRC sends to avoid having message data
 197 discarded. </para>
 198 </refsect1>
 199
 200 <refsect1 id='see_also'><title>SEE ALSO</title>
 201 <para>
 202 <citerefentry><refentrytitle>irkerhook</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 203 </para>
 204 </refsect1>
 205
 206 <refsect1 id='authors'><title>AUTHOR</title>
 207 <para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>.  See the
 208 project page at <ulink
 209 url='http://www.catb.org/~esr/irker'>http://www.catb.org/~esr/irker</ulink>
 210 for updates and other resources, including an installable repository
 211 hook script.</para>
 212 </refsect1>
 213 </refentry>
 214