580 lines
15 KiB
Groff
580 lines
15 KiB
Groff
.Dd February 24, 2018
|
|
.Dt RELEASE-ISO-BOOTCONFIG 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm release-iso-bootconfig
|
|
.Nd release .iso bootloader configuration
|
|
.Sh DESCRIPTION
|
|
You can customize the bootloader configuration of a release .iso by adding your
|
|
own
|
|
.Pa /boot/grub/hooks.cfg
|
|
to the .iso filesystem as part of the
|
|
.Xr release-iso-modification 7
|
|
procedure.
|
|
This manual page details the programming interface available when writing this
|
|
file.
|
|
.Pp
|
|
Commonly a custom
|
|
.Pa /boot/grub/hooks.cfg
|
|
would take some actions when loaded (such as setting variables)
|
|
and define hook functions as described in the
|
|
.Sx Hooks
|
|
subsection to inject behavior in certain locations, and otherwise make use of
|
|
the facilities described in this manual page.
|
|
.Ss Ports and Binary Packages
|
|
The release .iso contains binary packages.
|
|
The ports menu controls what binary packages are installed in the live
|
|
environment.
|
|
.Ss Port Sets
|
|
The binary packages menu controls what binary packages have a copy stored in the
|
|
.Pa /repository
|
|
directory inside the live environment.
|
|
.Pp
|
|
Sets of ports and binary packages are defined by
|
|
.Pa build-aux/ports.conf
|
|
in the source code:
|
|
.Bl -tag -width "12345678"
|
|
.It Sy all
|
|
All ports.
|
|
.It Sy basic
|
|
Common software and everything needed to develop the operating system
|
|
.It Sy minimal
|
|
Ports needed to successfully install and upgrade the operating system.
|
|
.It Sy no
|
|
No ports.
|
|
.El
|
|
.Ss Configuration Files
|
|
The bootloader configuration consists of these GRUB configuration files that you
|
|
can use or overwrite as desired:
|
|
.Bl -tag -width "12345678"
|
|
.It Pa /boot/grub/grub.cfg
|
|
The GRUB bootloader will load its configuration by loading this file.
|
|
.Pp
|
|
First, this file loads the default bootloader configuration by taking the following
|
|
actions:
|
|
.Pp
|
|
It defines no-operation versions of each of the hook functions defined below.
|
|
.Pp
|
|
It loads the appropriate GRUB modules.
|
|
.Pp
|
|
It initializes the global variable described below.
|
|
.Pp
|
|
It defines functions to select each set of ports and binary package, as
|
|
described below.
|
|
.Pp
|
|
Secondly, it loads
|
|
.Pa /boot/grub/hooks.cfg
|
|
(if it exists)
|
|
which can take any actions it wants and customize the default configuration.
|
|
.Pp
|
|
Finally, it loads
|
|
.Pa /boot/grub/main.cfg
|
|
to display the menu menu.
|
|
.It Pa /boot/grub/hooks.cfg
|
|
This file provides additional bootloader configuration if it exists.
|
|
.Pp
|
|
This file is loaded (if it exists) by
|
|
.Pa /boot/grub/grub.cfg
|
|
after the default bootloader configuration has been loaded.
|
|
The bootloader configuration is designed to be customized by setting the
|
|
variables defined below, defining any of the hook functions defined below, or
|
|
any other desired actions.
|
|
.It Pa /boot/grub/main.cfg
|
|
This file displays the main bootloader menu by taking the following actions:
|
|
.Pp
|
|
The
|
|
.Sy menu_title
|
|
variable is set to the contents of the
|
|
.Sy base_menu_title
|
|
variable.
|
|
.Pp
|
|
The
|
|
.Sy hook_menu_pre
|
|
hook is run.
|
|
.Pp
|
|
Menu entries are emitted for the live environment, the installer, and the
|
|
upgrader.
|
|
.Pp
|
|
The live environment menu entry runs:
|
|
.Li load_sortix -- /sbin/init --target=single-user
|
|
.Pp
|
|
The installer menu entry runs:
|
|
.Li load_sortix -- /sbin/init --target=sysinstall
|
|
.Pp
|
|
The upgrader menu entry runs:
|
|
.Li load_sortix -- /sbin/init --target=sysupgrade
|
|
.Pp
|
|
Menu entries are emitted for the ports selection bootloader menu (which runs
|
|
.Li configfile /boot/grub/ports.cfg )
|
|
and the advanced bootloader menu (which runs
|
|
.Li configfile /boot/grub/advanced.cfg )
|
|
.Pp
|
|
Finally the
|
|
.Sy hook_menu_post
|
|
hook is run.
|
|
.It Pa /boot/grub/advanced.cfg
|
|
This file displays the advanced bootloader menu by taking the following actions:
|
|
.Pp
|
|
A menu entry is emitted that goes back to the main menu (which runs
|
|
.Li configfile /boot/grub/main.cfg )
|
|
.Pp
|
|
The
|
|
.Sy menu_title
|
|
variable is set to the contents of the
|
|
.Sy base_menu_title
|
|
variable appended with " - Advanced Options".
|
|
.Pp
|
|
The
|
|
.Sy hook_advanced_menu_pre
|
|
hook is run.
|
|
.Pp
|
|
A menu entry is emitted to control whether network drivers are enabled.
|
|
.Pp
|
|
A menu entry is emitted that goes to the binary packages menu (which runs
|
|
.Li configfile /boot/grub/tix.cfg )
|
|
.Pp
|
|
Finally, the
|
|
.Sy hook_advanced_menu_post
|
|
hook is run.
|
|
.It Pa /boot/grub/ports.cfg
|
|
This file displays the port selection bootloader menu by taking the following
|
|
actions:
|
|
.Pp
|
|
A menu entry is emitted that goes back to the main menu (which runs
|
|
.Li configfile /boot/grub/main.cfg )
|
|
.Pp
|
|
The
|
|
.Sy menu_title
|
|
variable is set to the contents of the
|
|
.Sy base_menu_title
|
|
variable appended with " - Ports".
|
|
.Pp
|
|
The
|
|
.Sy hook_ports_menu_pre
|
|
hook is run.
|
|
.Pp
|
|
The following menu entries implicitly run
|
|
.Li configfile /boot/grub/ports.cfg
|
|
afterwards to return to this menu.
|
|
.Pp
|
|
A menu entry is emitted that loads all ports by running
|
|
.Sy select_ports_set_all .
|
|
.Pp
|
|
The
|
|
.Sy hook_ports_menu_pre
|
|
hook is run.
|
|
.Pp
|
|
Menu entries are emitted for each of the port sets, each of which load only
|
|
those ports set by running
|
|
.Sy select_ports_set_ Ns Ar $set .
|
|
.Pp
|
|
A menu entry is emitted that loads no ports by running
|
|
.Sy select_ports_set_no .
|
|
.Pp
|
|
The
|
|
.Sy hook_ports_menu
|
|
hook is run.
|
|
.Pp
|
|
Menu entries are emitted for each port, each stating whether that port will be
|
|
loaded, and selecting such a menu entry will toggle whether the port is loaded
|
|
by setting
|
|
.Sy port_ Ns Ar $set
|
|
variable to
|
|
.Sy true
|
|
or
|
|
.Sy false .
|
|
.Pp
|
|
Finally, the
|
|
.Sy hook_ports_menu_post
|
|
hook is run.
|
|
.It Pa /boot/grub/tix.cfg
|
|
This file displays the binary packages selection bootloader menu by taking the
|
|
following actions:
|
|
.Pp
|
|
A menu entry is emitted that goes back to the advanced menu (which runs
|
|
.Li configfile /boot/grub/advanced.cfg )
|
|
.Pp
|
|
The
|
|
.Sy menu_title
|
|
variable is set to the contents of the
|
|
.Sy base_menu_title
|
|
variable appended with " - Binary Packages".
|
|
.Pp
|
|
The
|
|
.Sy hook_tix_menu_pre
|
|
hook is run.
|
|
.Pp
|
|
The following menu entries implicitly run
|
|
.Li configfile /boot/grub/tix.cfg
|
|
afterwards to return to this menu.
|
|
.Pp
|
|
A menu entry is emitted that loads all binary packages by running
|
|
.Sy select_tix_set_all .
|
|
.Pp
|
|
The
|
|
.Sy hook_tix_menu_pre
|
|
hook is run.
|
|
.Pp
|
|
Menu entries are emitted for each of the binary package sets, each of which load
|
|
only those binary packages set by running
|
|
.Sy select_tix_set_ Ns Ar $set .
|
|
.Pp
|
|
A menu entry is emitted that loads no binary packages by running
|
|
.Sy select_tix_set_no .
|
|
.Pp
|
|
The
|
|
.Sy hook_tix_menu
|
|
hook is run.
|
|
.Pp
|
|
Menu entries are emitted for each binary package, each stating whether that
|
|
binary package will be loaded, and selecting such a menu entry will toggle
|
|
whether the binary package is loaded
|
|
by setting
|
|
.Sy tix_ Ns Ar $set
|
|
variable to
|
|
.Sy true
|
|
or
|
|
.Sy false .
|
|
.Pp
|
|
Finally, the
|
|
.Sy hook_tix_menu_post
|
|
hook is run.
|
|
.El
|
|
.Ss Variables
|
|
In addition to the standard GRUB variables, the following global variables are
|
|
set in
|
|
.Pa /boot/grub/grub.cfg :
|
|
.Bl -tag -width "12345678"
|
|
.It Sy base_menu_title
|
|
The base menu title which is used to construct the menu titles for each of the
|
|
menus by setting the
|
|
.Sy menu_title
|
|
variable.
|
|
The main menu uses this title verbatim, while the other menus will append
|
|
" -
|
|
.Ar menu_name Ns
|
|
" when constructing
|
|
.Sy menu_title.
|
|
(Default: "Sortix $version for $machine")
|
|
.It Sy default
|
|
Select this bootloader menu option number by default (counting from 0).
|
|
If the selected menu option itself is a submenu, it can be appended with a
|
|
.Sy '>'
|
|
and another selection to pick a default menu option in that submenu, and so on.
|
|
(Default: 0)
|
|
.It Sy enable_dhclient
|
|
Whether to start the
|
|
.Xr dhclient 8
|
|
daemon.
|
|
(Default: true)
|
|
.It Sy enable_network_drivers
|
|
An additional
|
|
.Xr kernel 7
|
|
command line parameter that controls whether network drivers are enabled.
|
|
Either set to the empty string (network drivers are enabled) or
|
|
.Sy --disable-network-drivers .
|
|
(Default: The empty string).
|
|
.It Sy enable_src
|
|
Whether to load the source code initrd containing
|
|
.Pa /src .
|
|
(Default:
|
|
.Sy true )
|
|
.It Sy enable_sshd
|
|
Whether to start the
|
|
.Xr sshd 8
|
|
daemon.
|
|
(Default: false)
|
|
.It Sy machine
|
|
The machine type this release was built for.
|
|
.It Sy menu_title
|
|
The menu title to display above the bootloader menu.
|
|
(Default: "$base_menu_title")
|
|
.It Sy no_random_seed
|
|
An additional command line parameter passed to the
|
|
.Xr kernel 7
|
|
turning off the warning about lack of entropy if there is no random seed.
|
|
This variable defaults to
|
|
.Sy --no-random-seed
|
|
if
|
|
.Pa /boot/random.seed
|
|
doesn't exist, otherwise it defaults to the empty string.
|
|
.It Sy port_ Ns Ar $port
|
|
The
|
|
.Ar port
|
|
is installed into live environment if this variable is set to
|
|
.Sy true
|
|
and not if set to
|
|
.Sy false .
|
|
(Default:
|
|
.Sy true )
|
|
.It Sy timeout
|
|
The time in seconds before the default menu entry (according to the
|
|
.Sy default
|
|
variable) is automatically selected.
|
|
If set to 0, the default menu entry is loaded instantaneously.
|
|
The timeout is disabled if set to -1.
|
|
(Default: 10)
|
|
.It Sy tix_ Ns Ar $port
|
|
A copy of the binary package is stored in
|
|
.Pa /repository
|
|
in the live environment if this variable is set to
|
|
.Sy true
|
|
and not if set to
|
|
.Sy false .
|
|
(Default:
|
|
.Sy true )
|
|
.It Sy version
|
|
The version number of this release.
|
|
.El
|
|
.Ss Functions
|
|
In addition to the standard GRUB functions, the following functions are set in
|
|
.Pa /boot/grub/grub.cfg :
|
|
.Bl -tag -width "12345678"
|
|
.It Sy load_base
|
|
This function loads the base system into the live environment by taking the
|
|
following actions:
|
|
.Pp
|
|
If this is x86_64 system, check using
|
|
.Li cpuid -l
|
|
whether the processor supports 64-bit mode and error if not.
|
|
.Pp
|
|
Run the
|
|
.Sy hook_kernel_pre
|
|
hook.
|
|
.Pp
|
|
Load
|
|
.Pa /boot/sortix.bin.xz
|
|
as a multiboot kernel,
|
|
with a
|
|
.Xr kernel 7
|
|
command line consisting of
|
|
.Sy $no_random_seed
|
|
.Sy $enable_network_drivers
|
|
followed by the arguments to this function (which should contain
|
|
.Li "-- /sbin/init --target=desired-target" )
|
|
followed by any additional options to
|
|
.Xr init 8 .
|
|
.Pp
|
|
Run the
|
|
.Sy hook_kernel_post
|
|
hook.
|
|
.Pp
|
|
If
|
|
.Sy no_random_seed
|
|
is not set to
|
|
.Sy --no-random-seed ,
|
|
load
|
|
.Pa /boot/random.seed
|
|
as a multiboot module with the
|
|
.Li --random-seed
|
|
command line.
|
|
.Pp
|
|
Load
|
|
.Pa /boot/system.initrd.xz ,
|
|
.Pa /boot/src.initrd.xz
|
|
(if
|
|
.Sy $enable_src ) ,
|
|
.Pa /boot/live.initrd.xz ,
|
|
and
|
|
.Pa /boot/overlay.initrd.xz
|
|
(only if a
|
|
.Pa sysroot-overlay
|
|
directory existed when making the release .iso)
|
|
as multiboot modules without any command line.
|
|
.Pp
|
|
Run the
|
|
.Sy hook_initrd_post
|
|
hook.
|
|
.It Sy load_ports
|
|
Load the ports and binary packages into the live environment by taking the
|
|
following actions:
|
|
.Pp
|
|
Run the
|
|
.Sy hook_ports_pre
|
|
hook.
|
|
.Pp
|
|
For each port, if
|
|
.Sy tix_ Ns Ar $port
|
|
is
|
|
.Sy true ,
|
|
then load the port as a binary package by running:
|
|
.Bd -literal
|
|
module --nounzip /repository/$port.tix.tar.xz \\
|
|
--to /repository/$port.tix.tar.xz
|
|
.Ed
|
|
And if
|
|
.Sy port_ Ns Ar $port
|
|
is
|
|
.Sy true ,
|
|
then install the port into the live environment by running:
|
|
.Bd -literal
|
|
module /repository/$port.tix.tar.xz --tix
|
|
.Ed
|
|
.Pp
|
|
Run the
|
|
.Sy hook_ports_post
|
|
hook.
|
|
.It Sy load_sortix
|
|
Load the base system and ports into the live environment by running
|
|
.Sy load_base
|
|
with the given arguments and then run
|
|
.Sy load_ports .
|
|
.It Sy select_ports_set_ Ns Ar $set
|
|
Install only the ports that belong to the ports set
|
|
.Ar set .
|
|
Run the
|
|
.Sy hook_port_set Ns Ar $set
|
|
hook afterwards.
|
|
.It Sy select_tix_set_ Ns Ar $set
|
|
Load only the binary packages that belong to the ports set
|
|
.Ar set .
|
|
Run the
|
|
.Sy hook_tix_set Ns Ar $set
|
|
hook afterwards.
|
|
.El
|
|
.Ss Hooks
|
|
The following hooks are run by the GRUB bootloader configuration:
|
|
.Bl -tag -width "12345678"
|
|
.It Sy hook_advanced_menu_post
|
|
After the advanced menu entries have been emitted.
|
|
.It Sy hook_advanced_menu_pre
|
|
Before the advanced menu entries are emitted.
|
|
.It Sy hook_initrd_post
|
|
After the initrd is loaded.
|
|
.It Sy hook_kernel_post
|
|
After the kernel has been loaded.
|
|
.It Sy hook_kernel_pre
|
|
Before the kernel is loaded and before the initrd is loaded.
|
|
.It Sy hook_menu_post
|
|
After the main menu entries have been emitted.
|
|
.It Sy hook_menu_pre
|
|
Before the main menu entries are emitted.
|
|
.It Sy hook_ports_menu
|
|
After the port sets menu entries have been emitted and before the individual
|
|
port menu entires are emitted as a way to define additional ports to be loaded
|
|
or not.
|
|
.It Sy hook_ports_menu_post
|
|
After the ports selection menu entries have been emitted.
|
|
.It Sy hook_ports_menu_pre
|
|
Before the ports selection menu entries are emitted.
|
|
.It Sy hook_ports_menu_sets
|
|
After the "Load all ports" menu entry has been emitted as a place to define
|
|
additional sets to be loaded.
|
|
.It Sy hook_ports_post
|
|
After the ports and binary packages have been loaded.
|
|
.It Sy hook_ports_pre
|
|
Before the ports and binary packages are loaded.
|
|
.It Sy hook_ports_set_ Ns Ar $set
|
|
After the menu entry has been picked that chooses the given
|
|
.Ar set
|
|
of ports and the port variables have been updated.
|
|
.It Sy hook_tix_menu
|
|
After the binary packages sets menu entries have been emitted and before the
|
|
individual binary packages menu entires are emitted as a way to define
|
|
additional binary packages to be loaded or not.
|
|
.It Sy hook_tix_menu_post
|
|
After the binary packages selection menu entries have been emitted.
|
|
.It Sy hook_tix_menu_pre
|
|
Before the binary packages selection menu entries are emitted.
|
|
.It Sy hook_tix_menu_sets
|
|
After the "Load all binary packages" menu entry has been emitted as a place to
|
|
define additional sets to be loaded.
|
|
.It Sy hook_tix_set_ Ns Ar $set
|
|
After the menu entry has been picked that chooses the given
|
|
.Ar set
|
|
of binary packages and the binary packages variables have been updated.
|
|
.El
|
|
.Pp
|
|
For more information on the GRUB configuration file format and the available
|
|
commands, see the GRUB manual.
|
|
.Sh EXAMPLES
|
|
Adding the port
|
|
.Sy foo
|
|
to the
|
|
.Sy basic
|
|
and
|
|
.Sy all
|
|
port sets can be done with this
|
|
.Pa /boot/grub/hooks.cfg :
|
|
.Bd -literal
|
|
port_foo=true
|
|
tix_foo=false
|
|
export port_foo
|
|
export tix_foo
|
|
function hook_ports_menu {
|
|
if $port_foo; then
|
|
menuentry "foo = true" {
|
|
port_foo=false
|
|
configfile /boot/grub/ports.cfg
|
|
}
|
|
else
|
|
menuentry "foo = false" {
|
|
port_foo=true
|
|
configfile /boot/grub/ports.cfg
|
|
}
|
|
fi
|
|
}
|
|
function hook_tix_menu {
|
|
if $tix_foo; then
|
|
menuentry "foo = true" {
|
|
tix_foo=false
|
|
configfile /boot/grub/tix.cfg
|
|
}
|
|
else
|
|
menuentry "foo = false" {
|
|
tix_foo=true
|
|
configfile /boot/grub/tix.cfg
|
|
}
|
|
fi
|
|
}
|
|
function hook_ports_set_all {
|
|
port_foo=true
|
|
}
|
|
function hook_tix_set_all {
|
|
tix_foo=true
|
|
}
|
|
function hook_ports_set_basic {
|
|
port_foo=true
|
|
}
|
|
function hook_tix_set_basic {
|
|
tix_foo=true
|
|
}
|
|
function hook_ports_set_minimal {
|
|
port_foo=false
|
|
}
|
|
function hook_tix_set_minimal {
|
|
tix_foo=false
|
|
}
|
|
function hook_ports_set_no {
|
|
port_foo=false
|
|
}
|
|
function hook_tix_set_no {
|
|
tix_foo=false
|
|
}
|
|
function hook_ports_pre {
|
|
if $tix_foo; then
|
|
echo -n "Loading /repository/foo.tix.tar.xz (3.0M) ... "
|
|
module --nounzip /repository/foo.tix.tar.xz \\
|
|
--to /repository/foo.tix.tar.xz
|
|
echo done
|
|
fi
|
|
if $port_foo; then
|
|
echo -n "Loading /repository/foo.tix.tar.xz (3.0M) ... "
|
|
module /repository/foo.tix.tar.xz --tix
|
|
echo done
|
|
fi
|
|
}
|
|
.Ed
|
|
.Pp
|
|
The
|
|
.Xr tix-iso-bootconfig 8
|
|
convenience script makes it easy to generate bootloader configuration for
|
|
common scenarios.
|
|
.Pp
|
|
See
|
|
.Xr release-iso-modification 7
|
|
for additional examples.
|
|
.Sh SEE ALSO
|
|
.Xr release-iso-bootconfig 7 ,
|
|
.Xr tix-iso-bootconfig 8
|