README.md

   1 # `ircpipe` - netcat for IRC
   2
   3 Sets up an irc connection, and takes care about 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 TLS (default port 6697)
  17 * `-S`: use plain TCP socket (default port 6667)
  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 parsed (using strtok) and checked for common
  27 error numerics to check for failures. Afterwards, ircpipe only listens to pings
  28 (to which it automatically responds) and fatal `ERROR` messages (on which
  29 ircpipe exits). When exiting due to an IRC protocol level error, ircpipe prints
  30 the full line of the responsible response to stderr and exits with code 1.
  31
  32 ircpipe reads from stdin and writes to stdout and does not modify in- or
  33 output. The user is expected to pass (or parse) raw IRC messages, as per RFC
  34 1459 or 2812. While ircpipe is meant to be used in shell pipelines to implement
  35 half-duplex bots, it can easily be used as a quick and dirty interactive IRC
  36 client as well (especially using the highlight script in contrib). By setting
  37 up a fifo (named pipe) and redirecting one of the streams though it and piping
  38 the other, both to the same program, it is possible to implement bidirectional
  39 bots as well.
  40
  41 The spec caps line length at 512 bytes; longer messages may or may not make it
  42 through the network unscathed. Since ircpipe doesn't understand PRIVMSG (the
  43 most likely message to go over that limit) it can't split messages up for you.
  44 Either make sure to only send relatively short payloads, or use an input filter
  45 to split them up into multiple privmsgs. Be sure to keep flooding limits in
  46 mind to avoid getting kicked when doing so.
  47
  48 IRC specifies that lines must be terminated by CR LF, but most if not all
  49 servers accept UNIX style (plain LF) line endings, too. ircpipe also relays
  50 lines from the IRC server unmodified, so it is likely that responses are CR LF
  51 terminated. If either of this is a problem, a simple pair of input and output
  52 filters, e.g. `unix2dos`(1) and `dos2unix`(1), can be placed around ircpipe.
  53
  54 While only the last `-j` flag is processed, it is still possible to supply
  55 multiple channels by seperating them with a comma (no space). To join a
  56 password protected channel, append a space and a comma seperated list of
  57 passwords for each channel. This behaviour emerges from how IRC specifies the
  58 argument of the `JOIN` message (same syntax) to which we forward `CHAN`
  59 unmodified.
  60
  61 For TLS, the only sane option, OpenBSD's libTLS or libreTLS (the reimplemen-
  62 tation on top of OpenSSL for other operating systems) was chosen. It removes
  63 all the complexity of using TLS and therefore prevents accidental misuse.
  64
  65 Note that there is one known vulnerability: we don't guard against escape
  66 sequences in responses. when used interactively, a bad actor could send
  67 malicious sequences causing terminal corruption. causing data leaks (by
  68 querying terminal information) is unlikely, as the responses won't be proper
  69 irc PRIVMSGs. An output filter (like the included `highlight`) is recommended
  70 to strip them out.
  71
  72 No nickserv (or chanserv or similar) support is implemented or planned. Modern
  73 IRC networks should support authenticating with SASL (as specified in IRCv3);
  74 for bouncers, IRC server passwords work well. Patches for SASL certificate
  75 authentication may be accepted, assuming they don't add an unproportional
  76 amount of code and complexity. Similarly, no fallback nicks can be configured
  77 and when the chosen nick is already in use, ircpipe exits with an error.
  78 Patches to improve this situation might get accepted (once again barring too
  79 much added complexity).
  80
  81
  82 ## Building
  83
  84 Make sure libreTLS (or libTLS) library and development headers are installed,
  85 then simply run `make`. Sensible `CFLAGS` are provided by default, unless given
  86 from either the environment or as an argument to make(1).
  87 The resulting executable, `ircpipe`, can then simply be copied to `$PATH` e.g.
  88 with install(1).