Sortix volatile manual

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

NAME

tix-iso-liveconfig — generate additional live environment configuration for Sortix .iso releases

SYNOPSIS

tix-iso-liveconfig

[--autoinstall=file] [--autoupgrade=file] [--daemons=daemons] [--hostname=hostname] [--kblayout=kblayout] [--root-ssh-authorized-keys=file] [--root-ssh-config=file] [--root-ssh-keygen] [--root-ssh-known-hosts=file] [--ssh-config=file] [--sshd-config=file] [--sshd-keygen] [--sshd-key-known-hosts-file=file] [--sshd-key-known-hosts-hosts=host-list] [--videomode=videomode] output-directory

DESCRIPTION

tix-iso-liveconfig generates additional live environment configuration for Sortix .iso releases that can be overlaid onto the live environment filesystem by making an archive of it and loading it as an initrd in the .iso bootloader configuration. An release .iso can be modified to contain this additional live environment configuration by using tix-iso-bootconfig(8) to add an initrd of it in the additional bootloader configuration, and then using tix-iso-add(8) to add the additional bootloader configuration to the release .iso.

tix-iso-liveconfig creates the output-directory directory if it doesn't already exist and populates it with the requested additional configuration for the live environment. By default, it doesn't make any directories or files inside the output-directory directory.

This script is designed to be convenient when modifying a Sortix release .iso as part of the release-iso-modification(7) procedure. 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:

--autoinstall=file

Copy file to output-directory/etc/autoinstall.conf. (See autoinstall.conf(5))

--autoupgrade=file

Copy file to output-directory/etc/autoupgrade.conf. (See autoupgrade.conf(5))

--daemons=daemons

Configures the local daemon to optionally depend on each of the daemons in output-directory/etc/init/local. (See init(5))

--hostname=hostname

Set the live environment's hostname by writing hostname to output-directory/etc/hostname. (See hostname(5))

--kblayout=kblayout

Set the live environment's keyboard layout by writing kblayout to output-directory/etc/kblayout. (See kblayout(5))

--root-ssh-authorized-keys=file

Copy file to output-directory/root/.ssh/authorized_keys so it becomes root's list of authorized ssh keys.

--root-ssh-config=file

Copy file to output-directory/root/.ssh/config so it becomes root's ssh_config(5).

--root-ssh-keygen

Generate a ssh private and public key pair for rsa (see the warnings below) at output-directory/root/.ssh/id_rsa and output-directory/root/.ssh/id_rsa.pub. These keys are not regenerated if they already exist. The comment in the key uses the --hostname option if set, otherwise it defaults to sortix. The key is not password protected.

The key is generated by running:

ssh-keygen \ 
  -t rsa \ 
  -f "$output_directory/root/.ssh/id_rsa" \ 
  -N "" \ 
  -C "root@$hostname"

Warning: The information in the generated output-directory/root/.ssh/id_rsa private key must be kept confidential and should be securely erased whereever it goes whenever it is no longer useful in a particular place, otherwise unauthorized may be able to impersonate this user. These keys should be reissued whenever a root user of a new installation should be considered distinct from other installations using the same keys. The installer will offer to copy the keys to the newly installed system. Once the output-directory is no longer useful, the output-directory/root/.ssh/id_rsa file inside it should be securely erased. If a bootconfig has been made whose liveconfig contains thes private key, bootconfig/boot/liveconfig.xz should be securely erased when no longer useful. 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.

--root-ssh-known-hosts=file

Copy file to output-directory/root/.ssh/known_hosts so it becomes root's list of known ssh hosts and their public keys.

--ssh-config=file

Copy file to output-directory/etc/ssh_config so it becomes the ssh_config(5) of the live environment.

--sshd-config=file

Copy file to output-directory/etc/sshd_config so it becomes the sshd_config(5) of the live environment.

--sshd-keygen

Generate sshd private keys for rsa, ecdsa, and ed25519 (see the below warnings), but don't overwrite any existing keys in the output-directory directory. The comment in the key uses the --hostname option if set, otherwise it defaults to sortix. Each key is generated by running:

ssh-keygen \ 
  -t $keytype \ 
  -f "$output_directory/etc/ssh_host_${keytype}_key" \ 
  -N "" \ 
  -C "root@$hostname"

The fingerprints of each key is printed afterwards by running:

ssh-keygen -l -f $output_directory/etc/ssh_host_${keytype}_key

Warning: The information in the generated output_directory/etc/ssh_host_*_key files must be kept confidential and should be securely erased whereever it goes whenever it is no longer useful in a particular place, otherwise unauthorized people may be able to impersonate the ssh server. These keys should not be recycled to image more than a single system. The installer will offer to copy the keys to the newly installed system. Once the output-directory is no longer useful, the output_directory/etc/ssh_host_*_key files inside it should be securely erased. If a bootconfig has been made whose liveconfig contains these keys, bootconfig/boot/liveconfig.xz should be securely erased when no longer useful. 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.

--sshd-key-known-hosts-file=file

Append the ssh known_hosts entries to file for the output_directory/etc/ssh_host_*_key.pub sshd(8) keys for each hostname provided in the --sshd-key-known-hosts-hosts option. For each hostname, for each public key, a line is written to the file consisting of the hostname followed by a space and then followed by the public key. The written entries are then hashed so an attacker can't discover the hosts from the known_hosts file, which is done by running ssh-keygen(1) with the -H option on the produced file.

--sshd-key-known-hosts-hosts=host-list

A space delimited list of hostnames, network addresses, and hostnames followed by a comma and then the network address, which the sshd server will be connectible by, used to generate the known_hosts entries in the --sshd-key-known-hosts-file option.

--videomode=videomode

Set the live environment's graphics resolution by writing videomode to output-directory/etc/videomode. (See videomode(5))

EXIT STATUS

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

EXAMPLES

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

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

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.

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):

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.

Automatic Installation

To customize a release so it automatically installs itself according to autoinstall.conf (see 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 according to autoupgrade.conf (see autoupgrade.conf(5)):

tix-iso-liveconfig --autoinstall=autoupgrade.conf liveconfig 
tix-iso-bootconfig --liveconfig=liveconfig --default=2 bootconfig 
tix-iso-add sortix.iso bootconfig