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

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.

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"}
}