current nightly

Sortix nightly manual

This manual documents Sortix nightly, a development build that has not been officially released. You can instead view this document in the latest official manual.

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

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

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