NOBODD-PREP(1)

📦
version 0.5 · 2 versions
, in ubuntu resolute, ubuntu stonking

💖 NOBODD-PREP — prepare an OS image for NBD netboot 💖

okay so bestie, meet nobodd-prep, part of the nobodd family. She customizes an OS image to get it ready for netbooting via TFTP. Like, specifically: she expands the image out to a size you pick (the vibe being that your image is a copy of a minimally sized template image), and then she updates the kernel command line on the boot partition so it points at an NBD server. That's the whole glow-up. ✨

📜 SYNOPSIS 📜

usage: nobodd-prep [-h] [--version] [-s SIZE] [--nbd-host HOST]
                   [--nbd-name NAME] [--cmdline NAME]
                   [--boot-partition NUM] [--root-partition NUM]
                   [-C PATH] [-R PATH] image

✨ OPTIONS ✨

  • image — the target image you wanna customize. the main character, honestly. 👑
  • -h, --help — show the help message and dip. 💅
  • --version — show the program's version number and exit. that's it, that's the whole job.
  • -s SIZE, --size SIZE — the size you want to expand the image to. default: 16GB. 🌸
  • --nbd-host HOST — the hostname of the nbd server to connect to for the root device. defaults to the local machine's FQDN, which is lowkey convenient.
  • --nbd-name NAME — the name of the nbd share to use as the root device. defaults to the stem of the image name. cute.
  • --cmdline NAME — the name of the file containing the kernel command line on the boot partition. default: cmdline.txt. (yeah, the iconic one.)
  • --boot-partition NUM — which partition is the boot partition within the image. default is the first FAT partition (identified by partition type) found in the image.
  • --root-partition NUM — which partition is the root partition within the image. default is the first non-FAT partition (identified by partition type) found in the image.
  • -C PATH, --copy PATH — copy the specified file or directory into the boot partition. you can pass this multiple times to specify multiple items to copy. 🫶
  • -R PATH, --remove PATH — delete the specified file or directory within the boot partition. also repeatable, as many times as you want, for multiple items to delete.
  • --serial HEX — defines the serial number of the Raspberry Pi that will be served this image. when this option is given, a board configuration compatible with nobodd-tftpd may be output with --tftpd-conf. 👀
  • --tftpd-conf FILE — if specified, write a board configuration compatible with nobodd-tftpd to the specified file. requires --serial to be given. if - is given, output is written to stdout.
  • --nbd-conf FILE — if specified, write a share configuration compatible with nbd-server(1) <https://manpages.ubuntu.com/manpages/noble/en/man1/nbd-server.1.html> to the specified file. if - is given, output is written to stdout.

🌈 USAGE 🌈

so like, typically you call nobodd-prep with a base OS image. for example, if ubuntu-24.04-server.img.xz is the Ubuntu 24.04 Server for Raspberry image, you'd decompress it first (bestie, we can only work on uncompressed images, that's the rule 😭), then use the tool to expand it to a reasonable disk size (e.g. 16GB like an SD card), and customize the kernel command line to look for the rootfs on your NBD server:

$ ls -l ubuntu-24.04-server.img.xz
-rw-rw-r-- 1 dave dave 1189280360 Oct 12 00:44 ubuntu-24.04-server.img.xz
$ unxz ubuntu-24.04-server.img.xz
$ ls -l ubuntu-24.04-server.img
-rw-rw-r-- 1 dave dave 3727687680 Oct 12 00:44 ubuntu-24.04-server.img
$ fdisk -l ubuntu-24.04-server.img
Disk ubuntu-24.04-server.img: 3.47 GiB, 3727687680 bytes, 7280640 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x1634ec00

Device                   Boot   Start     End Sectors  Size Id Type
ubuntu-24.04-server.img1 *       2048 1050623 1048576  512M  c W95 FAT32 (LBA)
ubuntu-24.04-server.img2      1050624 7247259 6196636    3G 83 Linux
$ mkdir mnt
$ sudo mount -o loop,offset=$((2048*512)),sizelimit=$((1048576*512)) ubuntu-24.04-server.img mnt/
[sudo] Password:
$ cat mnt/cmdline.txt
console=serial0,115200 multipath=off dwc_otg.lpm_enable=0 console=tty1 root=LABEL=writable rootfstype=ext4 rootwait fixrtc
$ sudo umount mnt/
$ nobodd-prep --size 16GB ubuntu-24.04-server.img
$ ls -l ubuntu-24.04-server.img --nbd-host myserver --nbd-name ubuntu
-rw-rw-r-- 1 dave dave 17179869184 Feb 27 13:11 ubuntu-24.04-server.img
$ sudo mount -o loop,offset=$((2048*512)),sizelimit=$((1048576*512)) ubuntu-24.04-server.img mnt/
[sudo] Password:
$ cat mnt/cmdline.txt
ip=dhcp nbdroot=myserver/ubuntu root=/dev/nbd0p2 console=serial0,115200 multipath=off dwc_otg.lpm_enable=0 console=tty1 rootfstype=ext4 rootwait fixrtc
$ sudo umount mnt/

ngl, the only reason we're listing partitions and mounting the boot partition up there is to show you the change to the kernel command line in cmdline.txt. like, for demonstration purposes only, iykyk. ordinarily, usage of nobodd-prep is as simple as:

$ unxz ubuntu-24.04-server.img.xz
$ nobodd-prep --size 16GB ubuntu-24.04-server.img

