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.