-
Notifications
You must be signed in to change notification settings - Fork 4
/
Copy pathINSTALL
157 lines (107 loc) · 4.87 KB
/
INSTALL
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
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
Requirements
============
- Twisted >= 8.0.1:
- Twisted Core
- Twisted Conch (for idavoll-http)
- Twisted Web (for idavoll-http)
- Twisted Web2 (for idavoll-http)
- Twisted Words
- uuid.py (Python 2.5 std. lib. or http://pypi.python.org/pypi/uuid)
- Wokkel >= 0.5.0 (http://wokkel.ik.nu/)
- simplejson (for idavoll-http)
- A Jabber server that supports the component protocol (XEP-0114)
For the PostgreSQL backend, the following is also required:
- PostgreSQL (including development files for psycopg2)
- psycopg2
Installation
============
Idavoll uses setuptools for package building and installing, and is also
available through the Python Package Index (pypi). The easiest way to
install idavoll is:
easy_install idavoll
This will pull down the dependencies, if needed, except for the Twisted
packages.
To building from source run:
python setup.py build
Then, to install run the following, possibly as root:
python setup.py install
See the setuptools documentation for further information on changing
installation locations.
Configuration
=============
Idavoll uses Twisted's twistd command for running its services. Starting with
Twisted 2.5.0, twistd supports running Twisted Application Plugins directly,
without the use of mktap. In Twisted 8.1.0, the use of mktap for configuration
is deprecated. These instructions will not cover the use of mktap anymore, but
you can use TAC files to store a configuration, as described near the end
of this document.
Idavoll provides two types of storage for the backend: a memory-based storage
facility, which is volatile, and a persistent storage facility using
PostgreSQL. By default, the memory backend is used.
For using the PostgreSQL backend, create a database (for example named pubsub)
like so:
createdb pubsub
psql pubsub <db/pubsub.sql
To use this backend, add the --backend=pgsql parameter to twistd, along
with the optional connection parameters (see twistd idavoll --help).
Your Jabber server must also be configured to accept component connections,
see below for details.
Running Idavoll
===============
Idavoll provides two twistd plugins: idavoll and idavoll-http. The former
provides a generic publish-subscribe service, and the latter adds to that an
HTTP interface to access some of the features of the Idavoll backend, and also
provides a way to subscribe to, and receive notifications from, remote
publish-subscribe nodes.
The minimal example for running idavoll is:
twistd idavoll
This will start the service and run it in the background. It generates a
file twistd.pid that holds the PID of the service and a log file twistd.log.
The twistd utility has a fair number of options that might be useful, and
can be viewed with:
twistd --help
When the service starts, it will connect to the Jabber server at the local
machine using the component protocol, and assumes the JID 'pubsub'. This
assumes a couple of defaults which can be overridden by passing parameters to
the twistd plugin. You can get an overview of the parameters and their defaults
using:
twistd idavoll --help
In particular, the following parameters will be of interest:
--jid: The Jabber ID the component will assume.
--rport: the port number of the Jabber server to connect to
--secret: the secret used to authenticate with the Jabber server.
--backend: the backend storage facility to be used (memory or PostgreSQL).
The defaults for Idavoll use the memory database and assume the default
settings of jabberd 2.x for --rport and --secret.
You may also want to provide the --verbose flag to see the traffic flow,
for example to debug the configuration. Below some specifics for the
different Jabber server implementations.
jabberd 2.x
===========
You can use the 'legacy' component support that defaults to port 5347 with
secret 'secret'. These are the defaults of Idavoll, so you don't need to
alter the connection details with a default jabberd 2.x install.
jabberd 1.4.x
=============
Put the following in the jabber.xml configuration file of jabberd:
<service id='pubsub.localhost'>
<accept>
<ip>127.0.0.1</ip>
<port>5347</port>
<secret>secret</secret>
</accept>
</service>
and restart jabberd. Unlike jabber 2.x, you can only have one component per
port, so the port number may need to be changed.
For other server implementations, please refer to its documentation on
how to interact with server side components using the protocol defined in
JEP-0114.
Then, you can start Idavoll with:
twistd idavoll --rport=5347 --jid=pubsub.localhost --secret=secret
This uses the (default) memory based backend.
Using TAC files to store a configuration
========================================
Apart from the provided TAPs that can be run with twistd, you can also create
a configuration file that can be used by twistd to start up Idavoll. You can
find an example in doc/examples/idavoll.tac, which can be run using:
twisted -y idavoll.tac