netinit builds minimal initramfs archives with just what's needed for network booting over a remote NFS root.

This is useful when the kernel was not compiled with the options needed to handle it itself (i.e., CONFIG_IP_PNP for network auto-configuration and CONFIG_ROOT_NFS for mounting the remote NFS root).

When booting, the generated initramfs system will parse kernel command line options ip and nfsroot to setup the network and mount a remote NFS root.

These options must be formatted according to the kernel documentation.

Installation

Clone this source directory and run make.

Note: running the tool directly from the source directory is supported too.

Usage

Simple workflow

The simplest case is to generate an initramfs file for the current machine:

$ netinit [options...] <out-initramfs-file>                        # (A)

Two-steps workflow

If you want to build the initramfs archive on another machine (or perhaps in a different environment, e.g., in a docker container), then you should process in two steps.

First, run netinit with option --probe on the target machine:

target$ netinit --probe [options...] > <env-file>                  # (B1)

This command detects the kernel modules needed on this machine (mainly the modules related to the network interfaces), and it generates an "environment file" accordingly as output.

Then, use option --env <env-file> when you run netinit on the build machine:

build$ netinit --env <env-file> [options...] <out-initramfs-file>  # (B2)

One of the options you will likely use in this second step is --rootfs, to specify the root directory of the target system on this build machine. If not specified, / is assumed.

Simplified build workflow

This last workflow is a simplified variant of the two-steps workflow described above. If you know that the target OS has all needed modules compiled into the kernel image for handling the network interfaces and the network filesystem, then you can bypass the probing step on the target machine and directly run the build step, specifying option --no-modules:

build$ netinit --no-modules [options...] <out-initramfs-file>      # (C)

Options

• --probe: Probe-only mode. Checkout the 'Two-steps workflow' above for details.

• --protocol [nfs3,nfs4]: By default this tool builds an initramfs using NFS version 3 at boot time. Use --protocol nfs4 to use NFS version 4 instead. This option is allowed at step A, B1, and C.

• --no-modules: If generating an initramfs file for an embedded system which has all needed modules built into the kernel image, you can use this option to skip module detection. This will bypass the checks regarding the directory at /lib/modules/<kversion>. This option is not compatible with steps B1 and B2, since the purpose of the env-file is to indicate which modules are needed. You may use it with step A or step C.

• --rootfs /path/to/rootfs: Consider the target OS for which the initramfs is being built is at the specified path, not at /. Usable only with step B2 or step C.

Output format

The output file generated by step A, B2 or C is an uncompressed cpio archive. If the kernel supports compressed initramfs archives, e.g. zstd or gzip archives, feel free to compress it with the appropriate tool.