257 lines
9.3 KiB
ReStructuredText
257 lines
9.3 KiB
ReStructuredText
.. _components:
|
|
|
|
===================
|
|
Libervia Components
|
|
===================
|
|
|
|
Libervia can act as an XMPP server component, which can be seen as a generic plugin for
|
|
XMPP servers.
|
|
|
|
This page explains which components are available and how to use them.
|
|
|
|
Running a component
|
|
===================
|
|
|
|
Components are linked to a Libervia profile in the same way as normal clients.
|
|
|
|
To run a component, you'll need to know its *entry point*, which is the name of the import
|
|
name of plugin managing it. The entry point to use will be specified in the component
|
|
installation documentation.
|
|
|
|
You'll also have to declare the component on your XMPP server, this is a server dependent
|
|
step and you'll have to check your server documentation for details. You'll have to
|
|
specify a **shared secret** (can also be named simply *password*) that must be set both on
|
|
the XMPP server and as the XMPP password of the Libervia profile.
|
|
|
|
Here is a list of relevant documentation for most common servers:
|
|
|
|
ejabberd
|
|
https://docs.ejabberd.im/admin/configuration/listen-options/
|
|
|
|
MongooseIm
|
|
https://esl.github.io/MongooseDocs/latest/configuration/listen/#xmpp-components-listenservice
|
|
|
|
OpenFire
|
|
use the web-based admin panel
|
|
|
|
Prosody
|
|
https://prosody.im/doc/components
|
|
|
|
Tigase
|
|
https://docs.tigase.net/tigase-server/stable-snapshot/Administration_Guide/webhelp/externalComponentConfiguration.html
|
|
|
|
|
|
On Libervia, setup is done with Libervia CLI's :ref:`profile create <li_profile_create>`
|
|
command.
|
|
|
|
You'll usually want to have the component to start automatically when the backend
|
|
is started, for this you must unset the profile password (not to be confused with the XMPP
|
|
password which is the one also set on the server configuration) with ``-p ""`` and set
|
|
auto-connection with ``-A``.
|
|
|
|
You'll specify the XMPP password (also named *shared secret* in `XEP-0144`_ terminology)
|
|
with ``-x <your_shared_secret>`` and the JID to use with ``-j
|
|
<component_subdomain>.<server.tld>``.
|
|
|
|
The component entry point is specified with ``-C <entry_point>``.
|
|
|
|
.. _XEP-0144: https://xmpp.org/extensions/xep-0114.html
|
|
|
|
example
|
|
-------
|
|
|
|
Louise wants to run an ActivityPub gateway on her server ``example.org`` with the JID
|
|
``ap.example.org``. The shared secret is ``xmpp_rocks`` and she wants the component to
|
|
start automatically with the backend, thus she doesn't set a profile password. The
|
|
entry-point for ActivityPub component is ``ap-gateway``, and she wants to use the same
|
|
name for the profile. To do this, she enters the following command::
|
|
|
|
$ li profile create ap-gateway -j ap.example.org -p "" -x xmpp_rocks -C ap-gateway -A
|
|
|
|
The component will then be started next time Libervia Backend is launched. If Louise
|
|
wants to connect it immediately, she can use::
|
|
|
|
$ li profile connect -cp ap-gateway
|
|
|
|
Available Components
|
|
====================
|
|
|
|
Below is a list of currently available components in Libervia, and instructions on what
|
|
they do and how to use them.
|
|
|
|
|
|
File Sharing
|
|
------------
|
|
|
|
**entry_point:** ``file-sharing``
|
|
|
|
File Sharing component manage the hosting of user files. Users can upload file there using
|
|
either `Jingle File Transfer`_ or `HTTP File Upload`_.
|
|
|
|
There is no limit to the size of files which can be uploaded, but administrators can set a
|
|
quota to limit the space that can be used.
|
|
|
|
Files can be retrieved using `File Information Sharing`_, and deleted using `Ad-Hoc Commands`_.
|
|
|
|
Files can be shared with a public HTTP link, or made available only to a specified list of
|
|
entities (JIDs). Permissions can be set through Ad-Hoc Commands.
|
|
|
|
.. _Jingle File Transfer: https://xmpp.org/extensions/
|
|
.. _HTTP File Upload: https://xmpp.org/extensions/xep-0363.html
|
|
.. _File Information Sharing: https://xmpp.org/extensions/xep-0329.html
|
|
.. _Ad-Hoc Commands: https://xmpp.org/extensions/xep-0050.html
|
|
|
|
Configuration
|
|
~~~~~~~~~~~~~
|
|
|
|
All options are to be set in ``[component file-sharing]`` section.
|
|
|
|
``http_upload_port``
|
|
port to use for HTTP File Upload
|
|
|
|
**default**: 8888
|
|
|
|
``http_upload_connection_type``
|
|
either ``http`` or ``https``.
|
|
|
|
**default**: ``https``
|
|
|
|
Note that HTTP Upload should always be ``https`` to end-user, the ``http`` option is to
|
|
be used only if you use a HTTP server as a proxy, and this server is already set for
|
|
TLS.
|
|
|
|
``http_upload_public_facing_url``
|
|
must be set to the URL that end-user will see. Notably useful if the component is behind
|
|
a proxy.
|
|
|
|
**default**: ``https://<component host>:<http_upload_port``
|
|
|
|
``quotas_json``
|
|
a JSON object indicating quotas to use for users. The object can have 3 keys:
|
|
|
|
``admins``
|
|
quotas to use for administrators (i.e. profiles set in ``admins_list``)
|
|
|
|
``users``
|
|
quotas to use for normal users (i.e. non admin profiles)
|
|
|
|
``jids``
|
|
per-jid specific quotas. The value is a JSON object where key is a user bare jid and
|
|
value is a quota.
|
|
|
|
Quotas can be either ``null`` for unlimited space, or a size value (`SI prefixes and
|
|
binary prefixes`_ can be used).
|
|
|
|
example::
|
|
|
|
quotas_json = {
|
|
"admins": null,
|
|
"users": "50 Mio",
|
|
"jids": {"pierre@example.org": "1 Gio"}
|
|
}
|
|
|
|
.. _SI prefixes and binary prefixes: https://en.wikipedia.org/wiki/Octet_(computing)#Unit_multiples
|
|
|
|
|
|
ActivityPub Gateway
|
|
-------------------
|
|
|
|
**entry_point:** ``ap-gateway``
|
|
|
|
.. note::
|
|
|
|
this component is currently in active development, and not yet usable for end-user. This
|
|
documentation will be updated during evolution of component.
|
|
|
|
You can follow the development by reading `Libervia Progress Notes`_.
|
|
|
|
.. _Libervia Progress Notes: https://www.goffi.org/tag/Libervia%20progress
|
|
|
|
This gateway will provide a bidirectional gateway between XMPP and `ActivityPub`_ (or AP
|
|
below). That means that user from XMPP will be able to follow actors or comments messages
|
|
from any software compatible with ActivityPub protocol, and vice versa.
|
|
|
|
.. _ActivityPub: https://activitypub.rocks/
|
|
|
|
.. note::
|
|
|
|
this component is mostly tested with Prosody as XMPP server reference, and Mastodon as
|
|
AP server reference, but it should work with any XMPP or AP server.
|
|
|
|
The component launches a HTTP server (necessary to communicate with AP software). This
|
|
server needs to handle HTTP requests made at paths ``/.well-known/webfinger`` and ``/_ap``
|
|
(or the ``ap_path`` set in configuration, see below). If the component is not directly
|
|
facing internet (e.g. integrated in an existing website though a proxy), you'll have to
|
|
redirect the requests made to those path to the HTTP server (i.e. to component host at the
|
|
port set at ``http_port``, see configuration below). Please check your HTTP server
|
|
documentation to find how this must be done.
|
|
|
|
how to address an AP actor from XMPP
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
When addressing an ActivityPub actor from XMPP, you must use a JID corresponding to the
|
|
actor. The domain part of the JID correspond to the gateway JID (the one set in gateway
|
|
profile), while the local part (before the ``@``) is used to specify the AP actor.
|
|
|
|
`XEP-0106`_ (JID Escaping) is used to indicate the AP actor identifier, thus the ``@``
|
|
must be escaped with ``\40``.
|
|
|
|
.. _XEP-0106: JID Escaping
|
|
|
|
**example**
|
|
|
|
If Louise wants to talk to Pierre which is on the ``example.net`` AP server, she can use
|
|
her XMPP AP gateway which is at ``ap.example.org``. Pierre AP's actor identifier is
|
|
``pierre@example.net``, Louise can access it via the JID
|
|
``pierre\40example.net@ap.example.org``.
|
|
|
|
Of course, this is a bit cumbersome to do by hand, it is expected that XMPP clients will
|
|
do the (un)escaping automatically for end-user, in a way that Louise could enter
|
|
``pierre@example.net`` directly, with an indicator to show that this is an ActivityPub
|
|
actor identifier rather than an XMPP JID.
|
|
|
|
how to address an XMPP entity from AP
|
|
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
|
|
|
To access an XMPP entity, just use its bare JID as AP actor.
|
|
|
|
**example**
|
|
|
|
If Pierre wants to talk Louise, he can directly use the JID which is the same as the AP
|
|
actor identifier, i.e. ``louise@example.org`` (note that on AP software, a ``@`` prefix is
|
|
often required, thus Pierre will look for ``@louise@example.org``).
|
|
|
|
.. note::
|
|
|
|
Currently the gateway only uses bare JID, and character set must be recognised by the
|
|
AP software to be used. This will evolve in the close future to have a way to access
|
|
various XMPP Pubsub nodes.
|
|
|
|
The actor endpoint can also be used directly in AP software (in the example above, it
|
|
would be by default ``https://example.org/_ap/actor/louise%40example.org``).
|
|
|
|
|
|
using the component
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
The component is currently only usable for development purpose, and it can be used with
|
|
the following method (with can be accessed through the ``APSend`` bridge method, client is
|
|
then replaced by the ``profile`` name, as last argument):
|
|
|
|
.. automethod:: sat.plugins.plugin_comp_ap_gateway.APGateway.publishMessage
|
|
|
|
The method can be used either with CLI's :ref:`debug bridge method
|
|
<li_debug_bridge_method>` or with any D-Bus tool like ``qdbus`` or ``d-feet`` (only if you
|
|
use the D-Bus bridge).
|
|
|
|
example
|
|
~~~~~~~
|
|
|
|
On its ``example.net`` Mastodon instance, Pierre has published a message with the id
|
|
``https://example.net/@pierre/106986412193109832``. To send a reply to this message,
|
|
Louise can use the following command::
|
|
|
|
$ li debug bridge method -c APSend '"{\"node\": \"https://example.net/@pierre/106986412193109832\", \"content\": \"A lille hello from XMPP\"}","pierre\\40example.net@ap.example.org", "louise"'
|
|
|
|
Note the double escaping, one for the shell argument, and the other to specify JSON
|
|
object.
|