annotate doc/overview.rst @ 4231:e11b13418ba6

plugin XEP-0353, XEP-0234, jingle: WebRTC data channel signaling implementation: Implement XEP-0343: Signaling WebRTC Data Channels in Jingle. The current version of the XEP (0.3.1) has no implementation and contains some flaws. After discussing this on xsf@, Daniel (from Conversations) mentioned that they had a sprint with Larma (from Dino) to work on another version and provided me with this link: https://gist.github.com/iNPUTmice/6c56f3e948cca517c5fb129016d99e74 . I have used it for my implementation. This implementation reuses work done on Jingle A/V call (notably XEP-0176 and XEP-0167 plugins), with adaptations. When used, XEP-0234 will not handle the file itself as it normally does. This is because WebRTC has several implementations (browser for web interface, GStreamer for others), and file/data must be handled directly by the frontend. This is particularly important for web frontends, as the file is not sent from the backend but from the end-user's browser device. Among the changes, there are: - XEP-0343 implementation. - `file_send` bridge method now use serialised dict as output. - New `BaseTransportHandler.is_usable` method which get content data and returns a boolean (default to `True`) to tell if this transport can actually be used in this context (when we are initiator). Used in webRTC case to see if call data are available. - Support of `application` media type, and everything necessary to handle data channels. - Better confirmation message, with file name, size and description when available. - When file is accepted in preflight, it is specified in following `action_new` signal for actual file transfer. This way, frontend can avoid the display or 2 confirmation messages. - XEP-0166: when not specified, default `content` name is now its index number instead of a UUID. This follows the behaviour of browsers. - XEP-0353: better handling of events such as call taken by another device. - various other updates. rel 441
author Goffi <goffi@goffi.org>
date Sat, 06 Apr 2024 12:57:23 +0200
parents 7fe1028acab2
children ba46d6a0ff3a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
3022
03fe31effa7f doc: some corrections:
Goffi <goffi@goffi.org>
parents: 3021
diff changeset
1 ========
03fe31effa7f doc: some corrections:
Goffi <goffi@goffi.org>
parents: 3021
diff changeset
2 Overview
03fe31effa7f doc: some corrections:
Goffi <goffi@goffi.org>
parents: 3021
diff changeset
3 ========
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
4
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
5 To have a better understanding of Libervia, this page gives a global view of what it is
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
6 and what are the important concepts linked to it. You don't need to read this to use it, but you
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
7 can if you wish to understand "who is doing what".
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
8
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
9 Libervia is a XMPP client. `XMPP`_ is an open standard used for communication (notably
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
10 instant messaging but not only). XMPP is a solid standard, which is decentralised and
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
11 federated.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
12
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
13 Libervia is not only focusing on instant messaging, and aims to be a universal communication
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
14 tools. In other words, you can use Libervia to chat, but also to blog publicly or privately, to
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
15 share file, photo albums, to create events, to have discussion forum, etc.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
16
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
17 Libervia is actually a whole ecosystem, and is made in a way that you can use it with many
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
18 different interfaces (or "frontends"). There is a common central part which is called the
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
19 "backend", it handles most of the work, while frontends are mostly about the interactions
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
20 with user(s).
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
21
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
22 To work, as Libervia is a XMPP **client**, a XMPP **server** is needed. You can either run your
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
23 own, or use an existing one (either public, or run by an organisation you belong to, like
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
24 family server, run by a friend, your company, university, association, etc.). If you want
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
25 to run your own server, there are already plenty of them and happily most of which are
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
26 `libre <https://en.wikipedia.org/wiki/Free_software>`_, you can check an `up-to-date list
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
27 on the XSF website <https://xmpp.org/software/servers.html>`_ (the XSF or *XMPP Standards
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
28 Foundation* being the non-profit organisation taking care of the XMPP standard).
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
29
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
30 So to summarise, Libervia is a communication ecosystem. Technically, it is a **XMPP
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
31 client** which connect to an **XMPP server**. Libervia itself works with a **backend** and
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
32 one or many **frontends**.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
33
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
34 .. _XMPP: https://xmpp.org
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
35
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
36
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
37 Backend
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
38 =======
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
39
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
40 The backend is a daemon, that means that it's a service running in the background.
3536
0985c47ffd96 doc: config file is now `libervia.conf` (even if `sat.conf` still works, for now)
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
41 It takes its main configuration from a file named ``libervia.conf`` and can be in different
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
42 locations (see below). It uses data in a directory called ``local_dir``, and which
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
43 default, on suitable platforms, to the corresponding `XDG directory`_, which is most of
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3536
diff changeset
44 time ``~/.local/share/libervia``. In this directory, you'll find the main database in the
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3536
diff changeset
45 ``libervia.db`` file, which is a `SQLite`_ database.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
46
3563
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3536
diff changeset
47 The backend is run and stopped with the ``libervia-backend`` executable. Running it
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3536
diff changeset
48 without argument launch the backend in the background, with ``libervia-backend fg`` you
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3536
diff changeset
49 run it in the foreground (you'll see log directly and can stop the backend with
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3536
diff changeset
50 ``Ctrl + c``). The ``libervia-backend status`` commands help you discover if the backend
267e4987b58b doc: fix remaining SàT references/typos + add `libervia-cli` missing commands
Goffi <goffi@goffi.org>
parents: 3536
diff changeset
51 is running or stopped.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
52
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
53 .. _XDG directory: https://www.freedesktop.org/wiki/Software/xdg-user-dirs/
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
54 .. _SQLite: https://sqlite.org
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
55
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
56 Frontends
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
57 =========
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
58
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
59 Frontends are used to make the interface between user and the backend. Frontends are
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
60 adapted to different use cases, and must be started after the backend (if the backend is
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
61 not started, you'll see a message telling you so). In most installations, the backend
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
62 should be started automatically when you want to use a frontend.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
63
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
64 Bellow you'll see a list of the official frontends currently maintained:
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
65
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
66 Libervia Deskop/Mobile (Cagou)
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
67 ------------------------------
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
68
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
69 Libervia Desktop (alias ``Libervia Mobile`` or ``Cagou``) is the desktop/mobile frontend.
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
70 It's probably the main interface for most users. It is based on the `Kivy`_ framework and
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
71 should run on most platforms (for now it is officially tested only on GNU/Linux and
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
72 Android phones and tablets).
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
73
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
74 .. _Kivy: https://kivy.org
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
75
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
76 Libervia Web
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
77 ------------
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
78
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
79 The Web frontend is the second main interface for most users. This frontend has the
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
80 particularity to be in 2 parts: a server which serves HTTP content, and a client which
3627
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
81 runs in the browser. So you have Libervia Web server which connect to Libervia backend which itself
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
82 connect to the XMPP server, and your browser will connect to Libervia Web server.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
83
3627
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
84 ..
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
85 # NOTE: currently not relevant as there is no Web APP anymore, may come back in the
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
86 future though
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
87 In the browser, you can access the server in two ways: either directly with what we call
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
88 **Libervia pages**, or with a JavaScript code in `single-page application`_ which is the
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
89 **Libervia client** (or **Libervia web app**) that we have mentioned above.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
90
3627
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
91 The **Libervia Web Pages** are web pages managing a single feature. They can work without
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
92 JavaScript when it's possible (it's not the case for instant messaging or similar highly
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
93 dynamic contents). They aims to be simple and straightforward to use. That what you're
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
94 accessing when you're using Libervia Web.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
95
3627
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
96 ..
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
97 #Note: as above, not relevant anymore but may come back in the future
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
98 The **Libervia Web Client** is a highly dynamic web application, used to access more features.
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
99 It's more complete and may be well adapted if you want to let Libervia running in a browser tab
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
100 for an extended period.
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
101
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
102 Libervia Web is also the central part of the **Web Framework**. Indeed, in addition of
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
103 being a frontend to Libervia features (which is built with this framework), you can create
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
104 totally different websites which are integrated in Libervia (and so XMPP) ecosystem. This
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
105 framework uses Libervia template engine (based on `Jinja2`_) and makes the creation of
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
106 decentralised and federated websites simple. Thanks to this framework, it's easy to
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
107 experiment new ideas/features, or to change completely the look and feel of the Libervia
7fe1028acab2 doc (overview): comment mentions of web app (not relevant anymore, for now) + web frontend name change
Goffi <goffi@goffi.org>
parents: 3563
diff changeset
108 frontend.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
109
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
110 The `official Libervia website`_ is made with Libervia web framework.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
111
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
112 .. _single-page application: https://en.wikipedia.org/wiki/Single-page_application
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
113 .. _Jinja2: http://jinja.pocoo.org/
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
114 .. _official Libervia website: https://salut-a-toi.org
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
115
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
116 Libervia TUI (Primitivus)
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
117 -------------------------
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
118
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
119 Libervia TUI (alias ``Primitivus``) is the Terminal User Interface. In other words, it
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
120 works in console and is intended for people at ease with it. Its text only interface has
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
121 several advantages: you get rid of many distracting things (like images), it works without
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
122 graphical environment installed (which is often the case on servers) and it works on
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
123 distant shell (like `ssh`_) while staying gentle with your bandwidth.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
124
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
125 Primitivus is shipped with the backend, so it should be always available once Libervia is
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
126 installed (but some distributions may provide it separately).
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
127
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
128 You can check :doc:`Libervia TUI documentation <libervia-tui/index>` for more details.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
129
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
130 .. _ssh: https://en.wikipedia.org/wiki/Secure_Shell
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
131
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
132 Libervia CLI (jp)
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
133 -----------------
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
134
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
135 Libervia CLI (alias ``li`` or ``jp``) is the Command Line Interface. It's a
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
136 powerful tool which allows to do nearly everything you can do with other frontends.
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
137 Particularly useful if you want to check something quickly, or if you want to do some
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
138 automation.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
139
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
140 You can check :doc:`Libervia CLI documentation <libervia-cli/index>` documentation for more details.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
141
3041
72583524cfd3 doc (jp): jp commands are now fully documented:
Goffi <goffi@goffi.org>
parents: 3022
diff changeset
142 .. _glossary:
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
143
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
144 Glossary
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
145 ========
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
146
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
147 While using Libervia you may see some terms or concept. This section explain the most important
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
148 ones.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
149
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
150 profile
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
151 -------
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
152
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
153 A profile is the name linked to an account data. Usually a profile correspond to an XMPP
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
154 account, but you can have several profiles using the same XMPP account (with different
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
155 parameters) even if this is not usual.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
156
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
157 On a Libervia installation used by a single user, the profiles are usually used for multiple
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
158 accounts. On a multi-users installations, there is usually one profile per user.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
159
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
160 When you connect to a Libervia frontend, you need to specify a profile and the associated password. The profile password is not the same as the password of the XMPP account. While this may sounds confusing, there are several reason why we use this notion of profile instead of directly the XMPP account/password:
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
161
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
162 - Libervia needs to know the plain XMPP password to connect, and it is encrypted in database.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
163 The profile password is used to encrypt/decrypt it, this way only a `password hash`_ is
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
164 stored and the XMPP password is encrypted `at rest`_.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
165
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
166 - As a further benefit, several passwords could be associated to the same profile (this
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
167 feature is currently not used in Libervia).
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
168
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
169 - profile password can be empty, in which case no password is requested when a profile is
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
170 used
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
171
3353
7726916c1ba6 doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 3251
diff changeset
172 .. note::
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
173
3353
7726916c1ba6 doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 3251
diff changeset
174 if you use an empty profile password, the XMPP password won't be encrypted in database
7726916c1ba6 doc: updated installation instructions
Goffi <goffi@goffi.org>
parents: 3251
diff changeset
175 (or more precisely, will be trivial to decrypt).
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
176
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
177 - a profile is a simple name associated with an account, it's easier to remember than a
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
178 whole XMPP identifier (also named "JID" for *Jabber ID*)
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
179
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
180 You always have a *default* profile which is the profile used when you don't select any
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
181 (notably used in jp). This is the first profile that you have created except if you have
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
182 changed it using a frontend (you can change it with jp).
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
183
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
184 .. _password hash: https://en.wikipedia.org/wiki/Key_derivation_function
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
185 .. _at rest: https://en.wikipedia.org/wiki/Data_at_rest
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
186
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
187 profile key
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
188 -----------
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
189
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
190 A profile **key** is a special name used as a way to select automatically one profile. The
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
191 most important one is ``@DEFAULT@`` which, as you can guess, means the default profile.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
192
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
193 bridge
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
194 ------
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
195
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
196 The "bridge" is the name used to design Libervia's `IPC`_, or in other words the way
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
197 the backend communicate with frontends. Several bridges can be used, the default one being
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
198 `D-Bus`_.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
199
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
200 The other available bridges are:
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
201
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
202 pb
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
203 `Perspective Broker`_ is a part of `Twisted`_ (the framework used by the backend and some
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
204 frontends)
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
205
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
206 embedded
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
207 this embeds the backend into the frontend. The frontend is then using the backend as a
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
208 library.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
209
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
210 .. _IPC: https://en.wikipedia.org/wiki/Inter-process_communication
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
211 .. _D-Bus: https://www.freedesktop.org/wiki/Software/dbus/
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
212 .. _Perspective Broker: https://twistedmatrix.com/documents/current/core/howto/pb-intro.html
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
213 .. _Twisted: https://twistedmatrix.com
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
214
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
215 Libervia Media
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
216 --------------
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
217
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
218 Most of the frontends use images or other media. To avoid duplication and to make the code
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
219 repositories lighter, those media are grouped in a separate repository. The Libervia media
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
220 repository is available at https://repos.goffi.org/sat_media. You can also download media
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
221 at https://ftp.goffi.org/sat_media/sat_media.tar.bz2. The path where Libervia media are
3536
0985c47ffd96 doc: config file is now `libervia.conf` (even if `sat.conf` still works, for now)
Goffi <goffi@goffi.org>
parents: 3488
diff changeset
222 installed must be specified in ``libervia.conf`` in ``media_dir`` option of the ``[DEFAULT``
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
223 section.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
224
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
225 Libervia Templates
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
226 ------------------
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
227
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
228 Libervia embeds a `Jinja2`_ template engine (see `Libervia Web`_ above). "Libervia templates" refers to
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
229 the default templates (i.e. the official templates, the ones used in default Libervia pages). Those template may also be used by other frontends than Libervia (jp can use them with the :ref:`libervia-cli_output` arguments).
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
230
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
231 Libervia templates repository is available at https://repos.goffi.org/sat_templates, they can
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
232 also be downloaded at `PyPI <https://pypi.org/project/sat-templates/>`_ and will be
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
233 installed automatically if you install Libervia.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
234
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
235 Related projects
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
236 ================
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
237
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
238 Some project are closely related to Libervia, here is a list of official related
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
239 project.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
240
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
241 Libervia PubSub
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
242 ---------------
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
243
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
244 Numerous features of Libervia are taking profit of `PubSub`_ functionalities of XMPP.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
245 Because PubSub implementations in the wild are not all on the same level, and some
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
246 experimental features are sometimes explored, a PubSub service as been written
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
247 specifically for the needs of Libervia (but it's not depending on Libervia and any XMPP software can
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
248 use it).
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
249
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
250 Libervia PubSub aims to be a feature complete, server-independent PubSub implementation, and
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
251 try to be up-to-date with latest XMPP PubSub extensions. It is the privileged service to
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
252 use with Libervia because it supports everything needed (but Libervia can work with any XMPP PubSub
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
253 service, it will adapt itself to available features).
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
254
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
255 Libervia PubSub can also be used as a `PEP`_ service, if some XMPP extensions are supported by
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
256 your server (see below).
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
257
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
258 .. _PubSub: https://xmpp.org/about/technology-overview.html#pubsub
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
259 .. _PEP: https://xmpp.org/extensions/xep-0163.html
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
260
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
261 XMPP Extension Protocols
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
262 ------------------------
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
263
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
264 For the needs of Libervia or Libervia PubSub, some `XMPP Extension Protocols`_ (or XEP) have been
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
265 proposed and got an official number. The current list of extensions is:
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
266
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
267 `XEP-0355`_: Namespace Delegation
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
268 This has been proposed for the needs of Libervia PubSub, and allows the XMPP server to
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
269 "delegate" some features management to a third party service. It is needed to use Libervia
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
270 Pubsub as a PEP service.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
271
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
272 `XEP-0356`_: Privileged Entity
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
273 In the same spirit as previous one, this has been done so Libervia PubSub could be used as a
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
274 PEP service. This extensions allows a "component" (which is more or less a server
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
275 generic plugin) to gain some privileged access to data such as presence information,
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
276 roster or to send a message like if it was sent by the server.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
277
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
278 `XEP-0413`_: Order-By
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
279 This extension is used to specify the sorting order in which a client wishes to retrieve
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
280 some results. It is notably used by Libervia and Libervia PubSub to retrieve items like blog posts
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
281 or tickets in creation order or order of last modification.
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
282
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
283 .. _XEP-0355: https://xmpp.org/extensions/xep-0355.html
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
284 .. _XEP-0356: https://xmpp.org/extensions/xep-0356.html
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
285 .. _XEP-0413: https://xmpp.org/extensions/xep-0413.html
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
286
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
287 .. _XMPP Extension Protocols: https://xmpp.org/about/standards-process.html
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
288
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
289 Prosody's `mod_delegation`_ and `mod_privilege`_
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
290 -------------------------------------------------
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
291
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
292 Prosody modules have been created to implement the *Namespace Delegation* and *Privileged
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
293 Entity* extensions mentioned above. If you use Prosody, you'll have to activate those 2
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
294 modules to use Libervia PubSub as a PEP service.
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
295
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
296 .. _mod_privilege: https://modules.prosody.im/mod_privilege.html
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
297 .. _mod_delegation: https://modules.prosody.im/mod_delegation.html
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
298
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
299 Libervia official website
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
300 -------------------------
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
301
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
302 The official website is made with Libervia web framework. You'll find it at https://repos.goffi.org/sat_web_site
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
303
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
304 Salut
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
305 -----
3488
c80a0f864b5d doc: updated doc following global renaming
Goffi <goffi@goffi.org>
parents: 3353
diff changeset
306 Probably the smaller side project used by Libervia, it is a simple users directory (registration must be done explicitly by users) using `XEP-0055`_ (Jabber Search).
3021
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
307
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
308 You'll find it at https://repos.goffi.org/salut/
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
309
8ec35cf13f66 doc: added, overview, configuration and Primitivus documentation + some small modifications
Goffi <goffi@goffi.org>
parents:
diff changeset
310 .. _XEP-0055: https://xmpp.org/extensions/xep-0055.html