annotate doc/components.rst @ 3712:799d4f6fa7ca

tools (common/async_process): use parent environment by default
author Goffi <goffi@goffi.org>
date Tue, 30 Nov 2021 17:28:42 +0100
parents ba4ef64a6938
children a1eff4e32848
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3678
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
1 .. _components:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
2
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
3 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
4 Libervia Components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
5 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
6
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
7 Libervia can act as an XMPP server component, which can be seen as a generic plugin for
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
8 XMPP servers.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
9
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
10 This page explains which components are available and how to use them.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
11
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
12 Running a component
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
13 ===================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
14
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
15 Components are linked to a Libervia profile in the same way as normal clients.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
16
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
17 To run a component, you'll need to know its *entry point*, which is the name of the import
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
18 name of plugin managing it. The entry point to use will be specified in the component
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
19 installation documentation.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
20
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
21 You'll also have to declare the component on your XMPP server, this is a server dependent
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
22 step and you'll have to check your server documentation for details. You'll have to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
23 specify a **shared secret** (can also be named simply *password*) that must be set both on
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
24 the XMPP server and as the XMPP password of the Libervia profile.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
25
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
26 Here is a list of relevant documentation for most common servers:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
27
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
28 ejabberd
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
29 https://docs.ejabberd.im/admin/configuration/listen-options/
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
30
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
31 MongooseIm
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
32 https://esl.github.io/MongooseDocs/latest/configuration/listen/#xmpp-components-listenservice
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
33
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
34 OpenFire
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
35 use the web-based admin panel
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
36
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
37 Prosody
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
38 https://prosody.im/doc/components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
39
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
40 Tigase
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
41 https://docs.tigase.net/tigase-server/stable-snapshot/Administration_Guide/webhelp/externalComponentConfiguration.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
42
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
43
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
44 On Libervia, setup is done with Libervia CLI's :ref:`profile create <li_profile_create>`
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
45 command.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
46
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
47 You'll usually want to have the component to start automatically when the backend
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
48 is started, for this you must unset the profile password (not to be confused with the XMPP
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
49 password which is the one also set on the server configuration) with ``-p ""`` and set
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
50 auto-connection with ``-A``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
51
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
52 You'll specify the XMPP password (also named *shared secret* in `XEP-0144`_ terminology)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
53 with ``-x <your_shared_secret>`` and the JID to use with ``-j
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
54 <component_subdomain>.<server.tld>``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
55
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
56 The component entry point is specified with ``-C <entry_point>``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
57
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
58 .. _XEP-0144: https://xmpp.org/extensions/xep-0114.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
59
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
60 example
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
61 -------
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
62
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
63 Louise wants to run an ActivityPub gateway on her server ``example.org`` with the JID
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
64 ``ap.example.org``. The shared secret is ``xmpp_rocks`` and she wants the component to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
65 start automatically with the backend, thus she doesn't set a profile password. The
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
66 entry-point for ActivityPub component is ``ap-gateway``, and she wants to use the same
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
67 name for the profile. To do this, she enters the following command::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
68
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
69 $ li profile create ap-gateway -j ap.example.org -p "" -x xmpp_rocks -C ap-gateway -A
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
70
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
71 The component will then be started next time Libervia Backend is launched. If Louise
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
72 wants to connect it immediately, she can use::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
73
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
74 $ li profile connect -cp ap-gateway
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
75
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
76 Available Components
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
77 ====================
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
78
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
79 Below is a list of currently available components in Libervia, and instructions on what
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
80 they do and how to use them.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
81
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
82
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
83 File Sharing
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
84 ------------
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
85
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
86 **entry_point:** ``file-sharing``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
87
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
88 File Sharing component manage the hosting of user files. Users can upload file there using
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
89 either `Jingle File Transfer`_ or `HTTP File Upload`_.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
90
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
91 There is no limit to the size of files which can be uploaded, but administrators can set a
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
92 quota to limit the space that can be used.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
93
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
94 Files can be retrieved using `File Information Sharing`_, and deleted using `Ad-Hoc Commands`_.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
95
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
96 Files can be shared with a public HTTP link, or made available only to a specified list of
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
97 entities (JIDs). Permissions can be set through Ad-Hoc Commands.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
98
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
99 .. _Jingle File Transfer: https://xmpp.org/extensions/
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
100 .. _HTTP File Upload: https://xmpp.org/extensions/xep-0363.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
101 .. _File Information Sharing: https://xmpp.org/extensions/xep-0329.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
102 .. _Ad-Hoc Commands: https://xmpp.org/extensions/xep-0050.html
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
103
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
104 Configuration
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
105 ~~~~~~~~~~~~~
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
106
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
107 All options are to be set in ``[component file-sharing]`` section.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
108
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
109 ``http_upload_port``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
110 port to use for HTTP File Upload
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
111
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
112 **default**: 8888
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
113
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
114 ``http_upload_connection_type``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
115 either ``http`` or ``https``.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
116
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
117 **default**: ``https``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
118
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
119 Note that HTTP Upload should always be ``https`` to end-user, the ``http`` option is to
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
120 be used only if you use a HTTP server as a proxy, and this server is already set for
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
121 TLS.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
122
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
123 ``http_upload_public_facing_url``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
124 must be set to the URL that end-user will see. Notably useful if the component is behind
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
125 a proxy.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
126
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
127 **default**: ``https://<component host>:<http_upload_port``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
128
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
129 ``quotas_json``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
130 a JSON object indicating quotas to use for users. The object can have 3 keys:
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
131
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
132 ``admins``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
133 quotas to use for administrators (i.e. profiles set in ``admins_list``)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
134
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
135 ``users``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
136 quotas to use for normal users (i.e. non admin profiles)
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
137
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
138 ``jids``
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
139 per-jid specific quotas. The value is a JSON object where key is a user bare jid and
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
140 value is a quota.
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
141
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
142 Quotas can be either ``null`` for unlimited space, or a size value (`SI prefixes and
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
143 binary prefixes`_ can be used).
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
144
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
145 example::
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
146
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
147 quotas_json = {
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
148 "admins": null,
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
149 "users": "50 Mio",
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
150 "jids": {"pierre@example.org": "1 Gio"}
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
151 }
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
152
ba4ef64a6938 doc: components documentation:
Goffi <goffi@goffi.org>
parents:
diff changeset
153 .. _SI prefixes and binary prefixes: https://en.wikipedia.org/wiki/Octet_(computing)#Unit_multiples