diff options
Diffstat (limited to 'README.adoc')
| -rw-r--r-- | README.adoc | 210 |
1 files changed, 210 insertions, 0 deletions
diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..3c09ba7 --- /dev/null +++ b/README.adoc @@ -0,0 +1,210 @@ +xK +== + +'xK' (chat kit) is an IRC software suite consisting of a daemon, bot, terminal +client, and a web frontend for the client. It's all you're ever going to +need for chatting, so long as you can make do with slightly minimalist software. + +They're all lean on dependencies, and offer a maximally permissive licence. + +xC +-- +The IRC client, and the core of 'xK'. It is largely defined by building on top +of GNU Readline or BSD Editline that have been hacked to death. Its interface +should feel somewhat familiar for weechat or irssi users. + +image::xC.webp[align="center"] + +It has most features you'd expect of an IRC client, such as being multiserver, +a powerful configuration system, integrated help, text formatting, automatic +message splitting, multiline editing, bracketed paste support, word wrapping +that doesn't break links, autocomplete, logging, CTCP queries, auto-away, +command aliases, SOCKS proxying, SASL EXTERNAL authentication using TLS client +certificates, a remote relay interface, or basic support for Lua scripting. +As a unique bonus, you can launch a full text editor from within. + +xP +-- +The web frontend for 'xC', making use of its networked relay interface. +It intentionally differs in that it uses a sans-serif font, and it shows +the list of all buffers in a side panel. Otherwise it is a near replica, +including link:xC.adoc#_key_bindings[keyboard shortcuts]. + +image::xP.webp[align="center"] + +xD +-- +The IRC daemon. It is designed for use as a regular user application rather +than a system-wide daemon, and follows the XDG Base Directory Specification. +If all you want is a decent, minimal IRCd for testing purposes or a small +network of respectful users (or bots), this one will do it just fine. + +It autodetects TLS on incoming connections (I'm still wondering why everyone +doesn't have this), authenticates operators via TLS client certificate +fingerprints, and supports a number of IRCv3 capabilities. + +What it notably doesn't support is online changes to configuration, any limits +besides the total number of connections and mode `+l`, or server linking +(which also means no services). + +This program has been https://git.janouch.name/p/haven/src/branch/master/hid[ +ported to Go] in a different project, and development continues over there. + +xB +-- +The IRC bot. While originally intended to be a simple rewrite of my old GNU AWK +bot in C, it fairly quickly became a playground, and it eventually got me into +writing the rest of this package. + +Its main characteristic is that it runs plugins as coprocesses, allowing for +enhanced reliability and programming language freedom. Moreover, it recovers +from any crashes, and offers native SOCKS support (even though socksify can add +that easily to any program). + +Packages +-------- +Regular releases are sporadic. git master should be stable enough. You can get +a package with the latest development version from Archlinux's AUR. + +Building +-------- +Build-only dependencies: CMake, pkg-config, awk, liberty (included), + asciidoctor or asciidoc (recommended but optional) + +Common runtime dependencies: openssl + +Additionally for 'xC': curses, libffi, readline >= 6.0 or libedit >= 2013-07-12, + lua >= 5.3 (optional) + + + $ git clone --recursive https://git.janouch.name/p/xK.git + $ mkdir xK/build + $ cd xK/build + $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=RelWithDebInfo \ + -DWANT_READLINE=ON -DWANT_LIBEDIT=OFF -DWITH_LUA=ON + $ make + +To install the application, you can do either the usual: + + # make install + +Or you can try telling CMake to make a package for you: + + $ cpack -G DEB # also supported: RPM, FreeBSD + # dpkg -i xK-*.deb + +Usage +----- +'xC' has in-program configuration. Just run it and read the instructions. +Consult its link:xC.adoc[man page] for details about the interface. + +For the rest you might want to generate a configuration file: + + $ xB --write-default-config + $ xD --write-default-config + +After making any necessary edits to the file (there are comments to aid you in +doing that), simply run the appropriate program with no arguments: + + $ xB + $ xD + +'xB' stays running in the foreground, therefore I recommend launching it inside +a Screen or tmux session. + +'xD', on the other hand, immediately forks into the background. Use the PID +file or something like `killall` if you want to terminate it. You can run it +as a `forking` type systemd user service. + +xP +~~ +The precondition for running 'xC' frontends is enabling its relay interface: + + /set general.relay_bind = "127.0.0.1:9000" + +To build the web server, you'll need to install the Go compiler, and run `make` +from the _xP_ directory. Then start it from the _public_ subdirectory, +and navigate to the adress you gave it as its first argument--in the following +example, that would be http://localhost:8080[]: + + $ ../xP 127.0.0.1:8080 127.0.0.1:9000 + +For remote use, it's recommended to put 'xP' behind a reverse proxy, with TLS, +and some form of HTTP authentication. Pass the external URL of the WebSocket +endpoint as the third command line argument in this case. + +Client Certificates +------------------- +'xC' will use the SASL EXTERNAL method to authenticate using the TLS client +certificate specified by the respective server's `tls_cert` option if you add +`sasl` to the `capabilities` option and the server supports this. + +'xD' uses SHA-1 fingerprints of TLS client certificates to authenticate users. +To get the fingerprint from a certificate file in the required form, use: + + $ openssl x509 -in public.pem -outform DER | sha1sum + +Custom Key Bindings in xC +------------------------- +The default and preferred frontend used in 'xC' is GNU Readline. This means +that you can change your bindings by editing '~/.inputrc'. For example: + +.... +# Preload with system-wide settings +$include /etc/inputrc + +# Make M-left and M-right reorder buffers +$if xC +"\e\e[C": move-buffer-right +"\e\e[D": move-buffer-left +$endif +.... + +Consult the source code and the GNU Readline manual for a list of available +functions. Also refer to the latter for the exact syntax of this file. +Beware that you can easily break the program if you're not careful. + +How do I make xC look like the screenshot? +------------------------------------------ +With the defaults, 'xC' doesn't look too fancy because I don't want to have +a hard dependency on either Lua for the bundled script that provides an easily +adjustable enhanced prompt, or on 256-colour terminals. Moreover, it's nearly +impossible to come up with a colour theme that would work well with both +black-on-white and white-on-black terminals, or anything wild in between. + +Assuming that your build supports Lua plugins, and that you have a decent, +properly set-up terminal emulator, it suffices to run: + + /set general.pager = Press Tab here and change +Gb to +Gb1d + /set general.date_change_line = "%a %e %b %Y" + /set general.plugin_autoload += "fancy-prompt.lua" + /set theme.userhost = "109" + /set theme.join = "108" + /set theme.part = "138" + /set theme.external = "248" + /set theme.timestamp = "250 255" + /set theme.read_marker = "202" + +Configuration profiles +---------------------- +Even though the applications don't directly support configuration profiles, +they conform to the XDG standard, and thus you can change the location they +load configuration from via XDG_CONFIG_HOME (normally '~/.config') and the +location where store their data via XDG_DATA_HOME (normally '~/.local/share'). + +It would be relatively easy to make the applications assume whatever name you +run them under (for example by using symbolic links), and load different +configurations accordingly, but I consider it rather messy and unnecessary. + +Contributing and Support +------------------------ +Use https://git.janouch.name/p/xK to report any bugs, request features, +or submit pull requests. `git send-email` is tolerated. If you want to discuss +the project, feel free to join me at ircs://irc.janouch.name, channel #dev. + +Bitcoin donations are accepted at: 12r5uEWEgcHC46xd64tt3hHt9EUvYYDHe9 + +License +------- +This software is released under the terms of the 0BSD license, the text of which +is included within the package along with the list of authors. + +Note that 'xC' becomes GPL-licensed when you link it against GNU Readline, +but that is not a concern of this source package. The licenses are compatible. |