table of contents
other sections
IRKERD(8) | Commands | IRKERD(8) |
NAME¶
irkerd - relay for shipping notifications to IRC serversSYNOPSIS¶
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"}
OPTIONS¶
irkerd takes the following options: -dTakes 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 sedond 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.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.01/17/2015 | irker |