Sortix
current nightly

Sortix cross-volatile manual

This manual documents Sortix cross-volatile. You can instead view this document in the latest official manual.

NAME

release-iso-modification — instructions on how to modify release .iso filesystems

DESCRIPTION

This document describes how to modify Sortix .iso releases to meet your custom needs. The bootloader configuration in .iso releases is designed with an extensible hooks system that let's you override it with further configuration and to load additional files of your choice into the live environment. The live environment is configurable through the normal operating system configuration as described in section 5 of the manual.
The release modification procedure lets you customize aspects such as the default bootloader menu option and timeout, the default hostname, the default keyboard layout, the default graphics resolution, adding files of your choice to the live environment, control which drivers are loaded by default, control which live environment daemons are started by default, deploy ssh keys so secure shell connections are trusted on the first connection, configure automatic installation and upgrading, and so on.

Prerequisites

  • A sortix-x.y-arch.iso release for your architecture.
  • xorriso(1) needs to be installed.

Overview

The release modification process has three stages:
  • Optionally, creating additional files that will be loaded onto the live environment (the liveconfig).
  • Creating additional bootloader configuration (the bootconfig), which will contain an archived copy of the liveconfig (if any).
  • Adding the bootconfig to the release .iso.
The bootloader menu Install and Upgrade selections will start the live environment and run the sysinstall(8) installer and sysupgrade(8) upgrader respectively and they are thus also customizable by this procedure.

Convenience Scripts

The release modification can be done manually by hand, or you can use the following convenience scripts that make the release modification easy:
  • tix-iso-liveconfig(8) that generates additional configuration files for the live environment.
  • tix-iso-bootconfig(8) that generates additional bootloader configuration and optionally configures the bootloader to load the liveconfig into the live environment.
  • tix-iso-add(8) that adds the bootconfig (and thus the liveconfig if any) to the release .iso.
These convenience scripts come with the operating system and are installed in the /sbin directory. These scripts are entirely for convenience and you can perform their tasks yourself if they don't meet your needs. The scripts are readable shell scripts and you can learn how they work and extend them with your own features.
If you are not on a Sortix system or on a different version of Sortix than the one you are customizing, you can download the shell scripts matching the latest stable release:
If you are not customizing the latest stable release, you can find the matching versions of the scripts in the scripts/ subdirectory of the appropriate release directory, or you can check out the tix directory in the source code from https://sortix.org/source/ matching the release you are currently customizing.

Additional Live Configuration Configuration

The live environment is a normal instance of the operating system and can be configured by adding additional files or overwriting existing files. Section 5 of the manual documents the system and software configuration files. Additional files can also be added for their own sake.
To do so, create a directory that will contain this additional live environment configuration (liveconfig), whose contents will be extracted on top of the live environment's root filesystem. A compressed archive of this directory will be made in the next subsection and needs to be registered with the bootloader configuration.
The tix-iso-liveconfig(8) convenience script is useful as it offers a lot of commonly useful customizations to the live environment and can populate an initial liveconfig directory for you.

Additional Bootloader Configuration

The GRUB bootloader configuration of an release .iso is extensible and allows additional configuration to hook into it by writing a /boot/grub/hooks.cfg configuration file as described in release-iso-bootconfig(7).
To do so, create a directory that will contain this additional bootloader configuration (bootconfig), whose contents will be added onto the release .iso. The liveconfig (if any) is normally added to the bootconfig as a compressed archive and the additional bootloader configuration loads it as an initrd onto the live environment. The bootconfig will be overlaid to the release .iso in the next subsection.
The tix-iso-bootconfig(8) convenience script makes it easy to generate common additional bootloader configuration and its documentation has examples of what it can do. It is commonly used with the --liveconfig option to generate the bootloader configuration that loads the additional files from the liveconfig into the live environment.

Adding Files To The Release

Releases are modified by adding the bootconfig (which contains a compressed copy of the liveconfig, if any) files to the release .iso.
The tix-iso-add(8) convenience script makes it easy to add files to a release .iso while taking care to keep the release .iso bootable after the modification. You need xorriso(1) installed to use this script. Alternatively you can add the files to the release .iso by running xorriso(1) yourself:
xorriso \ 
  -indev "$input_file" \ 
  -outdev "$output_file" \ 
  -boot_image grub keep \ 
  -pathspecs on \ 
  -add \ 
  ="$input_directory"
Your modified release can then be used in place of the original release. See the EXAMPLES section below for inspiration on what customizations to make, as well as the manual pages for the tix-iso-liveconfig(8) and tix-iso-bootconfig(8) convenience scripts.

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

Add Files to the Live Environment

