sortix--sortix/tix/tix-iso-bootconfig.8

.Dd February 4, 2018
.Dt TIX-ISO-BOOTCONFIG 8
.Os
.Sh NAME
.Nm tix-iso-bootconfig
.Nd generate additional bootloader configuration for Sortix .iso releases
.Sh SYNOPSIS
.Nm
.Op Fl \-append-title Ns = Ns Ar text
.Op Fl \-default Ns = Ns Ar default-boot-menu-option
.Op Fl \-disable-append-title
.Op Fl \-disable-src
.Op Fl \-enable-append-title
.Op Fl \-enable-src
.Op Fl \-liveconfig Ns = Ns Ar liveconfig-directory
.Op Fl \-random-seed
.Op Fl \-timeout Ns = Ns Ar boot-menu-timeout
.Ar output-directory
.Sh DESCRIPTION
.Nm
generates additional bootloader configuration for Sortix .iso releases that can
be overlaid onto the release .iso's filesystem, for instance by using a tool
such as
.Xr tix-iso-add 8 .
.Pp
.Nm
creates the
.Ar output-directory
directory if it doesn't already exist and populates it with the requested
additional configuration.
By default, the only action it takes is to creates a skeleton
.Pa output-directory/boot/grub/hooks.cfg
that appends " - modified by
.Ar username Ns @ Ns Ar hostname Ns
"
to the
.Sy base_menu_title
variable, which changes the boot menu title to say the .iso was modified by the
current username on the local hostname.
.Pp
This script is designed to be convenient when modifying a Sortix release .iso as
part of the
.Xr release-iso-modification 7
procedure.
Additional bootloader configuration can be provided as described in
.Xr release-iso-bootconfig 7 .
The user is free to take all its actions themselves if it doesn't meet their
needs, or to make changes to the output after running the script.
These configuration changes apply only to the live environment, not to any
installations made from inside it.
.Pp
The options are as follows:
.Bl -tag -width "12345678"
.It Fl \-append-title Ns = Ns Ar text
Append " - " followed by
.Ar text
to the bootloader menu title by appending to the
.Sy base_menu_title
GRUB variable.
If this option is not set, the default value is " - modified by
.Ar username Ns @ Ns Ar hostname Ns
", where
.Ar username
is the output of running
.Li id -un
and
.Ar hostname
is the output of running
.Li hostname .
The bootloader menu title is appended to by default, but can be disabled with
.Fl \-disable-append-title ,
and re-enabled with
.Fl \-enable-append-title ,
whichever comes last takes precedence.
.It Fl \-default Ns = Ns Ar default-boot-menu-option
Select bootloader menu option number
.Ar default-boot-menu-option
by default (counting from 0).
If the selected menu option itself is a submenu,
.Ar default-boot-menu-option
can be appended with a
.Sy '>'
and another selection to pick a default menu option in that submenu, and so on.
This option sets the
.Sy default
GRUB variable.
.It Fl \-disable-append-title
Don't append anything to the bootloader menu title by appending to the
.Sy base_menu_title
GRUB variable.
.It Fl \-disable-src
Disable loading the source code in
.Pa /src
by setting
.Sy enable_src
GRUB variable to
.Sy false .
.It Fl \-enable-append-title
Enable appending " - " followed by the value set with
.Fl \-append-title
to the bootloader menu title by appending to the
.Sy base_menu_title
GRUB variable.
This option is on by default and can be disabled with
.Fl \-disable-append-title .
.It Fl \-enable-src
Enable loading the source code in
.Pa /src
by setting
.Sy enable_src
GRUB variable to
.Sy true .
.It Fl \-liveconfig Ns = Ns Ar liveconfig-directory
Overlay the
.Ar liveconfig-directory
directory onto the live environment, allowing full customization of the
live environment.
The
.Xr tix-iso-liveconfig 8
script is convenient for making the
.Ar liveconfig-directory
directory.
This option makes a
.Xr tar 1
archive compressed with
.Xr xz 1
of the
.Ar liveconfig-directory
directory and places it at
.Pa output-directory/boot/liveconfig.tar.xz .
Regardless of this option, if a
.Pa output-directory/boot/liveconfig.tar.xz
is found, the
.Sy xzio
GRUB module is loaded and an
.Sy hook_initrd_post
hook is emitted that loads
.Pa output-directory/boot/liveconfig.tar.xz
as a multiboot module.
.It Fl \-random-seed
Copy 256 bytes of randomness from
.Pa /dev/urandom
to
.Pa output-directory/boot/random.seed ,
which the existing bootloader configuration will automatically detect and use
to seed the kernel's random number generation.
This option is recommended (but notice the warnings below) as the official
releases do not come with any entropy, as entropy must be secret and only known
to a single installation.
.Pp
Warning: The information in the generated
.Pa output-directory/boot/random.seed
file must be kept confidential and should be securely erased whereever it goes
whenever it is no longer useful in a particular place, otherwise the random
number generation of the system using this entropy might be vulnerable.
This random seed must not be recycled to boot more than a single system once.
Additional systems and boots should be done with different entropy by modifiying
the release again.
An installation live environment booted with such a random seed will use it to
randomly generate secure initial random seeds for each installation made, and
each such installation will take care not to reuse the random seed across boots.
Once the
.Ar output-directory
is no longer useful, the
.Pa output-directory/boot/random.seed
path inside it should be securely erased.
If a release .iso has been made from
.Ar output-directory ,
it should be securely erased when no longer useful.
If a release .iso has been burned to a physical media, it should be securely
erased when no longer useful.
.It Fl \-timeout Ns = Ns Ar boot-menu-timeout
Pick the default bootloader menu option after
.Ar boot-menu-timeout
seconds.
If
.Ar boot-menu-timeout
is 0, pick the default menu option immediately.
If
.Ar boot-menu-timeout
is -1, the timeout is disabled.
This option sets the
.Sy timeout
GRUB variable.
.El
.Sh EXIT STATUS
.Nm
will exit 0 on success and non-zero otherwise.
.Sh EXAMPLES
This section contains examples of how one can modify a release .iso.
.Ss "No Change"
To customize a release with no customizations except for the bootloader to say
the release was modified by the current user on the current host:
.Bd -literal
tix-iso-bootconfig bootconfig
tix-iso-add sortix.iso bootconfig
.Ed
.Ss Provide Random Seed
To customize a release with a random seed (which must be kept confidential and
not reused, see the above warnings):
.Bd -literal
tix-iso-bootconfig --random-seed bootconfig
tix-iso-add sortix.iso bootconfig
rm bootconfig/boot/random.seed # When no longer useful.
rm sortix.iso # When no longer useful.
# And erase any media made from sortix.iso when no longer useful.
.Ed
.Ss Add Files to the Live Environment
To customize a release with additional configuration for the live environment
(a directory that is overlaid onto the live environment) made either manually
or with
.Xr tix-iso-liveconfig 8 :
.Bd -literal
tix-iso-bootconfig --liveconfig=liveconfig bootconfig
tix-iso-add sortix.iso bootconfig
.Ed
.Ss Default Bootloader Menu Option and Timeout
To customize a release so the default bootloader menu option is to run the
installer (bootloader menu option 1, counting from 0) and to change the
bootloader menu timeout to 2 seconds:
.Bd -literal
tix-iso-bootconfig --default=1 --timeout=2 bootconfig
tix-iso-add sortix.iso bootconfig
.Ed
.Ss Add to Bootloader Menu Title
To customize a release so the bootloader menu title is appended with a message
of your choice:
.Bd -literal
tix-iso-bootconfig --append-title="Initech Company Edition" bootconfig
tix-iso-add sortix.iso bootconfig
.Ed
.Sh SEE ALSO
.Xr xorriso 1 ,
.Xr kernel 7 ,
.Xr release-iso-bootconfig 7 ,
.Xr release-iso-modification 7 ,
.Xr tix-iso-add 8 ,
.Xr tix-iso-liveconfig 8