336 lines
10 KiB
Groff
336 lines
10 KiB
Groff
.Dd February 4, 2018
|
|
.Dt TIX-ISO-BOOTCONFIG 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm tix-iso-bootconfig
|
|
.Nd generate additional bootloader configuration for Sortix .iso releases
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl \-append-title Ns = Ns Ar text
|
|
.Op Fl \-default Ns = Ns Ar default-boot-menu-option
|
|
.Op Fl \-disable-append-title
|
|
.Op Fl \-disable-dhclient
|
|
.Op Fl \-disable-network-drivers
|
|
.Op Fl \-disable-src
|
|
.Op Fl \-disable-sshd
|
|
.Op Fl \-enable-append-title
|
|
.Op Fl \-enable-dhclient
|
|
.Op Fl \-enable-network-drivers
|
|
.Op Fl \-enable-src
|
|
.Op Fl \-enable-sshd
|
|
.Op Fl \-init-target Ns = Ns Ar target
|
|
.Op Fl \-liveconfig Ns = Ns Ar liveconfig-directory
|
|
.Op Fl \-random-seed
|
|
.Op Fl \-timeout Ns = Ns Ar boot-menu-timeout
|
|
.Ar output-directory
|
|
.Sh DESCRIPTION
|
|
.Nm
|
|
generates additional bootloader configuration for Sortix .iso releases that can
|
|
be overlaid onto the release .iso's filesystem, for instance by using a tool
|
|
such as
|
|
.Xr tix-iso-add 8 .
|
|
.Pp
|
|
.Nm
|
|
creates the
|
|
.Ar output-directory
|
|
directory if it doesn't already exist and populates it with the requested
|
|
additional configuration.
|
|
By default, the only action it takes is to creates a skeleton
|
|
.Pa output-directory/boot/grub/hooks.cfg
|
|
that appends " - modified by
|
|
.Ar username Ns @ Ns Ar hostname Ns
|
|
"
|
|
to the
|
|
.Sy base_menu_title
|
|
variable, which changes the boot menu title to say the .iso was modified by the
|
|
current username on the local hostname.
|
|
.Pp
|
|
This script is designed to be convenient when modifying a Sortix release .iso as
|
|
part of the
|
|
.Xr release-iso-modification 7
|
|
procedure.
|
|
Additional bootloader configuration can be provided as described in
|
|
.Xr release-iso-bootconfig 7 .
|
|
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 \-append-title Ns = Ns Ar text
|
|
Append " - " followed by
|
|
.Ar text
|
|
to the bootloader menu title by appending to the
|
|
.Sy base_menu_title
|
|
GRUB variable.
|
|
If this option is not set, the default value is " - modified by
|
|
.Ar username Ns @ Ns Ar hostname Ns
|
|
", where
|
|
.Ar username
|
|
is the output of running
|
|
.Li id -un
|
|
and
|
|
.Ar hostname
|
|
is the output of running
|
|
.Li hostname .
|
|
The bootloader menu title is appended to by default, but can be disabled with
|
|
.Fl \-disable-append-title ,
|
|
and re-enabled with
|
|
.Fl \-enable-append-title ,
|
|
whichever comes last takes precedence.
|
|
.It Fl \-default Ns = Ns Ar default-boot-menu-option
|
|
Select bootloader menu option number
|
|
.Ar default-boot-menu-option
|
|
by default (counting from 0).
|
|
If the selected menu option itself is a submenu,
|
|
.Ar default-boot-menu-option
|
|
can be appended with a
|
|
.Sy '>'
|
|
and another selection to pick a default menu option in that submenu, and so on.
|
|
This option sets the
|
|
.Sy default
|
|
GRUB variable.
|
|
.It Fl \-disable-append-title
|
|
Don't append anything to the bootloader menu title by appending to the
|
|
.Sy base_menu_title
|
|
GRUB variable.
|
|
.It Fl \-disable-dhclient
|
|
Disable automatic DHCP configuration by setting the
|
|
.Sy enable_dhclient
|
|
GRUB variable to
|
|
.Sy false ,
|
|
causing the bootloader to load additional configuration that turns off the
|
|
.Xr dhclient 8
|
|
daemon on boot.
|
|
.It Fl \-disable-network-drivers
|
|
Disable network drivers by setting the
|
|
.Sy enable_network_drivers
|
|
GRUB variable to the
|
|
.Fl \-disable-network-drivers
|
|
option which will be passed on the
|
|
.Xr kernel 7
|
|
command line.
|
|
.It Fl \-disable-src
|
|
Disable loading the source code in
|
|
.Pa /src
|
|
by setting
|
|
.Sy enable_src
|
|
GRUB variable to
|
|
.Sy false .
|
|
.It Fl \-disable-sshd
|
|
Disable automatically starting the ssh server by setting the
|
|
.Sy enable_sshd
|
|
GRUB variable to
|
|
.Sy false ,
|
|
selecting the default behavior of not starting the
|
|
.Xr sshd 8
|
|
daemon.
|
|
.It Fl \-enable-append-title
|
|
Enable appending " - " followed by the value set with
|
|
.Fl \-append-title
|
|
to the bootloader menu title by appending to the
|
|
.Sy base_menu_title
|
|
GRUB variable.
|
|
This option is on by default and can be disabled with
|
|
.Fl \-disable-append-title .
|
|
.It Fl \-enable-dhclient
|
|
Enable automatic DHCP configuration by setting the
|
|
.Sy enable_dhclient
|
|
GRUB variable to
|
|
.Sy true ,
|
|
selecting the default behavior of starting the
|
|
.Xr dhclient 8
|
|
daemon.
|
|
.It Fl \-enable-network-drivers
|
|
Enable network drivers by setting the
|
|
.Sy enable_network_drivers
|
|
GRUB variable to the
|
|
.Fl \-enable-network-drivers
|
|
option which will be passed on the
|
|
.Xr kernel 7
|
|
command line.
|
|
.It Fl \-enable-src
|
|
Enable loading the source code in
|
|
.Pa /src
|
|
by setting
|
|
.Sy enable_src
|
|
GRUB variable to
|
|
.Sy true .
|
|
.It Fl \-enable-sshd
|
|
Enable automatically starting the ssh server by setting the
|
|
.Sy enable_sshd
|
|
GRUB variable to
|
|
.Sy true ,
|
|
causing the bootloader to load additional configuration that turns on the
|
|
.Xr sshd 8
|
|
daemon on boot.
|
|
.It Fl \-init-target Ns = Ns Ar target
|
|
Add a new first menu entry that boots the
|
|
.Ar target
|
|
daemon as the
|
|
.Xr init 8
|
|
target.
|
|
.It Fl \-liveconfig Ns = Ns Ar liveconfig-directory
|
|
Overlay the
|
|
.Ar liveconfig-directory
|
|
directory onto the live environment, allowing full customization of the
|
|
live environment.
|
|
The
|
|
.Xr tix-iso-liveconfig 8
|
|
script is convenient for making the
|
|
.Ar liveconfig-directory
|
|
directory.
|
|
This option makes a
|
|
.Xr tar 1
|
|
archive compressed with
|
|
.Xr xz 1
|
|
of the
|
|
.Ar liveconfig-directory
|
|
directory and places it at
|
|
.Pa output-directory/boot/liveconfig.tar.xz .
|
|
Regardless of this option, if a
|
|
.Pa output-directory/boot/liveconfig.tar.xz
|
|
is found, the
|
|
.Sy xzio
|
|
GRUB module is loaded and an
|
|
.Sy hook_initrd_post
|
|
hook is emitted that loads
|
|
.Pa output-directory/boot/liveconfig.tar.xz
|
|
as a multiboot module.
|
|
.It Fl \-random-seed
|
|
Copy 256 bytes of randomness from
|
|
.Pa /dev/urandom
|
|
to
|
|
.Pa output-directory/boot/random.seed ,
|
|
which the existing bootloader configuration will automatically detect and use
|
|
to seed the kernel's random number generation.
|
|
This option is recommended (but notice the warnings below) as the official
|
|
releases do not come with any entropy, as entropy must be secret and only known
|
|
to a single installation.
|
|
.Pp
|
|
Warning: The information in the generated
|
|
.Pa output-directory/boot/random.seed
|
|
file must be kept confidential and should be securely erased whereever it goes
|
|
whenever it is no longer useful in a particular place, otherwise the random
|
|
number generation of the system using this entropy might be vulnerable.
|
|
This random seed must not be recycled to boot more than a single system once.
|
|
Additional systems and boots should be done with different entropy by modifiying
|
|
the release again.
|
|
An installation live environment booted with such a random seed will use it to
|
|
randomly generate secure initial random seeds for each installation made, and
|
|
each such installation will take care not to reuse the random seed across boots.
|
|
Once the
|
|
.Ar output-directory
|
|
is no longer useful, the
|
|
.Pa output-directory/boot/random.seed
|
|
path inside it should be securely erased.
|
|
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 \-timeout Ns = Ns Ar boot-menu-timeout
|
|
Pick the default bootloader menu option after
|
|
.Ar boot-menu-timeout
|
|
seconds.
|
|
If
|
|
.Ar boot-menu-timeout
|
|
is 0, pick the default menu option immediately.
|
|
If
|
|
.Ar boot-menu-timeout
|
|
is -1, the timeout is disabled.
|
|
This option sets the
|
|
.Sy timeout
|
|
GRUB variable.
|
|
.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 "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:
|
|
.Bd -literal
|
|
tix-iso-bootconfig bootconfig
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss Provide Random Seed
|
|
To customize a release with a random seed (which must be kept confidential and
|
|
not reused, see the above warnings):
|
|
.Bd -literal
|
|
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.
|
|
.Ed
|
|
.Ss Add Files to the Live Environment
|
|
To customize a release with additional configuration for the live environment
|
|
(a directory that is overlaid onto the live environment) made either manually
|
|
or with
|
|
.Xr tix-iso-liveconfig 8 :
|
|
.Bd -literal
|
|
tix-iso-bootconfig --liveconfig=liveconfig bootconfig
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss 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:
|
|
.Bd -literal
|
|
tix-iso-bootconfig --default=1 --timeout=2 bootconfig
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss Non-interactive Live Environment
|
|
The interactive user environment can be disabled by setting the default
|
|
.Xr init 8
|
|
.Fl \-target
|
|
to
|
|
.Sy no-user :
|
|
.Bd -literal
|
|
tix-iso-bootconfig --init-target=no-user bootconfig
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss Add to Bootloader Menu Title
|
|
To customize a release so the bootloader menu title is appended with a message
|
|
of your choice:
|
|
.Bd -literal
|
|
tix-iso-bootconfig --append-title="Initech Company Edition" bootconfig
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss 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:
|
|
.Bd -literal
|
|
tix-iso-bootconfig --disable-network-drivers bootconfig
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss Disable DHCP Auto-Configuration By Default
|
|
To customize a release so
|
|
.Xr dhclient 8
|
|
doesn't automatically configure network interfaces using DHCP, useful if one
|
|
wants to manually configure network interfaces with
|
|
.Xr ifconfig 8 .
|
|
.Bd -literal
|
|
tix-iso-bootconfig --disable-dhclient bootconfig
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss Enable SSH Server By Default
|
|
To customize a release so it starts the SSH server
|
|
.Xr sshd 8
|
|
automatically using the SSH configuration found in the liveconfig directory:
|
|
.Bd -literal
|
|
tix-iso-bootconfig --liveconfig=liveconfig --enable-sshd bootconfig
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Sh SEE ALSO
|
|
.Xr xorriso 1 ,
|
|
.Xr kernel 7 ,
|
|
.Xr release-iso-bootconfig 7 ,
|
|
.Xr release-iso-modification 7 ,
|
|
.Xr init 8 ,
|
|
.Xr tix-iso-add 8 ,
|
|
.Xr tix-iso-liveconfig 8
|