Sortix
current nightly

Sortix cross-volatile manual

This manual documents Sortix cross-volatile. You can instead view this document in the latest official manual.

NAME

release-iso-bootconfig — release .iso bootloader configuration

DESCRIPTION

You can customize the bootloader configuration of a release .iso by adding your own /boot/grub/hooks.cfg to the .iso filesystem as part of the release-iso-modification(7) procedure. This manual page details the programming interface available when writing this file.
Commonly a custom /boot/grub/hooks.cfg would take some actions when loaded (such as setting variables) and define hook functions as described in the Hooks subsection to inject behavior in certain locations, and otherwise make use of the facilities described in this manual page.

Ports and Binary Packages

The release .iso contains binary packages. The ports menu controls what binary packages are installed in the live environment.

Port Sets

The binary packages menu controls what binary packages have a copy stored in the /repository directory inside the live environment.
Sets of ports and binary packages are defined by build-aux/ports.conf in the source code:
all
All ports.
basic
Common software and everything needed to develop the operating system
minimal
Ports needed to successfully install and upgrade the operating system.
no
No ports.

Configuration Files

The bootloader configuration consists of these GRUB configuration files that you can use or overwrite as desired:
/boot/grub/grub.cfg
The GRUB bootloader will load its configuration by loading this file.
First, this file loads the default bootloader configuration by taking the following actions:
It defines no-operation versions of each of the hook functions defined below.
It loads the appropriate GRUB modules.
It initializes the global variable described below.
It defines functions to select each set of ports and binary package, as described below.
Secondly, it loads /boot/grub/hooks.cfg (if it exists) which can take any actions it wants and customize the default configuration.
Finally, it loads /boot/grub/main.cfg to display the menu menu.
/boot/grub/hooks.cfg
This file provides additional bootloader configuration if it exists.
This file is loaded (if it exists) by /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.
/boot/grub/main.cfg
This file displays the main bootloader menu by taking the following actions:
The menu_title variable is set to the contents of the base_menu_title variable.
The hook_menu_pre hook is run.
Menu entries are emitted for the live environment, the installer, and the upgrader.
The live environment menu entry runs: load_sortix -- /sbin/init --target=single-user
The installer menu entry runs: load_sortix -- /sbin/init --target=sysinstall
The upgrader menu entry runs: load_sortix -- /sbin/init --target=sysupgrade
Menu entries are emitted for the ports selection bootloader menu (which runs configfile /boot/grub/ports.cfg) and the advanced bootloader menu (which runs configfile /boot/grub/advanced.cfg)
Finally the hook_menu_post hook is run.
/boot/grub/advanced.cfg
This file displays the advanced bootloader menu by taking the following actions:
A menu entry is emitted that goes back to the main menu (which runs configfile /boot/grub/main.cfg)
The menu_title variable is set to the contents of the base_menu_title variable appended with " - Advanced Options".
The hook_advanced_menu_pre hook is run.
A menu entry is emitted to control whether network drivers are enabled.
A menu entry is emitted that goes to the binary packages menu (which runs configfile /boot/grub/tix.cfg)
Finally, the hook_advanced_menu_post hook is run.
/boot/grub/ports.cfg
This file displays the port selection bootloader menu by taking the following actions:
A menu entry is emitted that goes back to the main menu (which runs configfile /boot/grub/main.cfg)
The menu_title variable is set to the contents of the base_menu_title variable appended with " - Ports".
The hook_ports_menu_pre hook is run.
The following menu entries implicitly run configfile /boot/grub/ports.cfg afterwards to return to this menu.
A menu entry is emitted that loads all ports by running select_ports_set_all.
The hook_ports_menu_pre hook is run.
Menu entries are emitted for each of the port sets, each of which load only those ports set by running select_ports_set_$set.
A menu entry is emitted that loads no ports by running select_ports_set_no.
The hook_ports_menu hook is run.
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 port_$set variable to true or false.
Finally, the hook_ports_menu_post hook is run.
/boot/grub/tix.cfg
This file displays the binary packages selection bootloader menu by taking the following actions:
A menu entry is emitted that goes back to the advanced menu (which runs configfile /boot/grub/advanced.cfg)
The menu_title variable is set to the contents of the base_menu_title variable appended with " - Binary Packages".
The hook_tix_menu_pre hook is run.
The following menu entries implicitly run configfile /boot/grub/tix.cfg afterwards to return to this menu.
A menu entry is emitted that loads all binary packages by running select_tix_set_all.
The hook_tix_menu_pre hook is run.
Menu entries are emitted for each of the binary package sets, each of which load only those binary packages set by running select_tix_set_$set.
A menu entry is emitted that loads no binary packages by running select_tix_set_no.
The hook_tix_menu hook is run.
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 tix_$set variable to true or false.
Finally, the hook_tix_menu_post hook is run.

Variables

