From 3aecc6d0a8d757d6159dfa5083f1b254296c5b43 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 7 Apr 2024 16:27:58 +0200 Subject: Adding upstream version 2.23+dfsg. Signed-off-by: Daniel Baumann --- install.adoc | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 install.adoc (limited to 'install.adoc') diff --git a/install.adoc b/install.adoc new file mode 100644 index 0000000..fd7d1c5 --- /dev/null +++ b/install.adoc @@ -0,0 +1,116 @@ += Forge installation instructions = + +irker and irkerhook.py are intended to be installed on forge sites +such as SourceForge, GitHub, GitLab, Gna, and Savannah. This +file explains the theory of operation, how to install the code, +and how to test it. + +== Prerequisites == + +You should have Python 3 installed. While Python 2 support +has not yet been removed, it is unmaintained and vulnerable +to bitrot. + +If you just want to use irkerd and/or irkerhook.py, +you need not bother with the Makefile. It's for building +the derived versions of the documebtation and rubnning +validation tools. + +If you want to run irkerd using a socket proxy, +you'll want to do this: + +------------------------------------- +pip install -r requirements.txt +------------------------------------- + +Otherwise the code has no dependencies outside +the Python standard library. + +== Theory of operation == + +irkerhook.py creates JSON notification requests and ships them to +irkerd's listener socket. irkerd run as a daemon in order to maintain +all the client state required to post multiple notifications while generating +a minimum of join/leave messages (which, from the point of view of +humans watching irkerd's output, are mere spam). + +See the security.txt document for a detailed discussion of security +and DoS vulnerabilities related to irker. The short version: as +long as your firewall blocks port 6659 and irkerd is running inside +it, you should be fine. + +== Prerequisites == + +You will need either + +1. Python at version 2.6 or later, which has JSON built in + +2. Python at version no older than 2.4, and a version of the + simplejson library installed that it can use. Some newer + versions of simplejson discard 2.4 compatibility; 2.0.9 + is known to work. + +== Installing irkerd == + +irker needs to run constantly, watching for TCP and UDP traffic on +port 6659. Install it accordingly. It has no config file; you can +just start it up with no arguments. If you want to see what it's +doing, give it command-line options -d info for sparse messages and +-d debug to show all traffic with IRC servers. + +You should *not* make irker visible from outside the site firewall, as +it can be used to spam IRC channels while masking the source address. +The firewall should block port 6659. + +The design of irker assumes the machine on which it is running is also +inside the firewall, so that repository hooks can reach port 6659. + +The file org.catb.irkerd.plist is a Mac OS/X plist that can be +installed to launch irkerd as a boot-time service on that system. + +irker.service is a systemd unit that can run irkerd as a boot-time +service on systems that support systemd. This is configured to +run irkerd under a separate user account (irker), so this needs to +be set up before starting irker, or the unit needs to be modified +to use a different user. + +== Installing irkerhook.py == + +Under git, a call to irkerhook.py should be installed in the update +hook script of your repo. Under Subversion, the call goes in your +repo's post-commit script. Under Mercurial there are two different +ways to install it. See the irkerhook manual page for details; the +source is irkerhook.xml in this distribution. + +SourceForge is a special case: see + +https://github.com/AI0867/sf-git-irker-pipeline + +for tools and instructions on how to work around its limitations. + +== Testing == + +To verify that your repo produces well-formed JSON notifications, +you can run irkerhook.py in the repo directory using the -n switch, +which emits JSON to standard output rather than attempting to ship +to an irkerd instance. + +Then, start irkerd and call irkerhook.py while watching the freenode +#commits channel. + +The 'irk' script is a little test tool that takes two arguments, +a channel and a message, and does what you'd expect. + +If you need help, there's a project chat channel at + + irc://chat.freenode.net/#irker + +== Read-only access == + +If, for whatever reason, you can't modify the hook scripts in your +repository, there is still hope. There's a poller daemon that can +watch activity in a Subversion repository and ship notifications via +an irker instance. + + https://github.com/shikadilord/irker-svnpoller + -- cgit v1.2.3