X-Git-Url: http://git.tremily.us/?p=irker.git;a=blobdiff_plain;f=irkerd.xml;h=fe60c876830f3d0084c450d02bc88bfb217e0b51;hp=c203fa8b789c2d4fa200e20ffcfd20e58aea5044;hb=HEAD;hpb=94012cbb895a7dbec7a33c2b7234c1fa43cc0453 diff --git a/irkerd.xml b/irkerd.xml index c203fa8..fe60c87 100644 --- a/irkerd.xml +++ b/irkerd.xml @@ -1,13 +1,13 @@ - + irkerd -1 +8 Aug 27 2012 -irkerd -irkerd +irker +irker Commands @@ -18,8 +18,17 @@ irkerd + -c ca-file -d debuglevel + -e cert-file + -l logfile + -H host + -n nick + -p password + -i IRC-URL -V + -h + message text @@ -30,6 +39,11 @@ 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 @@ -41,16 +55,52 @@ 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. +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 messages to the the default 6667 IRC -port of each server. +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 @@ -60,17 +110,95 @@ port of each server. -d -Takes a following value, setting the debugging level from -it. This option will generally only be of interest to developers; -consult the source code for details. + + + 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 two +following values interpreted as a channel URL and a message +string. Sends the message, then quits. -V Write the program version to stdout and terminate. + +-h +Print usage instructions and terminate. + - LIMITATIONS @@ -91,21 +219,27 @@ known to spew spam is always a good idea. 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 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 strungs with +irkerd will turn payload strings with embedded newlines into multiple IRC sends to avoid having message data discarded. +SEE ALSO + +irkerhook1, + + + AUTHOR Eric S. Raymond esr@snark.thyrsus.com. See the project page at http://www.catb.org/~esr/irker +url='http://www.catb.org/~esr/irker'>http://www.catb.org/~esr/irker for updates and other resources, including an installable repository -hook script. The implementation uses the Python IRC library by Joe -Rosdahl and Jason R. Coombs. +hook script.