Deuxfleurs/aerogramme.deuxfleurs.fr
17
0
Fork 0
Code Pull requests Activity

Config reference

Browse source
This commit is contained in:
Quentin 2024-01-22 18:05:49 +01:00
parent 0be4cdca4b
commit 6b521a980e
Signed by: quentin
GPG key ID: E9602264D639FF68
4 changed files with 219 additions and 111 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

9
content/documentation/design/_index.md
View file

@ -5,8 +5,15 @@ sort_by = "weight"
template = "documentation.html"
+++
## Goals
## Main concepts
[Per-user encryption](@/documentation/design/per-user-encryption.md) - TODO
[Unbreakable mailboxes](@/documentation/design/unbreakable-mailboxes.md) - TODO
**Stateless** - 12 factor app.
**Modular design** - Login and Mailbox storage is abstracted behind an interface: multiple
implementations are thus possible.
**Micro-service** - Stateless. 12 factor app.

4
content/documentation/reference/_index.md
View file

@ -5,4 +5,6 @@ sort_by = "weight"
template = "documentation.html"
+++
Reference documents on Aerogramme.
Aerogramme uses multiple TOML files, their syntax is described in the dedicated pages:
- [The main configuration](@/documentation/reference/config.md) that must be passed to the daemon to start it
- [The user list configuration](@/documentation/reference/user-list.md) that is used when you choose to use Aerogramme's integrated user management

238
content/documentation/reference/config.md
View file

