From 6859de3b83e15866f131df9d9eeae7eeea2c7119 Mon Sep 17 00:00:00 2001 From: Quentin Dufour Date: Thu, 25 Jan 2024 09:35:42 +0100 Subject: [PATCH] clean documentation --- .../connect/{ => _drafts}/caldav.md | 0 .../connect/{ => _drafts}/carddav.md | 0 .../connect/{ => _drafts}/proxy.md | 0 .../connect/{ => _drafts}/wasm.md | 0 content/documentation/connect/_index.md | 9 +++- content/documentation/connect/imap.md | 48 +++++++------------ .../cookbook/{ => _drafts}/autodiscovery.md | 0 .../cookbook/{ => _drafts}/backups.md | 0 .../{ => _drafts}/garage-cluster-storage.md | 0 .../cookbook/{ => _drafts}/ldap.md | 0 .../cookbook/{ => _drafts}/manual-hardened.md | 0 .../cookbook/{ => _drafts}/observability.md | 0 .../cookbook/{ => _drafts}/orchestrators.md | 0 .../cookbook/{ => _drafts}/updates.md | 0 content/documentation/cookbook/config.md | 3 ++ content/documentation/cookbook/discovery.txt | 3 -- content/documentation/cookbook/key_backup.txt | 22 --------- content/documentation/cookbook/ldap.txt | 5 -- content/documentation/cookbook/lmtp.txt | 3 -- .../cookbook/static-user-management.md | 4 +- content/documentation/cookbook/tls.txt | 1 - content/documentation/reference/config.md | 48 +++++++++++-------- 22 files changed, 56 insertions(+), 90 deletions(-) rename content/documentation/connect/{ => _drafts}/caldav.md (100%) rename content/documentation/connect/{ => _drafts}/carddav.md (100%) rename content/documentation/connect/{ => _drafts}/proxy.md (100%) rename content/documentation/connect/{ => _drafts}/wasm.md (100%) rename content/documentation/cookbook/{ => _drafts}/autodiscovery.md (100%) rename content/documentation/cookbook/{ => _drafts}/backups.md (100%) rename content/documentation/cookbook/{ => _drafts}/garage-cluster-storage.md (100%) rename content/documentation/cookbook/{ => _drafts}/ldap.md (100%) rename content/documentation/cookbook/{ => _drafts}/manual-hardened.md (100%) rename content/documentation/cookbook/{ => _drafts}/observability.md (100%) rename content/documentation/cookbook/{ => _drafts}/orchestrators.md (100%) rename content/documentation/cookbook/{ => _drafts}/updates.md (100%) delete mode 100644 content/documentation/cookbook/discovery.txt delete mode 100644 content/documentation/cookbook/key_backup.txt delete mode 100644 content/documentation/cookbook/ldap.txt delete mode 100644 content/documentation/cookbook/lmtp.txt delete mode 100644 content/documentation/cookbook/tls.txt diff --git a/content/documentation/connect/caldav.md b/content/documentation/connect/_drafts/caldav.md similarity index 100% rename from content/documentation/connect/caldav.md rename to content/documentation/connect/_drafts/caldav.md diff --git a/content/documentation/connect/carddav.md b/content/documentation/connect/_drafts/carddav.md similarity index 100% rename from content/documentation/connect/carddav.md rename to content/documentation/connect/_drafts/carddav.md diff --git a/content/documentation/connect/proxy.md b/content/documentation/connect/_drafts/proxy.md similarity index 100% rename from content/documentation/connect/proxy.md rename to content/documentation/connect/_drafts/proxy.md diff --git a/content/documentation/connect/wasm.md b/content/documentation/connect/_drafts/wasm.md similarity index 100% rename from content/documentation/connect/wasm.md rename to content/documentation/connect/_drafts/wasm.md diff --git a/content/documentation/connect/_index.md b/content/documentation/connect/_index.md index 66b736c..2e60dc4 100644 --- a/content/documentation/connect/_index.md +++ b/content/documentation/connect/_index.md @@ -5,13 +5,20 @@ sort_by = "weight" template = "documentation.html" +++ +This section references all the clients that can be connected to Aerogramme, +what features they can use, how well they behave. + ## Standard protocols - [IMAP](@/documentation/connect/imap.md) - Access to your mailbox - - [CalDAV](@/documentation/connect/caldav.md) - Access to your calendars + ## Client-side encryption + - **Companion Proxy** - Companion proxy is not yet documented as it will be refined in the near future. + diff --git a/content/documentation/connect/imap.md b/content/documentation/connect/imap.md index 99a14ea..7402853 100644 --- a/content/documentation/connect/imap.md +++ b/content/documentation/connect/imap.md @@ -3,37 +3,21 @@ title = "IMAP" weight = 5 +++ -Standard IMAP configuration. -Examples with some well known email clients. +The following clients are known to work with Aerogramme: -## Thunderbird +| Client | Date | Aerogramme version | Status | +|----------------|------------|--------------------|--------| +| Mutt | 2023 | pre 0.1 | ✅ | +| Thunderbird | 2024-01-08 | pre 0.2 | ✅ | +| Geary | 2024-01-08 | pre 0.2 | ✅ | +| Evolution | 2024-01-08 | pre 0.2 | ✅ | +| K9 Mail | 2024-01-08 | pre 0.2 | ✅ | +| Fair Email | 2024-01-08 | pre 0.2 | ✅ | +| Apple Mail iOS | 2024-01-08 | pre 0.2 | ✅ | +| Outlook iOS | 2024-01-08 | pre 0.2 | ✅ | +| Gmail Android | 2024-01-08 | pre 0.2 | ✅ | +| Windows Mail | 2024-01-08 | pre 0.2 | ✅ | -## K9Mail - -## Mutt - -Create a config file (`~/.muttrc`): - -```ini -set imap_user = alice -set imap_pass = p455w0rd -set folder = imap://localhost:1143 -set spoolfile = +INBOX -set ssl_starttls = no -set ssl_force_tls = no -mailboxes = +INBOX -bind index G imap-fetch-mail -``` - -And then simply launch `mutt`. -The first time nothing will happen as Aerogramme must -process your incoming emails. Just ask `mutt` to refresh its -view by pressing `G` (for *Get*). - -Now, you should see some emails: - -![Screenshot of mutt mailbox](/screenshots/mutt_mb.png) - -And you can read them: - -![Screenshot of mutt mail view](/screenshots/mutt_mail.png) +If you find a regression, please report it. +If you use a well-known email client, that work or not work with Aerogramme, +please report it here, so we can track Aerogramme's IMAP compatibility with the rest of the ecosystem. diff --git a/content/documentation/cookbook/autodiscovery.md b/content/documentation/cookbook/_drafts/autodiscovery.md similarity index 100% rename from content/documentation/cookbook/autodiscovery.md rename to content/documentation/cookbook/_drafts/autodiscovery.md diff --git a/content/documentation/cookbook/backups.md b/content/documentation/cookbook/_drafts/backups.md similarity index 100% rename from content/documentation/cookbook/backups.md rename to content/documentation/cookbook/_drafts/backups.md diff --git a/content/documentation/cookbook/garage-cluster-storage.md b/content/documentation/cookbook/_drafts/garage-cluster-storage.md similarity index 100% rename from content/documentation/cookbook/garage-cluster-storage.md rename to content/documentation/cookbook/_drafts/garage-cluster-storage.md diff --git a/content/documentation/cookbook/ldap.md b/content/documentation/cookbook/_drafts/ldap.md similarity index 100% rename from content/documentation/cookbook/ldap.md rename to content/documentation/cookbook/_drafts/ldap.md diff --git a/content/documentation/cookbook/manual-hardened.md b/content/documentation/cookbook/_drafts/manual-hardened.md similarity index 100% rename from content/documentation/cookbook/manual-hardened.md rename to content/documentation/cookbook/_drafts/manual-hardened.md diff --git a/content/documentation/cookbook/observability.md b/content/documentation/cookbook/_drafts/observability.md similarity index 100% rename from content/documentation/cookbook/observability.md rename to content/documentation/cookbook/_drafts/observability.md diff --git a/content/documentation/cookbook/orchestrators.md b/content/documentation/cookbook/_drafts/orchestrators.md similarity index 100% rename from content/documentation/cookbook/orchestrators.md rename to content/documentation/cookbook/_drafts/orchestrators.md diff --git a/content/documentation/cookbook/updates.md b/content/documentation/cookbook/_drafts/updates.md similarity index 100% rename from content/documentation/cookbook/updates.md rename to content/documentation/cookbook/_drafts/updates.md diff --git a/content/documentation/cookbook/config.md b/content/documentation/cookbook/config.md index 0ce0374..747c7ac 100644 --- a/content/documentation/cookbook/config.md +++ b/content/documentation/cookbook/config.md @@ -15,6 +15,9 @@ pid = "aerogramme.pid" [imap_unsecure] bind_addr = "[::]:1143" +[auth] +bind_addr = "[::1]:12345" + [lmtp] bind_addr = "[::1]:1025" hostname = "example.tld" diff --git a/content/documentation/cookbook/discovery.txt b/content/documentation/cookbook/discovery.txt deleted file mode 100644 index a36f98b..0000000 --- a/content/documentation/cookbook/discovery.txt +++ /dev/null @@ -1,3 +0,0 @@ -Discovery RFC (see Alps) - -Thunderbird discovery. diff --git a/content/documentation/cookbook/key_backup.txt b/content/documentation/cookbook/key_backup.txt deleted file mode 100644 index 7f2f4d6..0000000 --- a/content/documentation/cookbook/key_backup.txt +++ /dev/null @@ -1,22 +0,0 @@ -If you fear to loose your password, you can backup your key with the following command: - -```bash -aerogramme show-keys \ - --region garage \ - --k2v-endpoint http://127.0.0.1:3904 \ - --s3-endpoint http://127.0.0.1:3900 \ - --aws-access-key-id GK... \ - --aws-secret-access-key c0ffee... \ - --bucket aerogramme \ - --user-secret s3cr3t -``` - -You will then be asked for your key decryption password: - -``` -Enter key decryption password: -master_key = "..." -secret_key = "..." -``` - - diff --git a/content/documentation/cookbook/ldap.txt b/content/documentation/cookbook/ldap.txt deleted file mode 100644 index 81449b1..0000000 --- a/content/documentation/cookbook/ldap.txt +++ /dev/null @@ -1,5 +0,0 @@ -ldap - -bottin - -other ldap servers diff --git a/content/documentation/cookbook/lmtp.txt b/content/documentation/cookbook/lmtp.txt deleted file mode 100644 index b608d58..0000000 --- a/content/documentation/cookbook/lmtp.txt +++ /dev/null @@ -1,3 +0,0 @@ -lmtp -postfix -other smtp servers diff --git a/content/documentation/cookbook/static-user-management.md b/content/documentation/cookbook/static-user-management.md index f84c342..5ddc7d1 100644 --- a/content/documentation/cookbook/static-user-management.md +++ b/content/documentation/cookbook/static-user-management.md @@ -3,9 +3,9 @@ title = "User Management" weight = 20 +++ -Aerogramme can externalize its user management through [LDAP](@/documentation/cookbook/ldap.md), but if you target a simple deployment, it has also an internal user management system that will be covered here. +Aerogramme can externalize its user management through [LDAP](@/documentation/reference/config.md), but if you target a simple deployment, it has also an internal user management system that will be covered here. -As a pre-requisite, you must have your `aerogramme.toml` file configured for "Static" user management as described in [Configuration file](@/documentation/cookbook/config.md). You also need a configured Garage instance, either [local](@/documentation/cookbook/single-node-garage-storage.md) or [distributed](@/documentation/cookbook/garage-cluster-storage.md). +As a pre-requisite, you must have your `aerogramme.toml` file configured for "Static" user management as described in [Configuration file](@/documentation/cookbook/config.md). You also need a configured Garage instance, either [local](@/documentation/cookbook/single-node-garage-storage.md) or distributed. ## Adding users diff --git a/content/documentation/cookbook/tls.txt b/content/documentation/cookbook/tls.txt deleted file mode 100644 index f2d0bd4..0000000 --- a/content/documentation/cookbook/tls.txt +++ /dev/null @@ -1 +0,0 @@ -how to configure tls on aerogramme?! diff --git a/content/documentation/reference/config.md b/content/documentation/reference/config.md index 39a8c6f..129a3f9 100644 --- a/content/documentation/reference/config.md +++ b/content/documentation/reference/config.md @@ -34,6 +34,9 @@ The common part of the provider daemon configuration: role = "Provider" pid = "/var/run/aerogramme.pid" +[auth] +bind_addr = "[::1]:12345" + [imap_unsecure] bind_addr="[::1]:143" @@ -56,17 +59,20 @@ sure people run Aerogramme in the intended mode. 🔑 `pid` - *Optional, Path (String)* - The path to the file where the daemon PID will be stored. It's required to use the `aerogramme provider reload` command. +🗃️ `auth` - *Optional* - A socket implementing the [Dovecot SASL protocol](https://doc.dovecot.org/developer_manual/design/auth_protocol/), it can be used by some SMTP servers like Postfix, Chasquid or Maddy to delegate their authentication. +🔑 `bind_addr` - *Required, Socket (String)* - On which IP address and port the Dovecot SASL protocol should listen. Please note that this protocol is not encrypted, and thus you should only bind to localhost. + 🗃️ `imap_unsecure` - *Optional* - The cleartext IMAP configuration block, if not set, the IMAP cleartext service is not started. Be careful, it is dangerous to run IMAP without transport encryption. -🔑 `imap.bind_addr` - *Required, Socket (String)* - On which IP address and port the cleartext IMAP service must bind, can be IPv6 or IPv4 syntax. (Port 143 is reserved for this use). +🔑 `bind_addr` - *Required, Socket (String)* - On which IP address and port the cleartext IMAP service must bind, can be IPv6 or IPv4 syntax. (Port 143 is reserved for this use). 🗃️ `imap` - *Optional* - The TLS IMAP configuration block, if not set, the IMAP TLS service is not started. This is the recommanded way to expose your IMAP service. -🔑 `imap.bind_addr` - *Required, Socket (String)* - On which IP address and port the IMAP service must bind, can be IPv6 or IPv4 syntax. (Port 993 is reserved for this use). -🔑 `imap.certs` - *Required, Path (String)* - A path to the PEM encoded certificate list -🔑 `imap.key` - *Required, Path (String)* - A path to the PEM encoded private key +🔑 `bind_addr` - *Required, Socket (String)* - On which IP address and port the IMAP service must bind, can be IPv6 or IPv4 syntax. (Port 993 is reserved for this use). +🔑 `certs` - *Required, Path (String)* - A path to the PEM encoded certificate list +🔑 `key` - *Required, Path (String)* - A path to the PEM encoded private key 🗃️ `lmtp` - *Optional* - The LMTP configuration block, if not set, the LMTP service is not started -🔑 `lmtp.bind_addr` - *Required, Socket (String)* - On which IP address and port the LMTP service must bind, can be IPv6 or IPv4 syntax. +🔑 `bind_addr` - *Required, Socket (String)* - On which IP address and port the LMTP service must bind, can be IPv6 or IPv4 syntax. 🗃️ `users` - *Required* - How users must be handled 🔑 `user_driver` - *Required, Enum (String)* - Define which user driver must be used, the rest of the configuration depends on it. Valid values are: `Ldap` and `Static`. @@ -99,23 +105,23 @@ bucket_attr = "aeroBucket" default_bucket = "aerogramme" ``` -🔑 `users.user_driver="Ldap"` - to configure user management through LDAP, the `user_driver` value introduced in the previous section must be set to `Ldap`. +🔑 `user_driver="Ldap"` - to configure user management through LDAP, the `user_driver` value introduced in the previous section must be set to `Ldap`. -🔑 `users.ldap_server` - *Required, LDAP URI* - The LDAP URI of your LDAP server. +🔑 `ldap_server` - *Required, LDAP URI* - The LDAP URI of your LDAP server. -🔑 `users.pre_bind_on_login` - *Optional, boolean, default to false* - Sometimes users can't login directly on the LDAP server and require a service account that will bind to LDAP and be in charge of checking users' credentials. If this is your case, set it to true. -🔑 `users.bind_dn` - *Optional, LDAP distinguished name (String)* - The distinguished name of your service account (ignored if `pre_bind_on_login` is not set to true) -🔑 `users.bind_password` - *Optional, Password (String)* - The password of your service account (ignored if `pre_bind_on_login` is not set to true) -🔑 `users.search_base` - *Optional, LDAP distinguished name (String)* - Once logged with the service account, where the user entries must be searched. (ignored if `pre_bind_on_login` is not set to true) +🔑 `pre_bind_on_login` - *Optional, boolean, default to false* - Sometimes users can't login directly on the LDAP server and require a service account that will bind to LDAP and be in charge of checking users' credentials. If this is your case, set it to true. +🔑 `bind_dn` - *Optional, LDAP distinguished name (String)* - The distinguished name of your service account (ignored if `pre_bind_on_login` is not set to true) +🔑 `bind_password` - *Optional, Password (String)* - The password of your service account (ignored if `pre_bind_on_login` is not set to true) +🔑 `search_base` - *Optional, LDAP distinguished name (String)* - Once logged with the service account, where the user entries must be searched. (ignored if `pre_bind_on_login` is not set to true) -🔑 `users.storage_driver` - *Required, Enum (String)* - For now, only `Garage` is supported as a value (`InMemory` can be used for test purposes only) -🔑 `users.s3_endpoint` - *Required, String* - The S3 endpoint of the Garage instance -🔑 `users.k2v_endpoint` - *Required, String* - The K2V endpoint of the Garage instance -🔑 `users.aws_region` - *Required, String* - Regions are an AWS thing, for example `us-east-1`. If you followed Garage's documentation, you probably configured `garage` as your region. -🔑 `users.aws_access_key_id_attr` - *Required, String* - The LDAP attribute that will contain user's key id: each user has its own key, its own bucket, and so on. -🔑 `users.aws_secret_access_key_attr` - *Required, String* - The LDAP attribute that will contain user's secret key. -🔑 `users.bucket_attr` - *Optional, String* - The LDAP attribute that will contain user's bucket that is dedicated to Aerogramme. Again, each user has its own bucket. -🔑 `users.default_bucket` - *Optional, String* - If `bucket_attr` is not set, we assume that all users have a bucket named following this parameter (as Garage has a local bucket namespace in addition to the global namespace, so it's possible for different users to have independant buckets with the same name). +🔑 `storage_driver` - *Required, Enum (String)* - For now, only `Garage` is supported as a value (`InMemory` can be used for test purposes only) +🔑 `s3_endpoint` - *Required, String* - The S3 endpoint of the Garage instance +🔑 `k2v_endpoint` - *Required, String* - The K2V endpoint of the Garage instance +🔑 `aws_region` - *Required, String* - Regions are an AWS thing, for example `us-east-1`. If you followed Garage's documentation, you probably configured `garage` as your region. +🔑 `aws_access_key_id_attr` - *Required, String* - The LDAP attribute that will contain user's key id: each user has its own key, its own bucket, and so on. +🔑 `aws_secret_access_key_attr` - *Required, String* - The LDAP attribute that will contain user's secret key. +🔑 `bucket_attr` - *Optional, String* - The LDAP attribute that will contain user's bucket that is dedicated to Aerogramme. Again, each user has its own bucket. +🔑 `default_bucket` - *Optional, String* - If `bucket_attr` is not set, we assume that all users have a bucket named following this parameter (as Garage has a local bucket namespace in addition to the global namespace, so it's possible for different users to have independant buckets with the same name). ### Static user_driver @@ -127,8 +133,8 @@ user_driver = "Static" user_list = "/etc/aerogramme/users.toml" ``` -🔑 `users.user_driver="Static"` - to configure user management through LDAP, the `user_driver` value introduced in the previous section must be set to `Ldap`. -🔑 `users.user_list` - *Required, Path (String)* - the path to the file that will contain the list of your users, the hash of their password, and where their data is stored. The file must exist, but it can be blank. +🔑 `user_driver="Static"` - to configure user management through LDAP, the `user_driver` value introduced in the previous section must be set to `Ldap`. +🔑 `user_list` - *Required, Path (String)* - the path to the file that will contain the list of your users, the hash of their password, and where their data is stored. The file must exist, but it can be blank. The syntax of the user list file is described in the dedicated reference page [User List](@/documentation/reference/user-list.md).