Provided by: 3cpio_0.8.0-0ubuntu1_amd64 
NAME
3cpio - manage initrd cpio archives
SYNOPSIS
3cpio --count ARCHIVE
3cpio {-c|--create} [-v|--debug] [-C DIR] [ARCHIVE] < manifest
3cpio {-e|--examine} ARCHIVE
3cpio {-t|--list} [-v|--debug] ARCHIVE
3cpio {-x|--extract} [-v|--debug] [-C DIR] [-p] [-s NAME] [--force] ARCHIVE
3cpio {-V|--version}
3cpio {-h|--help}
DESCRIPTION
3cpio is a tool to manage initramfs cpio files for the Linux kernel. The Linux kernel’s initramfs buffer
format <https://www.kernel.org/doc/html/latest/driver-api/early-userspace/buffer-format.html> is based
around the newc or crc cpio formats. Multiple cpio archives can be concatenated and the last archive can
be compressed. Different compression algorithms can be used depending on what support was compiled into
the Linux kernel. 3cpio is tailored to initramfs cpio files and will not gain support for other cpio
formats.
Following compression formats are supported: bzip2, gzip, lz4, lzma, lzop, xz, zstd.
MODES
--count ARCHIVE
Print the number of concatenated cpio archives.
-c, --create [ARCHIVE]
Create a new cpio archive. Read the manifest from the standard input. See the MANIFEST section for
the description of the manifest format. Write the cpio archive to standard output or to the specified
ARCHIVE file if provided. The permission of the ARCHIVE file will be determined by the permission of
the input files (to avoid leaking sensitive information).
-e, --examine ARCHIVE
List the offsets of the cpio archives and their compression.
-t, --list ARCHIVE
List the contents of the cpio archives. By default only the file names are printed. If --verbose is
specified, the long listing format is used (similar to ls --long). If --debug is specified, the inode
is printed in addition to the long format.
-x, --extract ARCHIVE
Extract cpio archives.
-V, --version
Print version number.
-h, --help
Print help message.
OPTIONS
-C DIR, --directory=DIR
Change directory before performing any operation, but after opening the ARCHIVE. This option is only
taken into account in the --extract mode.
-p, --preserve-permissions
Set permissions of extracted files to those recorded in the archive (default for superuser). This
option is only taken into account in the --extract mode.
-s NAME, --subdir=NAME
Extract the cpio archives into separate sub-directories (using the given NAME plus an incrementing
number). This option is only taken into account in the --extract mode.
-v, --verbose
Verbose output. This option is only taken into account in the --extract and --list modes.
--debug
Debug output. This option is only taken into account in the --extract and --list modes.
--force
Force overwriting existing files. This option is only taken into account in the --extract mode.
MANIFEST
When generating initrd cpio archives, following manifest format will be used. The manifest is a text
format that is parsed line by line.
If the line starts with #cpio it is interpreted as section marker to start a new cpio. A compression may
be specified by adding a colon followed by the compression format and an optional compression level.
Example for a Zstandard-compressed cpio with compression level 9:
#cpio: zstd -9
All lines starting with # excluding #cpio (see above) will be treated as comments and will be ignored.
Each element in the line is separated by a tab and is expected to be one of the following file types:
<location> <name> file <mode> <uid> <gid> <mtime> <filesize>
<location> <name> dir <mode> <uid> <gid> <mtime>
<location> <name> block <mode> <uid> <gid> <mtime> <major> <minor>
<location> <name> char <mode> <uid> <gid> <mtime> <major> <minor>
<location> <name> link <mode> <uid> <gid> <mtime> <target>
<location> <name> fifo <mode> <uid> <gid> <mtime>
<location> <name> sock <mode> <uid> <gid> <mtime>
fifo is also known as named pipe (see fifo(7)).
In case an element is empty or equal to - it is treated as not specified and it is derived from the input
file.
<location>
Path of the input file. It can be left unspecified in case all other needed fields are specified (and
the file is otherwise empty). Limitation: The path must not start with #, be equal to -, or contain
tabs.
<name>
Path of the file inside the cpio. If the name is left unspecified it will be derived from <location>.
Limitation: The path must not be equal to - or contain tabs.
<mode>
File mode specified in octal.
<uid>
User ID (owner) of the file specified in decimal.
<gid>
Group ID of the file specified in decimal.
<mtime>
Modification time of the file specified as seconds since the Epoch (1970-01-01 00:00 UTC). The
specified time might be clamped by the time set in the SOURCE_DATE_EPOCH environment variable.
<filesize>
Size of the input file in bytes. 3cpio will fail in case the input file is smaller than the provided
file size.
<major>
Major block/character device number in decimal.
<minor>
Minor block/character device number in decimal.
<target>
Target of the symbolic link. Limitation: The target path must not be equal to - or contain tabs.
Limitations: Files cannot start with # (will be treated as comment), be equal to - (will be treated as
not specified), or contain tabs (will be split by tabs). These limitations of the manifest file are not
expected to cause problems in practice.
ENVIRONMENT VARIABLES
SOURCE_DATE_EPOCH
This environment variable will be taken into account when creating cpio archive. All modification
times that are newer than the time specified in "SOURCE_DATE_EPOCH" will be clamped. Compressors will
run with only one thread in case their multithreading implementation is not reproducible. The created
cpio archive will be reproducible across multiple runs.
EXIT STATUS
0
Success.
1
Failure.
EXAMPLES
List the number of cpio archives that an initramfs file contains:
$ 3cpio --count /boot/initrd.img
4
Examine the content of the initramfs cpio on an Ubuntu 24.04 system:
$ 3cpio --examine /boot/initrd.img
0 cpio
77312 cpio
7286272 cpio
85523968 zstd
This initramfs cpio consists of three uncompressed cpio archives followed by a Zstandard-compressed cpio
archive.
List the content of the initramfs cpio on an Ubuntu 24.04 system:
$ 3cpio --list /boot/initrd.img
.
kernel
kernel/x86
kernel/x86/microcode
kernel/x86/microcode/AuthenticAMD.bin
kernel
kernel/x86
kernel/x86/microcode
kernel/x86/microcode/.enuineIntel.align.0123456789abc
kernel/x86/microcode/GenuineIntel.bin
.
usr
usr/lib
usr/lib/firmware
usr/lib/firmware/3com
usr/lib/firmware/3com/typhoon.bin.zst
[...]
The first cpio contains only the AMD microcode. The second cpio contains only the Intel microcode. The
third cpio contains firmware files and kernel modules.
Extract the content of the initramfs cpio to the initrd subdirectory on an Ubuntu 24.04 system:
$ 3cpio --extract -C initrd /boot/initrd.img
$ ls initrd
bin cryptroot init lib lib.usr-is-merged run scripts var
conf etc kernel lib64 libx32 sbin usr
Create a cpio archive similar to the other cpio tools using the find command:
$ cd inputdir && find . | sort | 3cpio --create ../example.cpio
Due to its manifest file format support, 3cpio can create cpio archives without the need of copying files
into a temporary directory first. Example for creating an early microcode cpio image directly using the
system installed files:
$ cat manifest
- kernel dir 755 0 0 1751654557
- kernel/x86 dir 755 0 0 1752011622
/usr/lib/firmware/amd-ucode kernel/x86/microcode
/usr/lib/firmware/amd-ucode/microcode_amd_fam19h.bin kernel/x86/microcode/AuthenticAMD.bin
$ 3cpio --create amd-ucode.img < manifest
$ 3cpio --list --verbose amd-ucode.img
drwxr-xr-x 2 root root 0 Jul 4 20:42 kernel
drwxr-xr-x 2 root root 0 Jul 8 23:53 kernel/x86
drwxr-xr-x 2 root root 0 Jun 10 10:51 kernel/x86/microcode
-rw-r--r-- 1 root root 100684 Mar 23 22:42 kernel/x86/microcode/AuthenticAMD.bin
Example for creating an initrd image containing of an uncompressed early microcode cpio followed by a
Zstandard-compressed cpio:
$ cat manifest
#cpio
- kernel dir 755 0 0 1751654557
- kernel/x86 dir 755 0 0 1752011622
/usr/lib/firmware/amd-ucode kernel/x86/microcode
/usr/lib/firmware/amd-ucode/microcode_amd_fam19h.bin kernel/x86/microcode/AuthenticAMD.bin
#cpio: zstd -9
/
/bin
/usr
/usr/bin
/usr/bin/bash
# This is a comment. Leaving the remaining files as task for the reader.
$ 3cpio --create initrd.img < manifest
$ 3cpio --examine initrd.img
0 cpio
101332 zstd
$ 3cpio --list --verbose initrd.img
drwxr-xr-x 2 root root 0 Jul 4 20:42 kernel
drwxr-xr-x 2 root root 0 Jul 8 23:53 kernel/x86
drwxr-xr-x 2 root root 0 Jun 10 10:51 kernel/x86/microcode
-rw-r--r-- 1 root root 100684 Mar 23 22:42 kernel/x86/microcode/AuthenticAMD.bin
drwxr-xr-x 2 root root 0 Jun 5 14:11 .
lrwxrwxrwx 1 root root 7 Mar 20 2022 bin -> usr/bin
drwxr-xr-x 2 root root 0 Apr 20 2023 usr
drwxr-xr-x 2 root root 0 Jul 9 09:56 usr/bin
-rwxr-xr-x 1 root root 1740896 Mar 5 03:35 usr/bin/bash
SEE ALSO
bsdcpio(1), cpio(1), lsinitramfs(8), lsinitrd(1)
COPYING
Copyright © 2024-2025 Benjamin Drung. Free use of this software is granted under the terms of the ISC
License.
AUTHOR
Benjamin Drung
3cpio 0.5.1 2025-07-10 3CPIO(1)