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