diff options
author | Přemysl Janouch <p.janouch@gmail.com> | 2015-09-27 00:38:20 +0200 |
---|---|---|
committer | Přemysl Janouch <p.janouch@gmail.com> | 2015-09-27 00:38:20 +0200 |
commit | e75e840346ae0fe32153a66a49a2ecf952476274 (patch) | |
tree | 226e3dc30c80fe7ba50265a87acc503f4f264c11 /README.adoc | |
parent | 3d59a94554be170fee65e118b77216b138cae93a (diff) | |
download | xK-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.adoc | 134 |
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 |