Mercurial > libervia-backend

comparison doc/components.rst @ 3678:ba4ef64a6938

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