User list

3 min

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): 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:

aerogramme -c aerogramme.toml provider account add --login alice --setup setup.toml

The setup.toml must be previously created as follow:

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:

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.

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