diff options
Diffstat (limited to 'irkerd.xml')
| -rw-r--r-- | irkerd.xml | 261 |
1 files changed, 261 insertions, 0 deletions
diff --git a/irkerd.xml b/irkerd.xml new file mode 100644 index 0000000..93a9df4 --- /dev/null +++ b/irkerd.xml @@ -0,0 +1,261 @@ +<!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> |