gnuboot/manual/gnuboot.texi

\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename gnuboot.info
@include version.texi
@settitle GNU Boot @value{VERSION}

@c Define a new index for options.
@defcodeindex op
@c Combine everything into one index (arbitrarily chosen to be the
@c concept index).
@syncodeindex op cp
@c %**end of header

@copying

Copyright @copyright{} 2024 Denis 'GNUtoo' Carikli.

Copyright @copyright{} 2024 Adrien 'neox' Bourmault.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled
``GNU Free Documentation License''.
@end quotation
@end copying

@dircategory Kernel
@direntry
* GNU Boot: (gnuboot).                 Boot software distribution
@end direntry

@titlepage
@title GNU Boot manual (version @value{VERSION})
@author GNU Boot Contributors (@email{gnuboot@@gnu.org})
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents


@ifnottex
@node Top
@top GNU Boot

This manual is for GNU Boot version @value{VERSION}.
@end ifnottex

@node Table of contents

@menu
* Overview::					General purpose and information.
* Supported hardware and configurations::
* Using GNU Boot::
* Building GNU Boot from source::
* Helping GNU Boot::				How to contribute to GNU Boot
* GNU Free Documentation License::		Copying and sharing this documentation.
* Concept index::				Index of concepts.
@end menu


@node Overview
@chapter Overview

This chapter will explain what is GNU Boot, and how it compares with
somewhat similar projects.

@node What is GNU Boot
@section What is GNU Boot

GNU Boot is a boot software distribution. What this means will be
explained below.

@node boot software
@subsection boot software
@cindex @acronym{BIOS, Basic Input/Output System}
@cindex @acronym{UEFI, Unified Extensible Firmware Interface}
@cindex boot software

If you take a modern laptop computer, and remove the storage devices
(like @acronym{SSD, Solid State Drive}, hard disks, etc) and then
power on the computer, it will typically show something on the screen.

It often looks a bit like that:

@verbatim
+--------------------------------------------------------------------+
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                        [ Some company Logo ]                       |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
|                                                                    |
| Press F2 for BIOS setup, Press F12 for the startup menu.           |
+--------------------------------------------------------------------+
@end verbatim

What is being displayed on the screen is produced by software which is
often nonfree.

It is often called @acronym{BIOS, Basic Input/Output System} or
@acronym{UEFI, Unified Extensible Firmware Interface} on computers
people are most familiar with. This software is typically stored
inside a memory chip inside the computer mainboard. In some computers,
this software can be replaced by free software.

Depending on how you read the manual, right below you may or may not
see a picture of this memory chip on the mainboard of a ThinkPad X200.

@image{images/SOIC-16,6in,, Picture of the memory chip of the ThinkPad X200
mainboard.}

@sp 2

The goal of this boot software is to initialize the hardware and load
an operating system (like GNU/Linux).

@sp 1

This kind of ``boot software'' exists for a variety of reasons:

@itemize

@item The operating systems require certain hardware components like the
@acronym{RAM, Random Access Memory} to already work when they are
started.

@item The operating system is stored on a storage device(s) (like
@acronym{SSD, Solid State Drive}, hard disks, etc) and part of it needs to be
loaded inside the @acronym{RAM, Random Access Memory} to
work. Something has to do the loading, and this is done in software
for flexibility and/or efficiency reasons.

@item Finally, certain hardware components cannot be auto-detected and
something needs to tell the operating system what drivers to load,
which which settings.

@end itemize

GNU Boot provides such software. It enables to replace nonfree boot
software (typically nonfree @acronym{BIOS, Basic Input/Output System}
or @acronym{UEFI, Unified Extensible Firmware Interface}) on some
computers.

@node distribution
@subsection distribution

GNU Boot is only a distribution because it reuses various software to
produce something that can be installed.

So it is similar to GNU/Linux distributions like Trisquel 11
(aramo) that also reuse various software to produce something that
can be installed.

@node Why free boot software is important
@section Why free boot software is important

Freedom is important in general, and running nonfree software has
negative consequences regardless of the type of software (game, boot
software, operating system, driver, etc).

@sp 1

Here are some examples of common issues for nonfree boot software:

@itemize

