aerogramme.deuxfleurs.fr/content/documentation/reference/user-list.md
2024-01-22 18:05:49 +01:00

79 lines
3.8 KiB
Markdown

+++
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`