Experimental IRC client, daemon and bot
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

README.adoc 6.6KB

4 years ago
5 years ago
4 years ago
4 years ago
4 years ago
5 years ago
4 years ago
4 years ago
5 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
4 years ago
3 years ago
4 years ago
4 years ago
5 years ago
  1. uirc3
  2. =====
  3. :compact-option:
  4. The unethical IRC trinity. This project consists of an experimental IRC client,
  5. daemon, and bot. It's all you're ever going to need for chatting, as long as
  6. you can make do with minimalist software.
  7. All of them have these potentially interesting properties:
  8. - full IPv6 support
  9. - TLS support, including client certificates
  10. - lean on dependencies (with the exception of 'degesch')
  11. - compact and arguably easy to hack on
  12. - permissive license
  13. degesch
  14. -------
  15. The IRC client. It is largely defined by being built on top of GNU Readline
  16. that has been hacked to death. Its interface should feel somewhat familiar for
  17. weechat or irssi users.
  18. This is the largest application within the project. It has most of the stuff
  19. you'd expect of an IRC client, such as being able to set up multiple servers,
  20. a powerful configuration system, integrated help, text formatting, CTCP queries,
  21. automatic splitting of overlong messages, autocomplete, logging to file,
  22. auto-away, command aliases and rudimentary support for Lua scripting.
  23. kike
  24. ----
  25. The IRC daemon. It is designed to be used as a regular user application rather
  26. than a system-wide daemon. If all you want is a decent, minimal IRCd for
  27. testing purposes or a small network of respectful users (or bots), this one will
  28. do it just fine.
  29. Notable features:
  30. - TLS autodetection (why doesn't everyone have this?), using secure defaults
  31. - IRCop authentication via TLS client certificates
  32. - epoll/kqueue support; this means that it should be able to handle quite
  33. a number of concurrent user connections
  34. - partial IRCv3 support
  35. Not supported:
  36. - server linking (which also means no services); I consider existing protocols
  37. for this purpose ugly and tricky to implement correctly; I've also found no
  38. use for this feature yet
  39. - online changes to configuration; the configuration system from degesch could
  40. be used to implement this feature if needed
  41. - limits of almost any kind, just connections and mode `+l`
  42. ZyklonB
  43. -------
  44. The IRC bot. It builds upon the concept of my other VitaminA IRC bot. The main
  45. characteristic of these two bots is that they run plugins as coprocesses, which
  46. allows for enhanced reliability and programming language freedom.
  47. While originally intended to be a simple rewrite of the original AWK bot in C,
  48. it fairly quickly became a playground, and it eventually got me into writing
  49. the rest of the package.
  50. It survives crashes, server disconnects and timeouts, and also has native SOCKS
  51. support (even though socksify can add that easily to any program).
  52. Packages
  53. --------
  54. Regular releases are sporadic. git master should be stable enough. You can get
  55. a package with the latest development version from Archlinux's AUR, or from
  56. openSUSE Build Service for the rest of mainstream distributions. Consult the
  57. list of repositories and their respective links at:
  58. https://build.opensuse.org/project/repositories/home:pjanouch:git
  59. Building
  60. --------
  61. Build dependencies: CMake, pkg-config, help2man, awk, sh, liberty (included) +
  62. Runtime dependencies: openssl +
  63. Additionally for degesch: curses, libffi, lua >= 5.3 (optional),
  64. readline >= 6.0 or libedit >= 2013-07-12
  65. $ git clone --recursive https://github.com/pjanouch/uirc3.git
  66. $ mkdir uirc3/build
  67. $ cd uirc3/build
  68. $ cmake .. -DCMAKE_INSTALL_PREFIX=/usr -DCMAKE_BUILD_TYPE=Debug \
  70. $ make
  71. To install the application, you can do either the usual:
  72. # make install
  73. Or you can try telling CMake to make a package for you. For Debian it is:
  74. $ cpack -G DEB
  75. # dpkg -i uirc3-*.deb
  76. Usage
  77. -----
  78. 'degesch' has in-program configuration. Just run it and read the instructions.
  79. For the rest you might want to generate a configuration file:
  80. $ zyklonb --write-default-config
  81. $ kike --write-default-config
  82. After making any necessary edits to the file (there are comments to aid you in
  83. doing that), simply run the appropriate program with no arguments:
  84. $ zyklonb
  85. $ kike
  86. 'ZyklonB' stays running in the foreground, therefore I recommend launching it
  87. inside a Screen or tmux session.
  88. 'kike', on the other hand, immediately forks into the background. Use the PID
  89. file or something like `killall` if you want to terminate it. You can run it
  90. as a `forking` type systemd user service.
  91. Client Certificates
  92. -------------------
  93. 'kike' uses SHA1 fingerprints of TLS client certificates to authenticate users.
  94. To get the fingerprint from a certificate file in the required form, use:
  95. $ openssl x509 -in public.pem -outform DER | sha1sum
  96. Custom Key Bindings in degesch
  97. ------------------------------
  98. The default and preferred frontend used in 'degesch' is GNU Readline. This
  99. means that you can change your bindings by editing '~/.inputrc'. For example:
  100. ....
  101. # Preload with system-wide settings
  102. $include /etc/inputrc
  103. # Make M-left and M-right reorder buffers
  104. $if degesch
  105. "\e\e[C": move-buffer-right
  106. "\e\e[D": move-buffer-left
  107. $endif
  108. ....
  109. Consult the source code and the GNU Readline manual for a list of available
  110. functions. Also refer to the latter for the exact syntax of this file.
  111. Beware that you can easily break the program if you're not careful.
  112. Configuration profiles
  113. ----------------------
  114. Even though the applications don't directly support configuration profiles,
  115. they conform to the XDG standard, and thus you can change the location they
  116. load configuration from via XDG_CONFIG_HOME (normally '~/.config') and the
  117. location where store their data via XDG_DATA_HOME (normally '~/.local/share').
  118. It would be relatively easy to make the applications assume whatever name you
  119. run them under (for example by using symbolic links), and load different
  120. configurations accordingly, but I consider it rather messy and unnecessary.
  121. Contributing and Support
  122. ------------------------
  123. Use this project's GitHub to report any bugs, request features, or submit pull
  124. requests. If you want to discuss this project, or maybe just hang out with
  125. the developer, feel free to join me at irc://irc.janouch.name, channel #dev.
  126. Disclaimer
  127. ----------
  128. I am not an antisemitist, I'm just being an offensive asshole with the naming.
  129. And no, I'm not going to change the names.
  130. License
  131. -------
  132. 'uirc3' is written by Přemysl Janouch <p.janouch@gmail.com>.
  133. You may use the software under the terms of the ISC license, the text of which
  134. is included within the package, or, at your option, you may relicense the work
  135. under the MIT or the Modified BSD License, as listed at the following site:
  136. http://www.gnu.org/licenses/license-list.html
  137. Note that 'degesch' technically becomes GPL-licensed when you compile it against
  138. GNU Readline, but that is not a concern of this source package.