From f204711516f5bb88fb71d691eea5b189c67941cb Mon Sep 17 00:00:00 2001 From: oddlama Date: Wed, 8 Jun 2022 02:48:07 +0200 Subject: [PATCH] feat: (wip) rewrite readme --- README.md | 154 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 105 insertions(+), 49 deletions(-) diff --git a/README.md b/README.md index b0a8f1d..15c6c3f 100644 --- a/README.md +++ b/README.md @@ -1,71 +1,77 @@ -## About gentoo-install - -This is an installer for gentoo with a simple configuration TUI inspired by menuconfig. -The configurator is only used to generate a `gentoo.conf` file, which can also be -edited by hand, or reused later if desired. An example configuration is provided with the repository. - -The installer supports the most common disk layouts, different file systems like ext4, ZFS and btrfs as well -as additional layers such as LUKS or mdraid. It also supports both EFI (recommended) and BIOS boot, -and can be used with systemd or OpenRC as the init system. - ![](contrib/screenshot_configure.png) -## Quick start +## About gentoo-install -First, boot into a live environment of your choice. I recommend using an [Arch Linux](https://www.archlinux.org/download/) live iso, -as the installer will then be able to automatically download required programs or setup zfs support on the fly. After that, -proceed with the following steps: +This project aspires to be your favourite way to install gentoo. +It aims to provide a convenient way of installing gentoo, both for beginners and experts. +You may configure it by using a menuconfig-inspired interface or simply via a config file. + +It supports the most common disk layouts, different file systems like ext4, ZFS and btrfs as well +as additional layers such as LUKS or mdraid. It also supports both EFI (recommended) and BIOS boot, +and can be used with systemd or OpenRC as the init system. SSH can also be configured to allow using an automation framework +like [Ansible](https://github.com/ansible/ansible) or [fora](https://oddlama.gitbook.io/fora/) to automate beyond system installation. + +- [#Usage](Usage) +- [#Modern recommendations](Modern recommendations) +- [#Features](Features) +- [#FAQ](FAQ) + +## Why? + +This project might appeal to you if + +- you want to try gentoo without initially investing a lot of time, or fully committing to it yet. +- you already are a gentoo expert but want an automatic and repeatable best-practices installation. + +Of course we do encourage everyone to install gentoo manually. You will learn a lot if you +haven't done it already. + +## Usage + +First, boot into a live environment of your choice. I recommend using an [Arch Linux](https://www.archlinux.org/download/) live ISO, +as the installer will then be able to automatically download required programs or setup ZFS support on the fly. +Afterwards, proceed with the following steps: 1. Either clone this repo or download and extract a copy -1. Run `./configure` and save your desired configuration -1. Begin installation using `./install` +2. Run `./configure` and save your desired configuration +3. Begin installation using `./install` -Every option is explained in detail in `gentoo.conf.example` and in the help menu popups in the configurator. +Every option is explained in detail in `gentoo.conf.example` and in the help menus of the TUI configurator. When installing, you will be asked to review the partitioning before anything critical is done. -## Overview - -The system will use `sys-kernel/gentoo-kernel-bin`, which should be suitable -to boot most systems out of the box. It is strongly recommend to replace this kernel -with a custom built one, when the system is functional. - The installer 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. +to emerge. The critical commands will ask you what to do in case of a failure. If you encounter a +problem you cannot solve, you might want to consider getting in contact with some experienced people +on [IRC](https://www.gentoo.org/get-involved/irc-channels/) or [Discord](https://discord.com/invite/gentoolinux). -Here is an outline of the steps that are carried out: +## Overview -1. Partition disks (supports gpt, raid, luks) -1. Download and cryptographically verify the newest stage3 tarball -1. Extract the stage3 tarball -1. Sync portage tree -1. Configure portage (create zz-autounmask files, configure `make.conf`) -1. Select the fastest gentoo mirrors if desired -1. Configure the base system (timezone, keymap, locales, ...) -1. Install git and other required tools (e.g. zfs if you have used zfs) -1. Install `sys-kernel/gentoo-kernel-bin` (until you can compile your own) -1. Generate an initramfs with dracut -1. Create efibootmgr entry or install syslinux depending on whether your system uses EFI or BIOS -1. Generate fstab -1. Depending on the configuration: - - (Optional) Install sshd with secure config - - (Optional) Install dhcpcd (if using OpenRC) +The installer performs the following main steps (in roughly this order), +with some parts depending on the chosen configuration: + +1. Partition disks (highly dependent on configuration) +2. Download and extract stage3 tarball (with cryptographic verification) + (Continue in chroot from here) +3. Setup portage (initial rsync/git sync, run mirrorselect, create zz-autounmask files) +4. Base system configuration (hostname, timezone, keymap, locales) +5. Install required packages (git, kernel, ...) +6. Make system bootable (generate fstab, build initramfs, create efibootmgr/syslinux boot entry) +7. Ensure minimal working system (automatic wired networking, install eix, set root password) + + - (Optional) Install sshd with secure config (no password logins) - (Optional) Install additional packages provided in config -1. Asks if a root password should be set -Anything else is probably out of scope for this script, but you can obviously do -what you want later on when the system is booted. Here are some things that you probably -want to consider doing after the base system installation is finished: +The goal of the installer is just to setup a minimal gentoo system following best-practices. +Anything beyond that is considered out-of-scope (with the exception of configuring sshd). +Here are some things that you might want to consider doing after the system installation is finished: 1. Read the news with `eselect news read`. 2. Compile a custom kernel and remove `gentoo-kernel-bin` 3. Adjust `/etc/portage/make.conf` - - Set `CFLAGS` to `-O2 -pipe -march=native` for native builds + - Set `CFLAGS` to `-O2 -pipe ` for native builds by useing the `resolve-march-native` tool - Set `CPU_FLAGS_X86` using the `cpuid2cpuflags` tool - - Set `FEATURES="buildpkg"` if you want to build binary packages -4. Use a safe umask like `umask 0077` - -If you are looking for a way to detect and manage your kernel configuration, have a look at [autokernel](https://github.com/oddlama/autokernel). +4. Use a safe umask like `umask 077` ### (Optional) sshd @@ -84,8 +90,58 @@ These will simply be passed to a final `emerge` call before the script is done, where autounmasking will also be done automatically. It is recommended to keep this to a minimum, because of the quite "interactive" nature of gentoo package management ;) +## Updating the kernel + +By default, the installed system uses gentoo's binary kernel distribution (`sys-kernel/gentoo-kernel-bin`) +together with an initramfs generated by dracut. This ensures that the installed system works on all common hardware configurations. +Feel free to replace this with a custom built kernel (and possibly remove/adjust the initramfs) when the system is booted. + +The installer will provide the convenience script `generate_initramfs.sh` in `/boot/efi/` +or `/boot/bios` which may be used to generate a new initramfs for the given kernel version. +Depending on whether your system uses EFI or BIOS boot, you will also find your kernel and initramfs in different locations: + +```bash +# EFI +kernel="/boot/efi/vmlinuz.efi" +initrd="/boot/efi/initramfs.img" + +# BIOS +kernel="/boot/efi/vmlinuz.efi" +initrd="/boot/efi/initramfs.img" +``` + +In both cases, the update procedure is as follows: + +1. Emerge new kernel +2. `eselect kernel set ` +3. Backup old kernel and initramfs (`mv "$kernel"{,.bak}`, `mv "$initrd"{,.bak}`) +4. Generate new initramfs for this kernel `generate_initramfs.sh "$initrd"` +5. Copy new kernel `cp /boot/vmlinuz- "$kernel"` + +## Modern recommendations + +TODOOOOoo + +Below are some recommendations for setting up a modern system. +Please keep in mind that these are based on my (@oddlama's) personal opinions, but I've tried +my best to explain the rationale behind those decisions. Still, your mileage may vary. +I'll keep this project updated to This project will be updated to reflect my c +After all, these are just recommendations. + +- kernel (bin vs own) +- UUIDs +- EFI +- ZFS +- systemd +- encrypted system root +- efistub +- swap +- zstd compression + ## Troubleshooting and FAQ +TODO the installer can chroot. + After the initial sanity check, the script should be able to finish unattendedly. But given the unpredictability of future gentoo versions, you might still run into issues