6c8e6e5fff
This change adds the display(1) graphical user interface and desktop environment with basic windowing support and the graphical terminal(1) emulator along with integrations in chkblayout(1), chvideomode(1), sysinstall(8), sysupgrade(8), as well as the games and ports. Adopt the Aurora procedural wallpaper in display(1) and login(8). Remove the obsolete dispd. Juhani contributed keyboard and video mode APIs to the display protocol and other miscellaneous changes. dzwdz contributed the initial functioning window buttons, improved title bar, window tiling, and minor bug fixes Co-authored-by: Juhani Krekelä <juhani@krekelä.fi> Co-authored-by: dzwdz <kg67199@gmail.com>
388 lines
11 KiB
Groff
388 lines
11 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-gui
|
|
.Op Fl \-disable-network-drivers
|
|
.Op Fl \-disable-ntpd
|
|
.Op Fl \-disable-src
|
|
.Op Fl \-disable-sshd
|
|
.Op Fl \-enable-append-title
|
|
.Op Fl \-enable-dhclient
|
|
.Op Fl \-enable-gui
|
|
.Op Fl \-enable-network-drivers
|
|
.Op Fl \-enable-ntpd
|
|
.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-gui
|
|
Disable the GUI by setting the
|
|
.Sy enable_gui
|
|
GRUB variable to
|
|
.Sy false ,
|
|
which makes the bootloader configuration not append
|
|
.Sy -gui
|
|
to the requested
|
|
.Xr init 8
|
|
target.
|
|
.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-ntpd
|
|
Disable automatically starting the ntp client by setting the
|
|
.Sy enable_ntpd
|
|
GRUB variable to
|
|
.Sy false ,
|
|
selecting the default behavior of not starting the
|
|
.Xr ntpd 8
|
|
daemon.
|
|
.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-gui
|
|
Enable the GUI by setting the
|
|
.Sy enable_gui
|
|
GRUB variable to
|
|
.Sy true ,
|
|
which makes the bootloader configuration append
|
|
.Sy -gui
|
|
to the requested
|
|
.Xr init 8
|
|
target.
|
|
.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-ntpd
|
|
Enable automatically starting the ntp client by setting the
|
|
.Sy enable_ntpd
|
|
GRUB variable to
|
|
.Sy true ,
|
|
causing the bootloader to load additional configuration that turns on the
|
|
.Xr ntpd 8
|
|
daemon on boot.
|
|
.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.
|
|
.Pp
|
|
If the liveconfig contains
|
|
.Xr autoinstall.conf 5
|
|
or
|
|
.Xr autoupgrade.conf 5 ,
|
|
the menu titles are modified to loudly warn they will automatically
|
|
install/upgrade the operating system.
|
|
.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
|
|
.Ss Boot to Console Instead of GUI By Default
|
|
To customize a release so it boots to a console instead of the GUI:
|
|
.Bd -literal
|
|
tix-iso-bootconfig --disable-gui 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
|