Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/cbdevnet/jamdisk

Toolchain for creating custom initial RAM filesystems
https://github.com/cbdevnet/jamdisk

initramfs initramfs-generator initrd linux-boot

Last synced: 29 days ago
JSON representation

Toolchain for creating custom initial RAM filesystems

Awesome Lists containing this project

README 

        
# jamdisk



**jamdisk** is a minimal framework for building [initial RAM filesystems (initramfs)](https://wikipedia.org/wiki/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 `: Copy a binary executable to the initramfs. This also recursively includes shared libraries the binary depends on.

* `want_lib `: Include a shared library in your initramfs, including its dependencies.

* `want_module `: Include a kernel module and its dependencies in the initramfs. Included kernel modules will be loaded by the init script.

* `want_dir `: Include a complete directory by an absolute path (the directory will be available at the same path in the booted system).

* `want_file `: Include a single file by its absolute path (the file will be available at the same path in the booted system).



Note that all binaries, modules and files 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 `. 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](pxelinux.cfg).

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](LICENSE.txt)