Provided by: irker_2.17+dfsg-1_all bug

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] [-i IRC-URL] [-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
           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 irkerd's internal
           state. These tracing logs are independent of the traffic logs controlled by “-l”.

           Logging will be to standard error (if irkerd is running in the foreground) or to
           “/dev/syslog” with facility "daemon" (if irkerd is running in the background). The
           background-ness of irkerd 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 irkerd in Windows or another OS
           that doesn't support “os.getpgrp” or “tcgetpgrp”. We assume that if stdout is attached
           to a TTY associated with the same process group as irkerd, you do intend to log to
           stderr and not syslog.

       -e
           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 “CertFP.”

       -e
           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 “CertFP.”

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

       -H
           Takes a following hostname, and binds to that address when listening for messages.
           irkerd 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.

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

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

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

       -V
           Write the program version to stdout and terminate.

       -h
           Print usage instructions and terminate.

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.