Skip to main content


So what?

So, what is synth? synth is a script that reads a descriptive configuration (not shell variables) file and builds an ISO image based on those specifications: It is easier to maintain than piles of executable code. At first glance, you may be astonished, but if you think about it, all you need is to provide the most remarkable aspects of the system you want to build. If you want to see a proof, here’s how a configuration file that uses all the available options look like:

# Hi. I'm a comment.
# This is a synth file.

# System-related stuff.

BASE amd64/alpine



# Boot-related stuff.





The synth-file is organized based on keys, like PACKAGES and BASE. You can split lines by appending a comma (,) to the end of a line. Entry names can be left alone in a line. Comments start with a # and extend to the end of the line.

Let’s explain what does each key is for:

  • BASE: This is the only entry that cannot be omitted. It specifies the content with which the image will be populated initially. You can use Docker images or local or remote compressed tar archives. For the last two, you must prefix the path with either @LOCAL: or @URL: respectively. This image should have your repositories enabled, as otherwise you don’t have any other means of supplying your packages. The intention is that
  • UPDATES_URL: A URL providing a .zsync file. This is for compatibility with znx updates.
  • PACKAGE_MANAGER: In case no packages are specified, you can omit this entry; otherwise, here you specify the package manager present in the base image. Currently apt, pacman, and apk are supported. Pull requests are welcome!
  • PACKAGES: The packages that synth will install.

The values for the next entries must have the following syntax: /path/in/root:/destination/in/ISO.

  • KERNEL: A list of the kernel(s) that the image will have. synth will look for it after installing packages.
  • INITRAMFS: A list of the initramfs that the image will have. synth will look for it after installing packages.
  • GRUB_CONFIG: GRUB2 configuration files. synth will look for them after installing packages.
  • GRUB_THEME: An optional GRUB2 theme. synth will look for it after installing packages.

Apart from the ISO image, synth will also generate a sha256 hash and a .zsync file for the ISO file. With those, you’ll be left ready to deploy your ISO image. Happy hacking!.