Creating a custom BBB Debian image non-interactively

I need to automate the creation of a Debian-based custom BBB image that will be used in production. We’re currently using one of the “console-only” pre-built images and then interactively tweaking it via console commands via SSH. Our tweaking procedure includes:

  • Running apt install for additional needed packages not included in the pre-built image
  • Running apt remove for packages that we don’t need
  • Deploying the device overlays to match the hardware that we connect to the BBB header pins
  • Deploying our application executables
  • Setting-up systemd entries so that our executables are launched in the proper order

This method of creating custom images with a human interactively inputting commands is error-prone and time-consuming. I want to be able to automate the entire image creation process via a master script on a dedicated build machine (preferably a x64 computer, but I can also purchase a high-performance ARM machine if necessary).

Please advise on the way I should go about doing this. I found the omap-image-builder GitHub repo, but there’s very little documentation and it’s not clear what this tool actual does. It does not mention if the command can be run on a host computer, or if it should be run on a Beaglebone.

I also found this Digikey article that describes how to build the kernel. It also describes how to copy a minimal Debian filesystem prepared by Robert Nelson.

To make things more confusing, there’s this InstallingDebianOn page that doesn’t seem to have any relation with Robert Nelson’s stuff.

I want to be able to generate my own Debian filesystem from scratch with only the minimal packages that we need. How do I go about doing this?

While I appreciate everything Robert Nelson has been doing for the community, it seems that he’s the only one who understands how to create these images, and his notes are scattered across several places on the web. Is it possible for anyone else to replace Robert if he gets hit by a bus? We shouldn’t be relying on a single person.

Any guidance would be appreciated.

So this is the tool we use to generate all the Production Images, due to design of my build farm, i do everything in 2 stages…

For example, looking at: Debian 11.x (Bullseye) - Monthly Snapshot - 2023-10-07 , specifically:

Media	AM335x	Minimal Snapshot
microSD	Download	am335x-debian-11.2-minimal-armhf-2022-01-01-2gb.img.xz 2
microSD	sha256sum	bea213675ed23bd551db55702dc3c1d34db23ed57493ebb8ff77953914a880ce

Index of /rootfs/
[ICO]	Name	Last modified	Size	Description
[PARENTDIR]	Parent Directory	 	-	 
[   ]	am57xx-debian-11.2-minimal-armhf-2022-01-01-2gb.bmap	2022-01-01 15:33	4.0K	 
[   ]	am57xx-debian-11.2-minimal-armhf-2022-01-01-2gb.img.xz	2022-01-01 14:03	207M	 
[   ]	am57xx-debian-11.2-minimal-armhf-2022-01-01-2gb.img.xz.sha256sum	2022-01-01 15:34	121	 
[   ]	am335x-debian-11.2-minimal-armhf-2022-01-01-2gb.bmap	2022-01-01 15:32	4.0K	 
[   ]	am335x-debian-11.2-minimal-armhf-2022-01-01-2gb.img.xz	2022-01-01 14:03	207M	 
[   ]	am335x-debian-11.2-minimal-armhf-2022-01-01-2gb.img.xz.sha256sum	2022-01-01 15:33	121	 
[   ]	debian-11.2-minimal-armhf-2022-01-01.tar.xz	2022-01-01 14:28	199M	 
[   ]	debian-11.2-minimal-armhf-2022-01-01.tar.xz.sha256sum	2022-01-01 14:28	110	 

1: Build generic image - (Currently a bank of BeagleBoard-x15’s, but you can use qemu…)

git clone
cd ./omap-image-builder/
./ -c configs/

This will generate: debian-11.2-minimal-armhf-2022-01-01.tar.xz

2: Convert Generic to BeagleBone specific, (big x86 server…)

sudo ./ --img-4gb am335x-debian-11.2-iot-armhf-2022-01-01  --dtb beaglebone --distro-bootloader --enable-cape-universal --enable-uboot-disable-pru --enable-bypass-bootup-scripts

Which gives us the final: am335x-debian-11.2-minimal-armhf-2022-01-01-2gb.img.xz

This is the config file that generates above:



I have stumbled upon Buildroot since asking my question, and it looks like it may be the ticket. I even found this Buildroot training guide that uses the BBB as a example.

I’m now also considering BusyBox instead of Debian now that I’ve found a way I to generate my own images.

If anyone has been tips to share concerning Buildroot and BBB, they are most certainly welcome!

Buildroot is a nice build system for users.


