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
release-iso-modification — instructions on how to modify release .iso filesystemsDESCRIPTION
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.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.
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.
- https://sortix.org/release/stable/scripts/tix-iso-liveconfig
- https://sortix.org/release/stable/scripts/tix-iso-bootconfig
- https://sortix.org/release/stable/scripts/tix-iso-add
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.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).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.xorriso \ -indev "$input_file" \ -outdev "$output_file" \ -boot_image grub keep \ -pathspecs on \ -add \ ="$input_directory"
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 --tix 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.
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
(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 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.
mkdir -p -m 700 liveconfig/root/.ssh ssh-keygen -t rsa -f liveconfig/root/.ssh/id_rsa -N "" -C "root@$hostname"
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