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>
410 lines
13 KiB
Groff
410 lines
13 KiB
Groff
.Dd February 5, 2018
|
|
.Dt RELEASE-ISO-MODIFICATION 7
|
|
.Os
|
|
.Sh NAME
|
|
.Nm release-iso-modification
|
|
.Nd instructions on how to modify release .iso filesystems
|
|
.Sh DESCRIPTION
|
|
This document describes how to modify Sortix .iso releases to meet your custom
|
|
needs.
|
|
The bootloader configuration in .iso releases is designed with an extensible
|
|
hooks system that let's you override it with further configuration and to load
|
|
additional files of your choice into the live environment.
|
|
The live environment is configurable through the normal operating system
|
|
configuration as described in section 5 of the manual.
|
|
.Pp
|
|
The release modification procedure lets you customize aspects such as the
|
|
default bootloader menu option and timeout, the default hostname, the default
|
|
keyboard layout, the default graphics resolution, adding files of your choice to
|
|
the live environment, control which drivers are loaded by default, and so on.
|
|
.Ss Prerequisites
|
|
.Bl -bullet -compact
|
|
.It
|
|
A
|
|
.Pa sortix-x.y-arch.iso
|
|
release for your architecture.
|
|
.It
|
|
.Xr xorriso 1
|
|
needs to be installed.
|
|
.El
|
|
.Ss Overview
|
|
The release modification process has three stages:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
Optionally, creating additional files that will be loaded onto the live
|
|
environment (the liveconfig).
|
|
.It
|
|
Creating additional bootloader configuration (the bootconfig), which will
|
|
contain an archived copy of the liveconfig (if any).
|
|
.It
|
|
Adding the bootconfig to the release .iso.
|
|
.El
|
|
.Pp
|
|
The bootloader menu Install and Upgrade selections will start the live
|
|
environment and run the
|
|
.Xr sysinstall 8
|
|
installer and
|
|
.Xr sysupgrade 8
|
|
upgrader respectively and they are thus also customizable by this procedure.
|
|
.Ss Convenience Scripts
|
|
The release modification can be done manually by hand, or you can use the
|
|
following convenience scripts that make the release modification easy:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
.Xr tix-iso-liveconfig 8
|
|
that generates additional configuration files for the live environment.
|
|
.It
|
|
.Xr tix-iso-bootconfig 8
|
|
that generates additional bootloader configuration and optionally configures the
|
|
bootloader to load the liveconfig into the live environment.
|
|
.It
|
|
.Xr tix-iso-add 8
|
|
that adds the bootconfig (and thus the liveconfig if any) to the release .iso.
|
|
.El
|
|
.Pp
|
|
These convenience scripts come with the operating system and are installed in
|
|
the
|
|
.Pa /sbin
|
|
directory.
|
|
These scripts are entirely for convenience and you can perform their tasks
|
|
yourself if they don't meet your needs.
|
|
The scripts are readable shell scripts and you can learn how they work and
|
|
extend them with your own features.
|
|
.Pp
|
|
If you are not on a Sortix system or on a different version of Sortix than the
|
|
one you are customizing, you can download the shell scripts matching the latest
|
|
stable release:
|
|
.Pp
|
|
.Bl -bullet -compact
|
|
.It
|
|
.Lk https://sortix.org/release/stable/scripts/tix-iso-liveconfig
|
|
.It
|
|
.Lk https://sortix.org/release/stable/scripts/tix-iso-bootconfig
|
|
.It
|
|
.Lk https://sortix.org/release/stable/scripts/tix-iso-add
|
|
.El
|
|
.Pp
|
|
If you are not customizing the latest stable release, you can find the matching
|
|
versions of the scripts in the
|
|
.Pa scripts/
|
|
subdirectory of the appropriate release directory, or you can check out the
|
|
.Pa tix
|
|
directory in the source code from
|
|
.Lk https://sortix.org/source/
|
|
matching the release you are currently customizing.
|
|
.Ss Additional Live Configuration Configuration
|
|
The live environment is a normal instance of the operating system and can be
|
|
configured by adding additional files or overwriting existing files.
|
|
Section 5 of the manual documents the system and software configuration files.
|
|
Additional files can also be added for their own sake.
|
|
.Pp
|
|
To do so, create a directory that will contain this additional live environment
|
|
configuration (liveconfig), whose contents will be extracted on top of the live
|
|
environment's root filesystem.
|
|
A compressed archive of this directory will be made in the next subsection and
|
|
needs to be registered with the bootloader configuration.
|
|
.Pp
|
|
The
|
|
.Xr tix-iso-liveconfig 8
|
|
convenience script is useful as it offers a lot of commonly useful
|
|
customizations to the live environment and can populate an initial liveconfig
|
|
directory for you.
|
|
.Ss Additional Bootloader Configuration
|
|
The GRUB bootloader configuration of an release .iso is extensible and allows
|
|
additional configuration to hook into it by writing a
|
|
.Pa /boot/grub/hooks.cfg
|
|
configuration file as described in
|
|
.Xr release-iso-bootconfig 7 .
|
|
.Pp
|
|
To do so, create a directory that will contain this additional bootloader
|
|
configuration (bootconfig), whose contents will be added onto the release .iso.
|
|
The liveconfig (if any) is normally added to the bootconfig as a compressed
|
|
archive and the additional bootloader configuration loads it as an initrd onto
|
|
the live environment.
|
|
The bootconfig will be overlaid to the release .iso in the next subsection.
|
|
.Pp
|
|
The
|
|
.Xr tix-iso-bootconfig 8
|
|
convenience script makes it easy to generate common additional bootloader
|
|
configuration and its documentation has examples of what it can do.
|
|
It is commonly used with the
|
|
.Fl \-liveconfig
|
|
option to generate the bootloader configuration that loads the additional files
|
|
from the liveconfig into the live environment.
|
|
.Ss Adding Files To The Release
|
|
Releases are modified by adding the bootconfig (which contains a compressed copy
|
|
of the liveconfig, if any) files to the release .iso.
|
|
.Pp
|
|
The
|
|
.Xr tix-iso-add 8
|
|
convenience script makes it easy to add files to a release .iso while taking
|
|
care to keep the release .iso bootable after the modification.
|
|
You need
|
|
.Xr xorriso 1
|
|
installed to use this script.
|
|
Alternatively you can add the files to the release .iso by running
|
|
.Xr xorriso 1
|
|
yourself:
|
|
.Bd -literal
|
|
xorriso \\
|
|
-indev "$input_file" \\
|
|
-outdev "$output_file" \\
|
|
-boot_image grub keep \\
|
|
-pathspecs on \\
|
|
-add \\
|
|
="$input_directory"
|
|
.Ed
|
|
.Pp
|
|
Your modified release can then be used in place of the original release.
|
|
See the
|
|
.Sx EXAMPLES
|
|
section below for inspiration on what customizations to make, as well as the
|
|
manual pages for the
|
|
.Xr tix-iso-liveconfig 8
|
|
and
|
|
.Xr tix-iso-bootconfig 8
|
|
convenience scripts.
|
|
.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 Add Files to the Live Environment
|
|
To customize a release with additional files and directories in the live
|
|
environment:
|
|
.Bd -literal
|
|
mkdir -p liveconfig
|
|
mkdir -p liveconfig/root
|
|
echo foo > liveconfig/root/foofile
|
|
echo bar > liveconfig/root/barfile
|
|
tix-iso-bootconfig --liveconfig=liveconfig bootconfig
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss Provide Random Seed
|
|
To customize a release with a random seed
|
|
.Pa ( /boot/random.seed )
|
|
(which must be kept confidential and
|
|
not reused, see the warnings in
|
|
.Xr tix-iso-bootconfig 8 ) :
|
|
.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 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 Load Only Basic Ports by Default
|
|
To customize a release to only loads basic ports by default:
|
|
.Bd -literal
|
|
mkdir -p bootconfig/boot/grub
|
|
cat > bootconfig/boot/grub/hooks.cfg << EOF
|
|
select_ports_set_basic
|
|
EOF
|
|
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 Locked Down Multi-User Live Environment
|
|
To customize a release so the live environment boots to the login screen by
|
|
default with the provided database of users and groups
|
|
.Xr ( passwd 5
|
|
and
|
|
.Xr group 5 ) ,
|
|
password protect the
|
|
bootloader so only the default live environment option can be chosen by
|
|
unauthenticated users:
|
|
.Bd -literal
|
|
mkdir -p liveconfig/etc
|
|
# Each user's password is their username hashed with crypt_newhash(3).
|
|
(printf 'root:%s:0:0:root:/root:sh\\n' \\
|
|
'$2b$10$S/fJmYIJSkRdifk61xDYn.w62y.vNu35tZkznR6xa3Ntg0hsbI8tO' &&
|
|
printf 'alice:%s:1000:1000:alice:/home/alice:sh\\n' \\
|
|
'$2b$10$4xGAf5FyCYedWoNltWvbmOOreXcI5cH/f4Jz/pkWrWxwZ7TQ/WbRC' &&
|
|
printf 'bob:%s:1001:1001:bob:/home/bob:sh\\n' \\
|
|
'$2b$10$0.IukhbHNy63te6ozVJ7Pu/EvbCcr892981XbqRQ0w16UPhmDdUqa') |
|
|
cat > liveconfig/etc/passwd
|
|
cat > liveconfig/etc/group << EOF
|
|
root::0:root
|
|
alice::1000:alice
|
|
bob::1001:bob
|
|
EOF
|
|
mkdir -p liveconfig/home
|
|
mkdir -p -m 700 liveconfig/home/alice
|
|
mkdir -p -m 700 liveconfig/home/bob
|
|
grub-mkpasswd-pbkdf2 | # enter bootloader password
|
|
tee /dev/tty |
|
|
tail -n 1 |
|
|
sed 's/PBKDF2 hash of your password is //' > liveconfig/etc/grubpw
|
|
tix-iso-bootconfig --liveconfig=liveconfig bootconfig
|
|
(echo 'insmod password_pbkdf2'
|
|
echo 'set superusers="root"'
|
|
echo "password_pbkdf2 root $(cat liveconfig/etc/grubpw)") |
|
|
cat >> bootconfig/boot/grub/hooks.cfg
|
|
cat > bootconfig/boot/grub/main.cfg << \EOF
|
|
menu_title="$base_menu_title"
|
|
hook_menu_pre
|
|
menuentry "Sortix $version" --unrestricted {
|
|
load_sortix -- /sbin/init --target=multi-user
|
|
}
|
|
hook_menu_post
|
|
EOF
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss Add a new Port
|
|
To customize a release with a new port
|
|
.Sy foo
|
|
in the
|
|
.Sy basic
|
|
and
|
|
.Sy all
|
|
port sets and fully integrate it with the bootloader menus:
|
|
.Bd -literal
|
|
mkdir -p bootconfig/boot/grub
|
|
cat > bootconfig/boot/grub/hooks.cfg << \\EOF
|
|
port_foo=true
|
|
tix_foo=false
|
|
export port_foo
|
|
export tix_foo
|
|
function hook_ports_menu {
|
|
if $port_foo; then
|
|
menuentry "foo = true" {
|
|
port_foo=false
|
|
configfile /boot/grub/ports.cfg
|
|
}
|
|
else
|
|
menuentry "foo = false" {
|
|
port_foo=true
|
|
configfile /boot/grub/ports.cfg
|
|
}
|
|
fi
|
|
}
|
|
function hook_tix_menu {
|
|
if $tix_foo; then
|
|
menuentry "foo = true" {
|
|
tix_foo=false
|
|
configfile /boot/grub/tix.cfg
|
|
}
|
|
else
|
|
menuentry "foo = false" {
|
|
tix_foo=true
|
|
configfile /boot/grub/tix.cfg
|
|
}
|
|
fi
|
|
}
|
|
function hook_ports_set_all {
|
|
port_foo=true
|
|
}
|
|
function hook_tix_set_all {
|
|
tix_foo=true
|
|
}
|
|
function hook_ports_set_basic {
|
|
port_foo=true
|
|
}
|
|
function hook_tix_set_basic {
|
|
tix_foo=true
|
|
}
|
|
function hook_ports_set_minimal {
|
|
port_foo=false
|
|
}
|
|
function hook_tix_set_minimal {
|
|
tix_foo=false
|
|
}
|
|
function hook_ports_set_no {
|
|
port_foo=false
|
|
}
|
|
function hook_tix_set_no {
|
|
tix_foo=false
|
|
}
|
|
function hook_ports_pre {
|
|
if $tix_foo; then
|
|
echo -n "Loading /repository/foo.tix.tar.xz (3.0M) ... "
|
|
module --nounzip /repository/foo.tix.tar.xz \\
|
|
--to /repository/foo.tix.tar.xz
|
|
echo done
|
|
fi
|
|
if $port_foo; then
|
|
echo -n "Loading /repository/foo.tix.tar.xz (3.0M) ... "
|
|
module /repository/foo.tix.tar.xz --tix
|
|
echo done
|
|
fi
|
|
}
|
|
EOF
|
|
mkdir -p bootconfig/repository
|
|
cp foo.tix.tar.xz bootconfig/repository/foo.tix.tar.xz
|
|
tix-iso-add sortix.iso bootconfig
|
|
.Ed
|
|
.Ss Add a new Ports Set
|
|
To customize a release with your own set of ports that are loaded by
|
|
default and fully integrate it with the bootloader menus:
|
|
.Bd -literal
|
|
mkdir -p bootconfig/boot/grub
|
|
cat > bootconfig/boot/grub/hooks.cfg << \\EOF
|
|
function hook_ports_menu_sets {
|
|
menuentry "Load only recommended ports" {
|
|
select_ports_set_recommended
|
|
configfile /boot/grub/ports.cfg
|
|
}
|
|
}
|
|
function hook_tix_menu_sets {
|
|
menuentry "Load only basic binary packages" {
|
|
select_tix_set_recommended
|
|
configfile /boot/grub/tix.cfg
|
|
}
|
|
}
|
|
select_ports_set_recommended {
|
|
# The basic set can be extended by calling select_ports_set_basic here.
|
|
port_foo=false
|
|
port_bar=true
|
|
}
|
|
select_tix_set_recommended {
|
|
# The basic set can be extended by calling select_tix_set_basic here.
|
|
tix_foo=false
|
|
tix_bar=true
|
|
}
|
|
# Load the recommended set of ports by default.
|
|
hook_ports_menu_sets
|
|
EOF
|
|
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 development 7 ,
|
|
.Xr installation 7 ,
|
|
.Xr release-iso-bootconfig 7 ,
|
|
.Xr upgrade 7 ,
|
|
.Xr user-guide 7 ,
|
|
.Xr tix-iso-add 8 ,
|
|
.Xr tix-iso-bootconfig 8 ,
|
|
.Xr tix-iso-liveconfig 8
|