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).
  71
  72 ```
  73 IRC_PASSWD=myNick/myNet:myPass ircpipe -n myNick -p -s bouncer.example.org | ./contrib/highlight | ts
  74 ```
  75
  76 Forward some error logs to a special IRC channel. This is the original use case
  77 ircpipe was built for. It's easy to trigger anti-flood protections when using
  78 this, so only critical stuff should end up here. A client on your phone can then
  79 audibly alert you to important events (e.g by mentioning your nick in a prefix).
  80
  81 ```
  82 tail -f /var/log/myProgram | grep -i error | sed 's/^/PRIVMSG #myChan :/' | ircpipe -n myNick -j '#myChan' -s irc.example.com
  83 ```
  84
  85 Keep a very rudimentary log of conversations from multiple channels. Since you
  86 are not supposed to create too many connections to a network, this example
  87 exploits how the server interprets JOIN messages with multiple channels.
  88
  89 ```
  90 ircpipe -n myNick -j '#myChan1,#myChan2' -s irc.example.com >> /var/log/irc
  91 ```
  92
  93
  94 ## Caveats
  95
  96 The spec caps line length at 512 bytes; longer messages may or may not make it
  97 through the network unscathed. Since ircpipe doesn't understand PRIVMSG (the
  98 most likely message to go over that limit) it can't split messages up for you.
  99 Either make sure to only send relatively short payloads, or use an input filter
 100 to split them up into multiple privmsgs. Be sure to keep flooding limits in
 101 mind to avoid getting kicked when doing so.
 102
 103 IRC specifies that lines must be terminated by CR LF, but most if not all
 104 servers accept UNIX style (plain LF) line endings, too. ircpipe also relays
 105 lines from the IRC server unmodified, so it is likely that responses are CR LF
 106 terminated. If either of this is a problem, a simple pair of input and output
 107 filters, e.g. unix2dos(1) and dos2unix(1), can be placed around ircpipe.
 108
 109 Note that there is one known vulnerability: we don't guard against escape
 110 sequences in responses. when used interactively, a bad actor could send
 111 malicious sequences causing terminal corruption. causing data leaks (by
 112 querying terminal information) is unlikely, as the responses won't be proper
 113 irc PRIVMSGs. An output filter (like the included `highlight`) is recommended
 114 to strip them out.
 115
 116
 117 ## Building
 118
 119 Make sure libreTLS (or libTLS when on OpenBSD) library and development headers
 120 are installed, then simply run `make`. Sensible `CFLAGS` are provided by
 121 default, unless given from either the environment or as an argument to make(1).
 122 The resulting executable, `ircpipe`, can then simply be copied to `$PATH` e.g.
 123 with install(1).
 124
 125
 126 ## Licensing
 127
 128 This software is made available at https://git.gir.st/ircpipe.git under the
 129 terms of the GNU General Public License Version 3.