github.com/oweisse/u-root@v0.0.0-20181109060735-d005ad25fef1/README.md (about) 1 # u-root 2 3 [![Build 4 Status](https://circleci.com/gh/u-root/u-root/tree/master.png?style=shield&circle-token=8d9396e32f76f82bf4257b60b414743e57734244)](https://circleci.com/gh/u-root/u-root/tree/master) 5 [![Go Report 6 Card](https://goreportcard.com/badge/github.com/u-root/u-root)](https://goreportcard.com/report/github.com/u-root/u-root) 7 [![GoDoc](https://godoc.org/github.com/u-root/u-root?status.svg)](https://godoc.org/github.com/u-root/u-root) 8 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/u-root/u-root/blob/master/LICENSE) 9 10 # Description 11 12 u-root contains simple Go versions of many standard Linux tools, similar to 13 busybox. It's a pure Go userland! 14 15 u-root stands for "universal root". It can create an initramfs in two different 16 modes: 17 18 * source mode: Go toolchain binaries + simple shell + Go source for tools to 19 be compiled on the fly by the shell. 20 21 When you try to run a command that is not built, it is compiled first and 22 stored in tmpfs. From that point on, when you run the command, you get the 23 one in tmpfs. Don't worry: the Go compiler is pretty fast. 24 25 * bb mode: One busybox-like binary comprising all the Go tools you ask to 26 include. 27 28 In this mode, u-root copies and rewrites the source of the tools you asked 29 to include to be able to compile everything into one busybox-like binary. 30 31 # Usage 32 33 Make sure your Go version is 1.11. Make sure your `GOPATH` is set 34 up correctly. 35 36 Download and install u-root: 37 38 ```shell 39 go get github.com/u-root/u-root 40 ``` 41 42 You can now use the u-root command to build an initramfs. Here are some 43 examples: 44 45 ```shell 46 # Build a bb-mode cpio initramfs of all the Go cmds in ./cmds/... 47 u-root -build=bb 48 49 # Generate a cpio archive named initramfs.cpio. 50 u-root -format=cpio -build=source -o initramfs.cpio 51 52 # Generate a bb-mode archive with only these given commands. 53 u-root -format=cpio -build=bb ./cmds/{init,ls,ip,dhclient,wget,tcz,cat} 54 ``` 55 56 `-format=cpio` and `-build=source` are the default flag values. The default set 57 of packages included is all packages in `github.com/u-root/u-root/cmds/...`. 58 59 In addition to using paths to specify Go source packages to include, you may 60 also use Go package import paths (e.g. `golang.org/x/tools/imports`) to include 61 commands. Only the `main` package and its dependencies in those source 62 directories will be included. For example: 63 64 You can build the initramfs built by u-root into the kernel via the 65 `CONFIG_INITRAMFS_SOURCE` config variable or you can load it separately via an 66 option in for example Grub or the QEMU command line or coreboot config variable. 67 68 A good way to test the initramfs generated by u-root is with qemu: 69 70 ```shell 71 qemu-system-x86_64 -kernel path/to/kernel -initrd /tmp/initramfs.linux_amd64.cpio 72 ``` 73 74 Note that you do not have to build a special kernel on your own, it is 75 sufficient to use an existing one. Usually you can find one in `/boot`. 76 77 > NOTE: you can compress the initramfs but for xz compression, the kernel has 78 > some restrictions on the compression options and it is suggested to align the 79 > file to 512 byte boundaries `shell xz --check=crc32 -9 --lzma2=dict=1MiB 80 > --stdout /tmp/initramfs.linux_amd64.cpio \ | dd conv=sync bs=512 81 > of=/tmp/initramfs.linux_amd64.cpio.xz` 82 83 You may also include additional files in the initramfs using the `-files` flag. 84 If you add binaries with `-files` are listed, their ldd dependencies will be 85 included as well. As example for Debian, you want to add two kernel modules for 86 testing, executing your currently booted kernel: 87 88 > NOTE: these files will be placed in the `$HOME` dir in the initramfs. 89 90 ```shell 91 u-root -files "$HOME/hello.ko $HOME/hello2.ko" 92 qemu-system-x86_64 -kernel /boot/vmlinuz-$(uname -r) -initrd /tmp/initramfs.linux_amd64.cpio 93 ``` 94 95 To specify the location in the initramfs, use `<sourcefile>:<destinationfile>`. 96 For example: 97 98 ```shell 99 u-root -files "root-fs/usr/bin/runc:usr/bin/run" 100 ``` 101 102 ## Getting Packages of TinyCore 103 104 Using the `tcz` command included in u-root, you can install tinycore linux 105 packages for things you want. 106 107 You can use QEMU NAT to allow you to fetch packages. Let's suppose, for example, 108 you want bash. Once u-root is running, you can do this: 109 110 ```shell 111 % tcz bash 112 ``` 113 114 The tcz command computes and fetches all dependencies. If you can't get to 115 tinycorelinux.net, or you want package fetching to be faster, you can run your 116 own server for tinycore packages. 117 118 You can do this to get a local server using the u-root srvfiles command: 119 120 ```shell 121 % srvfiles -p 80 -d path-to-local-tinycore-packages 122 ``` 123 124 Of course you have to fetch all those packages first somehow :-) 125 126 ## Build an Embeddable U-root 127 128 You can build this environment into a kernel as an initramfs, and further embed 129 that into firmware as a coreboot payload. 130 131 In the kernel and coreboot case, you need to configure ethernet. We have a 132 `dhclient` command that works for both ipv4 and ipv6. Since v6 does not yet work 133 that well for most people, a typical invocation looks like this: 134 135 ```shell 136 % dhclient -ipv4 -ipv6=false 137 ``` 138 139 Or, on newer linux kernels (> 4.x) boot with ip=dhcp in the command line, 140 assuming your kernel is configured to work that way. 141 142 ## Updating Dependencies 143 144 ```shell 145 # The latest released version of dep is required: 146 curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh 147 dep ensure 148 ``` 149 150 # Hardware 151 152 If you want to see u-root on real hardware, this 153 [board](https://www.pcengines.ch/apu2.htm) is a good start. 154 155 # Contributions 156 157 See [CONTRIBUTING.md](CONTRIBUTING.md) 158 159 Improving existing commands (e.g., additional currently unsupported flags) is 160 very welcome. In this case it is not even required to build an initramfs, just 161 enter the `cmds/` directory and start coding. A list of commands that are on the 162 roadmap can be found [here](roadmap.md).