manuel
/
gentoo-install
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

feat: (wip) rewrite readme

This commit is contained in:
oddlama 2022-06-08 02:48:07 +02:00
parent 5f36dfb3d0
commit f204711516
No known key found for this signature in database
GPG Key ID: 14EFE510775FE39A
1 changed files with 105 additions and 49 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

154
README.md
View File

@ -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 <march_native_flags>` 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 <kver>`
3. Backup old kernel and initramfs (`mv "$kernel"{,.bak}`, `mv "$initrd"{,.bak}`)
4. Generate new initramfs for this kernel `generate_initramfs.sh <kver> "$initrd"`
5. Copy new kernel `cp /boot/vmlinuz-<kver> "$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