261 lines
11 KiB
XML
261 lines
11 KiB
XML
<!DOCTYPE refentry PUBLIC
|
|
"-//OASIS//DTD DocBook XML V4.1.2//EN"
|
|
"docbook/docbookx.dtd">
|
|
<refentry id='irkerd.8'>
|
|
<refmeta>
|
|
<refentrytitle>irkerd</refentrytitle>
|
|
<manvolnum>8</manvolnum>
|
|
<refmiscinfo class='date'>Aug 27 2012</refmiscinfo>
|
|
<refmiscinfo class='source'>irker</refmiscinfo>
|
|
<refmiscinfo class='product'>irker</refmiscinfo>
|
|
<refmiscinfo class='manual'>Commands</refmiscinfo>
|
|
</refmeta>
|
|
<refnamediv id='name'>
|
|
<refname>irkerd</refname>
|
|
<refpurpose>relay for shipping notifications to IRC servers</refpurpose>
|
|
</refnamediv>
|
|
<refsynopsisdiv id='synopsis'>
|
|
|
|
<cmdsynopsis>
|
|
<command>irkerd</command>
|
|
<arg>-c <replaceable>ca-file</replaceable></arg>
|
|
<arg>-d <replaceable>debuglevel</replaceable></arg>
|
|
<arg>-e <replaceable>cert-file</replaceable></arg>
|
|
<arg>-l <replaceable>logfile</replaceable></arg>
|
|
<arg>-H <replaceable>host</replaceable></arg>
|
|
<arg>-n <replaceable>nick</replaceable></arg>
|
|
<arg>-p <replaceable>password</replaceable></arg>
|
|
<arg>-P <replaceable>password-file</replaceable></arg>
|
|
<arg>-i <replaceable>IRC-URL</replaceable></arg>
|
|
<arg>-t <replaceable>timeout</replaceable></arg>
|
|
<arg>-V</arg>
|
|
<arg>-h</arg>
|
|
<arg choice='opt'><replaceable>message text</replaceable></arg>
|
|
</cmdsynopsis>
|
|
</refsynopsisdiv>
|
|
|
|
<refsect1 id='description'><title>DESCRIPTION</title>
|
|
|
|
<para><application>irkerd</application> is a specialized write-only IRC
|
|
client intended to be used for shipping notification messages to IRC
|
|
channels. The use case in mind when it was designed was broadcasting
|
|
notifications from commit hooks in version-control systems.</para>
|
|
|
|
<para>The main advantage of relaying through this daemon over
|
|
individual scripted sends from applications is that it can maintain
|
|
connection state for multiple channels, rather than producing obnoxious
|
|
join/leave channel spam on every message.</para>
|
|
|
|
<para><application>irkerd</application> is a socket server that
|
|
listens on for UDP or TCP packets on port 6659 for textual request
|
|
lines containing JSON objects and terminated by a newline. Each JSON
|
|
object must have two members: "to" specifying a destination or
|
|
destination list, and "privmsg" specifying the message text.
|
|
Examples:
|
|
|
|
<programlisting>
|
|
{"to":"irc://chat.freenode.net/git-ciabot", "privmsg":"Hello, world!"}
|
|
{"to":["irc://chat.freenode.net/#git-ciabot","irc://chat.freenode.net/#gpsd"],"privmsg":"Multichannel test"}
|
|
{"to":"irc://chat.hypothetical.net:6668/git-ciabot", "privmsg":"Hello, world!"}
|
|
{"to":"ircs://chat.hypothetical.net/git-private?key=topsecret", "privmsg":"Keyed channel test"}
|
|
{"to":"ircs://:topsecret@chat.example.net/git-private", "privmsg":"Password-protected server test"}
|
|
</programlisting></para>
|
|
|
|
<para>If the channel part of the URL does not have one of the prefix
|
|
characters <quote>#</quote>, <quote>&</quote>, or
|
|
<quote>+</quote>, a <quote>#</quote> will be prepended to it before
|
|
shipping - <emphasis>unless</emphasis> the channel part has the suffix
|
|
",isnick" (which is unconditionally removed).</para>
|
|
|
|
<para>The host part of the URL may have a port-number suffix separated by a
|
|
colon, as shown in the third example; otherwise
|
|
<application>irkerd</application> sends plaintext messages to the default
|
|
6667 IRC port of each server, and SSL/TLS messages to 6697.</para>
|
|
|
|
<para>The password for password-protected servers can be set using the
|
|
usual <quote>[{username}:{password}@]{host}:{port}</quote> defined in
|
|
RFC 3986, as shown in the fifth example. Non-empty URL usernames
|
|
override the default <quote>irker</quote> username.</para>
|
|
|
|
<para>When the <quote>to</quote> URL uses the <quote>ircs</quote>
|
|
scheme (as shown in the fourth and fifth examples), the connection to
|
|
the IRC server is made via SSL/TLS (vs. a plaintext connection with the
|
|
<quote>irc</quote> scheme). To connect via SSL/TLS with Python 2.x,
|
|
you need to explicitly declare the certificate authority file used to
|
|
verify server certificates. For example, <quote>-c
|
|
/etc/ssl/certs/ca-certificates.crt</quote>. In Python 3.2 and later,
|
|
you can still set this option to declare a custom CA file, but
|
|
<application>irkerd</application>; if you don't set it
|
|
<application>irkerd</application> will use OpenSSL's default file
|
|
(using Python's
|
|
<quote>ssl.SSLContext.set_default_verify_paths</quote>). In Python
|
|
3.2 and later, <quote>ssl.match_hostname</quote> is used to ensure the
|
|
server certificate belongs to the intended host, as well as being
|
|
signed by a trusted CA.</para>
|
|
|
|
<para>To join password-protected (mode +k) channels, the channel part of the
|
|
URL may be followed with a query-string indicating the channel key, of the
|
|
form <quote>?secret</quote> or <quote>?key=secret</quote>, where
|
|
<quote>secret</quote> is the channel key.</para>
|
|
|
|
<para>An empty message is legal and will cause
|
|
<application>irkerd</application> to join or maintain a connection to
|
|
the target channels without actually emitting a message. This may be
|
|
useful for advertising that an instance is up and running, or for
|
|
joining a channel to log its traffic.</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id='options'><title>OPTIONS</title>
|
|
|
|
<para><application>irkerd</application> takes the following options:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>-d</term>
|
|
<listitem>
|
|
<para>
|
|
Takes a following value, setting the debugging level from it;
|
|
possible values are 'critical', 'error', 'warning', 'info',
|
|
'debug'. This option will generally only be of interest to
|
|
developers, as the logs are designed to help trace
|
|
<application>irkerd</application>'s internal state. These tracing
|
|
logs are independent of the traffic logs controlled by
|
|
<quote>-l</quote>.
|
|
</para>
|
|
<para>
|
|
Logging will be to standard error (if
|
|
<application>irkerd</application> is running in the foreground) or
|
|
to <quote>/dev/syslog</quote> with facility "daemon" (if
|
|
<application>irkerd</application> is running in the background).
|
|
The background-ness of <application>irkerd</application> is
|
|
determined by comparing the process group id with the process
|
|
group associated with the terminal attached to stdout (with
|
|
non-matches for background processes). We assume you aren't
|
|
running <application>irkerd</application> in Windows or another OS
|
|
that doesn't support <quote>os.getpgrp</quote> or
|
|
<quote>tcgetpgrp</quote>. We assume that if stdout is attached to
|
|
a TTY associated with the same process group as
|
|
<application>irkerd</application>, you do intend to log to stderr
|
|
and not syslog.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-e</term>
|
|
<listitem><para>Takes a following filename in pem format and uses it
|
|
to authenticate to the IRC server. You must be connecting to the IRC server
|
|
over SSL for this to function properly. This is commonly known as
|
|
<quote>CertFP.</quote>
|
|
</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-e</term>
|
|
<listitem><para>Takes a following filename in pem format and uses it
|
|
to authenticate to the IRC server. You must be connecting to the IRC
|
|
server over SSL for this to function properly. This is commonly known
|
|
as <quote>CertFP.</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-l</term>
|
|
<listitem><para>Takes a following filename, logs traffic to that file.
|
|
Each log line consists of three |-separated fields; a numeric
|
|
timestamp in Unix time, the FQDN of the sending server, and the
|
|
message data.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-H</term>
|
|
<listitem><para>Takes a following hostname, and binds to that address
|
|
when listening for messages. <application>irkerd</application> binds
|
|
to localhost by default, but you may want to use your host's public
|
|
address to listen on a local network. Listening on a public interface
|
|
is not recommended, as it makes spamming IRC channels very
|
|
easy.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-n</term>
|
|
<listitem><para>Takes a following value, setting the nick
|
|
to be used. If the nick contains a numeric format element
|
|
(such as %03d) it is used to generate suffixed fallback names
|
|
in the event of a nick collision.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-p</term>
|
|
<listitem><para>Takes a following value, setting a nickserv
|
|
password to be used. If given, this password is shipped to
|
|
authenticate the nick on receipt of a welcome message.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-P</term>
|
|
<listitem><para>Liuke p, but the argument is interpreted as a filename
|
|
from which to read the password</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-t</term>
|
|
<listitem><para>Takes a following value, setting the connection
|
|
timeout for server-socket opens.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-i</term>
|
|
<listitem><para>Immediate mode, to be run in foreground. Takes a following
|
|
following value interpreted as a channel URL. May take a second
|
|
argument giving a message string; if the second argument is absent the
|
|
message is read from standard input (and may contain newlines).
|
|
Sends the message, then quits.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-V</term>
|
|
<listitem><para>Write the program version to stdout and
|
|
terminate.</para></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term>-h</term>
|
|
<listitem><para>Print usage instructions and terminate.</para></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</refsect1>
|
|
|
|
<refsect1 id='limitations'><title>LIMITATIONS</title>
|
|
<para>Requests via UDP optimizes for lowest latency and network load
|
|
by avoiding TCP connection setup time; the cost is that delivery is
|
|
not reliable in the face of packet loss.</para>
|
|
|
|
<para>An <application>irkerd</application> instance with a
|
|
publicly-accessible request socket could complicate blocking of IRC
|
|
spam by making it easy for spammers to submit while hiding their IP
|
|
addresses; the better way to deploy, then, is on places like
|
|
project-hosting sites where the <application>irkerd</application>
|
|
socket can be visible from commit-hook code but not exposed to the
|
|
outside world. Priming your firewall with blocklists of IP addresses
|
|
known to spew spam is always a good idea.</para>
|
|
|
|
<para>The absence of any option to set the service port is deliberate.
|
|
If you think you need to do that, you have a problem better solved at
|
|
your firewall.</para>
|
|
|
|
<para>IRC has a message length limit of 510 bytes; generate your
|
|
privmsg attribute values with appropriate care.</para>
|
|
|
|
<para>IRC ignores any text after an embedded newline. Be aware that
|
|
<application>irkerd</application> will turn payload strings with
|
|
embedded newlines into multiple IRC sends to avoid having message data
|
|
discarded. </para>
|
|
|
|
<para>Due to a bug in Python URL parsing, IRC urls with both a # and a
|
|
key part may fail unexpectedly. The workaround is to remove the #.</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id='see_also'><title>SEE ALSO</title>
|
|
<para>
|
|
<citerefentry><refentrytitle>irkerhook</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
|
|
</para>
|
|
</refsect1>
|
|
|
|
<refsect1 id='authors'><title>AUTHOR</title>
|
|
<para>Eric S. Raymond <email>esr@snark.thyrsus.com</email>. See the
|
|
project page at <ulink
|
|
url='http://www.catb.org/~esr/irker'>http://www.catb.org/~esr/irker</ulink>
|
|
for updates and other resources, including an installable repository
|
|
hook script.</para>
|
|
</refsect1>
|
|
</refentry>
|