<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>-i <replaceable>IRC-URL</replaceable></arg>
<arg>-V</arg>
- <arg>-h</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
{"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"}
+{"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
+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>
+<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
<quote>secret</quote> is the channel key.</para>
<para>An empty message is legal and will cause
-<application>irkerd</application> to join 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>
+<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>
<variablelist>
<varlistentry>
<term>-d</term>
-<listitem><para>Takes a following value, setting the debugging level from
-it. This option will generally only be of interest to developers;
-consult the source code for details.</para></listitem>
+<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>
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
<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 welcom message.</para></listitem>
+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>
</varlistentry>
<varlistentry>
<term>-h</term>
-<listitem><para>Print usage instructions and
-terminate.</para></listitem>
+<listitem><para>Print usage instructions and terminate.</para></listitem>
</varlistentry>
</variablelist>
-
</refsect1>
<refsect1 id='limitations'><title>LIMITATIONS</title>
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. The implementation uses the Python IRC library by Joe
-Rosdahl and Jason R. Coombs.</para>
+hook script.</para>
</refsect1>
</refentry>
projects / irker.git / blobdiff