Updated documentations

Author: Andre Rodier

docs/index.md

@@ -1,5 +1,5 @@
-This is the home documentation for "Homebox", a set of Ansible scripts to deploy
-a fully functional _and_ secure mail server at home or online.
+This is the home documentation for "Homebox", a set of Ansible scripts to deploy a fully functional _and_ secure mail
+server at home or online.
 
 The source code is on [GitHub](https://github.com/progmaticltd/homebox).
 
@@ -14,15 +14,15 @@ This project is for you if:
 ## Philosophy
 
 - You should be able to upgrade anything installed via the apt command. No git clone / wget / curl here, ever.
-- If you are using your own hardware, the disk will be fully encrypted using
-  [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup). Nobody will be able to steal your hardware _and_ your
-  information.
+- If you are using your own hardware, the disk can be fully encrypted using
+  [LUKS](https://en.wikipedia.org/wiki/Linux_Unified_Key_Setup).
+  Nobody will be able to steal your hardware _and_ your information.
 - AppArmor is activated on the first boot, and all the services are configured to support it. This makes your server
   very safe against remote intrusion, even when using 0-day vulnerabilities.
 - You can set up multiple backup destination, local and remote, all encrypted.
 - A lot of default choices made towards simplicity, [KISS principle](https://en.wikipedia.org/wiki/KISS_principle),
   and safety.
-- Attention to details, keep focused on the nitty-gritty features of self hosting, like full IPv6 support.
+- Attention to details, keep focused on the nitty-gritty features of self hosting, like full IPv6 support and DNSSEC.
 
 ## Main components
 
@@ -36,7 +36,6 @@ This project is for you if:
 - Antivirus: ClamAV
 - Groupware: SOGo
 - Jabber: ejabberd
-- Remote administration: Cockpit
 
 ## Other projects to mention
 

docs/installation.md

@@ -7,7 +7,7 @@ Whatever you chose to host your system at home, or with a VPS, you need to speci
 ```sh
 cd install/config
 cp hosts-example.yml hosts.yml
-nano hosts.yml
+vi hosts.yml
 ```
 
 Here is an example on your LAN:
@@ -41,8 +41,7 @@ The system configuration file is a complete YAML configuration file containing a
 - User and group details, like email addresses and aliases.
 - Email parameters, like maximum attachment size, antivirus options, etc.
 - Some password policies, like minimum length and complexity.
-- Webmail settings (roundcube or SOGo).
-- Low level system settings, mainly used during the development phase.
+- SOGo settings if you want to install it.
 - Firewall policies, especially SSH access.
 - Security settings.
 - Backup strategies.
@@ -58,18 +57,7 @@ Once you have modified the file, you are ready to start the installation.
 !!! Warning
     You need to be careful with the indentation in your Yaml file, the number of spaces is significant.
 
-## Step 3: Start the installation
-
-You can choose a flavour to install, using a different playbook.
-
-```sh
-cd install
-ansible-playbook -i ../config/hosts.yml install-mini.yml
-```
-
-# Most important sections
-
-## Network configuration
+## Step 3: Configure your system
 
 ### Domain name and host name
 
@@ -105,7 +93,7 @@ network:
 !!! Tip
     If you do not have a backup IP address, use "~", which means "None" or Null in yaml.
 
-## Users list
+### Users list
 
 The file format should be self-explanatory. The other piece of information you need to fill first is the user list. In
 its simplest form, you will have something like this:
@@ -130,19 +118,11 @@ users:
     - jane@homebox.space
 ```
 
-The email aliases are the other email addresses that belong to the same user.
+You do not have to set the passwords for each user. A random password will be generated, using XKCD, and saved into
+_pass_, in the ldap sub directory.
 
-You can also add more advanced features, like:
 
-- [Import emails from other accounts](external-accounts.md).
-- [Define some users as administrators](security-configuration.md#defining-administrators)
-- [Grant remote access to certain users](security-configuration.md#grant-some-users-remote-access)
-
-!!! Note
-    You do not have to set the passwords for each user. A random password will be generated, usinx XKCD, and saved into
-    _pass_, in the ldap sub directory.
-
-## Email options
+### Email options
 
 This is the second most important settings. Here is an example of the email options you can override:
 
@@ -155,10 +135,10 @@ mail:
     default: 1G             # Maximum allowed mailbox size for your users.
 ```
 
-All options are detailed on the [email configuration](email-configuration.md) page.
+Advanced options are detailed on the [email configuration](email-configuration.md) page.
 
 
-## Security options
+### Security options
 
 Security options are detailed on the [security page](security-configuration.md).
 The default settings are:
@@ -170,15 +150,17 @@ The default settings are:
 
 Other options are possible, see the security page for details.
 
+## Step 4: Start the installation
 
-## Backup configuration
+You can choose a flavour to install, using a different playbook. Four playbooks are included by default: mini, small,
+medium and large. Depending on the features and the capacity of your server.
 
-It is possible to regularly backup your emails, for instance locally on a NAS drive, or on the internet, using various
-methods.
+For instance, the mini server:
 
-By default, the whole home partition is backed up, but you can add or exclude more folders. The detailed instructions
-are on the [backup documentation](/backup-home/) page.
-
-You can also use [OpenDNS servers](https://en.wikipedia.org/wiki/OpenDNS#Name_server_IP_addresses) for forward.
+```sh
+cd install
+ansible-playbook -i ../config/hosts.yml install-mini.yml
+```
 
-Once your DNS set up is complete, you can monitor the [world wide propagation](/dns-propagation/).
+!!! Note
+    The large version, including clamAV, requires at least 2GB of ram.

docs/jabber-configuration.md

@@ -2,10 +2,10 @@
 
 The default configuration for the Jabber server comes with the following options:
 
-- Installed by default
-- Server to server communication active and public by default
-- Socks proxy to transfer files
-- HTTP upload for offline file transfer
+- Installed by default.
+- Server to server communication active and public by default.
+- Socks proxy to transfer files.
+- HTTPs upload for offline file transfer.
 
 Default options for the Jabber server:
 
@@ -41,11 +41,11 @@ ejabberd:
 
 Two certificates are created to ensure proper communication with clients and other servers.
 
-| Record      | Type   | Purpose                                | Example                  |
-| ----------- | ------ | ---------                              | ---------                |
-| @           | A      | Default certificate used by the server | homebox.space            |
-| xmpp        | A      | Handle file transfer over https        | xmpp.homebox.space       |
-| conference  | A      | S2S conference public URL              | conference.homebox.space |
+| Record     | Type | Purpose                                | Example                  |
+|------------|------|----------------------------------------|--------------------------|
+| @          | A    | Default certificate used by the server | homebox.space            |
+| xmpp       | A    | Handle file transfer over https        | xmpp.homebox.space       |
+| conference | A    | S2S conference public URL              | conference.homebox.space |
 
 ## Fine tuning
 

docs/maintenance.md

@@ -41,7 +41,8 @@ Then, run the dedicated playbook to update users:
 
 ```sh
 cd install
-ansible-playbook -v -i ../config/hosts.yml playbooks/update-users.yml
+export ROLE=ldap-openldap,user-setup
+ansible-playbook -v -i ../config/hosts.yml playbooks/install.yml
 ```
 
 The home playbook creates the home directories for this user.
@@ -69,55 +70,58 @@ This can be done through SSH, like you are doing on any Debian server.
 
 ## Adding or removing components
 
-Most components can be added or removed individually, using the unit ansible playbook, for instance:
+Most components can be added or removed individually, using the unit playbook, for instance:
 
 ```sh
-ROLE=diagnostic ansible-playbook -l homebox -v install.yml
+ROLE=ejabberd ansible-playbook -l homebox install.yml
 ```
 
+This will install the ejabberd XMPP server.
+
 or
 
 ```sh
-ROLE=diagnostic ansible-playbook -l homebox -v uninstall.yml
+ROLE=ejabberd ansible-playbook -l homebox uninstall.yml
 ```
 
+This will delete the ejabberd XMPP server.
 
 ### Removing ClamAV
 
-Removing ClamAV can be done using the following command:
+Adding or removing ClamAV can be done using the following command:
 
 ```sh
-ROLE=clamav ansible-playbook -l homebox -v uninstall.yml
+ROLE=clamav ansible-playbook -l homebox install.yml
 ```
 
-### Removing rspamd
-
-Removing Respamd can be done using the following command:
+Or to be removed:
 
 ```sh
-ROLE=clamav ansible-playbook -l homebox -v uninstall.yml
+ROLE=clamav ansible-playbook -l homebox uninstall.yml
 ```
 
-## Restarting the system
+
+## Restarting the system when the drive is encrypted
 
 If you have installed the system with the main drive encrypted using LUKS, you need to keep a way to decrypt your drive,
-locally or remotely
+locally or remotely.
 
-### With physical access
+There is a role you can run, to install _dropbear_. When the system starts, a small SSH server is started, to allowing
+you to decrypt the drive remotely.
 
-Plug a screen and a keyboard, and type your passphrase when the system boot.
+Here how to install it:
 
-### Remotely over SSH
+```sh
+ROLE=luks-remote ansible-playbook -l homebox install.yml
+```
 
-When the system starts, a small SSH server is started, which allows you to decrypt the drive remotely.
 Here is an example using a command line SSH client:
 
 ```sh
-andre@london:~ $ ssh root@rodier.me
+andre@london:~ $ ssh root@example.net
 
 To unlock root partition, and maybe others like swap, run `cryptroot-unlock`
 
-
 BusyBox v1.22.1 (Debian 1:1.22.0-19+b3) built-in shell (ash)
 Enter 'help' for a list of built-in commands.
 

docs/prerequisites.md

@@ -9,6 +9,7 @@ knowledge to achieve the above.
 You still need some basic understanding though, like what is an IP address or a port, how to run Ansible in a console,
 how to edit Yaml files, etc.
 
+
 ## Hosting emails at home
 
 If you want to seriously host your emails at home, you will need the following:
@@ -25,69 +26,39 @@ Pros:
 Cons:
 
 - Your internet connection and electric providers need to be stable.
-- Might be cumbersome when you are moving
+- Might be cumbersome when you are moving.
+- This is not _digital worker_ friendly.
+
 
 ## Hosting emails online
 
 Any serious hosting platform can provide a server, virtual or physical, with an externally accessible IP address. Some
 providers, however, are blocking the port 25 (e.g. Google cloud).
 
-Be careful, using a VPS (Virtual Private Server) is no more secure than hosting at your home.
-
 Pros:
 
-- Does not rely on the reliability of your internet connection or your electricity provider
-- You can move to another address easily.
+- Does not rely on the reliability of your internet connection or your electricity provider.
+- Easier to manage remotely, especially for _digital workers_.
 
 Cons:
 
-- You may not have control on the kernel installed. This is less secure than Homebox, which is by default configured to
-  run on AppArmor.
+- You may not have control on the kernel installed or the options available.
 - You may not be able to use Full Disk Encryption. Although there are some security measures in places, it is still
   perfectly possible to extract data from your disk without your knowledge or consent.
-- You will not have the choice on when and which security updates are applied. Most hosting providers have specific time
-  windows to update the kernel images they use, which may not be as soon as you need, or even appropriate to you.
 
 
 # Pre-installation steps
 
 ## Set up your domain name
 
-The first thing you need is a domain name and a DNS provider, there are many available. For instance, here is a
-[list of other DNS providers](https://github.com/AnalogJ/lexicon#providers) you can use.
-
-The screenshots and examples in this tutorial are specific to [Gandi](https://www.gandi.net/), but the principles are
-the same.
-
-Once you have chosen the domain name, it is necessary to configure the associated DNS servers, and the _glue records_.
-
-For instance, on Gandi, you will have to set up the glue records first and then the DNS servers used for your domain:
-
-### Glue records
-
-Create at least one record that points to your static IP address.
+If you are not familiar with DNS, I recommend to use Gandi and to create an API key. The playbook will handle the DNS
+settings itself.
 
-![Glue records](img/dns-setup/glue-records.png)
+Otherwise, here is a [list of other DNS providers](https://github.com/AnalogJ/lexicon#providers) you can use.
 
-### DNS servers
+In this case, it is necessary to configure the associated DNS servers, and the _glue records_.
 
-Add the DNS servers accordingly
-
-![DNS servers](img/dns-setup/dns-servers.png)
-
-## Choose the hardware
-
-An old laptop should be enough to start, with the main advantage of being somewhat resilient to power failures. I also
-suggest you to have a look on this Debian page: [Cheap Serverbox Hardware](https://wiki.debian.org/FreedomBox/Hardware)
-of the project freedombox, another excellent project.
-
-The preseed configuration (see next step) provides an option to use software RAID, so you can use this as well if you
-prefer.
-
-!!! Warning
-    You still need to regularly back up your data, even if you are using RAID.
-
-## Set-up your home network
+## Home based: set-up your home network
 
 This is necessary only if you choose to use a home device to host your emails. If you are using an online server, you
 can skip this section.
@@ -99,12 +70,11 @@ functionality if there is one. The other option is to redirect only the ports yo
 
 Initially, the following TCP ports are required:
 
-- To obtain your certificates from LetsEncrypt, the port 80 need to be exposed.
+- To obtain your certificates from LetsEncrypt, the port 53 in UDP and TCP mode.
 - To test sending and receiving emails, your system should be accessible on the port 25 as well.
-- To retrieve emails, your system should be accessible on ports 143, 993, 110, 995.
+- To retrieve emails, your system should be accessible on ports 993 and 995 if you are using POP3.
 - To send emails, your system should be accessible on ports 587 and/or 465.
-- For Thunderbird automatic configuration, your system should be accessible on port 80.
-- Once installed, SOGo and the webmail are accessible through https (port 443).
+- Once installed, SOGo is accessible through https (port 443).
 
 The next step is to link your domain name (e.g homebox.me) to your static IP address that has been assigned to you by
 your ISP.
@@ -119,9 +89,6 @@ on Debian or Ubuntu:
 $ sudo apt install ansible rsync
 ```
 
-Another package to install is `python-netaddr`, which is part of Debian too. It is required to guess your public IP
-address during the installation phase. Once the playbook has been run, you can uninstall it.
-
-If you already have a Debian server (Stretch) installed, and you prefer to use it, it's fine, you can skip the next
+If you already have a Debian server (Bullseye) installed, and you prefer to use it, it's fine, you can skip the next
 section and start the [installation](installation.md) directly. Otherwise, click on next to read the OS installation
 page.

docs/preseed.md

@@ -39,7 +39,7 @@ The file is self-explanatory. A content example is shown below:
 ``` yaml
 system:
   hostname: mail
-  passphrase: Correct horse battery stapple
+  passphrase: Correct horse battery staple
   preseed: luks
   version: 11.1
   arch: amd64
@@ -82,9 +82,6 @@ root:
 debug: true
 ```
 
-!!! Tip
-    If you do not have physical access to your box, don't worry, you will be able to enter the passphrase remotely over
-    SSH.
 
 ## 3. Set up remote access