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