From e75e840346ae0fe32153a66a49a2ecf952476274 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?P=C5=99emysl=20Janouch?= Date: Sun, 27 Sep 2015 00:38:20 +0200 Subject: Convert README to AsciiDoc So that it looks nice on GitHub. Neither Markdown nor RST worked for me. --- README | 125 -------------------------------------------------------- README.adoc | 134 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 134 insertions(+), 125 deletions(-) delete mode 100644 README create mode 100644 README.adoc diff --git a/README b/README deleted file mode 100644 index 512fbb8..0000000 --- a/README +++ /dev/null @@ -1,125 +0,0 @@ -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 . - -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 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 . + +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 -- cgit v1.2.3