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.
This page describe both configurations.
Provider
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.
The Aerogramme daemon can be launched in provider mode as follow:
aerogramme -c aerogramme.toml provider daemon
The syntax of the aerogramme.toml is described below.
Common
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"
[imap]
bind_addr="[::]:993"
certs = "my-certs.pem"
key = "my-key.pem"
[lmtp]
bind_addr="[::1]:1025"
hostname="example.tld"
[users]
user_driver = "<PLACEHOLDER>"
# ... depends on the user driver
🔑 role - Required, Enum (String) - Either Provider or Companion, here only Provider is valid. It's a 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.
🗃️ auth - Optional - A socket implementing the Dovecot SASL 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.
🔑 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.
🔑 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
🔑 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
# 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"
🔑 user_driver="Ldap" - to configure user management through LDAP, the user_driver value introduced in the previous section must be set to Ldap.
🔑 ldap_server - Required, LDAP URI - The LDAP URI of your LDAP server.
🔑 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)
🔑 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
# root part, see above...
[users]
user_driver = "Static"
user_list = "/etc/aerogramme/users.toml"
🔑 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.
Companion
Compared to the provider configuration, the companion configuration is static, so it is presented in a single block.
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.
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.