From 84a20cb80243f8614906be91953ca4213334b16b Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Mon, 6 May 2024 02:50:22 +0200 Subject: Adding upstream version 2.18+dfsg. Signed-off-by: Daniel Baumann --- irkerd.xml | 249 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 249 insertions(+) create mode 100644 irkerd.xml (limited to 'irkerd.xml') diff --git a/irkerd.xml b/irkerd.xml new file mode 100644 index 0000000..59b7dae --- /dev/null +++ b/irkerd.xml @@ -0,0 +1,249 @@ + + + +irkerd +8 +Aug 27 2012 +irker +irker +Commands + + +irkerd +relay for shipping notifications to IRC servers + + + + + 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 + +irkerhook1, + + + +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. + + -- cgit v1.2.3