TIX-ISO-LIVECONFIG(8)

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

SYNOPSIS
tix-iso-liveconfig [--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:

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

SEE ALSO
ssh-keygen(1), xorriso(1), hostname(5), kblayout(5), ssh_config(5), sshd_config(5), videomode(5), release-iso-modification(7), sshd(8), tix-iso-add(8), tix-iso-bootconfig(8)