@item Since the boot software loads the operating system, it
can potentially modify it in a malicious way. In most cases part of
the boot software also continues to run once the operating system is
started. Because of that and, and because of the way the hardware and
boot software run, the boot software can also do such modification at
any time. If the boot software is nonfree, it is way harder to find
and remove malicious code (it's even impossible to remove in some
cases), and there is no way to make sure that there is none left. For
instance many nonfree boot software where shipped with the CompuTrace
malware (which was advertised as an anti-theft security feature).

@item Vendors of various hardware components have to collaborate together
to provide updates for nonfree Boot software, so in practice
they decide when updates are done. So if a computer is not sold
anymore, it is unlikely to get update for its Boot software
unless the Boot software uses some free software that can be
updated. Also note that applying nonfree updates comes with huge risk
as we don't know what's inside the updates. Hardware vendors who
provide the updates also have an incentive to make things worse for
the users, so they would be pushed to buy new devices.

@item Some nonfree Boot software restrict what you can do with
your computer. For instance they refuse to boot if you changed or
removed some hardware components.

@end itemize

@node Why use GNU Boot
@section Why use GNU Boot

As explained before GNU boot is just a distribution. So it is also
possible to take the same software that GNU Boot reuses, and to build,
assemble and install it yourself.

However doing that is risky because if something goes wrong, your
computer won't boot anymore.

So the goals of GNU Boot are to:

@itemize

@item Collaborate together to test if GNU Boot releases works fine.

@item Provide documentation to enable easy installation and usage.

@item Limit the amount of work done by GNU Boot and contribute
directly to the software we reuse whenever possible.

@end itemize

GNU Boot also has a long term focus, so it tries not to break users
use cases, and tries as much as possible to fix issues in the projects
it reuses instead of doing workarounds that impact users.


@node Other free boot software distributions
@section Other free boot software distributions

