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
111
112
113
114
115
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
|
