annotate INSTALL @ 159:6fe78048baf9

Rework error handling, depend on Twisted Words 0.4.0. Twisted Words 0.4.0 introduced support for stanza error handling, much better than the custom error handling in Idavoll. Also, all protocol-level errors were examined and brought up to date with version 1.8 of JEP-0060. As a result of the error examination, the retrieval of default configuration options using <default/> is now supported properly.
author Ralph Meijer <ralphm@ik.nu>
date Wed, 06 Sep 2006 12:38:47 +0000
parents 5191ba7c4df8
children ef22e4150caa
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
1 Requirements
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
2 ============
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
3
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
4 - Twisted Core >= 2.0.0
159
6fe78048baf9 Rework error handling, depend on Twisted Words 0.4.0.
Ralph Meijer <ralphm@ik.nu>
parents: 155
diff changeset
5 - Twisted Words >= 0.4.0
155
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
6 - uuid.py (http://ofxsuite.berlios.de/uuid.py)
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
7 - A jabber server that supports the component protocol (JEP-0114)
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
8
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
9 For the PostgreSQL backend, the following is also required:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
10
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
11 - PostgreSQL
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
12 - pyPgSQL
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
13
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
14 Installation
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
15 ============
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
16
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
17 Run:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
18
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
19 python setup.py install
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
20
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
21 Configuration
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
22 =============
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
23
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
24 The configuration file is created using Twisted's mktap, which needs a number
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
25 of parameters:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
26
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
27 --jid: The Jabber ID the component will assume.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
28 --rport: the port number of the Jabber server to connect to
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
29 --secret: the secret used to authenticate with the Jabber server.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
30 --backend: the backend storage facility to be used (memory or PostgreSQL).
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
31
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
32 The default settings of mktap for Idavoll use the memory database and assume
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
33 the default settings of jabberd 2.x for --rport and --secret.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
34
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
35 jabberd 2.x
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
36 ===========
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
37 You can use the 'legacy' component support that defaults to port 5347 with
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
38 secret 'secret'. You do not need to add anything specific for this service.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
39
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
40 jabberd 1.4.x
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
41 =============
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
42
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
43 Put the following in the jabber.xml configuration file of jabberd:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
44
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
45 <service id='pubsub.localhost'>
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
46 <accept>
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
47 <ip>127.0.0.1</ip>
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
48 <port>5347</port>
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
49 <secret>secret</secret>
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
50 </accept>
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
51 </service>
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
52
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
53 and restart jabberd. Unlike jabber 2.x, you can only have one component per
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
54 port, so the port number may need to be changed.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
55
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
56 For other server implementations, please refer to its documentation on
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
57 how to interact with server side components using the protocol defined in
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
58 JEP-0114.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
59
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
60 Then, in the same directory as this file run:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
61
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
62 mktap idavoll --rport=5347 --jid=pubsub.localhost --secret=secret
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
63
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
64 This uses the (default) memory based backend.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
65
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
66 For using the PostgreSQL backend, create a database (for example named pubsub)
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
67 like so:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
68
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
69 createdb pubsub
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
70 psql pubsub <db/pubsub.sql
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
71
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
72 To use this backend, add the --backend=pgsql parameter to mktap.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
73
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
74 For viewing all options, run:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
75
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
76 mktap idavoll --help
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
77
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
78 The generated file idavoll.tap now holds the configuration.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
79
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
80 Running
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
81 =======
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
82
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
83 Using the configuration file idavoll.tap, run:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
84
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
85 twistd -of idavoll.tap
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
86
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
87 This will start the service and run it in the background. It generates a
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
88 file twistd.pid that holds the PID of the service and a log file twistd.log.
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
89 The twistd utility has a fair number of options that might be useful, and
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
90 can be viewed with:
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
91
5191ba7c4df8 Work towards first release 0.5.0.
Ralph Meijer <ralphm@ik.nu>
parents:
diff changeset
92 twistd --help