The following GNU/Linux distributions should also provide 100% free
boot software but they usually only provide them for computers using
the ARM architecture (which GNU Boot doesn't support yet):

@itemize

@item Parabola

@item PureOS

@item Trisquel

@end itemize

The GNU Guix package manager (which GNU Boot also reuses) also provide
100% free boot software for some ARM computers. However the Guix
packages are updated all the time and the Guix project doesn't provide
any way for users to report that specific ARM computers work fine with
the boot software they provide.

There is also Canoeboot which is a 100% free software boot
distribution similar to GNU Boot. Its goal is to remove nonfree
software from Libreboot. It focuses more on having the latest software
and many features, including some that are not available in the
projects it reuses. Because of that it can be harder for users to use.

@node How much free software is GNU Boot?
@section How much free software is GNU Boot?

Being a GNU package, GNU Boot itself is 100% free software. If you
find nonfree software in GNU Boot and/or any source code or binaries
released by GNU Boot, please contact its maintainers by opening a bug
report on its bug tracker at
@url{https://savannah.gnu.org/bugs/?group=gnuboot}.

But that doesn't mean that GNU Boot magically makes everything not
provided by GNU Boot free software.

In some cases GNU Boot even runs nonfree software not provided by GNU
Boot like nonfree GPUs drivers provided by the removable GPU
card. @xref{Supported computer parts and peripherals} for more
details about this issue and how to avoid running such nonfree
software.

To address problems like that the @uref{https://www.fsf.org/,Free
Software Foundation} has created the
@uref{https://ryf.fsf.org/,Respect Your Freedom hardware
certification} to list hardware that works with only free software
(with some very small exceptions for some components, see
@uref{https://ryf.fsf.org/about/criteria, its criteria} for more
details).

In addition there is also
@uref{https://www.fsfla.org/ikiwiki/blogs/lxo/draft/blob-fallacy,The
Blob Fallacy article} or
@uref{https://media.libreplanet.org/u/libreplanet/m/software-enshittification-or-freedom-it-s-not-a-hard-choice,
a video of a presentation about the same issue at LibrePlanet 2024} by
Alexandre Oliva that explains the related freedom issues with nonfree
software provided by the hardware and how they compare with other kind
of freedom issues (nonfree driver, nonfree firmware loaded
automatically by Linux, etc).

@node Limitations
@section Limitations

GNU Boot is fairly recent and doesn't have an official release
yet.

For the release we plan to have at least some install and upgrade
instructions for some computers and an easy way for users to use GNU
Boot.

Also the latest GNU Boot release candidate was not tested yet with all
the computers it's supposed to support (we badly need help for that).

@node Supported hardware and configurations
@chapter Supported hardware and configurations

@node Supported computers
@section Supported computers

For now, GNU Boot only provides images that can be installed on the
following computers:

@itemize

@item Acer G43T-AM3
@item Apple MacBook 1.1
@item Apple MacBook 2.1
@item Apple iMac 5,2
@item Asus KCMA-D8
@item Asus KFSN4-DRE
@item Asus KGPE-D16
@item Gigabyte D945GCLF2D
@item Gigabyte GA-G41M-ES2L
@item Intel D410PT
@item Intel D510MO
@item Intel D945GCLF
@item Lenovo ThinkPad R400
@item Lenovo ThinkPad R500
@item Lenovo ThinkPad T400
@item Lenovo ThinkPad T400S
@item Lenovo ThinkPad T500
@item Lenovo ThinkPad T60 with intel GPU
@item Lenovo ThinkPad W500
@item Lenovo ThinkPad X200
@item Lenovo ThinkPad X200S
@item Lenovo ThinkPad X200T
@item Lenovo ThinkPad X301
@item Lenovo ThinkPad X60
@item Lenovo ThinkPad X60T
@item Lenovo ThinkPad X60s
@item Libiquity Taurinus X200
@item Qemu PC (i440FX)
@item Technoethical D16
@item Technoethical T400
@item Technoethical T400s
@item Technoethical T500
@item Technoethical X200
@item Technoethical X200s
@item Technoethical X200 Tablet (X200T)
@item Vikings ASUS KCMA D8 mainboard and workstation
@item Vikings ASUS KGPE D16 mainboard
@item Vikings X200

@end itemize

However as GNU Boot is still relatively new, we lack installation and
upgrade instructions for most of these computers.

Also not all are well tested, so it's a good idea to look on the GNU
Boot website, on the status page (
@url{https://www.gnu.org/software/gnuboot/web/status.html}) for up to
date result of tests by GNU Boot users and contributors.

@node Supported computer parts and peripherals
@section Supported computer parts and peripherals

Most computer parts and peripherals don't have any compatibility issue
with GNU Boot because:

@itemize

@item they either use some standard that is most often already
implemented in the software GNU Boot reuses (storage devices like SATA
drives, USB keyboards, etc),

@item they are not relevant or supported for booting (for instance 3D printers,
cellular network cards, etc, unless people add support for them in GNU
Boot in the future). Until then they are only handled in the operating
system instead (with drivers),

@end itemize

however there is some exceptions as some hardware is non-standard and
still required for booting, these are documented in the subsections
below.

@node Supported GPUs and graphics
@subsection Supported GPUs and graphics

GNU Boot supports the GPUs that are present in the various laptops it
supports with 100% free software. Some consideration apply while
booting (@pxref{GNU Boot images} for more details), but so far once
booted these GPU are known to works well on tested computers.

In addition for the non-laptop computers, it also supports the builtin
AST graphics in the KGPE-D16 and KCMA-D8 with 100% free software, but
this also comes with some limitations: in GNU/Linux it's only possible
to display text but not images, so it's limited to console
applications.

In the case of PCIe GPU / graphics cards, we don't know yet if it
is possible to use them without running nonfree software.

If AMD, ATI, and Nvidia cards work under GNU Boot, it's because GNU
Boot loaded and run the nonfree video BIOS that is present on the
card.

It's possible to prevent the nonfree video BIOS from running and you
can easily confirm that as the display will not work until the Linux
driver is loaded.

The Free Software Foundation tech team has a wiki. In
@uref{https://savannah.gnu.org/maintenance/fsf/hardware/disable-option-roms-with-cbfstool/,
the disable option roms with cbfstool article}, they explains how to
do that.

And in
@uref{https://savannah.gnu.org/maintenance/fsf/hardware/graphics-cards/,
the graphics cards article} they also explain which GPU they tested.

However the Linux driver can also run nonfree software: All the
current AMD, ATI, and Nvidia drivers have code to load and run (a
different) initialization code provided on the card. For ATI and AMD
cards the code that Linux runs is called AtomBIOS.

We don't know yet if there are cases where this code is not run (this
would need to be tested by doing very simple modifications to the
drivers, and the GNU Boot project also welcome help in this area).

@node Supported card readers
@subsection Supported card readers

GNU Boot supports the builtin card reader of the following computers:

@itemize
@item Lenovo ThinkPad X200
@item Lenovo ThinkPad X200S
@item Lenovo ThinkPad X200T
@item Libiquity Taurinus X200
@item Technoethical X200
@item Technoethical X200s
@item Technoethical X200 Tablet (X200T)
@item Vikings X200

@end itemize

It also supports some USB card readers that are viewed as
mass-storage. With all that you can boot on an SD card a microSD card
and it will be viewed like a mass storage USB key.

@node Unsupported hardware supported by projects reused by GNU Boot
@subsection Unsupported hardware supported by projects reused by GNU Boot

The following hardware components are supported by software reused by
GNU Boot, but support for them hasn't been enabled yet in GNU Boot:

@itemize
@item Serial ports.
@item Software RAID cards: Some Silicon Image SIL3114 software RAID
      cards are supported by Coreboot but not enabled in GNU Boot.
@item Network interfaces. Projects like iPXE has drivers for many network cards
      and even some Wifi cards typically used with the computers supported by GNU
      Boot and free distributions.
@item Some printers that use serial ports could probably easily be supported
      once serial ports are working.
@end itemize

The GNU Boot project needs help to evaluate the impact of enabling
these and welcome contributions in this area.

@node Supported operating systems
@subsection Supported operating systems

While GNU Boot should be able to boot almost any GNU/Linux
distribution, but in some cases some configuration might be needed by
the GNU Boot user. The cases that do and don't require configuration
from the user will be documented in @ref{GNU Boot images} below.

Even if some cases require some configuration, GNU Boot makes sure to
provide at least one way to boot free GNU/Linux distributions (see
@url{https://www.gnu.org/distros/} for more information on these
distributions) without the need to configure anything in order to make
it possible for less technical users to use computers with GNU Boot,
and even reinstall the GNU/Linux distribution without needing to do
anything too complicated.

To make that possible, the GNU Boot contributors that proposes
improvements to the project typically test GNU Boot with free
distributions, and the GNU Boot project even runs automatic tests with
Trisquel 11 (aramo), one of the free distributions to make sure that
it can boot fine without needing any special configuration from the
user.

However sometimes fully free distributions also propose experimental
or non-standard configurations for very specific use cases. For
instance Guix has experimental support for GNU Hurd, an experimental
kernel from the GNU project, and Trisquel supports the Xen kernel,
which is a virtualization solution that not supported by all GNU/Linux
distributions. These configurations are not supported in the official
installers of these distribution and so users are usually aware thaty
they use Xen or GNU Hurd. Using GNU Boot with these configurations
might require some configuration from the user. Also we would need
help from users to report what works and doesn't work or what
workarounds are needed to make them work with GNU Boot.

The cases that are known not to require any configuration might also
work with any GNU/Linux distributions (even the nonfree ones), however
the GNU Boot project doesn't want to force contributors to download or
run nonfree software to test changes, so it relies on voulounteers
already running such distributions to report bugs in case something
doesn't work as it should.

As for other operating systems, there is some documentation on how to
boot some of them (like some BSD operating systems) on the GNU Boot
website, but again we need help from voulonteers already running such
systems to keep the documentation up to date and inform us of what
works and doesn't work.

Also if you want to do such tests, you can open a bug report on the
GNU Boot bug tracker at
@url{https://savannah.gnu.org/bugs/?group=gnuboot}.

@node GNU Boot images
@section GNU Boot images
@cindex flash images
@cindex image files

In computers people are most familar with, like laptops, the boot
software resides in a memory chip inside the mainboard (@pxref{boot
software} for more details).

GNU Boot provide @dfn{image files} which are files that replace the
content of these memory chip.

These files are similar to
@uref{https://en.wikipedia.org/wiki/Disk_image,disk images},
@uref{https://en.wikipedia.org/wiki/ISO_image,ISO images}, or
@uref{https://en.wikipedia.org/wiki/ROM_image,ROM images}.

We also sometime refer to the flash image files as @dfn{flash images}.

@node GNU Boot images types
@subsection GNU Boot images types

For a given computer, GNU Boot provides several images with different
software in it. This enable the users to choose between:

@itemize

@item Two boot software: GRUB or SeaBIOS
      (@acronym{BIOS, Basic Input/Output System} implementation)

@item Various keyboard layouts (colemak, deqwertz, esqwerty,
frazerty, frdvbepo, itqwerty, svenska, trqwerty, ukdvorak, ukqwerty,
usdvorak, usqwerty).

@item Low resolution or high resolution graphics.

@end itemize

If you are a less technical user or helping one, or don't have much
time to configure things, it is a good idea to choose an image with
GRUB, and a keyboard layout of your choice (the resolution is not very
important, but using high resolution looks nicer) as the image with
GRUB doesn't require to do any configuration in the distributions you
want to boot.

Otherwise here are the advantages/disadvantages of each combinaison:

@itemize

@item GRUB with high resolution graphics: Images with GRUB
usually don't require the user to do any configuration of the
distribution. More technical users can also use that to customize the
way the system boots for more security or to support unsual boot
configurations (that are not typically supported by graphical
installers of GNU/Linux distributions), however these more advanced
configurations also come with their set of limitations.

@item SeaBIOS with text-only low resolution: It implements
@acronym{BIOS, Basic Input/Output System} compatibility, so it is very
similar to a nonfree @acronym{BIOS, Basic Input/Output System} but it
require users to modify some settings inside the distribution they
use, otherwise the distribution still boots but usually has a black
screen during the boot (which can be problematic to diagnose a
non-booting distribution). The low resolution increase compatibility
with various software that are typically run at boot like memtest86+
(a software that detects broken RAM chips).

@item GRUB with text-only low resolution: Since these images
boot with GRUB, they also don't require any configuration of the
distribution and more technical users can also use them to customize
the way the system boots. Compared to GRUB images with high resolution
graphics:
    @itemize
    @item the text is bigger and that there is no background picture
    @item since on most supported computers, GRUB images can
          also load and run SeaBIOS (there is a menu entry for
          it), having a text-only low resolution increase the
          compatibility with various boot software.
    @end itemize

@item SeaBIOS with high resolution graphics:

Since these images boot with SeaBIOS they also implement some
@acronym{BIOS, Basic Input/Output System} compatibility, but they also
require users to modify some settings inside the distribution they
use. Compared with SeaBIOS images with text-only low resolution:

    @itemize

    @item they are less compatible with various boot software. This
           can be useful for testing if you contribute to some boot
           software.

    @item since on most supported computers, SeaBIOS images can also
          load and run GRUB (there is a menu entry for it when
          pressing the 'ESC' key at boot), having high resolution
          graphics can make GRUB look nicer.

    @end itemize

@end itemize

@node GNU Boot images naming
@subsection GNU Boot images naming

Images for specific computers can be found on
@uref{https://ftp.gnu.org/gnu/gnuboot/,the GNU Boot download area} or
in the release/roms directory if you built GNU Boot from source
yourself.

For a given release (or release candidate) like GNU Boot 0.1-rc3, you
can find such files inside the 'roms' directory like
@url{https://ftp.gnu.org/gnu/gnuboot/gnuboot-0.1-rc3/roms/} for GNU
Boot 0.1-rc3.

Inside you have archive files like
@option{gnuboot-0.1-rc3_x200_8mb.tar.xz} that are specific to a
specific computer (here the ThinkPad X200 with 8MiB flash chip).

@pxref{Installing or upgrading GNU Boot images} to understand how to
identify which archive file correspond to which computer.

Inside each archive files, there are many smaller files that are flash
images. @xref{boot software} to understand what a flash image is.

The flash image files correspond to the configurations described in
the @ref{GNU Boot images types}.

So for instance if we have an image named
@option{grub_x200_8mb_corebootfb_usqwerty.rom}, it is meant for a
ThinkPad X200 with 8MiB flash chip, and it uses the GRUB software to
boot, and it is configured to use a QWERTY keyboard layout.

If the image contains @option{seabios} in its file name instead of
@option{grub}, it uses the SeaBIOS software to boot.

The @option{corebootfb} in the file name correspond to the high
resolution graphics described in the previous subsection (@ref{GNU
Boot images types}).

If instead the file has @option{txtmode} in its name, this corresponds
to the text-only low resolution that was also described in the
previous subsection (@ref{GNU Boot images types}).

@node Installing or upgrading GNU Boot images
@chapter Installing or upgrading GNU Boot images

GNU Boot provides flash images for specific computers that can be
found on the GNU Boot download area (https://
ftp.gnu.org/gnu/gnuboot/).

But depending on your threat model, it could be a good idea to build
GNU Boot from source yourself instead, to avoid certain security
attacks. @xref{Security features} section for more context with
security and threat models and @ref{Building GNU Boot from source}
for more details about the security attacks mentioned above.

Once GNU Boot is downloaded or built, you will need to understand
which files you need to install or upgrade. @xref{Supported hardware
and configurations} chapter for more details on how to do that.

@node Installation and upgrade instructions
@section Installation and upgrade instructions

The GNU Boot manual doesn't have well integrated installation or
upgrade instructions yet but some generic installation and upgrade
instructions can be found in the GNU Boot website. We need help to
migrate these instructions in the manual and make them easier to
understand.

@node Using GNU Boot
@chapter Using GNU Boot

@node Using GNU Boot with QEMU
@section Using GNU Boot with QEMU

The GNU Boot project also release images for QEMU.

If you just want to try an image to see how it looks like you can use
the following command:

@example
qemu-system-x86_64 -M pc \
-bios grub_qemu-pc_2mb_corebootfb_usqwerty.rom
@end example

Here you need to replace
@emph{grub_qemu-pc_2mb_corebootfb_usqwerty.rom} by the
path to the image you want to try.

For a more complete example, you can look in the GNU Boot source code
as GNU Boot uses QEMU to run some automatic tests that boots Trisquel
11 (aramo).

Also note that the GNU Boot images for QEMU can be useful in some
situations, but it doesn't fully replace tests run on real computers.

For instance a distribution or operating system might work on QEMU but
not work on real hardware due to an incomplete graphic driver for the
real hardware GPU.

@node Security features
@section Security features
@cindex secure boot
@cindex threat modelling

Note that security is a process. To really make it work you need to
understand various threats and how to respond to them (this is called
@dfn{threat modelling}), so what security feature to use or not to use
depends on your life, use cases, etc.

Also note that in general some security features also have downsides,
such as making it harder to use the computer, making it harder to fix
issues, etc, so not everybody might want these security features.

As for security features typically found in other boot software, some
computers vendor sell computers with what they call @dfn{secure
boot}. When it cannot be turned off, it becomes an anti-feature and
the @uref{https://www.fsf.org/,Free Software Foundation} calls it
@dfn{restricted boot}.

In 2012, the @uref{https://www.fsf.org/,Free Software Foundation}
wrote
@uref{https://www.fsf.org/campaigns/secure-boot-vs-restricted-boot/campaigns/secure-boot-vs-restricted-boot/whitepaper.pdf,a
whitepaper}, on the topic and advised that:

@verbatim
The best solution currently available for operating system distributions
includes:
1. fully supporting user-generated keys, including providing tools and full
documentation for booting and installing both modified and official
versions of the distribution using this method;
2. using a GPLv3-covered bootloader to help protect users against the
dangers of Restricted Boot;
3. avoiding requiring or encouraging users to trust Microsoft or any com-
pany which makes proprietary software; and
4. joining the FSF and the broader free software movement in pressuring
computer distributors to facilitate easy and independent installation of
free software operating systems on any computer.
@end verbatim

GNU Boot supports various security mechanism: GRUB is a GPLv3-covered
bootloader that GNU Boot reuses, and it supports user-generated keys
or other security mechanism that that don't require any signing
keys.

GNU Boot also obviously doesn't Trust keys from companies that make
proprietary software.

At the end when used correctly, the security features provided by GNU
Boot thanks to the software it reuses (like GRUB) can provide similar
or stronger security guarantees than the UEFI secure boot with
different security features that you may or may not want want to use
depending on your threat model.

The GNU Boot Website contains various information on how to use such
security features, but they are also documented in the
@ref{,,,grub,GNU GRUB manual} as well in more details. Since the GRUB
version GNU Boot uses might be older than the online GRUB manual, you
can use Guix to install the manual of older GRUB versions
(@pxref{,,,guix,GNU Guix reference manual} for more details).

All the security mechanism described in the GRUB manual or GNU Boot
website are compatible with users freedom.

@node Building GNU Boot from source
@chapter Building GNU Boot from source

Currently building GNU Boot flash images on two different computers
will produce slightly different images.

This is a problem as it prevents people from easily verifying that the
official flash images really correspond to the source code published
by GNU Boot, and having the ability for anyone to verify that
increases the security guarantees.

The @uref{https://reproducible-builds.org,Reproducible builds} project
helps publicizing this problem and helps distributions and software to
fix it.

So while GNU Boot also started working to fix this problem the work
just stated and isn't complete yet, so in the meantime if you care
about this type of risks, it might be a good idea to build GNU Boot
from source yourself.

The GNU Boot website has instructions for building GNU Boot at the
following URL:
@url{https://www.gnu.org/software/gnuboot/web/docs/build/}.

@xref{Authenticating the GNU Boot source code} as GNU Boot has ways to
prevent network attacks from tempering with the souce code you are
downloading.

Note that at the moment, building GNU Boot from tarballs is
unsupported, so you will have to download GNU Boot from git and build
from git.

@node Authenticating the GNU Boot source code
@section Authenticating the GNU Boot source code

As explained on the
@uref{https://www.gnu.org/software/gnuboot/web/docs/build/,GNU Boot
build instructions} on the GNU Boot website, to build GNU Boot you
will need to install Guix first (it can be installed on top of another
GNU/Linux distribution).

You can consult either the
@uref{https://www.gnu.org/software/gnuboot/web/docs/build/,GNU Boot
build instructions} or the @ref{Installation,,,guix,GNU Guix
reference manual} for how to do that.

Once this is done you can download the GNU Boot source code with the
following command and go into it:
@example
$ git clone https://git.savannah.gnu.org/git/gnuboot.git
$ cd gnuboot
@end example

And you can then authenticate the source code with the following guix
command:

@example
$ guix git authenticate \
dde4223088cbfe8a347626638d32902ba2323b25 \
"E23C 26A5 DEEE C5FA 9CDD  D57A 57BC 26A3 6871 16F6" \
-k origin/keyring
@end example

It should then print the following text:
@example
guix git: successfully authenticated commit dde4223088cbfe8a347626638d32902ba2323b25
@end example

@xref{Invoking guix git authenticate,,,guix,GNU Guix manual} or
@uref{https://guix.gnu.org/en/blog/2024/authenticate-your-git-checkouts/,the
Authenticate your Git checkouts! Guix blog post} for more details.

The question that remains is then how to make sure that "E23C 26A5
DEEE C5FA 9CDD D57A 57BC 26A3 6871 16F6" is the right key.

To do that the GnuPG software can help (@pxref{,,,gnupg,its manual}
for now to use it if you are interested) but the solution to this
problem is not technical but social and could require significant time
and effort.

To solve this problem you will need to build some sort of chain of
trust between you and the person who controls the "E23C 26A5 DEEE C5FA
9CDD D57A 57BC 26A3 6871 16F6" key (here Adrien 'neox' Bourmault) with
or without the help of the GnuPG software.

Wikipedia has a bit more information on the problem in its
@uref{https://en.wikipedia.org/wiki/Web_of_trust,Web of trust} article,
and the @uref{https://www.gnupg.org/gph,The GNU Privacy Handbook} has
@uref{https://www.gnupg.org/gph/en/manual/x547.html,a section about
Building your web of trust}, that contains advises on how to do that,
especially in the part about "Key validation".

@node Helping GNU Boot
@chapter Helping GNU Boot

The GNU Boot project needs help with this manual, specifically on
moving information from the GNU Boot website to this manual.

In general there is also a lot of ways to help the GNU Boot project
(from reviewing website pages for very simple mistakes or outdated
information, testing GNU Boot images, etc).

See the
@uref{https://www.gnu.org/software/gnuboot/web/git.html,Helping GNU
Boot} page on the GNU Boot website for the areas where we need help
and on how to help practically speaking (how to contact the project,
where to send bug reports, etc).

@node GNU Free Documentation License
@appendix GNU Free Documentation License

@include fdl-1.3.texi


@node Concept index
@unnumbered Concept index

@printindex cp

@bye