diff --git a/doc/howto_backup.rst b/doc/howto_backup.rst index 22bc4392..192aeb03 100644 --- a/doc/howto_backup.rst +++ b/doc/howto_backup.rst @@ -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) diff --git a/doc/howto_email_gateway.rst b/doc/howto_email_gateway.rst index d0c21eab..19e43539 100644 --- a/doc/howto_email_gateway.rst +++ b/doc/howto_email_gateway.rst @@ -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`