# HG changeset patch # User Goffi # Date 1632667080 -7200 # Node ID ba4ef64a6938bdf63d40ba239fb825d829751f59 # Parent 02e5e2385a30900228b77f7c810a9e5a4a0f4c46 doc: components documentation: rel 362 diff -r 02e5e2385a30 -r ba4ef64a6938 doc/components.rst --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/components.rst Sun Sep 26 16:38:00 2021 +0200 @@ -0,0 +1,153 @@ +.. _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 ` +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 `` and the JID to use with ``-j +.``. + +The component entry point is specified with ``-C ``. + +.. _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://: