301 lines
9.9 KiB
Groff
301 lines
9.9 KiB
Groff
.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 \-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 \-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
|
|
.Sh SEE ALSO
|
|
.Xr ssh-keygen 1 ,
|
|
.Xr xorriso 1 ,
|
|
.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
|