See the security.txt document for a detailed discussion of security
and DoS vulnerabilities related to irker.
-== Installing irker ==
+== Installing irkerd ==
irker needs to run constantly, watching for TCP and UDP traffic on
-port 6659. Install it accordingly.
+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 1 for sparse messages and -d 2
+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.
You will need to have Jason Coombs's irc library where Python can see
-it. See <http://pypi.python.org/pypi/irc/>; use version 3.0, not the
-older code from SourceForge.
-
-For higher performance, also install the eventlet library from
-<http://pypi.python.org/pypi/eventlet/>. This merges in a cooperative
-threading implementation that is faster and has much lower space
-overhead than system threads, making irkerd more resistant to
-potential DoS attacks.
+it. See <http://pypi.python.org/pypi/irc/>; use version 3.4 or later.
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.
== Installing irkerhook.py ==
-irkerhook.py should be called from the post-commit hook of each
-repository. See its header comment for detailed installation
-instructions.
+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.
-You should set the server and (for Subversion) repository variables
-from the command line in your post-commit hook. The server variable
-should be set to the inside-the-firewall host running your irker
-instance.
+Note that if you were using the CIA service and have ciabot.py in your
+git update script, you can simply replace this
-A git invocation line should look something like this:
+/path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
-/usr/local/bin/irkerhook.py server=internal.foobar.net
+with this:
-Each project will be able to set its own channel URLs, provided it
-has access to its git config file.
+/path/to/irkerhook.py --refname=${refname} $(git rev-list ${oldhead}..${newhead} | tac)
-A Subversion invocation should look something like this:
+== Testing ==
-REPOSITORY=$1
-REV=$2
-irkerhook.py repository=$REPOSITORY commit=$REV server=internal.foobar.net
+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.
-Note that unless you supply additional overrides of project= and
-channels= in the hook, the basename of the repository will be used as
-the project name and will also be used as the IRC channel name on
-freenode. This is not a limitation of irker.irkerhook, but a
-result of the absence of a git-config equivalent that the hook can
-mine stuff out of.
+Then, start irkerd and call irkerhook.py while watching the freenode
+#commits channel.
-== Testing ==
+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 proxy that takes CIA XML-RPC notifications
+and passes them to a local irker instance. Find it here:
+
+ https://github.com/nenolod/irker-cia-proxy
+
+There's also a poller daemon that can watch activity in a Subversion
+repository and ship notifications via an irker instance.
+
+ https://github.com/shikadilord/irker-svnpoller
-Go to a project repo and call irkerhook.py as indicated above while
-watching the freenode #commits channel.
-
projects / irker.git / blobdiff