This change adds all the kernel parts of a network stack. The network stack is partial but implements many of the important parts. Add if(4) network interface abstraction. Network interfaces are registered in a global list that can be iterated and each assigned an unique integer identifier. Add reference counted packets with a cache that recycles recent packets. Add support for lo(4) loopback and ether(4) ethernet network interfaces. The /dev/lo0 loopback device is created automatically on boot. Add arp(4) address resolution protocol driver for translation of inet(4) network layer addresses into ether(4) link layer addresses. arp(4) entries are cached and evicted from the cache when needed or when the entry has not been used for a while. The cache is limited to 256 entries for now. Add ip(4) internet protocol version 4 support. IP fragmentation and options are not implemented yet. Add tcp(4) transmission control protocol sockets for a reliable transport layer protocol that provides a reliable byte stream connection between two hosts. The implementation is incomplete and does not yet implement out of band data, options, and high performance extensions. Add udp(4) user datagram protocol sockets for a connectionless transport layer that provides best-effort delivery of datagrams. Add ping(4) sockets for a best-effort delivery of echo datagrams. Change type of sa_family_t from unsigned short to uint16_t. Add --disable-network-drivers to the kernel(7) options and expose it with a bootloader menu. tix-iso-bootconfig can set this option by default. Import CRC32 code from libz for the Ethernet checksum. This is a compatible ABI change that adds features to socket(2) (AF_INET, IPPROTO_TCP, IPPROTO_UDP, IPPROTO_PING), the ioctls for if(4), socket options, and the lo0 loopback interface. This commit is based on work by Meisaka Yukara contributed as the commit bbf7f1e8a5238a2bd1fe8eb1d2cc5c9c2421e2c4. Almost no lines of this work remains in this final commit as it has been rewritten or refactored away over the years, see the individual file headers for which files contain remnants of this work. Co-authored-by: Meisaka Yukara <Meisaka.Yukara@gmail.com>
282 lines
8.7 KiB
Groff
282 lines
8.7 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-network-drivers
|
|
.Op Fl \-disable-src
|
|
.Op Fl \-enable-append-title
|
|
.Op Fl \-enable-network-drivers
|
|
.Op Fl \-enable-src
|
|
.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-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 \-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-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 \-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
|
|
.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
|