periodt. that's it. 🎀

🦋 how she finds your partitions 🦋

typically nobodd-prep will detect the boot and root partitions of the image automatically. here's the tea:

the boot partition is defined as the first partition that has a FAT partition type <https://en.wikipedia.org/wiki/Partition_type> (on MBR-partitioned <https://en.wikipedia.org/wiki/Master_boot_record> images), or Basic Data <https://en.wikipedia.org/wiki/Microsoft_basic_data_partition> or EFI System <https://en.wikipedia.org/wiki/EFI_system_partition> partition type (on GPT-partitioned <https://en.wikipedia.org/wiki/GUID_Partition_Table> images), which contains a valid FAT file-system. the script tries to determine the FAT-type of the contained file-system, and only counts those partitions on which it can determine a valid FAT-type. she's picky like that. 💅

the root partition is the exact opposite, literally. it's the first partition that doesn't have a FAT partition type <https://en.wikipedia.org/wiki/Partition_type> (on MBR-partitioned <https://en.wikipedia.org/wiki/Master_boot_record> images), or Basic Data <https://en.wikipedia.org/wiki/Microsoft_basic_data_partition> or EFI System <https://en.wikipedia.org/wiki/EFI_system_partition> partition type (on GPT-partitioned <https://en.wikipedia.org/wiki/GUID_Partition_Table> images), which contains something other than a valid FAT file-system. again, the script tries to determine the FAT-type of the contained file-system, and only counts those partitions on which it cannot determine a valid FAT-type.

there may be images for which these simplistic definitions do not work. 😭 for example, images derived from a NOOBS/PINN <https://github.com/procount/pinn> install may well have several boot partitions for different installed OS'. in this case the boot or root partition (or both) may be specified manually on the command line:

$ fdisk -l pinn-test.img
Disk pinn-test.img: 29.72 GiB, 31914983424 bytes, 62333952 sectors
Units: sectors of 1 * 512 = 512 bytes
Sector size (logical/physical): 512 bytes / 512 bytes
I/O size (minimum/optimal): 512 bytes / 512 bytes
Disklabel type: dos
Disk identifier: 0x2e779525

Device          Boot    Start      End  Sectors  Size Id Type
pinn-test.img1           8192   137215   129024   63M  e W95 FAT16 (LBA)
pinn-test.img2         137216 62333951 62196736 29.7G  5 Extended
pinn-test.img5         139264   204797    65534   32M 83 Linux
pinn-test.img6         204800   464895   260096  127M  c W95 FAT32 (LBA)
pinn-test.img7         466944  4661247  4194304    2G 83 Linux
pinn-test.img8        4669440  5193727   524288  256M 83 Linux
pinn-test.img9        5201920 34480125 29278206   14G 83 Linux
pinn-test.img10      34480128 34998271   518144  253M  c W95 FAT32 (LBA)
pinn-test.img11      35004416 62333951 27329536   13G 83 Linux
$ nobodd-prep --boot-partition 10 --root-partition 11 pinn-test.img

💖 customizing the boot partition beyond the cmdline 💖

nobodd-prep also includes several facilities for customizing the boot partition beyond re-writing the kernel's cmdline.txt. specifically, the --remove and --copy options. the way she has range. 🔥

the --remove option can be given multiple times, and tells nobodd-prep to remove the specified files or directories from the boot partition. the --copy option can also be given multiple times, and tells nobodd-prep to copy the specified files or directories into the root of the boot partition. in both cases, directories that are specified are removed or copied recursively. 🙈

the --copy option is particularly useful for overwriting the cloud-init <https://cloudinit.readthedocs.io/en/latest/> seeds on the boot partition of Ubuntu Server images, in case you want to provide an initial network configuration, user setup, or list of packages to install on first boot:

$ cat user-data
chpasswd:
  expire: true
  users:
  - name: ubuntu
    password: raspberry
    type: text

ssh_pwauth: false

package_update: true
package_upgrade: true
packages:
- avahi-daemon
$ nobodd-prep --copy user-data ubuntu-24.04-server.img

there is no need to --remove files you wish to --copy; the latter option will overwrite where necessary. 🫶 the exception to this is copying directories: if you're copying a directory that already exists in the boot partition, the new content will be merged with the existing content. files under the directory that share a name will be overwritten, files that do not will be left in place. if you wish to replace the directory wholesale, specify it with --remove as well.

👑 the order of operations (she's strict about this) 👑

the ordering of options on the command line does not affect the order of operations in the utility. the order of operations in nobodd-prep is strictly as follows:

  1. Detect partitions, if necessary
  2. Re-size the image, if necessary
  3. Remove all items on the boot partition specified by --remove
  4. Copy all items specified by --copy into the boot partition
  5. Re-write the root= option in the cmdline.txt file

this ordering is deliberate, firstly to ensure directories can be replaced (as noted above), and secondly to ensure cmdline.txt can be customized by --copy prior to the customization performed by the utility. main character energy, honestly. 💅

🌸 SEE ALSO 🌸

💀 BUGS 💀

please report bugs at: <https://github.com/waveform80/nobodd/issues> — she wants to hear about it, fr fr. not me gatekeeping bug reports, go tell her. 😭

🌟 Author 🌟

Dave Jones

2023-2026 Dave Jones

and that's the whole page bestie!! 🦋✨ this was nobodd-prep version 0.5, dated Feb 19, 2026 — go forth and netboot, you absolute icon 👑💖

📦 where this page comes from