README.md

   1 # `ircpipe` - netcat for IRC
   2
   3 Sets up an irc connection, and takes care of PINGs and PONGs.
   4
   5
   6 ## Usage
   7
   8 ```
   9 ircpipe [-pP] [-sSk] [-n NICK] [-j CHAN] HOST [PORT]
  10 ```
  11
  12 * `-n`: nick to use (mandatory)
  13 * `-j`: channel to join on connect
  14 * `-p`: read server password from `$IRC_PASSWD`
  15 * `-P`: authenticate using SASL PLAIN; reads password from `$IRC_PASSWD`
  16 * `-S`: use plain TCP socket (default port 6667, enabled by default)
  17 * `-s`: use TLS (default port 6697)
  18 * `-k`: use TLS without certificate verification
  19
  20
  21 ## Theory of Operation
  22
  23 ircpipe aims to abstract away the annoying parts of connecting to IRC with
  24 netcat. It handles authentication (including initial channel joins) and
  25 sends out and responds to pings to avoid the connection from timing out. During
  26 setup, received IRC messages are partially parsed and checked for common error
  27 numerics to check for failures. Until this point, data on stdin is not read and
  28 kept buffered by the operating system to avoid sending commands before the
  29 connectino is ready. Afterwards, ircpipe only listens to pings (to which it
  30 automatically responds) and fatal `ERROR` messages (on which ircpipe exits).
  31 When exiting due to an IRC protocol level error, ircpipe prints the full line of
  32 the responsible response to stderr and exits with code 1.
  33
  34 ircpipe reads from stdin and writes to stdout and does not modify in- or
  35 output. The user is expected to pass (or parse) raw IRC messages, as per RFC
  36 1459 or 2812. While ircpipe is meant to be used in shell pipelines to implement
  37 half-duplex bots, it can easily be used as a quick and dirty interactive IRC
  38 client as well (especially using the highlight script in contrib). By setting
  39 up a fifo (named pipe) and redirecting one of the streams though it and piping
  40 the other, both to the same program, it is possible to implement bidirectional
  41 bots as well.
  42
  43 While only the last `-j` flag is processed, it is still possible to supply
  44 multiple channels by seperating them with a comma (no space). To join a
  45 password protected channel, append a space and a comma seperated list of
  46 passwords for each channel. This behaviour emerges from how IRC specifies the
  47 argument of the `JOIN` message (same syntax) to which we forward `CHAN`
  48 unmodified.
  49
  50 For TLS, the only sane option, OpenBSD's libTLS or libreTLS (the reimplemen-
  51 tation on top of OpenSSL for other operating systems) was chosen. It removes
  52 all the complexity of using TLS and therefore prevents accidental misuse.
  53
  54 No nickserv (or chanserv or similar) support is implemented or planned. Modern
  55 IRC networks should support authenticating with SASL (as specified by IRCv3);
  56 for bouncers, IRC server passwords work well. Patches for SASL certificate
  57 authentication may be accepted, assuming they don't add an unproportional
  58 amount of code and complexity. Similarly, no fallback nicks can be configured
  59 and when the chosen nick is already in use, ircpipe exits with an error.
  60 Patches to improve this situation might get accepted (once again barring too
  61 much added complexity).
  62
  63
  64 ## Examples
  65
  66 Connect to an IRC bouncer and highlight incoming messages. Timestamps are
  67 provided by `ts`, part of the moreutils suite. This is a surprisingly usable
  68 interactive IRC client. Posting to a channel (or messaging a user) is possible
  69 by sending the raw command, e.g. `privmsg #myChan :hello, world!` (most ircd
  70 implementations are matching commands case-insensitively). For better input
  71 handling, wrapping the whole pipeline with `rlwrap sh -c '...'` prevents
  72 incoming messages from mangling half-typed commands.
  73
  74 ```
  75 IRC_PASSWD=myNick/myNet:myPass ircpipe -n myNick -p -s bouncer.example.org | ./contrib/highlight | ts
  76 # or:
  77 IRC_PASSWD=myNick/myNet:myPass rlwrap sh -c 'ircpipe -n myNick -p -s bouncer.example.org | ./contrib/highlight | ts'
  78 ```
  79
  80 Forward some error logs to a special IRC channel. This is the original use case
  81 ircpipe was built for. It's easy to trigger anti-flood protections when using
  82 this, so only critical stuff should end up here. A client on your phone can then
  83 audibly alert you to important events (e.g by mentioning your nick in a prefix).
  84
  85 ```
  86 tail -f /var/log/myProgram | grep -i error | sed 's/^/PRIVMSG #myChan :/' | ircpipe -n myNick -j '#myChan' -s irc.example.com
  87 ```
  88
  89 Keep a very rudimentary log of conversations from multiple channels. Since you
  90 are not supposed to create too many connections to a network, this example
  91 exploits how the server interprets JOIN messages with multiple channels.
  92
  93 ```
  94 ircpipe -n myNick -j '#myChan1,#myChan2' -s irc.example.com >> /var/log/irc
  95 ```
  96
  97 Sometimes, communicating using stdin and stdout might not be ideal. socat(1) can
  98 be used to connect ircpipe to a UNIX domain (or any other kind of) socket.
  99
 100 ```
 101 socat EXEC:'ircpipe -s -n myNick irc.example.com' UNIX-LISTEN:/tmp/ircpipe
 102 ```
 103
 104 ## Caveats
 105
 106 The spec caps line length at 512 bytes; longer messages may or may not make it
 107 through the network unscathed. Since ircpipe doesn't understand PRIVMSG (the
 108 most likely message to go over that limit) it can't split messages up for you.
 109 Either make sure to only send relatively short payloads, or use an input filter
 110 to split them up into multiple privmsgs. Be sure to keep flooding limits in
 111 mind to avoid getting kicked when doing so.
 112
 113 IRC specifies that lines must be terminated by CR LF, but most if not all
 114 servers accept UNIX style (plain LF) line endings, too. ircpipe also relays
 115 lines from the IRC server unmodified, so it is likely that responses are CR LF
 116 terminated. If either of this is a problem, a simple pair of input and output
 117 filters, e.g. unix2dos(1) and dos2unix(1), can be placed around ircpipe.
 118
 119 Note that there is one known vulnerability: we don't guard against escape
 120 sequences in responses. when used interactively, a bad actor could send
 121 malicious sequences causing terminal corruption. causing data leaks (by
 122 querying terminal information) is unlikely, as the responses won't be proper
 123 irc PRIVMSGs. An output filter (like the included `highlight`) is recommended
 124 to strip them out.
 125
 126
 127 ## Building
 128
 129 Make sure libreTLS (or libTLS when on OpenBSD) library and development headers
 130 are installed, then simply run `make`. Sensible `CFLAGS` are provided by
 131 default, unless given from either the environment or as an argument to make(1).
 132 The resulting executable, `ircpipe`, can then simply be copied to `$PATH` e.g.
 133 with install(1).
 134
 135
 136 ## Licensing
 137
 138 This software is made available at https://git.gir.st/ircpipe.git under the
 139 terms of the GNU General Public License Version 3.