In addition to the standard GRUB variables, the following global variables are set in /boot/grub/grub.cfg:
base_menu_title
The base menu title which is used to construct the menu titles for each of the menus by setting the menu_title variable. The main menu uses this title verbatim, while the other menus will append " - menu_name" when constructing menu_title. (Default: "Sortix $version for $machine")
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 '>' and another selection to pick a default menu option in that submenu, and so on. (Default: 0)
enable_dhclient
Whether to start the dhclient(8) daemon. (Default: true)
enable_network_drivers
An additional kernel(7) command line parameter that controls whether network drivers are enabled. Either set to the empty string (network drivers are enabled) or --disable-network-drivers. (Default: The empty string).
enable_ntpd
Whether to start the ntpd(8) daemon. (Default: false)
enable_src
Whether to load the source code initrd containing /src. (Default: true)
enable_sshd
Whether to start the sshd(8) daemon. (Default: false)
machine
The machine type this release was built for.
menu_title
The menu title to display above the bootloader menu. (Default: "$base_menu_title")
no_random_seed
An additional command line parameter passed to the kernel(7) turning off the warning about lack of entropy if there is no random seed. This variable defaults to --no-random-seed if /boot/random.seed doesn't exist, otherwise it defaults to the empty string.
port_$port
The port is installed into live environment if this variable is set to true and not if set to false. (Default: true)
timeout
The time in seconds before the default menu entry (according to the 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)
title_single_user
The menu title for the single-user selection. (Default: live environment)
title_sysinstall
The menu title for the sysinstall selection. (Default: new installation)
title_sysupgrade
The menu title for the sysupgrade selection. (Default: upgrade existing installation)
tix_$port
A copy of the binary package is stored in /repository in the live environment if this variable is set to true and not if set to false. (Default: true)
version
The version number of this release.

Functions

In addition to the standard GRUB functions, the following functions are set in /boot/grub/grub.cfg:
load_base
This function loads the base system into the live environment by taking the following actions:
If this is x86_64 system, check using cpuid -l whether the processor supports 64-bit mode and error if not.
Run the hook_kernel_pre hook.
Load /boot/sortix.bin.xz as a multiboot kernel, with a kernel(7) command line consisting of $no_random_seed $enable_network_drivers followed by the arguments to this function (which should contain -- /sbin/init --target=desired-target) followed by any additional options to init(8).
Run the hook_kernel_post hook.
If no_random_seed is not set to --no-random-seed, load /boot/random.seed as a multiboot module with the --random-seed command line.
Load /boot/system.tar.xz, /boot/src.tar.xz (if $enable_src), /boot/live.tar.xz, and /boot/overlay.tar.xz (only if a sysroot-overlay directory existed when making the release .iso) as multiboot modules without any command line.
Run the hook_initrd_post hook.
load_ports
Load the ports and binary packages into the live environment by taking the following actions:
Run the hook_ports_pre hook.
For each port, if tix_$port is true, then load the port as a binary package by running:
    module --nounzip /repository/$port.tix.tar.xz \ 
           --to /repository/$port.tix.tar.xz
And if port_$port is true, then install the port into the live environment by running:
    module /repository/$port.tix.tar.xz
Run the hook_ports_post hook.
load_sortix
Load the base system and ports into the live environment by running load_base with the given arguments and then run load_ports.
select_ports_set_$set
Install only the ports that belong to the ports set set. Run the hook_port_set$set hook afterwards.
select_tix_set_$set
Load only the binary packages that belong to the ports set set. Run the hook_tix_set$set hook afterwards.

Hooks

The following hooks are run by the GRUB bootloader configuration:
hook_advanced_menu_post
After the advanced menu entries have been emitted.
hook_advanced_menu_pre
Before the advanced menu entries are emitted.
hook_initrd_post
After the initrd is loaded.
hook_kernel_post
After the kernel has been loaded.
hook_kernel_pre
Before the kernel is loaded and before the initrd is loaded.
hook_menu_post
After the main menu entries have been emitted.
hook_menu_pre
Before the main menu entries are emitted.
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.
hook_ports_menu_post
After the ports selection menu entries have been emitted.
hook_ports_menu_pre
Before the ports selection menu entries are emitted.
hook_ports_menu_sets
After the "Load all ports" menu entry has been emitted as a place to define additional sets to be loaded.
hook_ports_post
After the ports and binary packages have been loaded.
hook_ports_pre
Before the ports and binary packages are loaded.
hook_ports_set_$set
After the menu entry has been picked that chooses the given set of ports and the port variables have been updated.
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.
hook_tix_menu_post
After the binary packages selection menu entries have been emitted.
hook_tix_menu_pre
Before the binary packages selection menu entries are emitted.
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.
hook_tix_set_$set
After the menu entry has been picked that chooses the given set of binary packages and the binary packages variables have been updated.
For more information on the GRUB configuration file format and the available commands, see the GRUB manual.

EXAMPLES

Adding the port foo to the basic and all port sets can be done with this /boot/grub/hooks.cfg:
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 
}
The tix-iso-bootconfig(8) convenience script makes it easy to generate bootloader configuration for common scenarios.
See release-iso-modification(7) for additional examples.

SEE ALSO

release-iso-bootconfig(7), tix-iso-bootconfig(8)
Copyright 2011-2024 Jonas 'Sortie' Termansen and contributors.
Sortix is free software under the ISC license. 		#sortix on irc.sortix.org
@sortix_org