NAME

tix-iso-bootconfig — generate additional bootloader configuration for Sortix .iso releases

SYNOPSIS

DESCRIPTION

tix-iso-bootconfig 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 tix-iso-add(8).

tix-iso-bootconfig creates the 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 output-directory/boot/grub/hooks.cfg that appends " - modified by username@hostname" to the base_menu_title variable, which changes the boot menu title to say the .iso was modified by the current username on the local hostname.

This script is designed to be convenient when modifying a Sortix release .iso as part of the release-iso-modification(7) procedure. Additional bootloader configuration can be provided as described in 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.

The options are as follows:

--append-title=text

Append " - " followed by text to the bootloader menu title by appending to the base_menu_title GRUB variable. If this option is not set, the default value is " - modified by username@hostname", where username is the output of running id -un and hostname is the output of running hostname. The bootloader menu title is appended to by default, but can be disabled with --disable-append-title, and re-enabled with --enable-append-title, whichever comes last takes precedence.

--console=terminal

Forward the --console option to the kernel(7) to select the terminal to use as the console and the settings to initialize it.

The TERM variable can be overridden by suffixing the quoted argument with a space followed by --term=terminal.

--default=default-boot-menu-option

Select bootloader menu option number default-boot-menu-option by default (counting from 0). If the selected menu option itself is a submenu, default-boot-menu-option can be appended with a '>' and another selection to pick a default menu option in that submenu, and so on. This option sets the default GRUB variable.

--disable-append-title

Don't append anything to the bootloader menu title by appending to the base_menu_title GRUB variable.

--disable-dhclient

Disable automatic DHCP configuration by setting the enable_dhclient GRUB variable to false, causing the bootloader to load additional configuration that turns off the dhclient(8) daemon on boot.

--disable-gui

Disable the GUI by setting the enable_gui GRUB variable to false, which makes the bootloader configuration not append -gui to the requested init(8) target.

--disable-network-drivers

Disable network drivers by setting the enable_network_drivers GRUB variable to the --disable-network-drivers option which will be passed on the kernel(7) command line.

--disable-ntpd

Disable automatically starting the ntp client by setting the enable_ntpd GRUB variable to false, selecting the default behavior of not starting the ntpd(8) daemon.

--disable-src

Disable loading the source code in /src by setting enable_src GRUB variable to false.

--disable-sshd

Disable automatically starting the ssh server by setting the enable_sshd GRUB variable to false, selecting the default behavior of not starting the sshd(8) daemon.

--enable-append-title

Enable appending " - " followed by the value set with --append-title to the bootloader menu title by appending to the base_menu_title GRUB variable. This option is on by default and can be disabled with --disable-append-title.

--enable-dhclient

Enable automatic DHCP configuration by setting the enable_dhclient GRUB variable to true, selecting the default behavior of starting the dhclient(8) daemon.

--enable-gui

Enable the GUI by setting the enable_gui GRUB variable to true, which makes the bootloader configuration append -gui to the requested init(8) target.

--enable-network-drivers

Enable network drivers by setting the enable_network_drivers GRUB variable to the --enable-network-drivers option which will be passed on the kernel(7) command line.

--enable-ntpd

Enable automatically starting the ntp client by setting the enable_ntpd GRUB variable to true, causing the bootloader to load additional configuration that turns on the ntpd(8) daemon on boot.

--enable-src

Enable loading the source code in /src by setting enable_src GRUB variable to true.

--enable-sshd

Enable automatically starting the ssh server by setting the enable_sshd GRUB variable to true, causing the bootloader to load additional configuration that turns on the sshd(8) daemon on boot.

--grub-serial=terminal

Use the serial terminal for GRUB's menu in the format of the kernel(7) --console option.

--kernel-options=options

Forward these additional options to the the kernel(7).

--init-target=target

Add a new first menu entry that boots the target daemon as the init(8) target.

--liveconfig=liveconfig-directory

Overlay the liveconfig-directory directory onto the live environment, allowing full customization of the live environment. The tix-iso-liveconfig(8) script is convenient for making the liveconfig-directory directory. This option makes a tar(1) archive compressed with xz(1) of the liveconfig-directory directory and places it at output-directory/boot/liveconfig.tar.xz. Regardless of this option, if a output-directory/boot/liveconfig.tar.xz is found, the xzio GRUB module is loaded and an hook_initrd_post hook is emitted that loads output-directory/boot/liveconfig.tar.xz as a multiboot module.

If the liveconfig contains autoinstall.conf(5) or autoupgrade.conf(5), the menu titles are modified to loudly warn they will automatically install/upgrade the operating system.

--random-seed

Copy 256 bytes of randomness from /dev/urandom to 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.

Warning: The information in the generated output-directory/boot/random.seed file must be kept confidential and should be securely erased wherever 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 modifying 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 output-directory is no longer useful, the output-directory/boot/random.seed path inside it should be securely erased. If a release .iso has been made from 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.

--serial=terminal

Boot entirely using the serial terminal as specified in the format of the kernel(7) --console option. This option is a shorthand equivalent to setting the --console, --grub-console, --serial-console, and --disable-gui options.

--serial-console=terminal

Whenever the serial console is enabled in the advanced bootloader menu, forward this --console option to the kernel(7) to select the terminal 1 to use as the console and the settings to initialize it.

The TERM variable can be overridden by suffixing the quoted argument with a space followed by --term=terminal.

--timeout=boot-menu-timeout

Pick the default bootloader menu option after boot-menu-timeout seconds. If boot-menu-timeout is 0, pick the default menu option immediately. If boot-menu-timeout is -1, the timeout is disabled. This option sets the timeout GRUB variable.

EXIT STATUS

tix-iso-bootconfig will exit 0 on success and non-zero otherwise.

EXAMPLES

This section contains examples of how one can modify a release .iso.

tix-iso-bootconfig bootconfig
tix-iso-add sortix.iso bootconfig

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.

tix-iso-bootconfig --liveconfig=liveconfig bootconfig
tix-iso-add sortix.iso bootconfig

tix-iso-bootconfig --default=1 --timeout=2 bootconfig
tix-iso-add sortix.iso bootconfig

tix-iso-bootconfig --init-target=no-user bootconfig
tix-iso-add sortix.iso bootconfig

tix-iso-bootconfig --append-title="Initech Company Edition" bootconfig
tix-iso-add sortix.iso bootconfig

tix-iso-bootconfig --disable-network-drivers bootconfig
tix-iso-add sortix.iso bootconfig

tix-iso-bootconfig --disable-dhclient bootconfig
tix-iso-add sortix.iso bootconfig

tix-iso-bootconfig --liveconfig=liveconfig --enable-sshd bootconfig
tix-iso-add sortix.iso bootconfig

tix-iso-bootconfig --disable-gui bootconfig
tix-iso-add sortix.iso bootconfig

tix-iso-bootconfig --serial="com1,9600n8,118x56 --term=xterm-256color" bootconfig
tix-iso-add sortix.iso bootconfig
qemu-system-x86_64 -serial mon:stdio -cdrom sortix.iso

SEE ALSO

xorriso(1), kernel(7), release-iso-bootconfig(7), release-iso-modification(7), init(8), tix(8), tix-iso-add(8), tix-iso-liveconfig(8)