skuf

SKUF - Suckless Kexec Using Fileshare

Ever wanted to be able to boot Linux[^1] over the network using an Ethernet cable but without setting up a PXE? Now you only need a SMB server that can be installed anywhere!

SKUF Network Boot System allows you to boot the Arch Linux[^2] operating system on a computer connected to network via Ethernet using USB flash drive (150MB minimum) and a SMB file share.

[!CAUTION] The only supported distribution is Arch Linux™. Other shitty systems like Debian, Ubuntu, Manjaro, Fedora, openSUSE, etc. are NOT supported and NEVER WILL BE.

Requirements

Two computers in the same network:

Server:

[x] Running SMB file server
[x] Your user on the SMB server has a password. Users without password or anonymous access are not supported

Client:

[x] Connected to network via Ethernet cable. Wireless is not supported.
[x] A temporary USB stick/CD/DVD with the skuflinux image (you can also use Ventoy)
[x] Brain not poisoned with beer so you have enough brain cells to read this manual

[!CAUTION] Prebuilt binaries and ISO images will NEVER be available due to possible security risks. Read the build instructions carefully.

Scheme of work

[!NOTE] The example illustrates how the server and client work together. Server — a computer with the SMB server running. Client — a computer that will boot the system from the server over the network using a cable

You have a USB flash drive/CD/DVD with an ISO image of skuflinux on it. You have two PCs in your room/college/office. First one is the one you will be sitting at. The other one is running SMB server with a directory that you have write access to. That directory contains filesystem image with the Arch Linux distribution and the skuf package installed on it.

Step 1: Loading kernel and initramfs from SMB server

After booting from USB drive with skuflinux you will be prompted to enter SMB server address and port, user credentials and path to filesystem image (you can unplug your USB flash drive at this point). Now SKUF script will do the following:

Obtain an IP address using dhcpcd
Mount the SMB directory (read-only)
Mount the image volume with Arch Linux (read-only)
Generate an encrypted string with your answers to the questions asked earlier
Load kernel and initramfs from a previously mounted Arch Linux image into RAM
Unmount SMB and image volume with Arch Linux
Execute kexec

Step 2: Re-mounting SMB and running system

Now when the kernel and initramfs of your Arch Linux were loaded from SMB server, SKUF mounts system image again:

The newly booted system obtaining IP address again
The previously encrypted string contained your answers to the questions. It was passed to the kernel command line (/proc/cmdline) in encrypted form, and will now be decrypted, so you don't have to write it all over again.
Mounting the SMB directory again (read/write)
Mounting the image with Arch Linux again (read/write)
Once everything mounted, SKUF executes switch_root and system is booted. Congratulations!

Building

See also: Arch Wiki article

[!CAUTION] The only supported distribution is Arch Linux™. Other shitty systems like Debian, Ubuntu, Manjaro, Fedora, openSUSE, etc. are NOT supported and NEVER WILL BE. To build SKUF on a non-Arch-based system, run Arch Linux, for example, in a docker container: 
docker run -it archlinux

Required packages

arch-install-scripts
archiso
base
base-devel
binutils
clang or gcc
musl
linux-api-headers
kernel-headers-musl
patch (optional, for build_rootfs_tar.sh, if patches present)

Build instructions

Clone this repository using git:

git clone https://github.com/BiteDasher/skuf
cd skuf
./switch-tag latest

Tune encryption obfuscation and encryption password (see Customization instructions):

vim tune.password
vim tune.crypt

Setup defaults for ISO (optional):

vim defaults

Install required packages:

./install_deps.sh

Run configuraion sripts:

./tune_crypt.sh
./tune_password.sh
./setup_defaults.sh

Build SKUF:

./build_rootfs_tar.sh
./build_package.sh
./setup_repo.sh
./build_iso.sh
./create_image.sh SIZE_IN_GIGABYTES additional_packages
# For sparse file, use ./create_image.sh -s

[!NOTE] Basic installation of Arch Linux without GUI or any additional software takes about 1 GB.

Done! 💪🎉 Now write skuflinux-smth.iso to your USB drive, put arch.ext4 into your directory on SMB server and try SKUF Network Boot System.

Customisation instructions

Password tuning

