u-root embodies four different projects.
-
Go versions of many standard Linux tools, such as ls, cp, or shutdown. See cmds/core for most of these.
-
A way to compile many Go programs into a single binary with busybox mode.
-
A way to create initramfs (an archive of files) to use with Linux kernels, embeddable into firmware.
-
Go bootloaders that use
kexecto boot Linux or multiboot kernels such as ESXi, Xen, or tboot. They are meant to be used with LinuxBoot.
Make sure your Go version is >= 1.21.
Download and install u-root either via git:
git clone https://github.com/u-root/u-root
cd u-root
go installOr install directly with go:
go install github.com/u-root/u-root@latestNote
The u-root command will end up in $GOPATH/bin/u-root, so you may
need to add $GOPATH/bin to your $PATH.
Here are some examples of using the u-root command to build an initramfs.
git clone https://github.com/u-root/u-root
cd u-root
# Build an initramfs of all the Go cmds in ./cmds/core/... (default)
u-root
# Generate an archive with bootloaders
#
# core and boot are templates that expand to sets of commands
u-root core boot
# Generate an archive with only these given commands
u-root ./cmds/core/{init,ls,ip,dhclient,wget,cat,gosh}
# Generate an archive with all of the core tools with some exceptions
u-root core -cmds/core/{ls,losetup}Important
u-root works exactly when go build and go list work as well.
Note
The u-root tool is the same as the
mkuimage tool with some defaults
applied.
In the near future, uimage will replace u-root.
Tip
To just build Go busybox binaries, try out
gobusybox's makebb tool.
There are several ways to build multi-module command images using standard Go tooling.
$ mkdir workspace
$ cd workspace
$ git clone https://github.com/u-root/u-root
$ git clone https://github.com/u-root/cpu
$ go work init ./u-root
$ go work use ./cpu
$ u-root ./u-root/cmds/core/{init,gosh} ./cpu/cmds/cpud
$ cpio -ivt < /tmp/initramfs.linux_amd64.cpio
...
-rwxr-x--- 0 root root 6365184 Jan 1 1970 bbin/bb
lrwxrwxrwx 0 root root 2 Jan 1 1970 bbin/cpud -> bb
lrwxrwxrwx 0 root root 2 Jan 1 1970 bbin/gosh -> bb
lrwxrwxrwx 0 root root 2 Jan 1 1970 bbin/init -> bb
...
# Works for offline vendored builds as well.
$ go work vendor # Go 1.22 feature.
$ u-root ./u-root/cmds/core/{init,gosh} ./cpu/cmds/cpudWhen creating a new Go workspace is too much work, the goanywhere tool can
create one on the fly. This works only with local file system paths:
$ go install github.com/u-root/gobusybox/src/cmd/goanywhere@latest
$ goanywhere ./u-root/cmds/core/{init,gosh} ./cpu/cmds/cpud -- u-rootgoanywhere creates a workspace in a temporary directory with the given
modules, and then execs u-root in the workspace passing along the command
names.
Tip
While workspaces are good for local compilation, they are not meant to be checked in to version control systems.
For a non-workspace way of building multi-module initramfs images, read more
in the mkuimage README. (The u-root
tool is mkuimage with more defaults applied.)
You may also include additional files in the initramfs using the -files flag.
If you add binaries with -files are listed, their ldd dependencies will be
included as well.
$ u-root -files /bin/bash
$ cpio -ivt < /tmp/initramfs.linux_amd64.cpio
...
-rwxr-xr-x 0 root root 1277936 Jan 1 1970 bin/bash
...
drwxr-xr-x 0 root root 0 Jan 1 1970 lib/x86_64-linux-gnu
-rwxr-xr-x 0 root root 210792 Jan 1 1970 lib/x86_64-linux-gnu/ld-linux-x86-64.so.2
-rwxr-xr-x 0 root root 1926256 Jan 1 1970 lib/x86_64-linux-gnu/libc.so.6
lrwxrwxrwx 0 root root 15 Jan 1 1970 lib/x86_64-linux-gnu/libtinfo.so.6 -> libtinfo.so.6.4
-rw-r--r-- 0 root root 216368 Jan 1 1970 lib/x86_64-linux-gnu/libtinfo.so.6.4
drwxr-xr-x 0 root root 0 Jan 1 1970 lib64
lrwxrwxrwx 0 root root 42 Jan 1 1970 lib64/ld-linux-x86-64.so.2 -> /lib/x86_64-linux-gnu/ld-linux-x86-64.so.2
...You can determine placement with colons:
$ u-root -files "/bin/bash:sbin/sh"
$ cpio -ivt < /tmp/initramfs.linux_amd64.cpio
...
-rwxr-xr-x 0 root root 1277936 Jan 1 1970 sbin/sh
...For example on Debian, if you want to add two kernel modules for testing, executing your currently booted kernel:
$ u-root -files "$HOME/hello.ko:etc/hello.ko" -files "$HOME/hello2.ko:etc/hello2.ko"
$ qemu-system-x86_64 -kernel /boot/vmlinuz-$(uname -r) -initrd /tmp/initramfs.linux_amd64.cpiou-root has a very simple (exchangable) init system controlled by the -initcmd
and -uinitcmd command-line flags.
-
-initcmddetermines what/initis symlinked to.-initcmdmay be a u-root command name or a symlink target. -
-uinitcmdis run by the default u-root init after some basic file system setup. There is no default, users should optionally supply their own.-uinitcmdmay be a u-root command name with arguments or a symlink target with arguments. -
After running a uinit (if there is one), init will start a shell determined by the
-defaultshargument.
We expect most users to keep their -initcmd as init, but to
supply their own uinit for additional initialization or to immediately load
another operating system.
All three command-line args accept both a u-root command name or a target
symlink path. Only -uinitcmd accepts command-line arguments, however. For
example,
u-root -uinitcmd="echo Go Gopher" ./cmds/core/{init,echo,gosh}
cpio -ivt < /tmp/initramfs.linux_amd64.cpio
# ...
# lrwxrwxrwx 0 root root 12 Dec 31 1969 bin/uinit -> ../bbin/echo
# lrwxrwxrwx 0 root root 9 Dec 31 1969 init -> bbin/init
qemu-system-x86_64 -kernel $KERNEL -initrd /tmp/initramfs.linux_amd64.cpio -nographic -append "console=ttyS0"
# ...
# [ 0.848021] Freeing unused kernel memory: 896K
# 2020/05/01 04:04:39 Welcome to u-root!
# _
# _ _ _ __ ___ ___ | |_
# | | | |____| '__/ _ \ / _ \| __|
# | |_| |____| | | (_) | (_) | |_
# \__,_| |_| \___/ \___/ \__|
#
# Go Gopher
# ~/>Passing command line arguments like above is equivalent to passing the arguments
to uinit via a flags file in /etc/uinit.flags, see Extra Files.
Additionally, you can pass arguments to uinit via the uroot.uinitargs kernel
parameters, for example:
u-root -uinitcmd="echo Gopher" ./cmds/core/{init,echo,gosh}
cpio -ivt < /tmp/initramfs.linux_amd64.cpio
# ...
# lrwxrwxrwx 0 root root 12 Dec 31 1969 bin/uinit -> ../bbin/echo
# lrwxrwxrwx 0 root root 9 Dec 31 1969 init -> bbin/init
qemu-system-x86_64 -kernel $KERNEL -initrd /tmp/initramfs.linux_amd64.cpio -nographic -append "console=ttyS0 uroot.uinitargs=Go"
# ...
# [ 0.848021] Freeing unused kernel memory: 896K
# 2020/05/01 04:04:39 Welcome to u-root!
# _
# _ _ _ __ ___ ___ | |_
# | | | |____| '__/ _ \ / _ \| __|
# | |_| |____| | | (_) | (_) | |_
# \__,_| |_| \___/ \___/ \__|
#
# Go Gopher
# ~/>Note the order of the passed arguments in the above example.
The command you name must be present in the command set. The following will not work:
u-root -uinitcmd="echo Go Gopher" ./cmds/core/{init,gosh}
# 21:05:57 could not create symlink from "bin/uinit" to "echo": command or path "echo" not included in u-root build: specify -uinitcmd="" to ignore this error and build without a uinitYou can also refer to non-u-root-commands; they will be added as symlinks. We don't presume to know whether your symlink target is correct or not.
This will build, but not work unless you add a /bin/foobar to the initramfs.
u-root -uinitcmd="/bin/foobar Go Gopher" ./cmds/core/{init,gosh}This will boot the same as the above.
u-root -uinitcmd="/bin/foobar Go Gopher" -files /bin/echo:bin/foobar -files your-hosts-file:/etc/hosts ./cmds/core/{init,gosh}The effect of the above command:
- Sets up the uinit command to be /bin/foobar, with 2 arguments: Go Gopher
- Adds /bin/echo as bin/foobar
- Adds your-hosts-file as etc/hosts
- builds in the cmds/core/init, and cmds/core/gosh commands.
This will bypass the regular u-root init and just launch a shell:
u-root -initcmd=gosh ./cmds/core/{gosh,ls}
cpio -ivt < /tmp/initramfs.linux_amd64.cpio
# ...
# lrwxrwxrwx 0 root root 9 Dec 31 1969 init -> bbin/gosh
qemu-system-x86_64 -kernel $KERNEL -initrd /tmp/initramfs.linux_amd64.cpio -nographic -append "console=ttyS0"
# ...
# [ 0.848021] Freeing unused kernel memory: 896K
# failed to put myself in foreground: ioctl: inappropriate ioctl for device
# ~/>(It fails to do that because some initialization is missing when the shell is started without a proper init.)
Cross-OS and -architecture compilation comes for free with Go. In fact, every PR to the u-root repo is built against the following architectures: amd64, x86 (i.e. 32bit), mipsle, armv7, arm64, and ppc64le.
Further, we run integration tests on linux/amd64, and linux/arm64, using several CI systems. If you need to add another CI system, processor or OS, please let us know.
To cross compile for an ARM, on Linux:
GOARCH=arm u-rootIf you are on OSX, and wish to build for Linux on AMD64:
GOOS=linux GOARCH=amd64 u-rootA good way to test the initramfs generated by u-root is with qemu:
qemu-system-x86_64 -nographic -kernel path/to/kernel -initrd /tmp/initramfs.linux_amd64.cpioNote that you do not have to build a special kernel on your own, it is
sufficient to use an existing one. Usually you can find one in /boot.
If you don't have a kernel handy, you can also get the one we use for VM testing:
go install github.com/hugelgupf/vmtest/tools/runvmtest@latest
runvmtest -- bash -c "cp \$VMTEST_KERNEL ./kernel"It may not have all features you require, however.
For framebuffer support, append a VESA mode via the vga kernel parameter:
qemu-system-x86_64 \
-kernel path/to/kernel \
-initrd /tmp/initramfs.linux_amd64.cpio \
-append "vga=786"For a list of modes, refer to the Linux kernel documentation.
Some utilities, e.g., dhclient, require entropy to be present. For a speedy
virtualized random number generator, the kernel should have the following:
CONFIG_VIRTIO_PCI=y
CONFIG_HW_RANDOM_VIRTIO=y
CONFIG_CRYPTO_DEV_VIRTIO=yThen you can run your kernel in QEMU with a virtio-rng-pci device:
qemu-system-x86_64 \
-device virtio-rng-pci \
-kernel vmlinuz \
-initrd /tmp/initramfs.linux_amd64.cpioIn addition, you can pass your host's RNG:
qemu-system-x86_64 \
-object rng-random,filename=/dev/urandom,id=rng0 \
-device virtio-rng-pci,rng=rng0 \
-kernel vmlinuz \
-initrd /tmp/initramfs.linux_amd64.cpioSystemBoot is a set of bootloaders written in Go. It is meant to be a
distribution for LinuxBoot to create a system firmware + bootloader. All of
these use kexec to boot. The commands are in cmds/boot.
Parsers are available for GRUB, syslinux,
and other config files to make the transition to LinuxBoot easier.
-
pxeboot: a network boot client that uses DHCP and HTTP or TFTP to get a boot configuration which can be parsed as PXELinux or iPXE configuration files to get a boot program. -
boot: finds all bootable kernels on local disk, shows a menu, and boots them. Supports (basic) GRUB, (basic) syslinux, (non-EFI) BootLoaderSpec, and ESXi configurations.
More detailed information about the build process for a full LinuxBoot firmware image using u-root/systemboot and coreboot can be found in the LinuxBoot book chapter about LinuxBoot using coreboot, u-root and systemboot.
This project started as a loose collection of programs in u-root by various LinuxBoot contributors, as well as a personal experiment by Andrea Barberio that has since been merged in. It is now an effort of a broader community and graduated to a real project for system firmwares.
You can compress the initramfs. However, for xz compression, the kernel has some restrictions on the compression options and it is suggested to align the file to 512 byte boundaries:
xz --check=crc32 -9 --lzma2=dict=1MiB \
--stdout /tmp/initramfs.linux_amd64.cpio \
| dd conv=sync bs=512 \
of=/tmp/initramfs.linux_amd64.cpio.xzUsing the tcz command included in u-root, you can install tinycore linux
packages for things you want.
You can use QEMU NAT to allow you to fetch packages. Let's suppose, for example, you want bash. Once u-root is running, you can do this:
% tcz bashThe tcz command computes and fetches all dependencies. If you can't get to tinycorelinux.net, or you want package fetching to be faster, you can run your own server for tinycore packages.
You can do this to get a local server using the u-root srvfiles command:
% srvfiles -p 80 -d path-to-local-tinycore-packagesOf course you have to fetch all those packages first somehow :-)
You can build the cpio image created by u-root into a Linux kernel via the
CONFIG_INITRAMFS_SOURCE config variable or coreboot config variable, and
further embed the kernel image into firmware as a coreboot payload.
In the kernel and coreboot case, you may need to configure ethernet. We have a
dhclient command that works for both ipv4 and ipv6. Since v6 does not yet work
that well for most people, a typical invocation looks like this:
% dhclient -ipv4 -ipv6=falseOr, on newer linux kernels (> 4.x) boot with ip=dhcp in the command line, assuming your kernel is configured to work that way.
u-root can create an initramfs in two different modes, specified by -build:
-
gbbmode: One busybox-like binary comprising all the Go tools you ask to include. See the gobusybox README for how it works. In this mode, u-root copies and rewrites the source of the tools you asked to include to be able to compile everything into one busybox-like binary. -
binarymode: each specified binary is compiled separately and all binaries are added to the initramfs.
go get -u
go mod tidy
go mod vendorThe u-root command supports building with workspace vendoring and module vendoring. In both of those cases, if all dependencies are found in the vendored directories, the build happens completely offline.
Read more in the mkuimage README.
u-root also still supports GO111MODULE=off builds.
If you want to see u-root on real hardware, this board is a good start.
For information about contributing, including how we sign off commits, please see CONTRIBUTING.md.
Improving existing commands (e.g., additional currently unsupported flags) is
very welcome. In this case it is not even required to build an initramfs, just
enter the cmds/ directory and start coding. A list of commands that are on the
roadmap can be found here.
The sources of u-root.org are inside the docs/ directory and
are deployed to the gh-pages branch. The CNAME file is currently not part of the CI
which deploys to the branch which shall be evaluated if this makes futures deployments easier.
![dependabot[bot] avatar](https://avatars.githubusercontent.com/in/29110?v=4 "dependabot[bot]")
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent