Mercurial > prosody-modules
annotate mod_client_proxy/README.markdown @ 3823:31b1797a78e1
mod_rest: Add support for XEP-XXXX: User-defined Data Transfer
author | Kim Alvefur <zash@zash.se> |
---|---|
date | Thu, 02 Jan 2020 09:30:47 +0100 |
parents | f04dbfad5407 |
children | 3dd7840cb923 |
rev | line source |
---|---|
3098
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
1 --- |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
2 labels: |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
3 - 'Stage-Alpha' |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
4 summary: 'Proxy multiple client resources behind a single component' |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
5 ... |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
6 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
7 What it does |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
8 ============ |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
9 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
10 This module must be used as a component. For example: |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
11 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
12 Component "proxy.domain.example" "client_proxy" |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
13 target_address = "some-user@some-domain.example" |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
14 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
15 All IQ requests against the proxy host (in the above example: |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
16 proxy.domain.example) are sent to a random resource of the target address (in |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
17 the above example: some-user@some-domain.example). The entity behind the |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
18 target address is called the "implementing client". |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
19 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
20 The IQ requests are JAT-ed (JAT: Jabber Address Translation) so that when the |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
21 implementing client answers the IQ request, it is sent back to the component, |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
22 which reverts the translation and routes the reply back to the user. |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
23 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
24 Let us assume that user@some-domain.exmaple sends a request. The |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
25 proxy.domain.example component has the client_proxy module loaded and proxies to |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
26 some-user@some-domain.example. some-user@some-domain.example has two resources, |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
27 /a and /b. |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
28 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
29 user -> component: |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
30 <iq type='get' id='1234' to='proxy.domain.example' from='user@some-domain.example/abc'> |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
31 component -> implementing client: |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
32 <iq type='get' id='1234' to='some-user@some-domain.example/a' from='proxy.domain.example/encoded-from'> |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
33 implementing client -> component: |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
34 <iq type='result' id='1234' to='proxy.domain.example/encoded-from' from='some-user@some-domain.example/a'> |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
35 component -> user: |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
36 <iq type='result' id='1234' to='user@some-domain.example/abc' from='proxy.domain.example'> |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
37 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
38 The encoded-from resource used in the exchange between the proxy component |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
39 and the implementing client is an implementation-defined string which allows |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
40 the proxy component to revert the JAT. |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
41 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
42 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
43 Use cases |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
44 ========= |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
45 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
46 * Implementation of services within clients instead of components, thus making |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
47 use of the more advanced authentication features. |
3102
f04dbfad5407
mod_client_proxy: extend readme
Jonas Wielicki <jonas@wielicki.name>
parents:
3098
diff
changeset
|
48 * Load-balancing requests to different client resources. |
3098
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
49 * General evilness |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
50 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
51 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
52 Configuration |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
53 ============= |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
54 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
55 To use this module, it needs to be loaded on a component: |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
56 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
57 Component "proxy.yourdomain.example" "client_proxy" |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
58 target_address = "implementation@yourdomain.example" |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
59 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
60 It will then send a subscription request to implementation@yourdomain.example |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
61 which MUST be accepted: this is required so that the component can detect the |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
62 resources to which IQ requests can be dispatched. |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
63 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
64 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
65 Limitations |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
66 =========== |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
67 |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
68 * It does not handle presence or message stanzas. |
a81456a13797
mod_client_proxy: a Jabber Address Translation implementation
Jonas Wielicki <jonas@wielicki.name>
parents:
diff
changeset
|
69 * It does not allow the implementing client to initiate IQ requests |