1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
|
= 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.
== 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 seperate user account (irker), so this needs to
be setup 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.
Note that if you were using the CIA service and have ciabot.py in your
git update script, you can simply replace this
/path/to/ciabot.py ${refname} $(git rev-list ${oldhead}..${newhead} | tac)
with this:
/path/to/irkerhook.py --refname=${refname} $(git rev-list ${oldhead}..${newhead} | tac)
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 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
|
