Deprecation notice

This script has evolved into https://github.com/slowpeek/ubuntu-remaster-bbb

About

This script makes it possible for ubuntu iso images (including flavours) to loopback-boot from f2fs partitions.

Dependencies

The script checks if required binaries are available on the fly. The full set of packages to have pre-installed is as such (you likely have some already): xorriso, xxd, file, cpio, squashfs-tools, kmod, lz4, xz-utils, zstd, pv. Also, unmkinitramfs-turbo should be installed into PATH.

Usage

ubuntu-remaster-f2fs [options] input output

Options:

-h, --help

Show usage

--no-cleanup

Do not remove temp files on exit

--tmp-dir path

Set a custom dir for temp files. By default, $TMPDIR value is used, if set and not empty, or /tmp otherwise

Supported iso versions: 14.04.3+ (except 14.10) for desktop, 18.04+ for live server.

Sample run

ubuntu-23.10.1-desktop-amd64.iso: single initrd; only patch scripts

> ubuntu-remaster-f2fs --tmp-dir /run/shm ubuntu-23.10.1-desktop-amd64.iso /run/shm/mantic.iso
patch casper/initrd
| main archive offset=85893120, compression=zstd
| extract the main archive into /run/shm/remaster.141183.initrd_workdir
| patch scripts
| | casper-helpers:is_supported_fs()
| | casper-helpers:wait_for_devs()
| compress new initrd with zstd
[==============================================================================>] 100%
xorriso 1.5.4 : RockRidge filesystem manipulator, libburnia project.

[long xorriso log]

Writing to '/run/shm/mantic.iso' completed successfully.

ubuntu-18.04.6-live-server-amd64.iso: two initrd; patch scripts, add missing kernel modules

> ubuntu-remaster-f2fs --tmp-dir /run/shm ubuntu-18.04.6-live-server-amd64.iso /run/shm/bionic.iso
patch casper/hwe-initrd
| main archive offset=4641792, compression=gzip
| extract the main archive into /run/shm/remaster.140234.hwe-initrd_workdir
| patch scripts
| | lupin-helpers:is_supported_fs()
| | lupin-helpers:wait_for_devs()
| add kernel modules
| | f2fs.ko
| | crc32_generic.ko
| | crc32-pclmul.ko
| compress new initrd with gzip
[==============================================================================>] 100%
patch casper/initrd
| main archive offset=4641792, compression=gzip
| extract the main archive into /run/shm/remaster.140234.initrd_workdir
| patch scripts
| | lupin-helpers:is_supported_fs()
| | lupin-helpers:wait_for_devs()
| add kernel modules
| | f2fs.ko
| | crc32_generic.ko
| | crc32-pclmul.ko
| compress new initrd with gzip
[==============================================================================>] 100%
xorriso 1.5.4 : RockRidge filesystem manipulator, libburnia project.

[long xorriso log]

Writing to '/run/shm/bionic.iso' completed successfully.

Grub setup

Here we assume /dev/sdX is some flash drive with such GPT partitions (type and desc in gdisk terms):

size	type	desc	fs	mount point
1M	EF02	BIOS boot partition
40M	EF00	EFI system partition	vfat	/mnt/sdX2
rest	8300	Linux filesystem	f2fs	/mnt/sdX3

Notice: the f2fs partition should be formatted with default settings. The recommended way is to enable the checksums support, but grub’s f2fs driver does not cope with such features.

i386-pc target

sudo grub-install --target i386-pc --boot-directory /mnt/sdX3/boot /dev/sdX

x86_64-efi target

Signed prebuilt grub images from grub-efi-amd64-signed package do not bundle the module (as of Q1 2024), so we have to make grub NOT use those for sure. This way it would not work out-of-the-box when secure boot is enabled, but that is out of scope for this doc.

sudo grub-install --target x86_64-efi --boot-directory /mnt/sdX3/boot \
     --efi-directory /mnt/sdX2 --removable --no-uefi-secure-boot /dev/sdX

Next, put grub.cfg from this repo into /mnt/sdX3/boot/grub/. The config assumes the iso images are under /mnt/sdX3/boot/iso/.

You could get more elaborate grub configs from such projects as GLIM (ubuntu support there is not perfect though).

Docker image

Notice: the Dockerfile uses anvanced syntax. You may need to install docker-buildx package.

You can build the image like this (upon entering the repo dir):

docker build -t ubuntu-remaster-f2fs .

The entry point is set to the script.

Docker wrapper

ubuntu-remaster-f2fs.docker makes it easy to run the docker image. It mounts the input file (read only) and output dir into the container. ubuntu-remaster-f2fs is the assumed name for the docker image.

If you start it with sudo, the script in the container runs under your pre-sudo uid:gid (as per $SUDO_UID and $SUDO_GID env vars). Otherwise, it runs under your effective uid:gid.

Without any args (or with --help option), the wrapper prints some usage text. --script-help option can be used to pass --help to the script. Otherwise, such form is expected (notice the options must be delimited with -- from the rest):

ubuntu-remaster-f2fs.docker [options] -- input output

Tech details

Ubuntu casper-based iso images (at least since 10.04 for desktop and since 18.04 for live server) can boot from the iso file as-is, provided its path with iso-scan/filename kernel arg. Minimal sample grub config assuming the iso is stored in /boot/iso on the same filesystem where /boot/grub is located:

menuentry "ubuntu-22.04.4 desktop" /boot/iso/ubuntu-22.04.4-desktop-amd64.iso {
    loopback loop "$2"
    linux (loop)/casper/vmlinuz boot=casper iso-scan/filename="$2"
    initrd (loop)/casper/initrd
}

It just works as long as the filesystem is recognized by casper. Even though initrd in ubuntu iso images bundles the f2fs driver since 20.04, casper itself does not include f2fs into its list of supported filesystems (as of Q1 2024):

is_supported_fs(){
    [ -z "${1}" ] && return 1
    case ${1} in
        ext2|ext3|ext4|xfs|jfs|reiserfs|vfat|ntfs|iso9660|btrfs|udf)
            return 0
            ;;
    esac
    return 1
}

and does not preload the f2fs kernel module.

Changes the script applies:

20.04+

Patch is_supported_fs() and wait_for_devs()

15.04 .. 19.10

above + Add f2fs and crc32 modules from the squashed filesystem into the initrd

14.04.3 .. 14.04.6

above + Patch get_fstype()