@ -3,129 +3,149 @@ title = "Configuration"
weight = 10
+++
## Sample
Aerogramme can be run in 2 modes: `provider` and `companion`.
`provider` is the "traditional" daemon that is run by the service provider on their servers.
`companion` is an optional, local proxy a user can run on their local computer to have better privacy.
This is an Aerogramme-specific concept that is explained in details in the concept page entitled [Per-user encryption](@/documentation/design/per-user-encryption.md).
A configuration file that illustrate all the possible options,
in practise, many fields are omitted:
This page describe both configurations.
```toml
s3_endpoint = "s3.garage.tld"
k2v_endpoint = "k2v.garage.tld"
aws_region = "garage"
## Provider
[lmtp]
bind_addr = "[::1]:2525"
hostname = "aerogramme.tld"
As the provider is modular (both the user management and the storage can be configured),
the configuration file is also modular. Depending on the modules you choose,
the configuration will look different. The reference configuration file will thus
be presented modules per modules. If you want to see complete configuration files in context,
please refer to the [cookbook](@/documentation/cookbook/_index.md).
[imap]
bind_addr = "[::1]:993"
[login_static]
default_bucket = "aerogramme"
[login_static.users.alan]
email_addresses = [
"alan@smith.me",
"aln@example.com"
]
password = "$argon2id$v=19$m=4096,t=3,p=1$..."
aws_access_key_id = "GK..."
aws_secret_access_key = "c0ffee"
bucket = "aerogramme-alan"
user_secret = "s3cr3t"
alternate_user_secrets = [ "s3cr3t2", "s3cr3t3" ]
master_key = "..."
secret_key = "..."
[login_ldap]
ldap_server = "ldap.example.com"
pre_bind_on_login = true
bind_dn = "cn=admin,dc=example,dc=com"
bind_password = "s3cr3t"
search_base = "ou=users,dc=example,dc=com"
username_attr = "cn"
mail_attr = "mail"
aws_access_key_id_attr = "garage_s3_access_key"
aws_secret_access_key_attr = "garage_s3_secret_key"
user_secret_attr = "secret"
alternate_user_secrets_attr = "secret_alt"
# bucket = "aerogramme"
bucket_attr = "bucket"
The Aerogramme daemon can be launched in provider mode as follow:
```bash
aerogramme -c aerogramme.toml provider daemon
```
## Global configuration details
The syntax of the `aerogramme.toml` is described below.
### `s3_endpoint`
### Common
### `k2v_endpoint`
The common part of the provider daemon configuration:
### `aws_region`
```toml
role = "Provider"
pid = "/var/run/aerogramme.pid"
## LMTP configuration details
[imap]
bind_addr="[::]:143"
### `lmtp.bind_addr`
[lmtp]
bind_addr="[::1]:1025"
hostname="example.tld"
### `lmtp.hostname`
[users]
user_driver = "<PLACEHOLDER>"
# ... depends on the user driver
```
## IMAP configuration details
### `imap.bind_addr`
## Static login configuration details
### `login_static.default_bucket`
### `login_static.user.<name>.email_addresses`
### `login_static.user.<name>.password`
### `login_static.user.<name>.aws_access_key_id`
### `login_static.user.<name>.aws_secret_access_key`
### `login_static.user.<name>.bucket`
### `login_static.user.<name>.user_secret`
### `login_static.user.<name>.master_key`
### `login_static.user.<name>.secret_key`
## LDAP login configuration details
### `login_ldap.ldap_server`
### `login_ldap.pre_bind_on`
### `login_ldap.bind_dn`
### `login_ldap.bind_password`
### `login_ldap.search_base`
### `login_ldap.username_attr`
### `login_ldap.mail_attr`
### `login_ldap.aws_access_key_id_attr`
### `login_ldap.aws_secret_access_key_attr`
### `login_ldap.user_secret_attr`
### `login_ldap.alternate_user_secrets_attr`
### `login_ldap.bucket`
### `login_ldap.bucket_attr`
🔑 `role` - *Required, Enum (String)* - Either `Provider` or `Companion`, here only `Provider` is valid. It's a [poka-yoke](https://en.wikipedia.org/wiki/Poka-yoke) to make
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.
🗃️ `imap` - *Optional* - The IMAP configuration block, if not set, the IMAP cleartext service is not started
🔑 `imap.bind_addr` - *Required, Socket (String)* - On which IP address and port the IMAP service must bind, can be IPv6 or IPv4 syntax.
🗃️ `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.
🗃️ `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`.
### LDAP user_driver
```toml
# root part, see above...
[users]
user_driver = "Ldap"
ldap_server = "ldap://[::1]:389"
pre_bind_on_login = true
bind_dn = "cn=admin,dc=example,dc=tld"
bind_password = "hunter2"
search_base = "ou=users,dc=example,dc=tld"
username_attr = "uid"
mail_attr = "mail"
crypto_root_attr = "aeroCryptoRoot"
storage_driver = "Garage"
s3_endpoint = "s3.example.tld"
k2v_endpoint = "k2v.example.tld"
aws_region = "garage"
aws_access_key_id_attr = "garageS3AccessKey"
aws_secret_access_key_attr = "garageS3AccessKey"
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`.
🔑 `users.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)
🔑 `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).
### Static user_driver
```toml
# root part, see above...
[users]
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.
The syntax of the user list file is described in the dedicated reference page [User List](@/documentation/reference/user-list.md).
## Companion
Compared to the provider configuration, the companion configuration is static, so it is presented
in a single block.
```toml
role = "Companion"
pid = "/var/run/user/1000/aerogramme.pid"
[imap]
bind_addr = "[::1]:1143"
[users]
user_list = "/home/user/.config/aerogramme-users.toml"
```
The parameters explanation is the same as above.
Accounts can be configured with `aerogramme companion account add --login alice --setup.toml`.
The content of the `setup.toml` file should be given by your email service provider.
More information about its content is available in [User List](@/documentation/reference/user-list.md).
## Environment variables
Aerogramme supports some environment variables. A non-exhaustive list is given here that apply to both provider and companion modes.
`AEROGRAMME_CONFIG=aerogramme.toml` - *Path* - The path to the configuration file.
`RUST_LOG=info,aerogramme=debug` - *Logger config* - Configure logger verbosity.

79
content/documentation/reference/user-list.md Normal file
View file

@ -0,0 +1,79 @@
+++
title = "User list"
weight = 11
+++
This file is used by Aerogramme to store its users
when you choose to use its internal user management feature.
Aerogramme also supports externalized user management (like [LDAP](@/documentation/reference/config.md)): in this case, this file is not needed.
Aerogramme provides utilities commands to generate the `user_list` file, but you can also generate it manually if you prefer. Both methods will be described here.
## CLI-assisted generation of the file
You can add a user to the `user_list` file with the command:
```bash
aerogramme -c aerogramme.toml provider account add --login alice --setup setup.toml
```
The `setup.toml` must be previously created as follow:
```toml
email_addresses = [ "alice@example.tld", "alice.smith@example.tld" ]
clear_password = "hunter2"
storage_driver = "Garage"
s3_endpoint = "s3.example.tld"
k2v_endpoint = "k2v.example.tld"
aws_region = "garage"
aws_access_key_id = "GK01dfa..."
aws_secret_access_key = "a32f..."
bucket = "aerogramme"
```
🔑 `email_addresses` - *Required, Array of emails (Array of String)* - The email addresses that will be associated to this account. Used by the LMTP service to know to which user an email must be delivered.
🔑 `clear_password` - *Optional, Password (String)* - The clear text password of the user. If not set, it will be interactively asked.
🔑 `storage_driver` - *Required, Enum (String)* - The only option is "Garage" for now (you can also use "InMemory" with nothing more for testing purposes).
🔑 `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` - *Required, String* - The user's access key id
🔑 `aws_secret_access_key` - *Required, String* - The user's secret access key
🔑 `bucket` - *Required, String* - The user's bucket in which Aerogramme must store their data
If your Aerogramme daemon is already running, you must reload it to activate this account:
```bash
aerogramme -c aerogramme.toml provider reload
```
*Of course, restarting it also works.*
The previous `... account add ...` command, under the hood, parsed the existing
`users.toml` file, added it the new account, then reserialized the file with the new information. The generated content is given as an example of the following section.
## Manual edit
Some people might want to generate their configuration from another source of truth (eg. Ansible or NixOS). This page will explain the different options available.
The following file has been generated by the `... account add ...` command.
```toml
[alice]
email_addresses = ["alice@example.tld", "alice.smith@example.tld"]
password = "$argon2id$v=19$m=19456,t=2,p=1$lW1IFw59vyZAgQvyPkCB6w$R4y9T+Zekx6tHpTInsXcOZ0H1/HIJoqckiagJq/292U"
crypto_root = "aero:cryptoroot:pass:t5tC2QiL+A543Lg59FmE4XxmS0cSdOWv3ZD1EeeC8CScgR5feMFJT+KyUpjRzplWTEArwTWZ0Ff0VA+HU+P7sbuKqshm5GnN2x7kqePmqRMfLf/q6XiucJmfcNiGVveyrzsRavbs6Vy2J/HyM/FytZ/4eLnZqH8pERpT5UWJdWQehDQnLpG6OEQRgqowun7m+CqF6A/vKydQUBRzMdvX6UGD2bIHLmhRBqIzOYDJQGxQ"
storage_driver = "Garage"
s3_endpoint = "s3.example.tld"
k2v_endpoint = "k2v.example.tld"
aws_region = "garage"
aws_access_key_id = "GK01dfa..."
aws_secret_access_key = "a32f..."
bucket = "aerogramme"
```
🔑 `email_addresses`, `storage_driver`, `s3_endpoint`, `k2v_endpoint`, `aws_region`, `aws_access_key_id`, `aws_secret_access_key`, `bucket` are the same as above.
🔑 `password` - *Required, String* - To generate a compatible hash, run `aerograme tools password-hash`
🔑 `crypto_root` - *Required, String* - To generate a compatible string, run `aerogramme tools crypto-root new`