Man page - rpi-modcopy(1)

Packages contains this manual

Manual

RPI-MODCOPY

NAME
SYNOPSIS
DESCRIPTION
OPTIONS
SOURCE DIRECTORY
Module directory location
DESTINATION DIRECTORY
STDOUT
STDERR
EXIT STATUS
EXAMPLES
USB gadget mode (mass storage)
Encrypted root filesystem
Encrypted root with Adiantum (low-power devices)
Network boot with USB gadget
Using a module list file
Traditional /lib/modules layout
Preview without copying
REQUIREMENTS
SEE ALSO
AUTHOR

NAME

rpi-modcopy - selectively copy kernel modules and their dependencies

SYNOPSIS

rpi-modcopy [ OPTIONS ] SOURCE DEST

DESCRIPTION

rpi-modcopy copies a specified set of kernel modules, along with all their dependencies, from a source directory into a destination root filesystem. This is useful for building minimal Linux images that include only the kernel modules actually required.

The tool performs recursive dependency resolution: for each requested module, it identifies all dependent modules and includes them automatically. Built-in modules (compiled into the kernel itself) are recognised and handled safely.

Module aliases are supported in addition to literal module names. Common alias formats include:

•

Crypto aliases: crypto-xts(aes)

•

USB function aliases: usbfunc:ffs

•

Simple module names: dwc2 , ipv6 , fuse

OPTIONS

-m MODULE , --module= MODULE

Include the specified module (and its dependencies). May be specified multiple times. Can be a module name or a module alias.

-f FILE , --module-file= FILE

Read module names from FILE , one per line. Lines beginning with # are treated as comments and ignored. Empty lines are ignored. If FILE is - , read from standard input.

May be specified multiple times. All sources are combined additively with any --module arguments.

-k VERSION , --kernel-version= VERSION

Specify the kernel version string (e.g., 6.6.20+rpt-rpi-v8 ). Defaults to the currently running kernel as reported by uname -r .

-M PATH , --module-dir= PATH

Specify the module directory path relative to SOURCE . Defaults to /usr/lib/modules , which is correct for modern distributions including Raspberry Pi OS and Yocto-based systems. Use /lib/modules for traditional layouts.

-n , --dry-run

Show what would be copied without actually copying anything. Implies --verbose .

-v , --verbose

Produce verbose output, showing dependency resolution and files being copied.

--keep-going

Continue processing even if some modules cannot be found. A warning is printed for each missing module. The exit status will be non-zero if any modules were skipped.

-h , --help

Display usage information and exit.

SOURCE DIRECTORY

The SOURCE directory must contain kernel modules in the standard hierarchy:

SOURCE/<module-dir>/<kernel-version>/
├── kernel/
│ └── .../*.ko[.xz|.zst]
├── modules.builtin
├── modules.builtin.modinfo
└── modules.order

where <module-dir> is /usr/lib/modules by default, or as specified by --module-dir .

Module directory location

Kernel modules may be stored under lib/modules (traditional) or usr/lib/modules (modern distributions including Raspberry Pi OS, Yocto).

rpi-modcopy uses libkmod (3) directly for module lookup and dependency resolution, which handles both layouts seamlessly. The source directory is never modified.

The modules.builtin and modules.builtin.modinfo files must be present; they describe modules compiled directly into the kernel and are required for correct dependency resolution of built-in modules.

DESTINATION DIRECTORY

rpi-modcopy creates the following structure within DEST :

DEST/<module-dir>/<kernel-version>/
├── kernel/
│ └── <only requested modules + deps>
├── modules.alias
├── modules.alias.bin
├── modules.builtin
├── modules.builtin.modinfo
├── modules.dep
├── modules.dep.bin
├── modules.order
└── ...

The directory structure is created automatically. File permissions, ownership, timestamps, ACLs, and extended attributes are preserved from the source.

After copying, depmod (8) is run on the destination to generate the module dependency files ( modules.dep , modules.alias , etc.) for the copied subset of modules.

The modules.order file is filtered to include only the modules that were actually copied. This ensures consistency with modprobe implementations that reference this file.

Note: Most modern systems use a lib -> usr/lib symbolic link at the root filesystem level. If your target system expects modules at /lib/modules but you are using the default --module-dir=/usr/lib/modules , ensure the destination contains this symlink. The symlink is not created by rpi-modcopy ; it should be part of your base root filesystem setup.

STDOUT

In normal operation, rpi-modcopy produces no output on stdout.

With --verbose , the following is printed to stdout:

•

Each module being resolved and its dependencies

•

The list of files being copied

•

Summary statistics (number of modules copied, total size)

With --dry-run , the list of files that would be copied is printed to stdout, one per line.

STDERR

Warnings and errors are printed to stderr, including:

•

Modules not found (fatal unless --keep-going is specified)

•

Missing or invalid source directory structure

•

Permission errors

•

Errors from depmod (8)

EXIT STATUS

0

Success.

1

One or more modules could not be found (when using --keep-going ).

2

Invalid arguments or usage error.

3

Source directory missing or invalid structure.

4

Destination directory not writable or other I/O error.

5

No modules specified (neither --module nor --module-file provided).

EXAMPLES

USB gadget mode (mass storage)

Copy the USB FunctionFS module for implementing USB gadgets:

rpi-modcopy --module=usbfunc:ffs /mnt/kernel-pkg /mnt/rootfs

Encrypted root filesystem

Copy modules required for dm-crypt with AES-XTS encryption:

cat <<EOF | rpi-modcopy --module-file=- /mnt/kernel-pkg /mnt/rootfs
dm-crypt
algif_skcipher
crypto-xts(aes)
EOF

Encrypted root with Adiantum (low-power devices)

Copy modules for Adiantum encryption, suitable for devices without AES hardware acceleration:

rpi-modcopy --module=dm-crypt --module=crypto-nhpoly1305 \
--module=crypto-xchacha12 --module=crypto-adiantum \
/mnt/kernel-pkg /mnt/rootfs

Network boot with USB gadget

Copy modules for a fastboot-style image with USB gadget and network support:

rpi-modcopy --module-file=gadget-modules.list --module=ipv6 --module=dwc2 \
/mnt/kernel-pkg /mnt/rootfs

Using a module list file

Given a file modules.list containing:

# USB gadget support
dwc2
usbfunc:ffs

# Networking
ipv6

# Filesystem
fuse

Copy all listed modules:

rpi-modcopy --module-file=modules.list /mnt/kernel-pkg /mnt/rootfs

Traditional /lib/modules layout

For source directories using the traditional layout where modules are under lib/modules :

rpi-modcopy --module-dir=/lib/modules --module=dwc2 \
/mnt/kernel-pkg /mnt/rootfs

Preview without copying

Show what would be copied for a cryptroot setup:

rpi-modcopy --dry-run --module=dm-crypt --module=crypto-xtsæs \
/mnt/kernel-pkg /mnt/rootfs

REQUIREMENTS

rpi-modcopy requires the following to be available:

•

depmod (8) — typically at /sbin/depmod , used to generate module dependency files at the destination.

•

libkmod (3) — the kmod library, used for module lookup and dependency resolution.

SEE ALSO

depmod (8), modinfo (8), modprobe (8), libkmod (3), uname (1)

AUTHOR

Written for Raspberry Pi image building.