Custom readme for my personal fork

             @@ -1,160 +1,55 @@     1      1# ParticleOS     2      2     3       ParticleOS is a fully customizable immutable distribution implementing the     4       concepts described in     5       [Fitting Everything Together](https://0pointer.net/blog/fitting-everything-together.html).     6            7       Note that ParticleOS is still in development, and we don't provide any backwards     8       compatibility guarantees at all.     9           10       The crucial difference that makes ParticleOS unique compared to other immutable    11       distributions is that users build the ParticleOS image themselves and sign it    12       with their own keys instead of installing vendor signed images. This allows    13       configuring the image to your liking by having full control over which    14       distribution is used as the base and which packages are installed into the    15       image.    16           17       The ParticleOS image is built using [mkosi](https://github.com/systemd/mkosi).    18       You will need to install the current main branch of mkosi to build current    19       ParticleOS images.    20           21       First, configure the variant you'd like to build in `mkosi.local.conf`. For a    22       desktop system, you'll want the `desktop` profile and either the `gnome` or the    23       `kde` profile.    24           25       ```conf    26       [Distribution]    27       Distribution=arch    28           29       [Config]    30       Profiles=desktop,kde    31       ```    32           33       To build the image, run `mkosi -B -f` from the ParticleOS repository. Currently    34       `arch`, `fedora` and `debian` are supported distributions. Implementing support for a    35       new distribution (that's already supported in mkosi) is as simple as writing the    36       necessary config files to install the required packages for that distribution.    37           38       To update the system after installation, you clone the ParticleOS repository    39       or your fork of it, make sure `mkosi.local.conf` is configured to your liking and    40       run `mkosi -B -ff sysupdate -- update --reboot` which will update the system using    41       `systemd-sysupdate` and then reboot.    42           43       ## Using the OBS profile to fetch a newer systemd    44           45       Sometimes ParticleOS adopts systemd features as soon as they get merged into    46       systemd without waiting for an official release. That's why we recommend    47       enabling the `obs` profile to enable the systemd repositories on OBS    48       (https://software.opensuse.org//download.html?project=system%3Asystemd&package=systemd)    49       containing systemd packages which are built every day from systemd's git main    50       branch.    51           52       To enable the `obs` profile, add the following to `mkosi.local.conf`:    53           54       ```conf    55       [Config]    56       Profiles=obs    57       ```    58           59       ## Building systemd from source    60           61       As an alternative to using the `obs` profile, you can build systemd from source:    62           63       ```sh    64       git clone https://github.com/systemd/systemd    65       cd systemd    66       mkosi -f sandbox -- meson setup build    67       mkosi -f sandbox -- meson compile -C build    68       mkosi -t none -f    69       ```    70           71       Then write the following to `mkosi.local.conf` in the ParticleOS repository to    72       use the artifacts from the systemd repository built by mkosi in ParticleOS:    73           74       ```conf    75       [Content]    76       VolatilePackageDirectories=../systemd/build/mkosi.builddir/<distribution>~<release>~<arch>    77           78       [Build]    79       ExtraSearchPaths=../systemd/build    80       ```    81           82       Make sure the distribution and release in `mkosi.local.conf` are identical in the    83       systemd checkout and the particleos checkout.    84           85       To build a newer systemd, run `git pull` in the systemd repository followed by    86        `mkosi -f sandbox -- meson compile -C build` and `mkosi -t none`.    87           88       ## Signing keys    89           90       ParticleOS images are signed for Secure Boot with the user's keys. To generate a new key,    91       run `mkosi genkey`. The key must be stored safely, it will be required to sign updates.    92           93       The key can be stored in a smartcard. Then you have to set the key in `mkosi.local.conf`:    94           95       ```    96       [Validation]    97       SecureBootKey=pkcs11:object=Private key 1;type=private    98       SecureBootKeySource=provider:pkcs11    99       SignExpectedPcrKey=pkcs11:object=Private key 1;type=private   100       SignExpectedPcrKeySource=provider:pkcs11   101       VerityKey=pkcs11:object=Private key 1;type=private   102       VerityKeySource=provider:pkcs11   103       ```   104          105       ## Installation   106          107       Before installing ParticleOS, make sure that Secure Boot is in setup mode on the   108       target system. The Secure Boot mode can be configured in the UEFI firmware   109       interface of the target system. If there's an existing Linux installation on the   110       target system already, run `systemctl reboot --firmware-setup` to reboot into   111       the UEFI firmware interface. At the same time, make sure the UEFI firmware   112       interface is password protected so an attacker cannot just disable Secure Boot   113       again.   114          115       To install ParticleOS with a USB drive, first build the image on an existing   116       Linux system as described above. Then, burn it to the USB drive with   117       `mkosi burn /dev/<usb>`. Once burned to the USB drive, plug the USB drive into   118       the system onto which you'd like to install ParticleOS and boot into the USB   119       drive via the firmware. Then, boot into the "Installer" UKI profile. When you   120       end up in the root shell, run   121       `systemd-repart --dry-run=no --empty=force --defer-partitions=swap,root,home /dev/<drive>`   122       to install ParticleOS to the system's drive. Finally, reboot into the target   123       drive (not the USB) and the regular profile (not the installer one) to complete   124       the installation.   125          126       ## LUKS recovery key   127          128       systemd doesn't support adding a recovery key to a partition enrolled with a token   129       only (tpm/fido2). It is possible to use cryptenroll to add a recovery password   130       to the root partition: `cryptsetup luksAddKey --token-type systemd-tpm2 /dev/<id>`   131          132       ## Firmwares   133          134       Only firmwares that are dependencies of a kernel module are included, but some   135       modules don't declare their dependencies properly. Dependencies of a module can be   136       found with `modinfo`. If you experience missing firmwares, you should report   137       this to the module maintainer. `FirmwareInclude=` can be added in `mkosi.local.conf`   138       to include the firmware regardless of whether a module depends on it.   139          140       ## Configuring systemd-homed after installation   141          142       After installing ParticleOS and logging into your systemd-homed managed user,   143       run the following to configure systemd-homed for the best experience:   144          145       ```sh   146       homectl update \   147           --auto-resize-mode=off \   148           --disk-size=max \   149           --luks-discard=on"   150       ```   151          152       Disabling the auto resize mode avoids slow system boot and shutdown. Enabling   153       LUKS discard makes sure the home directory doesn't become inaccessible because   154       systemd-homed is unable to resize the home directory.   155          156       ## Default root password and user when booting in a virtual machine   157          158       If you boot ParticleOS in a virtual machine using `mkosi vm`, the root password   159       is automatically set to `particleos` and a default user `particleos` with password   160       `particleos` is created as well.            3[ParticleOS](https://github.com/systemd/particleos) is an extremely cool            4meta-distribution from the systemd project. It's my favorite thing in software            5since getting into IPv6. Concretely, it's a configuration for systemd's [`mkosi`            6tool](https://mkosi.systemd.io/) that you use to build your own ParticleOS            7images. As described in the readme:            8            9> ParticleOS is a fully customizable immutable distribution implementing the           10concepts described in [Fitting Everything           11Together](https://0pointer.net/blog/fitting-everything-together.html).           12           13Among other things, it has the following characteristics:           14           15- OS versions are delivered as immutable `/usr` partitions           16  - A/B partitions for worry-free upgrades and rollbacks           17  - Block-level integrity provided by           18    [dm-verity](https://wiki.archlinux.org/title/Dm-verity)           19  - Authenticity provided by a signature on the dm-verity data, with signing           20    done by your own keys           21- Is easily hacked on, just like traditional mutable OSes           22  - Essentially *is* a traditional OS (one of Arch, Debian, or Fedora), built           23    entirely from regular distro packages           24  - Hacking on `/usr` is done at image build-time, rather than during OS runtime           25- Is signed with your own SecureBoot keys           26- LUKS-encrypted root partition with TPM-bound key for automatic unlocking           27- LUKS-encrypted home directory managed by           28  [`systemd-homed`](https://systemd.io/HOME_DIRECTORY/)           29           30This here is my own customized version/soft fork of ParticleOS. It's the Fedora           31variant.           32           33See [here](https://www.cgl.sh/blog/posts/particleos.html) for my blog post on           34ParticleOS and mkosi.           35           36## Notable files/directories           37           38- [makefile](makefile)—contains most important commands. `build` and           39  `sysupdate` targets are the main ones. is also responsible for downloading           40  miscellaneous unpackaged binaries.           41- [mkosi.local.conf](mkosi.local.conf)—the linchpin that holds the custom           42  configuration together.           43- [mkosi.profiles/custom](mkosi.profiles/custom)—the custom `mkosi` profile           44  where most of my customizations live.           45  - [mkosi.conf](mkosi.profiles/custom/mkosi.conf)—contains the           46    packages I want installed.           47  - [mkosi.extra](mkosi.profiles/custom/mkosi.extra)—additional files that           48    get included in the built images.           49           50## Other changes           51           52In addition to the above customizations, there are a number of other small           53tweaks I've made, mostly to get Fedora+KDE Plasma working together. Some of them           54should probably be upstreamed to the ParticleOS project. The overall patchset           55can be seen [here on Gitpatch](https://gitpatch.com/jcgl/particleos/patch/5).