<!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.1.2//EN"
"docbook/docbookx.dtd">
-<refentry id='irkerd.1'>
+<refentry id='irkerd.8'>
<refmeta>
<refentrytitle>irkerd</refentrytitle>
-<manvolnum>1</manvolnum>
+<manvolnum>8</manvolnum>
<refmiscinfo class='date'>Aug 27 2012</refmiscinfo>
-<refmiscinfo class='source'>irkerd</refmiscinfo>
-<refmiscinfo class='product'>irkerd</refmiscinfo>
+<refmiscinfo class='source'>irker</refmiscinfo>
+<refmiscinfo class='product'>irker</refmiscinfo>
<refmiscinfo class='manual'>Commands</refmiscinfo>
</refmeta>
<refnamediv id='name'>
<cmdsynopsis>
<command>irkerd</command>
<arg>-d <replaceable>debuglevel</replaceable></arg>
+ <arg>-l <replaceable>logfile</replaceable></arg>
+ <arg>-n <replaceable>nick</replaceable></arg>
+ <arg>-p <replaceable>password</replaceable></arg>
+ <arg>-i <replaceable>IRC-URL</replaceable></arg>
<arg>-V</arg>
+ <arg>-h</arg>
+ <arg choice='opt'><replaceable>message text</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
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 test.
+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":"irc://chat.hypothetical.net:6668/git-private?key=topsecret", "privmsg":"Keyed channel 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.</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 messages to the the default 6667 IRC
port of each server.</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>
consult the source code for details.</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>-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>-i</term>
+<listitem><para>Immediate mode, to be run in foreground. Takes two
+following values interpreted as a channel URL and a message
+string. 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>
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 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 strungs with
+<application>irkerd</application> will turn payload strings with
embedded newlines into multiple IRC sends to avoid having message data
discarded. </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/'>http://www.catb.org/~esr/irker</ulink>
-for updates and other resources, including an insrtallable repository
-hook script. The implementation uses the Python IRC library by Joe
-Rosdahl and Jason R. Coombs.</para>
+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>