Author: Josuah Demangeon <firstname.lastname@example.org>
Date: Sat, 18 Apr 2020 00:37:07 +0200
add documentation on jj + ucspi + s6
|A||wiki/jj/index.md|| | ||152||+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++|
1 file changed, 152 insertions(+), 0 deletions(-)
diff --git a/wiki/jj/index.md b/wiki/jj/index.md
@@ -0,0 +1,152 @@
+ The jj irc client
+[[jj]] is an [Internet Relay Chat][irc] client based on the principles of
+[[ii]], using FIFO (named pipe) files to read commands from the user, and
+simply logs the output of each channels to plain files.
+How jj works
+As opposed to ii, which is plain C, jj uses an awk script to do the heavy
+lifting of IRC parsing, called from a compiled binary coded in C, that only
+does the fifo creation, and multiplexing of user and network input, and
+write both to the awk script.
+It reads its entire configuration from environment variables, described on
+the the project's README.md, such as $IRC_DIR, in which it create a direcTory
+with the channel as a name.
+I set IRC_DIR to /var/irc, which give us (full list on the README.md):
+ * /var/irc/irc.freenode.net/channels/*.log - messages from users and channels.
+ * /var/irc/irc.freenode.net/in - the FIFO pipe to which write messages.
+There is one instance of jj per server conexion, which greatly simplifies
+the software, makes debugging much easier, and permit to adapt and configure
+it specifically for the requirements of each host to connect to.
+Recently, jj acquired the [[UCSPI]] connexion interface, which is a way to
+write programs without handling the network protocols into the program itself,
+but instead expect an running connexion (TCP, TLS, SSH, SOCKS5...) from standard
+input and output (for servers) or file descripTor 6 and 7 (for clients).
+This permits to run it through [[s6-networking]], [[ucspi-y]], [[ucspi-ssl]],
+[[curvecp]], or any protocol that has an UCSPI adapter for it.
+State of IRC client<->server connexions
+Because it is run by different people and projects, the connexion to IRC
+servers varies greatly through the different cases:
+ * Some servers only accept TCP connexions.
+ * Some servers only accept TLS connexions.
+ * Some servers permit to use a client TLS certificate to authenticate.
+ * Some servers support connexion coming form [[Tor]], providing the extra
+ privacy that the IRC protocol lacks
+ * Some servers refuse connexions coming from Tor.
+ * Some are published as Tor hidden services directly: so no need for TLS.
+ * Some servers still propose TLS over Tor, with certificate authentication.
+ * Some servers use a self-signed certificate, and publish a fingerprint
+ of their certificate.
+ * Some servers used a private certificate *authority* and publish their
+ root certificate.
+From this plethora of security fine tuning, it is necessary to have an irc
+client with a good TLS implementation (lots of lines of code), and a socks
+proxy (more lines of code), with a configuration interface (many many lines of
+How UCSPI helps
+I use jj under the [[s6]] and [[s6-rc]] supervision tree on a VPS (until I get
+real hardware home).
+jj having one instance per host to connect to, and jj supporting UCSPI, all of
+these are of a great fit:
+By using ucspi, we are entirely avoiding the problemm, as we can compose a
+socks client to talk to the Tor daemon (one line of scripts), and once the
+connexion has started, it is possible to start a tlsclient program that uses
+the active connexion and start a TLS session within that Tor socket, which can
+be configured as well to use a client certificate.
+All of the UCSPI tools work by performing their startup work (opening a TCP
+connexion, initiating a TLS/SOCKS/... session), and starting a child program,
+which was pased as argument to it, with a pipe, or executing them directly.
+This gives more or less long chain, aka [[chainloading]], that [[djb]] used
+and popularized through its set of programs.
+How I use jj and s6/s6-rc and UCSPI together
+The s6 and s6-rc package come with an execline shell-like language that makes
+this style of pipling as natural
+This is how it looks like in an [[execline]] ./run script in practice, as povided by s6 for
+configuration of daemon (jj) startup scripts:
+Boilerplate I have everywhere (sorry sk., #!/usr/bin/env...):
+ #!/usr/bin/env execlineb
+ fdmove -c 2 1
+This command reads the content of each file in ./env/ and export environment
+variables to their content: env/IRC_HOST, env/IRC_USER, env/IRC_PASSWORD, ...
+ s6-envdir "env"
+I use the "irc" user and the /var/irc/ direcTory:
+ s6-setuidgid irc
+This starts a TCP connexion to the local Tor daemon running:
+ s6-tcpclient 127.0.0.1 9050
+This starts a SOCK5 proxy session for communicating with the [[hackint]]
+ sockc "5ogdsfyoqk47ompu.onion" "6667"
+At that point, the program called by sockc will be able to communicate
+directly with IRC commands, as the TCP connexion is ready, the socks
+session is set, and the raw IRC protocol follows.
+It is now possible to call jjd directly, which will recognize the UCSPI
+environment through the $PROTO environment variable.
+In case there is another context, situation, other UCSPI commands can be
+inserted or moved, including the setup of client certifiates, that often goes
+through environment variables.
+This is the same script while run as #!/bin/sh. Yes, this is a single command!
+ fdmove -c 2 1 \
+ s6-envdir "env" \
+ s6-setuidgid irc \
+ s6-tcpclient 127.0.0.1 9050 \
+ sockc "5ogdsfyoqk47ompu.onion" "6667" \