Mercurial > libervia-backend
changeset 3681:742e466fa000
merge bookmark `@`
author | Goffi <goffi@goffi.org> |
---|---|
date | Sun, 26 Sep 2021 16:41:49 +0200 (2021-09-26) |
parents | 68f2a9c171d1 (current diff) ba4ef64a6938 (diff) |
children | 7c990aaa49d3 |
files | doc/index.rst sat/plugins/plugin_comp_file_sharing.py sat_frontends/jp/common.py |
diffstat | 5 files changed, 166 insertions(+), 10 deletions(-) [+] |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/components.rst Sun Sep 26 16:41:49 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 <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
--- a/doc/index.rst Sun Sep 26 16:38:40 2021 +0200 +++ b/doc/index.rst Sun Sep 26 16:41:49 2021 +0200 @@ -26,6 +26,7 @@ installation.rst overview.rst configuration.rst + components.rst developer.rst /libervia-cli/index.rst /libervia-tui/index.rst
--- a/doc/libervia-cli/profile.rst Sun Sep 26 16:38:40 2021 +0200 +++ b/doc/libervia-cli/profile.rst Sun Sep 26 16:41:49 2021 +0200 @@ -41,6 +41,7 @@ $ li profile disconnect -p pierre +.. _li_profile_create: create ======
--- a/sat/plugins/plugin_comp_file_sharing.py Sun Sep 26 16:38:40 2021 +0200 +++ b/sat/plugins/plugin_comp_file_sharing.py Sun Sep 26 16:41:49 2021 +0200 @@ -1,6 +1,6 @@ #!/usr/bin/env python3 -# SAT plugin for parrot mode (experimental) +# Libervia File Sharing component # Copyright (C) 2009-2021 Jérôme Poisson (goffi@goffi.org) # This program is free software: you can redistribute it and/or modify @@ -49,7 +49,7 @@ PLUGIN_INFO = { C.PI_NAME: "File sharing component", - C.PI_IMPORT_NAME: "file_sharing", + C.PI_IMPORT_NAME: "file-sharing", C.PI_MODES: [C.PLUG_MODE_COMPONENT], C.PI_TYPE: C.PLUG_TYPE_ENTRY_POINT, C.PI_PROTOCOLS: [], @@ -208,7 +208,7 @@ request.content = None # the 2 following headers are not standard, but useful in the context of file - # sharing with HTTP Upload: first one allow uploaded to specify the path + # sharing with HTTP Upload: first one allow uploader to specify the path # and second one will disable public exposure of the file through HTTP path = request.getHeader("Xmpp-File-Path") if path: @@ -244,7 +244,7 @@ @property def upload_data(self): - """A tuple with upload_id and filename retrieve from requested path""" + """A tuple with upload_id and filename retrieved from requested path""" if self._upload_data is not None: return self._upload_data @@ -370,9 +370,9 @@ self._getDirectoryMetadataElts) self.files_path = self.host.getLocalPath(None, C.FILES_DIR, profile=False) self.http_port = int(self.host.memory.getConfig( - 'component file_sharing', 'http_upload_port', 8888)) + 'component file-sharing', 'http_upload_port', 8888)) connection_type = self.host.memory.getConfig( - 'component file_sharing', 'http_upload_connection_type', 'https') + 'component file-sharing', 'http_upload_connection_type', 'https') if connection_type not in ('http', 'https'): raise exceptions.ConfigError( 'bad http_upload_connection_type, you must use one of "http" or "https"' @@ -383,7 +383,7 @@ reactor.listenTCP(self.http_port, self.server) else: options = tls.getOptionsFromConfig( - self.host.memory.config, "component file_sharing") + self.host.memory.config, "component file-sharing") tls.TLSOptionsCheck(options) context_factory = tls.getTLSContextFactory(options) reactor.listenSSL(self.http_port, self.server, context_factory) @@ -394,7 +394,7 @@ def profileConnecting(self, client): self.init() public_base_url = self.host.memory.getConfig( - 'component file_sharing', 'http_upload_public_facing_url') + 'component file-sharing', 'http_upload_public_facing_url') if public_base_url is None: client._file_sharing_base_url = f"https://{client.host}:{self.http_port}" else: @@ -410,7 +410,7 @@ def getQuota(self, client, entity): """Return maximum size allowed for all files for entity""" # TODO: handle special entities like admins - quotas = self.host.memory.getConfig("component file_sharing", "quotas_json", {}) + quotas = self.host.memory.getConfig("component file-sharing", "quotas_json", {}) entity_bare_s = entity.userhost() try: quota = quotas["jids"][entity_bare_s]
--- a/sat_frontends/jp/common.py Sun Sep 26 16:38:40 2021 +0200 +++ b/sat_frontends/jp/common.py Sun Sep 26 16:41:49 2021 +0200 @@ -36,11 +36,12 @@ from configparser import NoSectionError, NoOptionError from collections import namedtuple -# defaut arguments used for some known editors (editing with metadata) +# default arguments used for some known editors (editing with metadata) VIM_SPLIT_ARGS = "-c 'set nospr|vsplit|wincmd w|next|wincmd w'" EMACS_SPLIT_ARGS = '--eval "(split-window-horizontally)"' EDITOR_ARGS_MAGIC = { "vim": VIM_SPLIT_ARGS + " {content_file} {metadata_file}", + "nvim": VIM_SPLIT_ARGS + " {content_file} {metadata_file}", "gvim": VIM_SPLIT_ARGS + " --nofork {content_file} {metadata_file}", "emacs": EMACS_SPLIT_ARGS + " {content_file} {metadata_file}", "xemacs": EMACS_SPLIT_ARGS + " {content_file} {metadata_file}",