Toolchain for creating custom initial RAM filesystems
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
stowaway
.gitignore
LICENSE.txt
README.md
functions
init
jamdisk
pxelinux.cfg
stowaway.script
udhcpc.script

README.md

jamdisk

jamdisk is a minimal framework for building initial RAM filesystems (initramfs) files used for system initalization during boot. Usually, these are generated by your operating system (if you even need them) and simply mount the actual root file system before transitioning to it.

They can, however, be used as powerful minimal environments for things like system and disk management, disaster recovery or system setup.

jamdisk wants to make it easy to create initial RAM filesystems for such purposes by abstracting the complications (such as fiddling with library dependencies) away, while still staying as minimal as possible.

Usage

jamdisk supports two primary methods of customization. To create your own project, you can use one or both of them, though most projects will require both.

The project script

The project script is run by jamdisk while the image is being built and can be used to extend the ramdisk environment with additional tools, libraries and kernel modules. As most hardware won't work without the proper drivers loaded, this section is very important. If you don't use it, your project will be limited to the capabilites of the default BusyBox.

Simply create a file named projectname.script in your jamdisk directory and fill it with calls to the following functions:

  • want_bin <program binary>: Copy a binary executable to the initramfs. This also recursively includes shared libraries the binary depends on.
  • want_lib <shared library>: Include a shared library in your initramfs, including its dependencies.
  • want_module <kernel module name>: Include a kernel module and its dependencies in the initramfs. Included kernel modules will be loaded by the init script.

Note that all binaries and modules you want to include in the initramfs have to exist (i.e., be installed) on the system running jamdisk.

The project override directory

To add arbitrary files to your initramfs, such as program data or custom scripts, just create a directory named for your project. This directory will be copied into the initramfs as-is, preserving symlinks if possible.

If present, the jamdisk init script will execute the main binary within the root of your project, which may also be a script if the interpreter is correct and present within the initramfs. This can be used to implement menus and other custom functionality.

Creating the image

To create an initramfs for your project, run ./jamdisk <projectname>. To create a minimal initramfs running just a shell, you can omit the argument. Note that jamdisk requires read access to the binaries it is instructed to include, so if you want to copy privileged binaries (e.g., from /sbin) to your initramfs, you need to run jamdisk as root.

Booting the image

As jamdisk was created primarily with PXE boot environments in mind, it ships with an example pxelinux configuration file. jamdisk uses the kernel modules from the host on which it is run. This means that the appropriate kernel should be used to boot the resulting initramfs, though in many cases, the ABI remains stable so other versions might work. It is of course also possible to boot the resulting initramfs files from a bootloader of your choice (such as Grub, LiLo, etc).

Any parameters passed to the initramfs (e.g. via an APPEND directive) are present in the main script of your project.

When booting with PXELinux, setting the SYSAPPEND 2 flag provides the init script with the MAC address of the interface used to PXE boot the system. This information can then be used by the script to configure networking.

The stowaway project

stowaway was the original reason for the creation of jamdisk. It provides a simple, bootable interface to create and restore full-disk host backups quickly and without much configuration.

Author & Licensing

See LICENSE.txt