NAME¶

irkerd - relay for shipping notifications to IRC servers

SYNOPSIS¶

irkerd [-c ca-file] [-d debuglevel] [-e cert-file] [-l logfile] [-H host] [-n nick] [-p password] [-P password-file] [-i IRC-URL] [-t timeout] [-V] [-h] [message text]

DESCRIPTION¶

irkerd 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.

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.

irkerd 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:

{"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"}

If the channel part of the URL does not have one of the prefix characters “#”, “&”, or “+”, a “#” will be prepended to it before shipping - unless the channel part has the suffix ",isnick" (which is unconditionally removed).

The host part of the URL may have a port-number suffix separated by a colon, as shown in the third example; otherwise irkerd sends plaintext messages to the default 6667 IRC port of each server, and SSL/TLS messages to 6697.

The password for password-protected servers can be set using the usual “[{username}:{password}@]{host}:{port}” defined in RFC 3986, as shown in the fifth example. Non-empty URL usernames override the default “irker” username.

When the “to” URL uses the “ircs” 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 “irc” 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, “-c /etc/ssl/certs/ca-certificates.crt”. In Python 3.2 and later, you can still set this option to declare a custom CA file, but irkerd; if you don't set it irkerd will use OpenSSL's default file (using Python's “ssl.SSLContext.set_default_verify_paths”). In Python 3.2 and later, “ssl.match_hostname” is used to ensure the server certificate belongs to the intended host, as well as being signed by a trusted CA.

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 “?secret” or “?key=secret”, where “secret” is the channel key.

An empty message is legal and will cause irkerd 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.

OPTIONS¶

irkerd takes the following options:

-d

-e

-e

-l

-H

-n

-p

-P

-t

-i

-V

-h

LIMITATIONS¶

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.

An irkerd 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 irkerd 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.

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.

IRC has a message length limit of 510 bytes; generate your privmsg attribute values with appropriate care.

IRC ignores any text after an embedded newline. Be aware that irkerd will turn payload strings with embedded newlines into multiple IRC sends to avoid having message data discarded.

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 #.

SEE ALSO¶

irkerhook(1),

AUTHOR¶

Eric S. Raymond <esr@snark.thyrsus.com>. See the project page at http://www.catb.org/~esr/irker for updates and other resources, including an installable repository hook script.