X-Git-Url: http://git.tremily.us/?a=blobdiff_plain;f=irkerd.xml;h=c2c37fb53d61a5021a74debfbb8b16e2ed0b773b;hb=f52ae77db0199703e10101b985ec1ab4af26f288;hp=9b0161eebd4ca3ed3eef41fdf6fb0bebed01e71c;hpb=f2f74272f1b32943f5620bf9f7243379e0c7827e;p=irker.git diff --git a/irkerd.xml b/irkerd.xml index 9b0161e..c2c37fb 100644 --- a/irkerd.xml +++ b/irkerd.xml @@ -1,13 +1,13 @@ - + irkerd -1 +8 Aug 27 2012 -irkerd -irkerd +irker +irker Commands @@ -19,7 +19,13 @@ irkerd -d debuglevel + -l logfile + -n nick + -p password + -i IRC-URL -V + -h + message text @@ -30,27 +36,46 @@ 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 test. +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":"irc://chat.hypothetical.net:6668/git-private?key=topsecret", "privmsg":"Keyed channel 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 - unlessthe 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. + +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 @@ -65,10 +90,40 @@ it. This option will generally only be of interest to developers; consult the source code for details. +-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. + + +-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. + @@ -91,21 +146,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 -for updates and other resources, including an insrtallable repository -hook script. The implementation uses the Python IRC library by Joe -Rosdahl and Jason R. Coombs. +url='http://www.catb.org/~esr/irker'>http://www.catb.org/~esr/irker +for updates and other resources, including an installable repository +hook script.