doc (how-tos/email gateway): update the email gateway how-to:
pdate the gateway how-to to follow changes in configuration: - configure the component with the simplifiedi configuration (`[component.email_gateway]`) - remove the "supported features" section (redundant with email gateway documentation in `components.rst`)
This commit is contained in:
Goffi
parent
0c955f6abd
commit
b51b942103
2 changed files with 47 additions and 89 deletions
|
|
@ -20,7 +20,7 @@ A backup is made of data *types*, included or excluded with ``-i/--include`` and
|
|||
- ``private``: private storage: PEP-like client data, OMEMO crypto keys, PGP trust state
|
||||
- ``roster``: contact lists (from the roster cache in the database, kept up to date on
|
||||
every connection)
|
||||
- ``pep``: client PEP nodes and items (nick, avatar metadata, ...)
|
||||
- ``pep``: client PEP nodes and items (nick, avatar metadata, …)
|
||||
- ``gpg``: GPG home per profile (public and secret keys)
|
||||
- ``files``: shared files (the blobs of ``~/.sat/files/``)
|
||||
- ``db``: full copy of the database (not portable, SQLite only)
|
||||
|
|
|
|||
|
|
@ -4,18 +4,23 @@
|
|||
How-To: Email Gateway
|
||||
=====================
|
||||
|
||||
This document explains how to configure and use the Libervia Email Gateway component. **Note that the Libervia backend must be installed first** (see :ref:`installation`).
|
||||
This document explains how to configure and use the Libervia Email Gateway component.
|
||||
|
||||
The Email Gateway component allows users to send and receive emails through XMPP clients and convert mailing list to XMPP forums. It connects to IMAP/SMTP servers using credentials provided by users during registration.
|
||||
The Email Gateway component allows users to send and receive emails through XMPP clients
|
||||
and connect mailing lists to XMPP forums. It connects to IMAP/SMTP servers using
|
||||
credentials provided by users during registration.
|
||||
|
||||
For the supported features and other details, refer to the :ref:`email-gateway` section
|
||||
of the components documentation.
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
|
||||
Before configuring the Email Gateway, ensure you have:
|
||||
|
||||
1. Libervia backend installed and running (see :ref:`installation`)
|
||||
2. An XMPP server configured with component support (such as Prosody, Ejabberd, Openfire,
|
||||
Tigase, MongooseIM, etc).
|
||||
1. Libervia backend installed and working (see :ref:`installation`)
|
||||
2. An XMPP server configured with component support (such as Prosody, Ejabberd,
|
||||
Openfire, Tigase, MongooseIM, etc).
|
||||
|
||||
Configuration Steps
|
||||
-------------------
|
||||
|
|
@ -30,7 +35,7 @@ Configuration Steps
|
|||
|
||||
-- Add to /etc/prosody/prosody.cfg.lua
|
||||
Component "email.example.org"
|
||||
component_secret = "your_unique_secret"
|
||||
component_secret = "secret"
|
||||
|
||||
*For Ejabberd:*
|
||||
|
||||
|
|
@ -46,30 +51,26 @@ Configuration Steps
|
|||
module: ejabberd_service
|
||||
hosts:
|
||||
"email.example.org":
|
||||
password: "your_unique_secret"
|
||||
password: "secret"
|
||||
|
||||
**Important:** Replace `email.example.org` with your actual domain and `your_unique_secret` with a secure random string (you may use `openssl rand -hex 16` to generate).
|
||||
Of course replace ``email.example.org`` with your actual domain and ``secret`` with a
|
||||
secure random string (you may use ``openssl rand -hex 16`` to generate one).
|
||||
|
||||
2. **Create Libervia Profile for Email Gateway**
|
||||
2. **Configure the Email Gateway Component in Libervia**
|
||||
|
||||
Use the Libervia CLI to create the gateway profile:
|
||||
Add the following section to your Libervia configuration file (usually
|
||||
``libervia.toml``), using the same JID and shared secret as the ones configured on
|
||||
your XMPP server:
|
||||
|
||||
.. code-block:: bash
|
||||
.. code-block:: toml
|
||||
|
||||
$ li profile create email-gateway \
|
||||
-j email.example.org \
|
||||
-p "" \
|
||||
-x "your_unique_secret" \
|
||||
-C email-gateway \
|
||||
-A
|
||||
[component.email_gateway]
|
||||
jid = "email.example.org"
|
||||
secret = "secret"
|
||||
|
||||
This creates a profile named `email-gateway` with:
|
||||
|
||||
- JID: `email.example.org`
|
||||
- No profile password (`-p ""`), to avoid password prompts during Libervia backend startup.
|
||||
- XMPP server shared secret (`-x "your_unique_secret"`)
|
||||
- Component entry point (`-C email-gateway`)
|
||||
- Auto-connect enabled (`-A`)
|
||||
The component profile is then created automatically on backend startup, and the
|
||||
component starts automatically. See :ref:`components` for details about the
|
||||
components configuration.
|
||||
|
||||
3. **User Registration**
|
||||
|
||||
|
|
@ -81,7 +82,7 @@ Configuration Steps
|
|||
|
||||
.. code-block:: bash
|
||||
|
||||
$ li gateway register -cp your_user_profile email.example.org
|
||||
$ li gateway register -c -p your_user_profile email.example.org
|
||||
|
||||
**Registration Fields**
|
||||
|
||||
|
|
@ -117,55 +118,16 @@ Configuration Steps
|
|||
SMTP Password
|
||||
Password for SMTP authentication
|
||||
|
||||
**Important Notes**
|
||||
.. note::
|
||||
|
||||
- Ensure your IMAP/SMTP servers are accessible from the Libervia backend
|
||||
- The IMAP server must support the IDLE extension for real-time notifications
|
||||
- Ensure your IMAP/SMTP servers are accessible from the Libervia backend
|
||||
- The IMAP server must support the IDLE extension for real-time notifications
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
The Email Gateway uses user-specific registration data - **no additional configuration is needed** in Libervia's main config file. All settings are stored per-user during registration.
|
||||
|
||||
Supported Features
|
||||
------------------
|
||||
|
||||
- **Normal Email Conversion**: Standard email messages are converted to XMPP chat
|
||||
messages. Each email appears as a regular message in the user's XMPP client.
|
||||
|
||||
- **Mailing List Handling**: Mailing list emails are converted to PubSub blog nodes
|
||||
(microblogging) using XEP-0277:
|
||||
|
||||
* Each mailing list becomes a separate pubsub node
|
||||
* Each email in the list becomes a blog item
|
||||
* Replies to specific topics appear as comments to the corresponding item
|
||||
* Title tags within square brackets (e.g., `[tag]`) are converted to blog categories
|
||||
* Only the recipient JID associated with the mailing list can access the pubsub node by
|
||||
default.
|
||||
|
||||
- **Extended Addressing Support**: Properly handles email addressing metadata (To, CC,
|
||||
BCC) via XEP‑0033, converting it into XMPP addressing information for correct delivery.
|
||||
This allows multi‑party discussions without relying on group chat (XEP‑0045 MUC), which
|
||||
can be tricky to implement in email‑based communication.
|
||||
|
||||
- **Header Conversion**: Converts important email headers to XMPP metadata, such as:
|
||||
|
||||
* Keywords → XMPP "Keywords" header (XEP-0131)
|
||||
* Importance → XMPP "Urgency" header (XEP-0131)
|
||||
|
||||
- **Message Cleaning**: Automatically detects noisy elements in mailing list emails
|
||||
(quoted replies, signatures) and tags them with a CSS class named "noise" so XMPP
|
||||
clients can selectively hide or visually distinguish these parts of the message.
|
||||
|
||||
- **Attachment Management**: Allows users to retrieve and delete email attachments via
|
||||
PubSub File Sharing (XEP-0498).
|
||||
|
||||
.. note::
|
||||
Attachments cannot yet be sent with messages (this
|
||||
functionality is in development).
|
||||
|
||||
- **End-to-End Encryption**: Supports Gateway Relayed Encryption (not yet an official XEP)
|
||||
for encrypted email messages. Requires XMPP clients that implement this specification.
|
||||
Besides the component configuration described above, no other configuration is needed:
|
||||
the gateway uses user-specific data provided during registration.
|
||||
|
||||
Troubleshooting
|
||||
---------------
|
||||
|
|
@ -178,37 +140,33 @@ Troubleshooting
|
|||
- Solution
|
||||
* - XMPP component connection failed
|
||||
- Verify the shared secret matches on **both** Libervia and the XMPP server.
|
||||
The component JID must *exactly* match the JID configured on the XMPP server (e.g.
|
||||
“email.example.org” in Prosody must match the JID you set when creating the
|
||||
Libervia profile).
|
||||
The component JID must *exactly* match the JID configured on the XMPP server
|
||||
(e.g. "email.example.org" in Prosody must match the JID you set in the Libervia
|
||||
configuration).
|
||||
* - User registration fails
|
||||
- * Check the IMAP/SMTP credentials and make sure the servers are reachable from the
|
||||
- * Check the IMAP credentials and make sure the IMAP server is reachable from the
|
||||
Libervia host.
|
||||
* Verify that the IMAP server supports the **IDLE** extension (required for
|
||||
real‑time notifications).
|
||||
* If you use self‑signed certificates, add them to the system trust store.
|
||||
real-time notifications).
|
||||
* If you use self-signed certificates, add them to the system trust store.
|
||||
* - Email not received
|
||||
- * Confirm the user’s email credentials (you can re-register to check).
|
||||
- * Confirm the user's email credentials (you can re-register to check).
|
||||
* Check Libervia Backend logs to ensure that the IMAP connection succeeded.
|
||||
* Verify that messages are arriving in the user’s INBOX.
|
||||
* - “DBus not launched” error
|
||||
- Follow :ref:`installation_dbus` instructions for headless servers – the
|
||||
Libervia backend relies on D‑Bus to run.
|
||||
* Verify that messages are arriving in the user's INBOX.
|
||||
* - Email not sent
|
||||
- * Check the SMTP credentials and make sure the SMTP server is reachable from the
|
||||
Libervia host.
|
||||
* Check the Libervia backend logs for the sending error.
|
||||
* - Attachments not appearing
|
||||
- The Email Gateway can *retrieve* attachments, but does not yet deliver them with
|
||||
outgoing messages (feature work in progress).
|
||||
* - Encrypted emails not working
|
||||
- “Gateway Relayed Encryption” is a work‑in‑progress extension (not yet an official XEP).
|
||||
Use a client that implements this specification.
|
||||
- "Gateway Relayed Encryption" is a work-in-progress extension (not yet an official
|
||||
XEP). Use a client that implements this specification.
|
||||
* - Mailing lists not converted
|
||||
- Verify that the incoming e‑mail contains a **valid “List‑ID”** header. The value
|
||||
- Verify that the incoming e-mail contains a **valid "List-ID"** header. The value
|
||||
must match the format expected for PubSub node creation.
|
||||
|
||||
.. note::
|
||||
|
||||
The Email Gateway is under active development. Some features may have limitations.
|
||||
|
||||
See Also
|
||||
--------
|
||||
|
||||
- For Libervia components overview: :ref:`components`
|
||||
|
|
|
|||
Loading…
Reference in a new issue