String for /proc/cmdline is encrypted using OpenSSL. You need to specify encryption password and number of iterations in the tune.password file in following format:

ITERATIONS_COUNT PASSWORD

[!NOTE] For an example, see the tune.passwordX file

Obfuscation tuning

String that is encrypted through OpenSSL is eventually turned into a base64 string. You can obfuscate this string by swapping these symbols. Write pairs of letters or numbers in the following format to the tune.crypt file:

A B
X Y
I O
0 1
4 8

[!NOTE] For an example, see the tune.cryptX file

Defaults setup

When you booted up the skuflinux ISO image from your media device, you will be asked questions like: SMB server address, SMB server port, SMB protocol version and so on. Edit the defaults file if you want to preset them manually.

Table of main SKUF variables: |Variable|Meaning| |:---|:---| |`SAMBA_USERNAME`|Username for the SMB server | |`SAMBA_PASSWORD`|User password for the SMB server | |`SAMBA_ADDRESS`|Address of the SMB server where the client directory with the `Arch Linux` image is located | |`SAMBA_PORT`|SMB server port| |`SAMBA_VERSION`|SMB server protocol version| |`SAMBA_DOMAIN`|Domain for the SMB server (default domain is `WORKGROUP`)| |`VOLUME_PATH`|Path to the directory on the SMB server where the client Arch Linux image volume and swap file are located(see Tips and Tricks) | |`VOLUME_FILENAME`|Arch Linux image volume name that is located in `VOLUME_PATH` | |`SWAP_FILENAME`|Swap file name that is located in `VOLUME_PATH`| |`SAMBA_EXTRA_MOUNT_OPTS`|Additional SMB mount options. Applies to both step 1 and step 2 of SKUF boot process| |`VOLUME_EXTRA_MOUNT_OPTS`|Additional client Arch Linux image volume mount options. Applies to both step 1 and step 2 of SKUF boot process| |`CHECK_FS`|Whether to check the integrity of a file system image with Arch Linux. Accepts `Yes` or `No`. Applies only to step 2| |`EXTRA_KERNEL_OPTS`|Additional linux kernel options| |`PATH_TO_NEW_KERNEL`|Path to the new kernel that will be loaded using kexec. The new kernel must be in the Arch Linux image that is lies on SMB server | |`PATH_TO_NEW_INITRAMFS`|Path to the new initramfs that will be loaded using kexec alongside kernel. The new initramfs must be in the Arch Linux image that is lies on SMB server *|

Table of auxiliary SKUF variables: |Variable|Meaning| |:---|:---| |MAX_SMB_RETRY_COUNT|Maximum number of attempts to re-enter SMB credentials if the first mount attempt failed. Applies only to step 1| |SKIP|Automate the startup process. Set to 0 or nothing if you want to achieve the default behavior of having to enter answers to questions using keyboard. Set to 1 if you want the startup to proceed without your participation. Be sure you have set all the mandatory variables! Applies to step 1|

[!NOTE] "Mandatory" variables are marked with an asterisk at the end.

[!NOTE]

Use ,,, as a separator in extra mount options to specify additional mount options that will be concatenated and applied only to step 2 (i.e. mount options specified only before ,,, will be applied to step 1 and options specified both before and after ,,, will be applied to step 2). 

Use ,,,| as a separator in extra mount options to specify different mount options for step 1 and step 2 (i.e. everything before ,,,| will be applied only to step 1 and everything after ,,,| will be appled only to step 2).

Presets using bootloader (iMac with wireless keyboard)

If you need to change any presets before booting into SKUF, you can change the bootable kernel parameters through the bootloader. This can be useful when you have, for example, an iMac with a wireless keyboard that only works in EFI applications. The way to change kernel parameters depends on the bootloader:

syslinux: hit <kbd>Tab</kbd> and start typing
grub2: select entry in menu and click <kbd>e</kbd> to open editor
systemd-boot: click <kbd>e</kbd> and start typing

1. Set presets using variables

You can specify presets using one or more kernel variables like this:

skuf.samba_username="Username with spaces"
skuf.SAMBA_PASSWORD='Password \' with \\ character escaping'
skuf.VOLUME_PATH=Path\

Skuf

Install / Use

README