README
¶
u-root
Description
u-root contains simple Go versions of many standard Linux tools, similar to busybox. It's a pure Go userland!
u-root stands for "universal root". It can create an initramfs in two different modes:
-
source mode: Go toolchain binaries + simple shell + Go source for tools to be compiled on the fly by the shell.
When you try to run a command that is not built, it is compiled first and stored in tmpfs. From that point on, when you run the command, you get the one in tmpfs. Don't worry: the Go compiler is pretty fast.
-
bb mode: One busybox-like binary comprising all the Go tools you ask to include.
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.
Usage
Make sure your Go version is 1.11. Make sure your GOPATH is set
up correctly.
Download and install u-root:
go get github.com/u-root/u-root
You can now use the u-root command to build an initramfs. Here are some examples:
# Build a bb-mode cpio initramfs of all the Go cmds in ./cmds/...
u-root -build=bb
# Generate a cpio archive named initramfs.cpio.
u-root -format=cpio -build=source -o initramfs.cpio
# Generate a bb-mode archive with only these given commands.
u-root -format=cpio -build=bb ./cmds/{init,ls,ip,dhclient,wget,tcz,cat}
-format=cpio and -build=source are the default flag values. The default set
of packages included is all packages in github.com/u-root/u-root/cmds/....
In addition to using paths to specify Go source packages to include, you may
also use Go package import paths (e.g. golang.org/x/tools/imports) to include
commands. Only the main package and its dependencies in those source
directories will be included. For example:
You can build the initramfs built by u-root into the kernel via the
CONFIG_INITRAMFS_SOURCE config variable or you can load it separately via an
option in for example Grub or the QEMU command line or coreboot config variable.
A good way to test the initramfs generated by u-root is with qemu:
qemu-system-x86_64 -kernel path/to/kernel -initrd /tmp/initramfs.linux_amd64.cpio
Note 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.
NOTE: you can compress the initramfs but for xz compression, the kernel has some restrictions on the compression options and it is suggested to align the file to 512 byte boundaries
shell xz --check=crc32 -9 --lzma2=dict=1MiB --stdout /tmp/initramfs.linux_amd64.cpio \ | dd conv=sync bs=512 of=/tmp/initramfs.linux_amd64.cpio.xz
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. As example for Debian, you want to add two kernel modules for
testing, executing your currently booted kernel:
NOTE: these files will be placed in the
$HOMEdir in the initramfs.
u-root -files "$HOME/hello.ko $HOME/hello2.ko"
qemu-system-x86_64 -kernel /boot/vmlinuz-$(uname -r) -initrd /tmp/initramfs.linux_amd64.cpio
To specify the location in the initramfs, use <sourcefile>:<destinationfile>.
For example:
u-root -files "root-fs/usr/bin/runc:usr/bin/run"
Getting Packages of TinyCore
Using 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 bash
The 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-packages
Of course you have to fetch all those packages first somehow :-)
Build an Embeddable U-root
You can build this environment into a kernel as an initramfs, and further embed that into firmware as a coreboot payload.
In the kernel and coreboot case, you 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=false
Or, on newer linux kernels (> 4.x) boot with ip=dhcp in the command line, assuming your kernel is configured to work that way.
Updating Dependencies
# The latest released version of dep is required:
curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh
dep ensure
Hardware
If you want to see u-root on real hardware, this board is a good start.
Contributions
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.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmds
|
|
|
ansi
command
Print ansi escape sequences.
|
Print ansi escape sequences. |
|
basename
command
Basename return name with leading path information removed.
|
Basename return name with leading path information removed. |
|
boot
command
|
|
|
boot2
command
|
|
|
bzimage
command
bzImage is used to modify bzImage files.
|
bzImage is used to modify bzImage files. |
|
cat
command
Cat concatenates files and prints to stdout.
|
Cat concatenates files and prints to stdout. |
|
cbmem
command
cbmem prints out coreboot mem table information in JSON by default, and also implements the basic cbmem -list and -console commands.
|
cbmem prints out coreboot mem table information in JSON by default, and also implements the basic cbmem -list and -console commands. |
|
chmod
command
Change modifier bits of a file.
|
Change modifier bits of a file. |
|
chroot
command
|
|
|
cksum
command
|
|
|
cmp
command
Cmp compares two files and prints a message if their contents differ.
|
Cmp compares two files and prints a message if their contents differ. |
|
comm
command
Perform a set comparisons over two files.
|
Perform a set comparisons over two files. |
|
console
command
console implements a basic console.
|
console implements a basic console. |
|
cp
command
Copy files.
|
Copy files. |
|
cpio
command
cpio operates on cpio files using a cpio package It only implements basic cpio options.
|
cpio operates on cpio files using a cpio package It only implements basic cpio options. |
|
date
command
Print the date.
|
Print the date. |
|
dd
command
Convert and copy a file.
|
Convert and copy a file. |
|
df
command
df reports details of mounted filesystems
|
df reports details of mounted filesystems |
|
dhclient
command
dhclient sets up DHCP.
|
dhclient sets up DHCP. |
|
dirname
command
dirname prints out the directory name of one or more args.
|
dirname prints out the directory name of one or more args. |
|
dmesg
command
Read the system log.
|
Read the system log. |
|
echo
command
Echo writes its arguments separated by blanks and terminated by a newline on the standard output.
|
Echo writes its arguments separated by blanks and terminated by a newline on the standard output. |
|
elvish
command
Elvish is a cross-platform shell, supporting Linux, BSDs and Windows.
|
Elvish is a cross-platform shell, supporting Linux, BSDs and Windows. |
|
elvish/build
Package build contains build information.
|
Package build contains build information. |
|
elvish/edit
Package edit implements a command line editor.
|
Package edit implements a command line editor. |
|
elvish/edit/eddefs
Package eddefs contains types used in the Editor.
|
Package eddefs contains types used in the Editor. |
|
elvish/edit/highlight
Package highlight implements syntax highlighting for Elvish code.
|
Package highlight implements syntax highlighting for Elvish code. |
|
elvish/edit/location
Package location implements the location mode for the editor.
|
Package location implements the location mode for the editor. |
|
elvish/edit/prompt
Package prompt implements the prompt subsystem of the editor.
|
Package prompt implements the prompt subsystem of the editor. |
|
elvish/edit/tty
Package tty provides terminal functionality for the Elvish editor.
|
Package tty provides terminal functionality for the Elvish editor. |
|
elvish/edit/ui
Package ui contains types that may be used by different editor frontends.
|
Package ui contains types that may be used by different editor frontends. |
|
elvish/eval
Package eval handles evaluation of parsed Elvish code and provides runtime facilities.
|
Package eval handles evaluation of parsed Elvish code and provides runtime facilities. |
|
elvish/eval/bundled
Package bundled keeps bundled modules.
|
Package bundled keeps bundled modules. |
|
elvish/eval/vals
Package vals contains basic facilities for manipulating values used in the Elvish runtime.
|
Package vals contains basic facilities for manipulating values used in the Elvish runtime. |
|
elvish/eval/vars
Package vars contains basic types for manipulating Elvish variables.
|
Package vars contains basic types for manipulating Elvish variables. |
|
elvish/getopt
Package getopt implements a command-line argument parser.
|
Package getopt implements a command-line argument parser. |
|
elvish/glob
Package glob implements globbing for elvish.
|
Package glob implements globbing for elvish. |
|
elvish/parse
Package parse implements the elvish parser.
|
Package parse implements the elvish parser. |
|
elvish/parse/parseutil
Package parseutil contains utilities built on top of the parse package.
|
Package parseutil contains utilities built on top of the parse package. |
|
elvish/program
Package program provides the entry point to Elvish.
|
Package program provides the entry point to Elvish. |
|
elvish/program/shell
Package shell is the entry point for the terminal interface of Elvish.
|
Package shell is the entry point for the terminal interface of Elvish. |
|
elvish/runtime
Package runtime assembles the Elvish runtime.
|
Package runtime assembles the Elvish runtime. |
|
elvish/store/storedefs
Package storedefs contains definitions used by the store package.
|
Package storedefs contains definitions used by the store package. |
|
elvish/sys
Package sys provide convenient wrappers around syscalls.
|
Package sys provide convenient wrappers around syscalls. |
|
elvish/tt
Package tt supports table-driven tests with little boilerplate.
|
Package tt supports table-driven tests with little boilerplate. |
|
elvish/util
Package util contains utility functions.
|
Package util contains utility functions. |
|
false
command
Returns 1.
|
Returns 1. |
|
field
command
The `field` command reads newline-separated lines of data from either the standard input or the specified files.
|
The `field` command reads newline-separated lines of data from either the standard input or the specified files. |
|
find
command
Find finds files.
|
Find finds files. |
|
free
command
free reports usage information for physical memory and swap space.
|
free reports usage information for physical memory and swap space. |
|
freq
command
Freq reads the given files (default standard input) and prints histograms of the character frequencies.
|
Freq reads the given files (default standard input) and prints histograms of the character frequencies. |
|
gpgv
command
gpgv validates a signature against a file.
|
gpgv validates a signature against a file. |
|
gpt
command
gpt reads and writes GPT headers.
|
gpt reads and writes GPT headers. |
|
grep
command
Concurrent, parallel grep.
|
Concurrent, parallel grep. |
|
gzip
command
|
|
|
hexdump
command
Prints files in hexadecimal.
|
Prints files in hexadecimal. |
|
hostname
command
Print the system's hostname.
|
Print the system's hostname. |
|
id
command
Synopsis:
|
Synopsis: |
|
init
command
Build commands in background processes.
|
Build commands in background processes. |
|
insmod
command
Insert a module into the Linux kernel
|
Insert a module into the Linux kernel |
|
installcommand
command
|
|
|
io
command
io reads and writes to physical memory and ports.
|
io reads and writes to physical memory and ports. |
|
ip
command
|
|
|
kexec
command
kexec executes a new kernel over the running kernel (u-root).
|
kexec executes a new kernel over the running kernel (u-root). |
|
kill
command
Kill kills processes.
|
Kill kills processes. |
|
lddfiles
command
lddfiles prints the arguments and all .so dependencies of those arguments
|
lddfiles prints the arguments and all .so dependencies of those arguments |
|
less
command
less pages through a file
|
less pages through a file |
|
ln
command
Ln makes links to files.
|
Ln makes links to files. |
|
losetup
command
Setup loop devices.
|
Setup loop devices. |
|
ls
command
Ls prints the contents of a directory.
|
Ls prints the contents of a directory. |
|
lsmod
command
List modules currently loaded in the Linux kernel
|
List modules currently loaded in the Linux kernel |
|
md5sum
command
|
|
|
mkdir
command
Mkdir makes a new directory.
|
Mkdir makes a new directory. |
|
mkfifo
command
mkfifo creates a named pipe.
|
mkfifo creates a named pipe. |
|
mknod
command
Unmount a filesystem at the specified path.
|
Unmount a filesystem at the specified path. |
|
mktemp
command
Mktemp makes a temporary file (or directory)
|
Mktemp makes a temporary file (or directory) |
|
mm
command
|
|
|
modprobe
command
modprobe - Add and remove modules from the Linux Kernel
|
modprobe - Add and remove modules from the Linux Kernel |
|
more
command
More pages through files without any terminal trickery.
|
More pages through files without any terminal trickery. |
|
mount
command
Mount a filesystem at the specified path.
|
Mount a filesystem at the specified path. |
|
msr
command
msr lets you read and write an msr for one or more cores.
|
msr lets you read and write an msr for one or more cores. |
|
mv
command
Mv renames files and directories.
|
Mv renames files and directories. |
|
netcat
command
Netcat pipes over the network.
|
Netcat pipes over the network. |
|
ntpdate
command
simple ntpd daemon in Go.
|
simple ntpd daemon in Go. |
|
pci
command
pci: show pci bus vendor ids and other info
|
pci: show pci bus vendor ids and other info |
|
pe
command
Dump the headers of a PE file.
|
Dump the headers of a PE file. |
|
ping
command
Send icmp packets to a server to test network connectivity.
|
Send icmp packets to a server to test network connectivity. |
|
printenv
command
Print environment variables.
|
Print environment variables. |
|
ps
command
Print process information.
|
Print process information. |
|
pwd
command
Print name of current directory.
|
Print name of current directory. |
|
pxeboot
command
|
|
|
readlink
command
readlink display value of symbolic link file.
|
readlink display value of symbolic link file. |
|
rm
command
Delete files.
|
Delete files. |
|
rmmod
command
Remove a module from the Linux kernel
|
Remove a module from the Linux kernel |
|
rsdp
command
rsdp allows to determine the ACPI RSDP structure address which could be passed to the boot command later on It must be executed at the system init as it relies on scanning the kernel messages which could be quickly filled up in some cases
|
rsdp allows to determine the ACPI RSDP structure address which could be passed to the boot command later on It must be executed at the system init as it relies on scanning the kernel messages which could be quickly filled up in some cases |
|
scp
command
Scp copies files between hosts on a network.
|
Scp copies files between hosts on a network. |
|
seq
command
Print a sequence of numbers.
|
Print a sequence of numbers. |
|
shasum
command
|
|
|
shutdown
command
shutdown halts, suspends, or reboots.
|
shutdown halts, suspends, or reboots. |
|
sleep
command
Delay for the specified amount of time.
|
Delay for the specified amount of time. |
|
sort
command
Sort lines.
|
Sort lines. |
|
sos
command
|
|
|
srvfiles
command
Serve files on the network.
|
Serve files on the network. |
|
sshd
command
|
|
|
strace
command
strace is a simple multi-process tracer.
|
strace is a simple multi-process tracer. |
|
strings
command
Strings finds printable strings.
|
Strings finds printable strings. |
|
stty
command
The command works like this: stty [verb] [options] Verbs are: dump -- dump the json of the struct to stdout load -- read a json file from stdin and use it to set raw -- convenience command to set raw cooked -- convenience command to set cooked In common stty usage, options may be specified without a verb.
|
The command works like this: stty [verb] [options] Verbs are: dump -- dump the json of the struct to stdout load -- read a json file from stdin and use it to set raw -- convenience command to set raw cooked -- convenience command to set cooked In common stty usage, options may be specified without a verb. |
|
switch_root
command
|
|
|
sync
command
sync command in Go.
|
sync command in Go. |
|
tac
command
tac concatenates files and prints to stdout in reverse order, file by file
|
tac concatenates files and prints to stdout in reverse order, file by file |
|
tail
command
|
|
|
tcz
command
|
|
|
tee
command
Tee transcribes the standard input to the standard output and makes copies in the files.
|
Tee transcribes the standard input to the standard output and makes copies in the files. |
|
timesos
command
|
|
|
tr
command
|
|
|
true
command
Returns 0.
|
Returns 0. |
|
truncate
command
Truncate - shrink or extend the size of a file to the specified size
|
Truncate - shrink or extend the size of a file to the specified size |
|
umount
command
Unmount a filesystem at the specified path.
|
Unmount a filesystem at the specified path. |
|
uname
command
Print build information about the kernel and machine.
|
Print build information about the kernel and machine. |
|
uniq
command
Uniq removes repeated lines.
|
Uniq removes repeated lines. |
|
unshare
command
Disassociate parts of the process execution context.
|
Disassociate parts of the process execution context. |
|
upspinsos
command
|
|
|
validate
command
This program validates a file by verifying a checksum and a signature file.
|
This program validates a file by verifying a checksum and a signature file. |
|
vboot
command
|
|
|
wc
command
Wc counts lines, words, runes, syntactically–invalid UTF codes.
|
Wc counts lines, words, runes, syntactically–invalid UTF codes. |
|
wget
command
Wget reads one file from a url and writes to stdout.
|
Wget reads one file from a url and writes to stdout. |
|
which
command
Which locates a command.
|
Which locates a command. |
|
wifi
command
|
|
|
xinit
command
|
|
|
zimage
command
zimage dumps the header of a zImage.
|
zimage dumps the header of a zImage. |
|
examples
|
|
|
sos
command
|
|
|
uinit
command
This is a basic init script.
|
This is a basic init script. |
|
testcmd/gotest/uinit
command
|
|
|
testcmd/helloworld/uinit
command
|
|
|
testcmd/io/uinit
command
|
|
|
testcmd/kexec/uinit
command
|
|
|
testcmd/pxeserver
command
|
|
|
pkg
|
|
|
abi
Package abi describes the interface between a kernel and userspace.
|
Package abi describes the interface between a kernel and userspace. |
|
bb/cmd
command
|
|
|
binary
Package binary translates between select fixed-sized types and a binary representation.
|
Package binary translates between select fixed-sized types and a binary representation. |
|
bzimage
package bzImage implements encoding.UnmarshalBinary for bzImage files.
|
package bzImage implements encoding.UnmarshalBinary for bzImage files. |
|
cmdline
The cmdline package provides a parser and convenience functions for reading configuration data from /proc/cmdline it's conformant with https://www.kernel.org/doc/html/v4.14/admin-guide/kernel-parameters.html, though making 'var_name' and 'var-name' equivalent may need to be done separately.
|
The cmdline package provides a parser and convenience functions for reading configuration data from /proc/cmdline it's conformant with https://www.kernel.org/doc/html/v4.14/admin-guide/kernel-parameters.html, though making 'var_name' and 'var-name' equivalent may need to be done separately. |
|
complete
Package complete implements a simple completion package designed to be used in shells and other programs.
|
Package complete implements a simple completion package designed to be used in shells and other programs. |
|
cpio
Package cpio implements utilities for reading and writing cpio archives.
|
Package cpio implements utilities for reading and writing cpio archives. |
|
dhclient
Package dhclient provides a unified interface for interfacing with both DHCPv4 and DHCPv6 clients.
|
Package dhclient provides a unified interface for interfacing with both DHCPv4 and DHCPv6 clients. |
|
dhcp6client
Package dhcp6client implements a DHCPv6 client as per RFC 3315.
|
Package dhcp6client implements a DHCPv6 client as per RFC 3315. |
|
forth
Package forth implements Forth parsing, which allows programs to use forth-like syntax to manipulate a stack of Cells.
|
Package forth implements Forth parsing, which allows programs to use forth-like syntax to manipulate a stack of Cells. |
|
gpt
gpt implements reading and writing of GUID Partition tables.
|
gpt implements reading and writing of GUID Partition tables. |
|
kexecbin
Package kexecbin offers a kexec API via a callout to kexec-tools.
|
Package kexecbin offers a kexec API via a callout to kexec-tools. |
|
ldd
ldd returns all the library dependencies of a list of file names.
|
ldd returns all the library dependencies of a list of file names. |
|
lockfile
Package lockfile coordinates process-based file locking.
|
Package lockfile coordinates process-based file locking. |
|
loop
Package loop provides an interface to interacting with Linux loop devices.
|
Package loop provides an interface to interacting with Linux loop devices. |
|
mount
The mount package implements functions for mounting and unmounting file systems and defines the mount interface.
|
The mount package implements functions for mounting and unmounting file systems and defines the mount interface. |
|
multiboot
Multiboot header as defined in https://www.gnu.org/software/grub/manual/multiboot/multiboot.html#Header-layout
|
Multiboot header as defined in https://www.gnu.org/software/grub/manual/multiboot/multiboot.html#Header-layout |
|
multiboot/internal/trampoline
Trampoline sets machine to a specific state defined by multiboot v1 spec and boots the final kernel.
|
Trampoline sets machine to a specific state defined by multiboot v1 spec and boots the final kernel. |
|
null
Package null extends ioutil.Discard and adds an io.WriteCloser and WriteNameCloser for use within u-root.
|
Package null extends ioutil.Discard and adds an io.WriteCloser and WriteNameCloser for use within u-root. |
|
pty
Package pty provides basic pty support.
|
Package pty provides basic pty support. |
|
pxe
Package pxe aims to implement the PXE specification.
|
Package pxe aims to implement the PXE specification. |
|
qemu
Package qemu provides a Go API for starting QEMU VMs.
|
Package qemu provides a Go API for starting QEMU VMs. |
|
strace
Package strace implements the logic to print out the input and the return value of each traced syscall.
|
Package strace implements the logic to print out the input and the return value of each traced syscall. |
|
termios
Package termios implements basic termios operations including getting a tty struct, termio struct, a winsize struct, and setting raw mode.
|
Package termios implements basic termios operations including getting a tty struct, termio struct, a winsize struct, and setting raw mode. |
|
uroot/test/foo
command
|
|
|
uroot/test/gopath1/src/foo
command
|
|
|
uroot/test/gopath1/src/os
command
|
|
|
uroot/test/gopath2/src/mypkga
command
|
|
|
uroot/test/gopath2/src/mypkgb
command
|
|
|
uroot/util
Package util contains various u-root utility functions.
|
Package util contains various u-root utility functions. |
|
zimage
Package zimage contains a Parser for the arm zImage Linux format.
|
Package zimage contains a Parser for the arm zImage Linux format. |
|
scripts
|
|
|
build_perf
command
Measure the performance of building all the Go commands under various GOGC values.
|
Measure the performance of building all the Go commands under various GOGC values. |
|
checklicenses
command
Run with `go run checklicenses.go`.
|
Run with `go run checklicenses.go`. |
|
testramfs
command
testramfs tests things, badly
|
testramfs tests things, badly |
|
tools
|
|
|
makebb
command
makebb compiles many Go commands into one bb-style binary.
|
makebb compiles many Go commands into one bb-style binary. |
|
makebbmain
command
makebbmain creates a bb main.go source file.
|
makebbmain creates a bb main.go source file. |
|
mkinitramfs
mkinitramfs creates a u-root initramfs given the list of files on the command line.
|
mkinitramfs creates a u-root initramfs given the list of files on the command line. |
|
xcmds
|
|
|
archive
command
Archive archives files.
|
Archive archives files. |
|
ash
command
our first builtin: cd
|
our first builtin: cd |
|
builtin
command
|
|
|
ectool
command
These should all implement io.ReadAt, with the address as the Offset; same for WriteAt.
|
These should all implement io.ReadAt, with the address as the Offset; same for WriteAt. |
|
ed
command
Options:
|
Options: |
|
esxiboot
command
|
|
|
forth
command
Forth is a forth interpreter.
|
Forth is a forth interpreter. |
|
pflask
command
|
|
|
pox
command
pox builds a portable executable as a squashfs image.
|
pox builds a portable executable as a squashfs image. |
|
run
command
Run executes its arguments as a Go program.
|
Run executes its arguments as a Go program. |
|
rush
command
our first builtin: cd
|
our first builtin: cd |
|
sshd
command
|
Click to show internal directories.
Click to hide internal directories.