If I want to add/remove Debian packages from your minimal config, is it as simple as modifying the deb_include list? Will it automatically resolve dependencies if I add packages this way?

Start with removing packages from:


these are addon’s for pkgs not in debian… For example if you don’t have the wl1835 (WiFi/BLE), you don’t need bb-wl18xx-firmware… if you don’t have any Firmware devices, nuke… “include_firmware”… and work your way up the *.conf…

deb_additional_pkgs = packages that fail first pass of debootstrap, usually pretty small in minimal, but any iot/xfce example config will have more here…

deb_include = base pkg install, remove what you don’t need…

Basically hack away, you can open up scripts/ to see the order of everything, let us know if you have any issues, or want to try something… At one time we had a 64MB Debian image, but that was pre-systemd… all it had was apt/perl/bash…

Buildroot/Yocto will always be able to make a smaller install…


1 Like


I was unaware that this question existed or could even be asked w/ an appropriate answer. Thank you guys.


Yep, that’s the plan now, but knowing how to hack your minimal Debian image is good plan B.

Hi Robert,
I just found this, because I was searching for more details and documentation of your omap image builder.
Currently using buildroot, but since it creates only static busybox RFS, I decided to use your approach. Thanks for everything you gave to the community!

Can you please provide more details if it possible to use custom kernel, u-boot and how to use my MLO, u-boot.img, uImage or boot.scr (because as I know with newer u-boot versions uEnv.txt is no longer used) within this image builder?
Where to include dtb overlays?
Where to make modifications on RFS before final image is created, for example to set static IP address of my BBB, or to install my custom packages to be a part of the final image?
If there is any documentation which privides more details of image-builder it will be highly appreciated.

Thanks a lot!

‘possible’ everything is ‘possible’…

  • custom kernel

Are you setting a debian repo? Are you hosting that linux-image*.deb on your own network?

The easy way is to setup a debian ppa rep, here’s one simple example: / ti-linux-kernel-6.6.y-armhf · GitLab Index of /public

  • custom u-boot: has these two flags…

--spl = image-builder/tools/ at master · beagleboard/image-builder · GitHub

--bootloader = image-builder/tools/ at master · beagleboard/image-builder · GitHub

I’ve moved away from this, and just doing --distro-bootloader on a normal run, you’ll see this at the end:

Copying: packaged version of U-Boot
├── bb-u-boot-am335x-evm
│   ├──
│   ├──
│   ├──
│   ├── MLO
│   ├── u-boot-dtb.img
│   └── u-boot.img
└── bb-u-boot-am57xx-evm
    ├── MLO
    └── u-boot-dtb.img

3 directories, 11 files
Log: packaging rootfs: [armhf-rootfs-debian-bookworm.tar]
-rw-r--r-- 1 root root 1.1G Jan 23 18:14 /var/lib/jenkins/workspace/
Log: USER:jenkins
Log: complete

Just copy your custom MLO/u-boot-dtb.img above ^ before you run

boot.scr/uEnv.txt is all the old ways, use extlinux.conf, for am335x doesn’t really matter as all are supported…

  • Where to include dtb overlays?

Where ever you want to stick it, your in charge of boot.scr/uEnv.txt so you need to decide where you want to stick it…

Personally i chose in 2014: Beagleboard:U-boot partitioning layout 2.0 -

├── dtbs
│   └── 4.19.94-ti-r74
│       └── overlays

For BBB, i’ll probally never change that… While u-boot/etc has moved on to preferred locations, i’d like to not break something that’s been that way for 10 years…

On newer devices, we try to do extlinux.conf with this layout:

voodoo@bbai64-02:~$ tree -d /boot/firmware/
├── extlinux
├── overlays
└── ti

static IP is tricky, as the ‘second_pass’ of debootstrap runs in a chroot, so if you play with the network while in the chroot, it’ll fail… but yeah, a lot of that describes what is done here ls target/chroot/*

As far as docs… scripts/ is the main script… every function is enabled/disabled by config options.

For easy reading start with:

and compare with:

Both these make a simple rootfs that can be used with any armel/armhf board, but they contain no u-boot or kernel… so the end user needs to provide these…

If you run:

meld configs/eewiki_minfs_debian_bookworm_armel.conf configs/eewiki_minfs_debian_bookworm_armhf.conf

You can see how ‘armhf’ has a custom repo, where as ‘armel’ doesnt’…

Next compare configs/

we now have a custom kernel, u-boot, etc…

meld configs/eewiki_minfs_debian_bookworm_armel.conf configs/eewiki_minfs_debian_bookworm_armhf.conf