Skip to main content

Customizing the Filesystem with Overlays

Tachyon’s build system uses an overlay mechanism to introduce custom files, configurations, and even software packages into the base Ubuntu 24.04 filesystem. This approach cleanly separates our modifications from the stock Ubuntu image. By creating or editing overlays in the tachyon-overlays repository, you can add your own files to the image or tweak system settings. This page outlines how overlays work and how to use them to customize the filesystem.

What is an Overlay?​

An overlay is essentially a set of changes to apply on top of the root filesystem. These changes can include:

  • Adding new files or directories.
  • Replacing or modifying existing configuration files.
  • Installing additional Debian packages or running commands (via scripts) to configure the image.

Each overlay is typically defined in a directory structure that mirrors the target filesystem, along with optional scripts to execute.

For example, an overlay might have a structure:

my-overlay/
├── files/
│   ├── etc/
│   │   └── myconfig.conf
│   └── usr/
│       └── local/bin/myscript.sh
└── scripts/
└── 10-run-after-chroot.sh
└── overlay.json

The overlay.json file contains a structure of what operations to run (copy files in, run a script etc..).

In this case, this hypothetical overlay would copy myconfig.conf to /etc/ and myscript.sh to /usr/local/bin/ in the image. The script 10-run-after-chroot.sh might contain shell commands that run inside the mounted image (chroot environment) – for instance, to install a package or set up user accounts.

Overlay Stacks​

An overlay by itself usually provides one set of related changes. A stack is an ordered list of overlays to apply for a particular image variant. In the build command, we saw INPUT_OVERLAY_STACK=ubuntu-headless-24.04. This corresponds to a definition in tachyon-overlays/stacks that lists which overlays to apply for the “ubuntu-headless-24.04” build.

By editing a stack or adding overlays, you can customize what ends up in the final image.

Using the Tachyon Overlay Tool​

The tachyon-overlay-tool automates applying overlays. It will:

  • Mount the base image’s root filesystem.
  • For each overlay in the stack, copy files from the overlay into the mount (overlaying them).
  • Enter a chroot environment on the mounted filesystem to run any overlay scripts (so from the script’s perspective, it’s operating inside the new system).
  • Unmount and finalize the image.

Locating Overlay Definitions​

In the tachyon-overlays repository, look for:

  • A directory structure for overlays, possibly overlays/<name>/... as shown in the example above.
  • Stack definitions, possibly in a subfolder like stacks/ or in a configuration file (some build systems use a simple text file listing overlays for a given stack).

Open the tachyon-overlays repo and identify the overlay you want to modify or the place to add new ones. Some overlays likely exist for:

  • particle-core (common Particle additions like the agent or keys),
  • enable-ssh (ensuring SSH is on for headless),
  • disable-gui (for headless),
  • etc.

Adding a File via an Overlay​

Let’s say you want to include a custom startup script /usr/local/bin/hello.sh in the image:

  1. Choose or create an overlay. If there’s already an overlay for custom user scripts, you might add to it. Otherwise, create a new overlay directory under tachyon-overlays/overlays/ (for example, user-customizations/).
  2. Inside that overlay directory, create a files/ subdirectory that mimics the filesystem. For our file:
overlays/user-customizations/files/usr/local/bin/hello.sh

Put your script in that path. Also ensure it has the proper permissions (you may need to use a Git attribute or a script to set executable bit if needed).

  1. Optionally, if any commands must run (like setting permissions or adding a symlink), create a script in overlays/user-customizations/scripts/. For instance:
overlays/user-customizations/scripts/50-set-perms.sh

with contents:

#!/bin/bash
chmod +x /usr/local/bin/hello.sh

This script will execute inside the chroot after files are copied, ensuring the script is executable.

  1. Create a new overlay.json and put into the root
overlays/user-customizations/overlay.json

Copy an existing file and update according to your needs.

  1. Include your overlay in a stack. If this overlay should apply to both headless and desktop images, you might add it to both ubuntu-headless-24.04 and ubuntu-desktop-24.04 stacks. Locate the stack definition (perhaps a YAML in stacks/ubuntu-headless-24.04.yml or similar) and add an entry for user-customizations in the sequence.
  2. Re-run the build (as described in the build page) with the updated overlay stack. The overlay tool will pick up your changes:

  • It will copy hello.sh into the image’s /usr/local/bin.

  • It will execute 50-set-perms.sh inside the image, setting the executable bit.

    1. After flashing or booting the new image, verify that your file is present (ls /usr/local/bin/hello.sh) and has correct permissions.

Installing Packages via Overlays​

If you want to pre-install additional Debian packages in the image (for example, a Python library or a tool like htop), you can do so in an overlay script:

  • The overlay script can run apt-get update and apt-get install -y package inside the chroot. Because the image is chrooted with networking enabled, it will fetch from Ubuntu repos. (Alternatively, you could include the .deb files in the overlay and use dpkg -i to install them offline.)
  • There are multiple overlays doing package installs so apt-get update should already be run. ` Be mindful of the image size – installing many packages can significantly increase the image footprint.

Modifying Existing Configs​

To override an existing file (say you want to change a setting in /etc/sysctl.conf):

  • You can either copy a full modified file in the overlay (which will replace the original in the image), or
  • Use a script to append or edit it (for example, a script with sed or echo >> to tweak a line without replacing the whole file).

Directly replacing a config is straightforward: put the new file under files/etc/sysctl.conf in an overlay. However, if your change should be merged with future changes from Ubuntu updates, sometimes a script approach is more maintainable (to just toggle one value).

Testing Overlay Changes​

Overlay modifications don’t require compiling code, but you should still test them:

  • After building the image with a new overlay, boot it up.
  • Confirm that files landed in the right places and with correct content.
  • Ensure any services or settings effected by those files behave as expected (for example, if you added an init script, does it run? If you changed a config, is the new setting applied?).

If something didn’t apply:

  • Check the build logs: the overlay tool usually logs which overlays and files it applied. Look for your overlay’s name to ensure it ran.
  • Perhaps the stack file wasn’t updated correctly, or a script failed (sometimes a script error can halt that overlay’s application).

You can also mount the built image on your dev machine (using losetup/mount on the image file) to inspect its contents before flashing, as a quicker iteration cycle.

Contributing Overlay Changes​

Since overlays mainly deal with adding Particle or user-specific customizations, contributions here could be:

  • New overlays that add support for a certain use case (for example, an overlay to set up a particular hardware accessory or enable a certain mode).
  • Improvements to existing overlays (like cleaning up config, fixing install scripts).

Submit changes to the tachyon-overlays repository via pull request. Make sure to document what the overlay does in a README if one exists for the repo, and follow any naming conventions.

One thing to note: overlays can be powerful, but also can risk breaking the image if used improperly (e.g., installing conflicting packages). Keep them focused and tested.

With the knowledge of overlays, you have full control over what goes into the Tachyon OS image – from the kernel and bootloader, through the hardware description, up to the user-space software and configs.

The final page in our guide will summarize how you can get involved with this development effort, including where to find support, how to share your contributions, and the process for working with the Particle team and community on Ubuntu 24.04 for Tachyon.