|
3678
|
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 |
