TIX-ISO-BOOTCONFIG(8)

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

SYNOPSIS
tix-iso-bootconfig [--append-title=text] [--console=terminal] [--default=default-boot-menu-option] [--disable-append-title] [--disable-dhclient] [--disable-gui] [--disable-network-drivers] [--disable-ntpd] [--disable-src] [--disable-sshd] [--enable-append-title] [--enable-dhclient] [--enable-gui] [--enable-network-drivers] [--enable-ntpd] [--enable-src] [--enable-sshd] [--grub-serial=terminal] [--kernel-options=options] [--init-target=target] [--liveconfig=liveconfig-directory] [--random-seed] [--serial=terminal] [--serial-console=terminal] [--timeout=boot-menu-timeout] output-directory

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 whereever 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 modifiying 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 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.

  No Change
To customize a release with no customizations except for the bootloader to say the release was modified by the current user on the current host:

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

  Provide Random Seed
To customize a release with a random seed (which must be kept confidential and not reused, see the above warnings):

    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.

  Add Files to the Live Environment
To customize a release with additional configuration for the live environment (a directory that is overlaid onto the live environment) made either manually or with tix-iso-liveconfig(8):

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

  Default Bootloader Menu Option and Timeout
To customize a release so the default bootloader menu option is to run the installer (bootloader menu option 1, counting from 0) and to change the bootloader menu timeout to 2 seconds:

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

  Non-interactive Live Environment
The interactive user environment can be disabled by setting the default init(8) --target to no-user:

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

  Add to Bootloader Menu Title
To customize a release so the bootloader menu title is appended with a message of your choice:

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

  Disable Networking Drivers By Default
To customize a release so it doesn't load network drivers by default, useful for security reasons or to work around driver issues:

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

  Disable DHCP Auto-Configuration By Default
To customize a release so dhclient(8) doesn't automatically configure network interfaces using DHCP, useful if one wants to manually configure network interfaces with ifconfig(8).

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

  Enable SSH Server By Default
To customize a release so it starts the SSH server sshd(8) automatically using the SSH configuration found in the liveconfig directory:

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

  Boot to Console Instead of GUI By Default
To customize a release so it boots to a console instead of the GUI:

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

  Boot to Serial Console using Qemu
To boot to a serial terminal with a custom serial settings and a custom terminal window size of 118 colums by 256 rows and a specific TERM variable inside the qemu virtual machine:

    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-iso-add(8), tix-iso-liveconfig(8)