summaryrefslogtreecommitdiff
path: root/README.adoc
diff options
context:
space:
mode:
authorPřemysl Janouch <p.janouch@gmail.com>2015-09-27 00:38:20 +0200
committerPřemysl Janouch <p.janouch@gmail.com>2015-09-27 00:38:20 +0200
commite75e840346ae0fe32153a66a49a2ecf952476274 (patch)
tree226e3dc30c80fe7ba50265a87acc503f4f264c11 /README.adoc
parent3d59a94554be170fee65e118b77216b138cae93a (diff)
downloadxK-e75e840346ae0fe32153a66a49a2ecf952476274.tar.gz
xK-e75e840346ae0fe32153a66a49a2ecf952476274.tar.xz
xK-e75e840346ae0fe32153a66a49a2ecf952476274.zip
Convert README to AsciiDoc
So that it looks nice on GitHub. Neither Markdown nor RST worked for me.
Diffstat (limited to 'README.adoc')
-rw-r--r--README.adoc134
1 files changed, 134 insertions, 0 deletions
diff --git a/README.adoc b/README.adoc
new file mode 100644
index 0000000..538a138
--- /dev/null
+++ b/README.adoc
@@ -0,0 +1,134 @@
+= uirc3
+
+The unethical IRC trinity. This project consists of an experimental IRC client,
+daemon, and bot. It's all you're ever going to need for chatting.
+
+All of them have these potentially interesting properties:
+
+ - full IPv6 support
+ - TLS support, including client certificates
+ - minimal dependencies
+ - very compact and easy to hack on
+ - permissive license
+
+== degesch
+
+The IRC client. It is largely defined by being built on top of GNU Readline.
+Its interface should however feel familiar for weechat or irssi users.
+
+This is the youngest and largest application within the project. It has most of
+the stuff you'd expect of an IRC client, such as being able to set up multiple
+servers, powerful configuration system, integrated help, mIRC text formatting,
+CTCP queries, automatic splitting of overlong messages, autocomplete, logging
+to file, and command aliases.
+
+== kike
+
+The IRC daemon. It is designed to be used as a regular user application rather
+than a system-wide daemon. If all you want is a decent, minimal IRCd for
+a small network of respectful users (or bots), or testing, this one will do it.
+
+Notable features:
+
+ - TLS autodetection (why doesn't everyone have this?)
+ - IRCop authentication through TLS client certificates
+ - epoll/kqueue support; it should be able to handle quite a number of users
+ - partial IRCv3 support
+
+Not supported:
+
+ - server linking (which also means no services); I consider existing protocols
+ for this purpose ugly and tricky to implement correctly
+ - online changes to configuration; the config system from degesch could be used
+ - limits of almost any kind, just connections and mode `+l`
+
+== ZyklonB
+
+The IRC bot. It builds upon the concept of my other VitaminA IRC bot. The main
+characteristic of these two bots is that they run plugins as coprocesses, which
+allows for enhanced reliability and programming language freedom.
+
+While originally intended to be a simple C99 rewrite of the original bot, which
+was written in the GNU dialect of AWK, it fairly quickly became a playground
+where I added everything that seemed nice, and it eventually got me into writing
+the rest of this package.
+
+Notable features:
+
+ - resilient against crashes, server disconnects and timeouts
+ - SOCKS support (even though socksify can add that easily to any program)
+
+== Building
+
+Build dependencies: CMake, pkg-config, help2man, awk, sh, liberty (included) +
+Runtime dependencies: openssl, curses (degesch),
+ readline or libedit >= 2013-07-12 (degesch)
+
+ $ git clone --recursive https://github.com/pjanouch/uirc3.git
+ $ mkdir uirc3/build
+ $ cd uirc3/build
+ $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug \
+ -DWANT_READLINE=ON -DWANT_LIBEDIT=OFF
+ $ 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. For Debian it is:
+
+ $ cpack -G DEB
+ # dpkg -i uirc3-*.deb
+
+Note that for versions of CMake before 2.8.9, you need to prefix `cpack` with
+`fakeroot` or file ownership will end up wrong.
+
+== Running
+
+_degesch_ has in-program configuration. Just run it and read the instructions.
+
+For the rest you might want to generate a configuration file:
+
+ $ zyklonb --write-default-config
+ $ kike --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:
+
+ $ zyklonb
+ $ kike
+
+_ZyklonB_ stays running in the foreground, therefore I recommend launching it
+inside a Screen or tmux session.
+
+_kike_, 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.
+
+== Client Certificates
+
+_kike_ uses SHA1 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
+
+== Contributing and Support
+
+Use this project's GitHub to report any bugs, request features, or submit pull
+requests. If you want to discuss this project, or maybe just hang out with
+the developer, feel free to join me at irc://anathema.irc.so, channel #anathema.
+
+== Disclaimer
+
+I am not an antisemitist, I'm just being an offensive asshole with the naming.
+And no, I'm not going to change the names.
+
+== License
+
+`uirc3' is written by Přemysl Janouch <p.janouch@gmail.com>.
+
+You may use the software under the terms of the ISC license, the text of which
+is included within the package, or, at your option, you may relicense the work
+under the MIT or the Modified BSD License, as listed at the following site:
+
+http://www.gnu.org/licenses/license-list.html