RELEASE-ISO-BOOTCONFIG(7)

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 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_src
    Whether to load the source code initrd containing /src. (Default: true)

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)

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 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.initrd.xz, /boot/src.initrd.xz (if $enable_src), /boot/live.initrd.xz, and /boot/overlay.initrd.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 --tix

    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)