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