u-root

command module
v1.0.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 15, 2018 License: BSD-3-Clause Imports: 7 Imported by: 0

README

u-root

Build Status Go Report Card GoDoc License

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 the latest (>=1.10). 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/{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:

go get github.com/u-root/elvish
u-root -build=bb ./cmds/* github.com/u-root/elvish

Side note: elvish is a nicer shell than our default shell rush; and also written in Go.

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 $HOME dir 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.

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

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
cmds
ansi
Print ansi escape sequences.
Print ansi escape sequences.
basename
Basename return name with leading path information removed.
Basename return name with leading path information removed.
bzImage
bzImage is used to modify bzImage files.
bzImage is used to modify bzImage files.
cat
Cat concatenates files and prints to stdout.
Cat concatenates files and prints to stdout.
cbmem
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
Change modifier bits of a file.
Change modifier bits of a file.
cmp
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
Perform a set comparisons over two files.
Perform a set comparisons over two files.
console
console implements a basic console.
console implements a basic console.
cp
Copy files.
Copy files.
cpio
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
Print the date.
Print the date.
dd
Convert and copy a file.
Convert and copy a file.
df
dhclient
dhclient sets up DHCP.
dhclient sets up DHCP.
dirname
dirname prints out the directory name of one or more args.
dirname prints out the directory name of one or more args.
dmesg
Read the system log.
Read the system log.
echo
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.
false
Returns 1.
Returns 1.
field
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
Find finds files.
Find finds files.
free
free reports usage information for physical memory and swap space.
free reports usage information for physical memory and swap space.
freq
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
gpgv validates a signature against a file.
gpgv validates a signature against a file.
gpt
gpt reads and writes GPT headers.
gpt reads and writes GPT headers.
grep
Concurrent, parallel grep.
Concurrent, parallel grep.
hexdump
Prints files in hexadecimal.
Prints files in hexadecimal.
hostname
Print the system's hostname.
Print the system's hostname.
id
Synopsis: id [-gGnu] Description: id displays the uid, guid and groups of the calling process Options: -g, --group print only the effective group ID -G, --groups print all group IDs -n, --name print a name instead of a number, for -ugG -u, --user print only the effective user ID
Synopsis: id [-gGnu] Description: id displays the uid, guid and groups of the calling process Options: -g, --group print only the effective group ID -G, --groups print all group IDs -n, --name print a name instead of a number, for -ugG -u, --user print only the effective user ID
init
Build commands in background processes.
Build commands in background processes.
insmod
Insert a module into the Linux kernel Synopsis: insmod [filename] [module options...] Description: insmod is a clone of insmod(8)
Insert a module into the Linux kernel Synopsis: insmod [filename] [module options...] Description: insmod is a clone of insmod(8)
io
io lets you do IO operations.
io lets you do IO operations.
ip
kexec
kexec executes a new kernel over the running kernel (u-root).
kexec executes a new kernel over the running kernel (u-root).
kill
Kill kills processes.
Kill kills processes.
lddfiles
lddfiles prints the arguments and all .so dependencies of those arguments Description: lddfiles prints the arguments on the command line and all .so's on which they depend.
lddfiles prints the arguments and all .so dependencies of those arguments Description: lddfiles prints the arguments on the command line and all .so's on which they depend.
ln
Ln makes links to files.
Ln makes links to files.
losetup
Setup loop devices.
Setup loop devices.
ls
Ls prints the contents of a directory.
Ls prints the contents of a directory.
lsmod
List modules currently loaded in the Linux kernel Synopsis: lsmod Description: lsmod is a clone of lsmod(8) Author: Roland Kammerer <dev.rck@gmail.com>
List modules currently loaded in the Linux kernel Synopsis: lsmod Description: lsmod is a clone of lsmod(8) Author: Roland Kammerer <dev.rck@gmail.com>
mkdir
Mkdir makes a new directory.
Mkdir makes a new directory.
mkfifo
mkfifo creates a named pipe.
mkfifo creates a named pipe.
mknod
Unmount a filesystem at the specified path.
Unmount a filesystem at the specified path.
mktemp
Mktemp makes a temporary file (or directory) Synopsis: mktemp [OPTION]...
Mktemp makes a temporary file (or directory) Synopsis: mktemp [OPTION]...
mm
modprobe
modprobe - Add and remove modules from the Linux Kernel Synopsis: modprobe [-n] modulename [parameters...] modprobe [-n] -a modulename...
modprobe - Add and remove modules from the Linux Kernel Synopsis: modprobe [-n] modulename [parameters...] modprobe [-n] -a modulename...
mount
Mount a filesystem at the specified path.
Mount a filesystem at the specified path.
msr
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
Mv renames files and directories.
Mv renames files and directories.
netcat
Netcat pipes over the network.
Netcat pipes over the network.
ntpdate
simple ntpd daemon in Go.
simple ntpd daemon in Go.
pci
pe
Dump the headers of a PE file.
Dump the headers of a PE file.
ping
Send icmp packets to a server to test network connectivity.
Send icmp packets to a server to test network connectivity.
printenv
Print environment variables.
Print environment variables.
ps
Print process information.
Print process information.
pwd
Print name of current directory.
Print name of current directory.
readlink
readlink display value of symbolic link file.
readlink display value of symbolic link file.
rm
Delete files.
Delete files.
rmmod
Remove a module from the Linux kernel Synopsis: rmmod name Description: rmmod is a clone of rmmod(8) Author: Roland Kammerer <dev.rck@gmail.com>
Remove a module from the Linux kernel Synopsis: rmmod name Description: rmmod is a clone of rmmod(8) Author: Roland Kammerer <dev.rck@gmail.com>
rush
our first builtin: cd The u-root shell is intended to be very simple, since builtins and extensions are written in Go.
our first builtin: cd The u-root shell is intended to be very simple, since builtins and extensions are written in Go.
scp
Scp copies files between hosts on a network.
Scp copies files between hosts on a network.
seq
Print a sequence of numbers.
Print a sequence of numbers.
shutdown
shutdown halts, suspends, or reboots.
shutdown halts, suspends, or reboots.
sleep
Delay for the specified amount of time.
Delay for the specified amount of time.
sort
Sort lines.
Sort lines.
sos
srvfiles
Serve files on the network.
Serve files on the network.
strings
Strings finds printable strings.
Strings finds printable strings.
stty
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.
sync
sync command in Go.
sync command in Go.
tcz
tee
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.
true
Returns 0.
Returns 0.
truncate
Truncate - shrink or extend the size of a file to the specified size Synopsis: truncate [OPTIONS] [FILE]...
Truncate - shrink or extend the size of a file to the specified size Synopsis: truncate [OPTIONS] [FILE]...
umount
Unmount a filesystem at the specified path.
Unmount a filesystem at the specified path.
uname
Print build information about the kernel and machine.
Print build information about the kernel and machine.
uniq
Uniq removes repeated lines.
Uniq removes repeated lines.
unshare
Disassociate parts of the process execution context.
Disassociate parts of the process execution context.
validate
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.
wc
Wc counts lines, words, runes, syntactically–invalid UTF codes.
Wc counts lines, words, runes, syntactically–invalid UTF codes.
wget
Wget reads one file from a url and writes to stdout.
Wget reads one file from a url and writes to stdout.
which
Which locates a command.
Which locates a command.
examples
sos
uinit
This is a basic init script.
This is a basic init script.
pkg
bb
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.
cp
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
the forth package is designed for use by programs needing to evaluate command-line arguments or simple expressions to set program variables.
the forth package is designed for use by programs needing to evaluate command-line arguments or simple expressions to set program variables.
gpt
gpt implements reading and writing of GUID Partition tables.
gpt implements reading and writing of GUID Partition tables.
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.
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.
pci
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 is suitable for running QEMU-based integration tests.
Package qemu is suitable for running QEMU-based integration tests.
sos
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.
uio
uroot/util
Package util contains various u-root utility functions.
Package util contains various u-root utility functions.
scripts
build_perf
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
Run with `go run checklicenses.go`.
Run with `go run checklicenses.go`.
testramfs
testramfs tests things, badly
testramfs tests things, badly
tools
makebb
makebb compiles many Go commands into one bb-style binary.
makebb compiles many Go commands into one bb-style binary.
makebbmain
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.
rewriteast
rewriteast rewrites a Go command to be bb-compatible.
rewriteast rewrites a Go command to be bb-compatible.
xcmds
archive
Archive archives files.
Archive archives files.
ash
ectool
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
Options: ED(1) Unix Programmer's Manual ED(1) NAME ed - text editor SYNOPSIS ed [ - ] [ -d ] [ name ] DESCRIPTION Ed is the standard text editor.
Options: ED(1) Unix Programmer's Manual ED(1) NAME ed - text editor SYNOPSIS ed [ - ] [ -d ] [ name ] DESCRIPTION Ed is the standard text editor.
forth
Forth is a forth interpreter.
Forth is a forth interpreter.
run
Run executes its arguments as a Go program.
Run executes its arguments as a Go program.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL