.Dd February 4, 2018
.Dt TIX-ISO-LIVECONFIG 8
.Os
.Sh NAME
.Nm tix-iso-liveconfig
.Nd generate additional live environment configuration for Sortix .iso releases
.Sh SYNOPSIS
.Nm
.Op Fl \-autoinstall Ns = Ns Ar file
.Op Fl \-autoupgrade Ns = Ns Ar file
.Op Fl \-daemons Ns = Ns Ar daemons
.Op Fl \-hostname Ns = Ns Ar hostname
.Op Fl \-kblayout Ns = Ns Ar kblayout
.Op Fl \-root-ssh-authorized-keys Ns = Ns Ar file
.Op Fl \-root-ssh-config Ns = Ns Ar file
.Op Fl \-root-ssh-keygen
.Op Fl \-root-ssh-known-hosts Ns = Ns Ar file
.Op Fl \-ssh-config Ns = Ns Ar file
.Op Fl \-sshd-config Ns = Ns Ar file
.Op Fl \-sshd-keygen
.Op Fl \-sshd-key-known-hosts-file Ns = Ns Ar file
.Op Fl \-sshd-key-known-hosts-hosts Ns = Ns Ar host-list
.Op Fl \-videomode Ns = Ns Ar videomode
.Ar output-directory
.Sh DESCRIPTION
.Nm
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
.Xr tix-iso-bootconfig 8
to add an initrd of it in the additional bootloader configuration, and then
using
.Xr tix-iso-add 8
to add the additional bootloader configuration to the release .iso.
.Pp
.Nm
creates the
.Ar 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
.Ar output-directory
directory.
.Pp
This script is designed to be convenient when modifying a Sortix release .iso as
part of the
.Xr 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.
.Pp
The options are as follows:
.Bl -tag -width "12345678"
.It Fl \-autoinstall Ns = Ns Ar file
Copy
.Ar file
to
.Pa output-directory/etc/autoinstall.conf .
(See
.Xr autoinstall.conf 5 )
.It Fl \-autoupgrade Ns = Ns Ar file
Copy
.Ar file
to
.Pa output-directory/etc/autoupgrade.conf .
(See
.Xr autoupgrade.conf 5 )
.It Fl \-daemons Ns = Ns Ar daemons
Configures the
.Sy local
daemon to optionally depend on each of the
.Ar daemons
in
.Pa output-directory/etc/init/local .
(See
.Xr init 5 )
.It Fl \-hostname Ns = Ns Ar hostname
Set the live environment's hostname by writing
.Ar hostname
to
.Pa output-directory/etc/hostname .
(See
.Xr hostname 5 )
.It Fl \-kblayout Ns = Ns Ar kblayout
Set the live environment's keyboard layout by writing
.Ar kblayout
to
.Pa output-directory/etc/kblayout .
(See
.Xr kblayout 5 )
.It Fl \-root-ssh-authorized-keys Ns = Ns Ar file
Copy
.Ar file
to
.Pa output-directory/root/.ssh/authorized_keys
so it becomes root's list of authorized ssh keys.
.It Fl \-root-ssh-config Ns = Ns Ar file
Copy
.Ar file
to
.Pa output-directory/root/.ssh/config
so it becomes root's
.Xr ssh_config 5 .
.It Fl \-root-ssh-keygen
Generate a ssh private and public key pair for rsa (see the warnings below) at
.Pa output-directory/root/.ssh/id_rsa
and
.Pa output-directory/root/.ssh/id_rsa.pub .
These keys are not regenerated if they already exist.
The comment in the key uses the
.Fl \-hostname
option if set, otherwise it defaults to
.Sy sortix .
The key is not password protected.
.Pp
The key is generated by running:
.Bd -literal
ssh-keygen \\
  -t rsa \\
  -f "$output_directory/root/.ssh/id_rsa" \\
  -N "" \\
  -C "root@$hostname"
.Ed
.Pp
Warning: The information in the generated
.Pa 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
.Ar output-directory
is no longer useful, the
.Pa 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,
.Pa bootconfig/boot/liveconfig.xz
should be securely erased when no longer useful.
If a release .iso has been made from
.Ar 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.
.It Fl \-root-ssh-known-hosts Ns = Ns Ar file
Copy
.Ar file
to
.Pa output-directory/root/.ssh/known_hosts
so it becomes root's list of known ssh hosts and their public keys.
.It Fl \-ssh-config Ns = Ns Ar file
Copy
.Ar file
to
.Pa output-directory/etc/ssh_config
so it becomes the
.Xr ssh_config 5
of the live environment.
.It Fl \-sshd-config Ns = Ns Ar file
Copy
.Ar file
to
.Pa output-directory/etc/sshd_config
so it becomes the
.Xr sshd_config 5
of the live environment.
.It Fl \-sshd-keygen
Generate sshd private keys for rsa, ecdsa, and ed25519 (see the below
warnings), but don't overwrite any existing keys in the
.Ar output-directory
directory.
The comment in the key uses the
.Fl \-hostname
option if set, otherwise it defaults to
.Sy sortix .
Each key is generated by running:
.Bd -literal
ssh-keygen \\
  -t $keytype \\
  -f "$output_directory/etc/ssh_host_${keytype}_key" \\
  -N "" \\
  -C "root@$hostname"
.Ed
.Pp
The fingerprints of each key is printed afterwards by running:
.Bd -literal
.Li ssh-keygen -l -f "$output_directory/etc/ssh_host_${keytype}_key"
.Ed
.Pp
Warning: The information in the generated
.Pa 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
.Ar output-directory
is no longer useful, the
.Pa output_directory/etc/ssh_host_*_key
files inside it should be securely erased.
If a bootconfig has been made whose liveconfig contains these keys,
.Pa bootconfig/boot/liveconfig.xz
should be securely erased when no longer useful.
If a release .iso has been made from
.Ar 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.
.It Fl \-sshd-key-known-hosts-file Ns = Ns Ar file
Append the ssh known_hosts entries to
.Ar file
for the
.Pa output_directory/etc/ssh_host_*_key.pub
.Xr sshd 8
keys for each hostname provided in the
.Fl \-sshd-key-known-hosts-hosts
option.
For each hostname, for each public key, a line is written to the
.Ar 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
.Xr ssh-keygen 1
with the
.Fl H
option on the produced file.
.It Fl \-sshd-key-known-hosts-hosts Ns = Ns Ar 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
.Fl \-sshd-key-known-hosts-file
option.
.It Fl \-videomode Ns = Ns Ar videomode
Set the live environment's graphics resolution by writing
.Ar videomode
to
.Pa output-directory/etc/videomode .
(See
.Xr videomode 5 )
.El
.Sh EXIT STATUS
.Nm
will exit 0 on success and non-zero otherwise.
.Sh EXAMPLES
This section contains examples of how one can modify a release .iso.
.Ss 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:
.Bd -literal
tix-iso-liveconfig \\
  --hostname=dragon \\
  --kblayout=dk \\
  --videomode=1920x1080x32 \\
  liveconfig
tix-iso-bootconfig --liveconfig=liveconfig bootconfig
tix-iso-add sortix.iso bootconfig
.Ed
.Ss SSH Into Live Environment
To customize the live environment of a release so you can ssh into its root
user, to have the hostname
.Sy 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):
.Bd -literal
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.
.Ed
.Ss 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
.Sy example.com
(the address to which the new installation will be connecting):
.Bd -literal
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.
.Ed
.Ss Automatic Installation
To customize a release so it automatically installs itself according to
.Pa autoinstall.conf
(see
.Xr autoinstall.conf 5 ) :
.Bd -literal
tix-iso-liveconfig --autoinstall=autoinstall.conf liveconfig
tix-iso-bootconfig --liveconfig=liveconfig --default=1 bootconfig
tix-iso-add sortix.iso bootconfig
.Ed
.Ss Automatic Upgrade
To customize a release so it automatically upgrades a local installation
according to
.Pa autoupgrade.conf
(see
.Xr autoupgrade.conf 5 ) :
.Bd -literal
tix-iso-liveconfig --autoinstall=autoupgrade.conf liveconfig
tix-iso-bootconfig --liveconfig=liveconfig --default=2 bootconfig
tix-iso-add sortix.iso bootconfig
.Ed
.Sh SEE ALSO
.Xr ssh-keygen 1 ,
.Xr xorriso 1 ,
.Xr autoinstall.conf 5 ,
.Xr autoupgrade.conf 5 ,
.Xr hostname 5 ,
.Xr kblayout 5 ,
.Xr ssh_config 5 ,
.Xr sshd_config 5 ,
.Xr videomode 5 ,
.Xr release-iso-modification 7 ,
.Xr sshd 8 ,
.Xr tix-iso-add 8 ,
.Xr tix-iso-bootconfig 8