'\" t
.\"     Title: irkerd
.\"    Author: [see the "AUTHOR" section]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 02/17/2024
.\"    Manual: Commands
.\"    Source: irker
.\"  Language: English
.\"
.TH "IRKERD" "8" "02/17/2024" "irker" "Commands"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
irkerd \- relay for shipping notifications to IRC servers
.SH "SYNOPSIS"
.HP \w'\fBirkerd\fR\ 'u
\fBirkerd\fR [\-c\ \fIca\-file\fR] [\-d\ \fIdebuglevel\fR] [\-e\ \fIcert\-file\fR] [\-l\ \fIlogfile\fR] [\-H\ \fIhost\fR] [\-n\ \fInick\fR] [\-p\ \fIpassword\fR] [\-P\ \fIpassword\-file\fR] [\-i\ \fIIRC\-URL\fR] [\-t\ \fItimeout\fR] [\-V] [\-h] [\fImessage\ text\fR]
.SH "DESCRIPTION"
.PP
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\&.
.PP
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\&.
.PP
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:
.sp
.if n \{\
.RS 4
.\}
.nf
{"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"}
.fi
.if n \{\
.RE
.\}
.PP
If the channel part of the URL does not have one of the prefix characters
\(lq#\(rq,
\(lq&\(rq, or
\(lq+\(rq, a
\(lq#\(rq
will be prepended to it before shipping \-
\fIunless\fR
the channel part has the suffix ",isnick" (which is unconditionally removed)\&.
.PP
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\&.
.PP
The password for password\-protected servers can be set using the usual
\(lq[{username}:{password}@]{host}:{port}\(rq
defined in RFC 3986, as shown in the fifth example\&. Non\-empty URL usernames override the default
\(lqirker\(rq
username\&.
.PP
When the
\(lqto\(rq
URL uses the
\(lqircs\(rq
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
\(lqirc\(rq
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,
\(lq\-c /etc/ssl/certs/ca\-certificates\&.crt\(rq\&. In Python 3\&.2 and later, you can still set this option to declare a custom CA file, but
irkerd; if you don\*(Aqt set it
irkerd
will use OpenSSL\*(Aqs default file (using Python\*(Aqs
\(lqssl\&.SSLContext\&.set_default_verify_paths\(rq)\&. In Python 3\&.2 and later,
\(lqssl\&.match_hostname\(rq
is used to ensure the server certificate belongs to the intended host, as well as being signed by a trusted CA\&.
.PP
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
\(lq?secret\(rq
or
\(lq?key=secret\(rq, where
\(lqsecret\(rq
is the channel key\&.
.PP
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\&.
.SH "OPTIONS"
.PP
irkerd
takes the following options:
.PP
\-d
.RS 4
Takes a following value, setting the debugging level from it; possible values are \*(Aqcritical\*(Aq, \*(Aqerror\*(Aq, \*(Aqwarning\*(Aq, \*(Aqinfo\*(Aq, \*(Aqdebug\*(Aq\&. This option will generally only be of interest to developers, as the logs are designed to help trace
irkerd\*(Aqs internal state\&. These tracing logs are independent of the traffic logs controlled by
\(lq\-l\(rq\&.
.sp
Logging will be to standard error (if
irkerd
is running in the foreground) or to
\(lq/dev/syslog\(rq
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\*(Aqt running
irkerd
in Windows or another OS that doesn\*(Aqt support
\(lqos\&.getpgrp\(rq
or
\(lqtcgetpgrp\(rq\&. 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\&.
.RE
.PP
\-e
.RS 4
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
\(lqCertFP\&.\(rq
.RE
.PP
\-e
.RS 4
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
\(lqCertFP\&.\(rq
.RE
.PP
\-l
.RS 4
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\&.
.RE
.PP
\-H
.RS 4
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\*(Aqs public address to listen on a local network\&. Listening on a public interface is not recommended, as it makes spamming IRC channels very easy\&.
.RE
.PP
\-n
.RS 4
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\&.
.RE
.PP
\-p
.RS 4
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\&.
.RE
.PP
\-P
.RS 4
Liuke p, but the argument is interpreted as a filename from which to read the password
.RE
.PP
\-t
.RS 4
Takes a following value, setting the connection timeout for server\-socket opens\&.
.RE
.PP
\-i
.RS 4
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\&.
.RE
.PP
\-V
.RS 4
Write the program version to stdout and terminate\&.
.RE
.PP
\-h
.RS 4
Print usage instructions and terminate\&.
.RE
.SH "LIMITATIONS"
.PP
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\&.
.PP
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\&.
.PP
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\&.
.PP
IRC has a message length limit of 510 bytes; generate your privmsg attribute values with appropriate care\&.
.PP
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\&.
.PP
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 #\&.
.SH "SEE ALSO"
.PP
\fBirkerhook\fR(1),
.SH "AUTHOR"
.PP
Eric S\&. Raymond
<esr@snark\&.thyrsus\&.com>\&. See the project page at
\m[blue]\fBhttp://www\&.catb\&.org/~esr/irker\fR\m[]
for updates and other resources, including an installable repository hook script\&.