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:

Configuration Files

The bootloader configuration consists of these GRUB configuration files that you can use or overwrite as desired:

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")
console: Optionally contains --console and --term options to forward to the kernel(7).
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)
kernel_options: Optionally contains additional options for the kernel(7).
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)
serial_console: When the serial console is enabled in the advanced menu, this variable contains the --console and --term options to forward to the kernel(7).
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:

Hooks

The following hooks are run by the GRUB bootloader configuration:

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.