From 7480308889be854b9e40b3a7124bb011c31f917b Mon Sep 17 00:00:00 2001 From: Quentin Dufour Date: Fri, 2 Jun 2023 17:29:36 +0200 Subject: [PATCH] WIP doc --- content/documentation/cookbook/key_backup.txt | 22 ++ content/documentation/cookbook/ldap.txt | 5 + content/documentation/cookbook/lmtp.txt | 3 + content/documentation/development/netcat.md | 2 +- content/documentation/quick-start/_index.md | 222 +++++++++++------- content/documentation/reference/config.md | 18 +- 6 files changed, 181 insertions(+), 91 deletions(-) create mode 100644 content/documentation/cookbook/key_backup.txt create mode 100644 content/documentation/cookbook/ldap.txt create mode 100644 content/documentation/cookbook/lmtp.txt diff --git a/content/documentation/cookbook/key_backup.txt b/content/documentation/cookbook/key_backup.txt new file mode 100644 index 0000000..7f2f4d6 --- /dev/null +++ b/content/documentation/cookbook/key_backup.txt @@ -0,0 +1,22 @@ +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 new file mode 100644 index 0000000..81449b1 --- /dev/null +++ b/content/documentation/cookbook/ldap.txt @@ -0,0 +1,5 @@ +ldap + +bottin + +other ldap servers diff --git a/content/documentation/cookbook/lmtp.txt b/content/documentation/cookbook/lmtp.txt new file mode 100644 index 0000000..b608d58 --- /dev/null +++ b/content/documentation/cookbook/lmtp.txt @@ -0,0 +1,3 @@ +lmtp +postfix +other smtp servers diff --git a/content/documentation/development/netcat.md b/content/documentation/development/netcat.md index aa22a32..cea34d9 100644 --- a/content/documentation/development/netcat.md +++ b/content/documentation/development/netcat.md @@ -1,5 +1,5 @@ +++ -title = "netcat" +title = "Debug with netcat" weight = 10 +++ diff --git a/content/documentation/quick-start/_index.md b/content/documentation/quick-start/_index.md index f4692d3..2b2ccb2 100644 --- a/content/documentation/quick-start/_index.md +++ b/content/documentation/quick-start/_index.md @@ -5,9 +5,11 @@ sort_by = "weight" template = "documentation.html" +++ -## Installation +*This quick start guide is specifically written with docker and docker-compose to make it more tangible. But nothing prevent your from deploying Aerogramme in production without docker or on other OS like FreeBSD.* -Go to the download page and follow the instruction steps for your preferred installation method: +## Pull an image + +Go to the download page, select a version and follow the instruction steps: -## Setup +Do the same for [Garage](https://garagehq.deuxfleurs.fr/download/), as Aerogramme can't run without Garage. + +## Prepare your environment + +Create a deployment folder: + +```bash +mkdir /tmp/mailstack && cd /tmp/mailstack +``` + +*`/tmp` is used as the quick start guide assume you want to evaluate Aerogramme, not deploy it in production. Follow the cookbook for a production deployment.* + +Add a `docker-compose.yml` file inside it: + +```yml +version: "3.9" +services: + aerogramme: + image: registry.deuxfleurs.org/aerogramme:{{TAG}} + volumes: + - ./aerogramme.toml:/etc/aerogramme.toml + ports: + - 1143:1143 # IMAP + - 2424:2424 # LMTP + garage: + image: docker.io/dxflrs/garage:{{TAG}} + volumes: + - ./garage.toml:/etc/garage.toml +``` + +Create empty configuration files for now (they will be filled later but docker requires them now): + +```bash +touch aerogramme.toml garage.toml +``` + +*Do not forget to replace `{{TAG}}` by the tag you chose!* + +## Setup Garage + +Create a basic configuration file for Garage: + +```bash +cat > garage.toml <] +[login_static.users.alice] password = "$argon2id$v=19$m=4096,t=3,p=1$..." -aws_access_key_id = "GK..." -aws_secret_access_key = "c0ffee..." +user_secret = "..." ``` -In this tutorial, we will use the static login provider (and not the LDAP one). -We will thus create a config file named `aerogramme.toml` in which we will paste the previous snippet. You also need to enter some other keys. In the end, your file should look like that: +*Note: user-secret is not the user's password. It is an additional secret used when deriving user's secret key from their password. The idea is that, even if user leaks their password, their encrypted data remain safe as long as this additional secret does not leak. You can generate it with openssl for example: `openssl rand -base64 30`. Read [Cryptography & key management](./crypt-key.md) for more details.* -```toml -s3_endpoint = "http://127.0.0.1:3900" -k2v_endpoint = "http://127.0.0.1:3904" -aws_region = "garage" - -[lmtp] -bind_addr = "[::1]:12024" -hostname = "aerogramme.tld" - -[imap] -bind_addr = "[::1]:1993" - -[login_static] -default_bucket = "mailrage" - -[login_static.users.me] -bucket = "mailrage-me" -user_secret = "s3cr3t" -email_addresses = [ - "me@aerogramme.tld" -] - -# copy pasted values from first-login -password = "$argon2id$v=19$m=4096,t=3,p=1$..." -aws_access_key_id = "GK..." -aws_secret_access_key = "c0ffee..." -``` - -If you fear to loose your password, you can backup your key with the following command: +Restart the server to load the new configuration: ```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 mailrage-me \ - --user-secret s3cr3t -``` - -You will then be asked for your key decryption password: - -``` -Enter key decryption password: -master_key = "..." -secret_key = "..." -``` - -## Launch - -Start a server as follow: - -```bash -aerogramme server +docker compose up -d --force-recreate aerogramme ``` ## Validate +Now that your Aerogramme server is running, + +### Inject emails + Inject test emails: ```bash ./test/inject_emails.sh '' dxflrs ``` +*replace with netcat* + +### Check with netcat + +*Todo* + +### Check with mutt + Now you can connect your mailbox with `mutt`. Start by creating a config file, for example we used the following `~/.muttrc` file: diff --git a/content/documentation/reference/config.md b/content/documentation/reference/config.md index a5bf43c..c7550d0 100644 --- a/content/documentation/reference/config.md +++ b/content/documentation/reference/config.md @@ -3,7 +3,7 @@ title = "Configuration" weight = 10 +++ -# Configuration file +## Sample A configuration file that illustrate all the possible options, in practise, many fields are omitted: @@ -23,9 +23,9 @@ bind_addr = "[::1]:993" [login_static] default_bucket = "aerogramme" -[login_static.user.alan] +[login_static.users.alan] email_addresses = [ - "alan@smith.me" + "alan@smith.me", "aln@example.com" ] password = "$argon2id$v=19$m=4096,t=3,p=1$..." @@ -35,7 +35,7 @@ aws_secret_access_key = "c0ffee" bucket = "aerogramme-alan" user_secret = "s3cr3t" -alternate_user_secrets = [ "s3cr3t2" "s3cr3t3" ] +alternate_user_secrets = [ "s3cr3t2", "s3cr3t3" ] master_key = "..." secret_key = "..." @@ -61,7 +61,7 @@ bucket_attr = "bucket" ``` -## Global configuration options +## Global configuration details ### `s3_endpoint` @@ -69,17 +69,17 @@ bucket_attr = "bucket" ### `aws_region` -## LMTP configuration options +## LMTP configuration details ### `lmtp.bind_addr` ### `lmtp.hostname` -## IMAP configuration options +## IMAP configuration details ### `imap.bind_addr` -## Static login configuration options +## Static login configuration details ### `login_static.default_bucket` @@ -99,7 +99,7 @@ bucket_attr = "bucket" ### `login_static.user..secret_key` -## LDAP login configuration options +## LDAP login configuration details ### `login_ldap.ldap_server`