Přemysl Eric Janouch
4bc2f736f2
And translate them for frontends. This is very long overdue, and a rather significant cleanup. Bump liberty.
213 lines
8.0 KiB
Plaintext
213 lines
8.0 KiB
Plaintext
xK
|
|
==
|
|
|
|
'xK' (chat kit) is an IRC software suite consisting of a daemon, bot, terminal
|
|
client, and X11/web frontends 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.png[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.
|
|
So far it's a bit rough around the edges, yet fully usable.
|
|
|
|
xF
|
|
--
|
|
The X11 frontend for 'xC', making use of its networked relay interface.
|
|
This subproject has been put on hold, partly because of its massive overlap
|
|
with 'xP', and is hidden behind a CMake option.
|
|
|
|
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, asciidoctor or asciidoc, awk, liberty (included) +
|
|
Common runtime dependencies: openssl +
|
|
Additionally for 'xC': curses, libffi, readline >= 6.0 or libedit >= 2013-07-12,
|
|
lua >= 5.3 (optional) +
|
|
Additionally for 'xF': x11, xft
|
|
|
|
$ 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.
|
|
|
|
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.
|