To customize a release with additional files and directories in the live environment:
mkdir -p liveconfig 
mkdir -p liveconfig/root 
echo foo > liveconfig/root/foofile 
echo bar > liveconfig/root/barfile 
tix-iso-bootconfig --liveconfig=liveconfig bootconfig 
tix-iso-add sortix.iso bootconfig

Provide Random Seed

To customize a release with a random seed (/boot/random.seed) (which must be kept confidential and not reused, see the warnings in tix-iso-bootconfig(8)):
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.

Hostname, Keyboard Layout, and Graphics Resolution

To customize the live environment of a release with a custom hostname, custom keyboard layout, and custom graphics resolution:
tix-iso-liveconfig \ 
  --hostname=dragon \ 
  --kblayout=dk \ 
  --videomode=1920x1080x32 \ 
  liveconfig 
tix-iso-bootconfig --liveconfig=liveconfig bootconfig 
tix-iso-add sortix.iso bootconfig

Load Only Basic Ports by Default

To customize a release to only loads basic ports by default:
mkdir -p bootconfig/boot/grub 
cat > bootconfig/boot/grub/hooks.cfg << EOF 
select_ports_set_basic 
EOF 
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

Locked Down Multi-User Live Environment

To customize a release so the live environment boots to the login screen by default with the provided database of users and groups (passwd(5) and group(5)), password protect the bootloader so only the default live environment option can be chosen by unauthenticated users:
mkdir -p liveconfig/etc 
# Each user's password is their username hashed with crypt_newhash(3). 
(printf 'root:%s:0:0:root:/root:sh\n' \ 
        '$2b$10$S/fJmYIJSkRdifk61xDYn.w62y.vNu35tZkznR6xa3Ntg0hsbI8tO' && 
 printf 'alice:%s:1000:1000:alice:/home/alice:sh\n' \ 
        '$2b$10$4xGAf5FyCYedWoNltWvbmOOreXcI5cH/f4Jz/pkWrWxwZ7TQ/WbRC' && 
 printf 'bob:%s:1001:1001:bob:/home/bob:sh\n' \ 
        '$2b$10$0.IukhbHNy63te6ozVJ7Pu/EvbCcr892981XbqRQ0w16UPhmDdUqa') | 
cat > liveconfig/etc/passwd 
cat > liveconfig/etc/group << EOF 
root::0:root 
alice::1000:alice 
bob::1001:bob 
EOF 
mkdir -p liveconfig/home 
mkdir -p -m 700 liveconfig/home/alice 
mkdir -p -m 700 liveconfig/home/bob 
grub-mkpasswd-pbkdf2 | # enter bootloader password 
tee /dev/tty | 
tail -n 1 | 
sed 's/PBKDF2 hash of your password is //' > liveconfig/etc/grubpw 
tix-iso-bootconfig --liveconfig=liveconfig bootconfig 
(echo 'insmod password_pbkdf2' 
 echo 'set superusers="root"' 
 echo "password_pbkdf2 root $(cat liveconfig/etc/grubpw)") | 
cat >> bootconfig/boot/grub/hooks.cfg 
cat > bootconfig/boot/grub/main.cfg << \EOF 
menu_title="$base_menu_title" 
hook_menu_pre 
menuentry "Sortix $version" --unrestricted { 
  load_sortix -- /sbin/init --target=multi-user 
} 
hook_menu_post 
EOF 
tix-iso-add sortix.iso bootconfig

Add a new Port

To customize a release with a new port foo in the basic and all port sets and fully integrate it with the bootloader menus:
mkdir -p bootconfig/boot/grub 
cat > bootconfig/boot/grub/hooks.cfg << \EOF 
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 
    echo done 
  fi 
} 
EOF 
mkdir -p bootconfig/repository 
cp foo.tix.tar.xz bootconfig/repository/foo.tix.tar.xz 
tix-iso-add sortix.iso bootconfig

Add a new Ports Set

To customize a release with your own set of ports that are loaded by default and fully integrate it with the bootloader menus:
mkdir -p bootconfig/boot/grub 
cat > bootconfig/boot/grub/hooks.cfg << \EOF 
function hook_ports_menu_sets { 
  menuentry "Load only recommended ports" { 
    select_ports_set_recommended 
    configfile /boot/grub/ports.cfg 
  } 
} 
function hook_tix_menu_sets { 
  menuentry "Load only basic binary packages" { 
    select_tix_set_recommended 
    configfile /boot/grub/tix.cfg 
  } 
} 
select_ports_set_recommended { 
  # The basic set can be extended by calling select_ports_set_basic here. 
  port_foo=false 
  port_bar=true 
} 
select_tix_set_recommended { 
  # The basic set can be extended by calling select_tix_set_basic here. 
  tix_foo=false 
  tix_bar=true 
} 
# Load the recommended set of ports by default. 
hook_ports_menu_sets 
EOF 
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

