Updated README

README.md

@@ -1,12 +1,17 @@
 ## About gentoo-install
 
 This script performs a reasonably minimal installation of gentoo. An EFI system is highly
-recommended, but legacy BIOS boot is still supported.
+recommended, but legacy BIOS boot is also supported. The script supports both systemd (default)
-It does everything from the ground up, including creating partitions, downloading
+and OpenRC as the init system. The main performed steps are:
-and extracting the stage3 archive, initial system configuration and optionally installing
-some additional software. The script only supports OpenRC and not systemd.
 
-The system will temporarily use `sys-kernel/vanilla-kernel-bin`, which should be suitable
+#. Partitioning
+#. Download & verify stage3 tarball
+#. Extract stage3
+#. Initialize portage
+#. Install kernel
+#. Install additional software
+
+The system will use `sys-kernel/gentoo-kernel-bin`, which should be suitable
 to boot most systems out of the box. I strongly recommend you to replace this kernel
 with a custom built one, when the system is functional. If you are looking for a way
 to detect and manage your kernel configuration, have a look at [autokernel](https://github.com/oddlama/autokernel).
@@ -14,48 +19,40 @@ to detect and manage your kernel configuration, have a look at [autokernel](http
 ## Quick start
 
 Edit `scripts/config.sh` and execute `./install` in any live system.
-This will apply the selected partitioning scheme (with confirmation), and properly
+You can review the partitioning that will be applied before anything critical is done.
+Afterwards, this will apply the partitioning scheme and properly
 install the selected stage3 gentoo system. The new system will by default use
-`vanilla-kernel-bin` as the kernel, and an initramfs generated with dracut to provide
+`gentoo-kernel-bin` as the kernel, and an initramfs generated by dracut to provide
 a bootable environment. The script can optionally install `sshd` and `ansible` to
-allow for quick setup of the new system. So when the script finishes, you can
+allow for a convenient setup of the new system afterwards.
-directly begin to deploy your specific setup.
 
 ## Overview
 
-Here is a quick overview of what this script does:
+Here is a more complete overview of what this script does:
 
-* Does everything minus something
+#. Partition disks (supports gpt, raid, luks)
-* Partition disks (supports gpt, raid, luks)
+#. Download and cryptographically verify the newest stage3 tarball
-* Download and cryptographically verify the newest stage3 tarball
+#. Extract the stage3 tarball
-* Extract the stage3 tarball
+#. Sync portage tree
-* Sync portage tree
+#. Configure portage (create zz-autounmask files, configure MAKEOPTS, EMERGE_DEFAULT_OPTS)
-* Configure the base system
+#. Select the fastest gentoo mirrors
-  - Set hostname
+#. Configure the base system
-  - Set timezone
+#. Install git (so you can add your portage overlays later)
-  - Set keymap
+#. Install `sys-kernel/gentoo-kernel-bin` (until you replace it)
-  - Generate and select locale
+#. Create efibootmgr entry or install syslinux depending on whether your system uses EFI
-  - Prepare `zz-autounmask` files for portage autounmasking
+#. Generate a basic fstab
-* Select best gentoo portage mirrors
+#. Ask for a root password
-* Install git (so you can add your portage overlays later)
-* Install `sys-kernel/vanilla-kernel-bin` (temporarily, until you replace it)
-  - EFI: Copy kernel to efi partition
-  - EFI: Create boot entry using efibootmgr (or install syslinux for BIOS boot)
-  - BIOS: Install syslinux
-* Generate fstab
-* Ask for a root password
 
 Also, optionally the following will be done:
 
 * Install sshd with secure config
-* Install dhcpcd
+* Install dhcpcd (only for OpenRC)
 * Install ansible, create ansible user and add authorized ssh key
 * Install additional packages provided in config
 
 Anything else is probably out of scope for this script,
 but you can obviously do anything later on when the system is booted.
-I highly recommend building a custom kernel and maybe encrypting your
+I highly recommend building a custom kernel. Have a look at the [Recommendations](#Recommendations) section.
-root filesystem. Have a look at the [Recommendations](#Recommendations) section.
 
 ## Install
 
@@ -66,11 +63,15 @@ Installing gentoo with this script is simple.
    Any [Arch Linux](https://www.archlinux.org/download/) live iso works fine.
 2. Clone this repository
 3. Edit `scripts/config.sh`, and particularily pay attention to
-   the device which will be partitioned. The script will ask before partitioning,
+   the device which will be partitioned. The script will ask for confirmation
-   but better be safe than sorry.
+   before partitioning, but better be safe there.
 4. Execute `./install`. The script will tell you if your live
    system is missing any required software.
 
+The script should be able to run without any user supervision after partitioning, but depending
+on the current state of the gentoo repository you might need to intervene in case a package fails
+to emerge. The critical commands will ask you what to do in case of a failure.
+
 ### Config
 
 The config file `scripts/config.sh` allows you to adjust some parameters of the installation.
@@ -80,20 +81,20 @@ to install. By default you will get the hardened nomultilib profile without syst
 ### (Optional) sshd
 
 The script can provide a fully configured ssh daemon with reasonably good security settings.
-It will by default run on port `2222`, only allow ed25519 keys, restrict the key exchange
+It will by default only allow ed25519 keys, restrict the key exchange
 algorithms, disable any password based authentication, and only allow specifically mentioned
 users to use ssh service (none by default).
 
-To add a user to the list of allowed users, append `AllowUsers myuser` to `/etc/ssh/sshd_config`.
+The script will create a group named `sshusers`, and only users in that group will be
-I recommend to create a separate group for all ssh users (like `sshusers`) and
+allowed to log in via ssh. If you have added a user for yourself, you might want
-to use `AllowGroups sshusers`. You should adjust this to your preferences when
+to add the user to that group. Be aware that root login is always denied.
-the system is installed.
 
 ### (Optional) Ansible
 
 This script can install ansible, create a system user for ansible and add an ssh key of
 you choice to the `.authorized_keys` file. This allows you to directly use ansible when
-the new system is up to configure the rest of the system.
+the new system is up to configure the rest of the system. The ansible user will be added to
+the sshusers group.
 
 ### (Optional) Additional packages
 
@@ -114,21 +115,12 @@ There are some things that you probably want to do after installing the base sys
 or should consider:
 
 * Read the news with `eselect news read`.
-* Use a custom kernel (config and hardening, see [kernconf](https://github.com/oddlama/kernconf)), and remove `vanilla-kernel-bin`
+* Use a custom kernel (config and hardening, see [autokernel](https://github.com/oddlama/autokernel)), and remove `gentoo-kernel-bin`
 * Adjust `/etc/portage/make.conf`
   - Set `CFLAGS` to `-O2 -pipe -march=native` for native builds
   - Set `CPU_FLAGS_X86` using the `cpuid2cpuflags` tool
-  - Set `MAKEOPTS` to `-jN` with N being the amount of threads used for building
-  - Set `EMERGE_DEFAULT_OPTS` to `-jN` if you want parallel emerging
   - Set `FEATURES="buildpkg"` if you want to build binary packages
 * Use a safe umask like `umask 0077`
-* Edit `/etc/ssh/sshd_config`, change the port if you want and create a `sshusers` group.
-* Encrypt your system using LUKS
-  - Remount the root fs read-only
-  - Use `rsync -axHAWXS --numeric-ids --info=progress2 / /path/to/backup` to safely backup the whole
-    system including all extended attributes.
-  - Encrypt partition with LUKS
-  - Use rsync to restore the saved system root.
 
 ## References