SSH Into Live Environment

To customize the live environment of a release so you can ssh into its root user, to have the hostname example.com, to start a ssh server with the keys generated now, authorize the local user to ssh into the live environment's root user, and register the sshd server's keys by their hostnames and network addresses so the connection is trusted on the first attempt (you can omit the network addresses if you don't know yet):
tix-iso-liveconfig \ 
  --hostname=example.com \ 
  --root-ssh-authorized-keys="$HOME/.ssh/id_rsa.pub" \ 
  --sshd-keygen \ 
  --sshd-key-known-hosts-file="$HOME/.ssh/known_hosts" \ 
  --sshd-key-known-hosts-hosts="example.com example.com,192.0.2.1 192.0.2.1" \ 
  liveconfig 
tix-iso-bootconfig --liveconfig=liveconfig --enable-sshd bootconfig 
tix-iso-add sortix.iso bootconfig 
rm -f liveconfig/etc/ssh_host_*_key # When no longer useful. 
rm -f bootconfig/boot/liveconfig.xz # When no longer useful. 
rm -f sortix.iso # When no longer useful. 
# And erase any media made from sortix.iso when no longer useful. 
ssh root@example.org # When the system is running.
This example generates sshd private keys (remember to delete them when no longer needed, see the warnings in tix-iso-liveconfig(8)) and shows them by running:
mkdir -p liveconfig/etc 
for keytype in rsa ecdsa ed25519; do 
  ssh-keygen -t $keytype -f liveconfig/etc/ssh_host_${keytype}_key" -N "" \ 
             -C "root@$hostname" 
done 
for keytype in rsa ecdsa ed25519; do 
  ssh-keygen -l -f liveconfig/etc/ssh_host_${keytype}_key 
done
It then constructs a known_hosts file for each network address and hashes it.
(for host in $network_addresses; do 
  for keytype in rsa ecdsa ed25519; do 
    printf '%s ' "$host" && 
    sed -E 's/^([^ ]* [^ ]*).*/\1/' \ 
      liveconfig/etc/ssh_host_${keytype}_key.pub 
  done 
done) > known_hosts 
ssh-keygen -H -f known_hosts 
rm -f known_hosts.old
ssh(1) will trust the server by the network addresses on the first connection if you append the contents of known_hosts to your ~/.ssh/known_hosts. liveconfig/root/.ssh/authorized_keys file is made by appending the appropriate public keys previously made with ssh-keygen(1).

SSH Back From Live Environment

To customize the live environment of a release so its root user can ssh back to your user, where the local hostname is example.com (the address to which the new installation will be connecting), by generating a private key for the root user (remember to delete it when no longer needed, see the warnings in tix-iso-liveconfig(8)) and adding its public key to your local ~/.ssh/authorized_keys:
tix-iso-liveconfig --root-ssh-keygen liveconfig 
ssh-keyscan -H example.com > liveconfig/root/.ssh/known_hosts 
cat liveconfig/root/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys 
tix-iso-bootconfig --liveconfig=liveconfig --enable-sshd bootconfig 
tix-iso-add sortix.iso bootconfig 
rm -f output-directory/root/.ssh/id_rsa # When no longer useful. 
rm -f bootconfig/boot/liveconfig.xz # When no longer useful. 
rm -f sortix.iso # When no longer useful. 
# And erase any media made from sortix.iso when no longer useful.
This example will generate a ssh key for the root user by running:
mkdir -p -m 700 liveconfig/root/.ssh 
ssh-keygen -t rsa -f liveconfig/root/.ssh/id_rsa -N "" -C "root@$hostname"
Consider omitting the -N option and password protect the private key to protect it in the case of a leak.

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

Automatic Installation

To customize a release so it automatically installs itself per the autoinstall.conf(5):
tix-iso-liveconfig --autoinstall=autoinstall.conf liveconfig 
tix-iso-bootconfig --liveconfig=liveconfig --default=1 bootconfig 
tix-iso-add sortix.iso bootconfig

Automatic Upgrade

To customize a release so it automatically upgrades a local installation per the autoupgrade.conf(5):
tix-iso-liveconfig --autoinstall=autoupgrade.conf liveconfig 
tix-iso-bootconfig --liveconfig=liveconfig --default=2 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 columns 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), development(7), installation(7), release-iso-bootconfig(7), upgrade(7), user-guide(7), tix-iso-add(8), tix-iso-bootconfig(8), tix-iso-liveconfig(8)
Copyright 2011-2025 Jonas 'Sortie' Termansen and contributors.
Sortix's source code is free software under the ISC license. 		#sortix on irc.sortix.org
@sortix_org