github.com/zaolin/u-root@v0.0.0-20200428085104-64aaafd46c6d/README.md (about) 1 # u-root 2 3 [![Build 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) 4 [![Go Report Card](https://goreportcard.com/badge/github.com/u-root/u-root)](https://goreportcard.com/report/github.com/u-root/u-root) 5 [![GoDoc](https://godoc.org/github.com/u-root/u-root?status.svg)](https://godoc.org/github.com/u-root/u-root) 6 [![License](https://img.shields.io/badge/License-BSD%203--Clause-blue.svg)](https://github.com/u-root/u-root/blob/master/LICENSE) 7 8 # Description 9 10 u-root embodies four different projects. 11 12 * Go versions of many standard Linux tools, such as [ls](cmds/core/ls/ls.go), 13 [cp](cmds/core/cp/cp.go), or [shutdown](cmds/core/shutdown/shutdown.go). See 14 [cmds/core](cmds/core) for most of these. 15 16 * Go bootloaders that use `kexec` to boot Linux or multiboot kernels such as 17 ESXi, Xen, or tboot. They are meant to be used with 18 [LinuxBoot](https://www.linuxboot.org). With that, parsers for 19 [GRUB config files](pkg/boot/diskboot) or 20 [syslinux config files](pkg/boot/syslinux) are to make transition to 21 LinuxBoot easier. 22 23 * A way to create very small Go programs using 24 [busybox mode](pkg/bb/README.md) or source mode (see below). 25 26 * A way to create initramfs (an archive of files) to use with Linux kernels. 27 28 # Creating Initramfs Archives 29 30 u-root can create an initramfs in two different modes: 31 32 * source mode includes Go toolchain binaries + simple shell + Go source files 33 in the initramfs archive. Tools are compiled from source on the fly by the 34 shell. 35 36 When you try to run a command that is not built, it is compiled first and 37 stored in tmpfs. From that point on, when you run the command, you get the 38 one in tmpfs. Don't worry: the Go compiler is pretty fast. 39 40 * bb mode: One busybox-like binary comprising all the Go tools you ask to 41 include. See [here for how it works](pkg/bb/README.md). 42 43 In this mode, u-root copies and rewrites the source of the tools you asked 44 to include to be able to compile everything into one busybox-like binary. 45 46 # SystemBoot 47 48 SystemBoot is a set of bootloaders written in Go. It is meant to be a 49 distribution for LinuxBoot to create a system firmware + bootloader. All of 50 these use `kexec` to boot. The commands are in [cmds/boot](cmds/boot). 51 52 * `pxeboot`: a network boot client that uses DHCP and HTTP or TFTP to get a 53 boot configuration which can be parsed as PXELinux or iPXE configuration 54 files to get a boot program. 55 56 * `fbnetboot`: a network boot client that uses DHCP and HTTP to get a boot 57 program based on Linux, and boots it. To be merged with `pxeboot`. 58 59 * `localboot`: a tool that finds bootable kernel configurations on the local 60 disks and boots them. 61 62 * `boot2`: similar to `localboot`, finds a bootable kernel configuration on 63 disk (GRUB or syslinux) and boots it. To be merged into `localboot`. 64 65 * `systemboot`: a wrapper around `fbnetboot` and `localboot` that just mimicks 66 a BIOS/UEFI BDS behaviour, by looping between network booting and local 67 booting. Use `-uinitcmd` argument to the u-root build tool to make it the 68 boot program. 69 70 This project started as a loose collection of programs in u-root by various 71 LinuxBoot contributors, as well as a personal experiment by 72 [Andrea Barberio](https://github.com/insomniacslk) that has since been merged 73 in. It is now an effort of a broader community and graduated to a real project 74 for system firmwares. 75 76 More detailed information about the build process for a full LinuxBoot firmware 77 image using u-root/systemboot and coreboot can be found in the 78 [LinuxBoot book](https://github.com/linuxboot/book) chapter 10, 79 [LinuxBoot using coreboot, u-root and systemboot](https://github.com/linuxboot/book/blob/master/coreboot.u-root.systemboot/README.md). 80 81 You can build systemboot like this: 82 83 ```sh 84 u-root -build=bb -uinitcmd=systemboot core github.com/u-root/u-root/cmds/boot/{systemboot,localboot,fbnetboot} 85 ``` 86 87 # Usage 88 89 Make sure your Go version is 1.12. Make sure your `GOPATH` is set up correctly. 90 91 Download and install u-root: 92 93 ```shell 94 go get github.com/u-root/u-root 95 ``` 96 97 You can now use the u-root command to build an initramfs. Here are some 98 examples: 99 100 ```shell 101 # Build a bb-mode cpio initramfs of all the Go cmds in ./cmds/core/... 102 u-root -build=bb 103 104 # Generate a bb-mode archive with bootloaders 105 u-root -build=bb core boot 106 107 # Generate a cpio archive named initramfs.cpio. 108 u-root -format=cpio -build=source -o initramfs.cpio 109 110 # Generate a bb-mode archive with only these given commands. 111 u-root -format=cpio -build=bb ./cmds/core/{init,ls,ip,dhclient,wget,cat} 112 ``` 113 114 `-format=cpio` and `-build=source` are the default flag values. The default set 115 of packages included is all packages in 116 `github.com/u-root/u-root/cmds/core/...`. 117 118 In addition to using paths to specify Go source packages to include, you may 119 also use Go package import paths (e.g. `golang.org/x/tools/imports`) to include 120 commands. Only the `main` package and its dependencies in those source 121 directories will be included. For example: 122 123 You can build the initramfs built by u-root into the kernel via the 124 `CONFIG_INITRAMFS_SOURCE` config variable or you can load it separately via an 125 option in for example Grub or the QEMU command line or coreboot config variable. 126 127 ## Testing in QEMU 128 129 A good way to test the initramfs generated by u-root is with qemu: 130 131 ```shell 132 qemu-system-x86_64 -nographic -kernel path/to/kernel -initrd /tmp/initramfs.linux_amd64.cpio 133 ``` 134 135 Note that you do not have to build a special kernel on your own, it is 136 sufficient to use an existing one. Usually you can find one in `/boot`. 137 138 If you quickly need to obtain a kernel, for example, when you are on a non-Linux 139 system, you can assemble a URL to download one through Arch Linux's 140 [iPXE menu file](https://www.archlinux.org/releng/netboot/archlinux.ipxe). It 141 would download from `${mirrorurl}iso/${release}/arch/boot/x86_64/vmlinuz`, so 142 just search for a mirror URL you prefer and a release version, for example, 143 `http://mirror.rackspace.com/archlinux/iso/2019.10.01/arch/boot/x86_64/vmlinuz`. 144 145 ### Framebuffer 146 147 For framebuffer support, append a VESA mode via the `vga` kernel parameter: 148 149 ```shell 150 qemu-system-x86_64 \ 151 -kernel path/to/kernel \ 152 -initrd /tmp/initramfs.linux_amd64.cpio \ 153 -append "vga=786" 154 ``` 155 156 For a list of modes, refer to the 157 [Linux kernel documentation](https://github.com/torvalds/linux/blob/master/Documentation/fb/vesafb.rst#how-to-use-it). 158 159 ### Entropy / Random Number Generator 160 161 Some utilities, e.g., `dhclient`, require entropy to be present. For a speedy 162 virtualized random number generator, the kernel should have the following: 163 164 ``` 165 CONFIG_VIRTIO_PCI=y 166 CONFIG_HW_RANDOM_VIRTIO=y 167 CONFIG_CRYPTO_DEV_VIRTIO=y 168 ``` 169 170 Then you can run your kernel in QEMU with a `virtio-rng-pci` device: 171 172 ```sh 173 qemu-system-x86_64 \ 174 -device virtio-rng-pci \ 175 -kernel vmlinuz \ 176 -initrd /tmp/initramfs.linux_amd64.cpio 177 ``` 178 179 In addition, you can pass your host's RNG: 180 181 ```sh 182 qemu-system-x86_64 \ 183 -object rng-random,filename=/dev/urandom,id=rng0 \ 184 -device virtio-rng-pci,rng=rng0 \ 185 -kernel vmlinuz \ 186 -initrd /tmp/initramfs.linux_amd64.cpio 187 ``` 188 189 ## Compression 190 191 You can compress the initramfs. However, for xz compression, the kernel has some 192 restrictions on the compression options and it is suggested to align the file to 193 512 byte boundaries: 194 195 ```shell 196 xz --check=crc32 -9 --lzma2=dict=1MiB \ 197 --stdout /tmp/initramfs.linux_amd64.cpio \ 198 | dd conv=sync bs=512 \ 199 of=/tmp/initramfs.linux_amd64.cpio.xz 200 ``` 201 202 ## Extra Files 203 204 You may also include additional files in the initramfs using the `-files` flag. 205 If you add binaries with `-files` are listed, their ldd dependencies will be 206 included as well. As example for Debian, you want to add two kernel modules for 207 testing, executing your currently booted kernel: 208 209 > NOTE: these files will be placed in the `$HOME` dir in the initramfs. 210 211 ```shell 212 u-root -files "$HOME/hello.ko $HOME/hello2.ko" 213 qemu-system-x86_64 -kernel /boot/vmlinuz-$(uname -r) -initrd /tmp/initramfs.linux_amd64.cpio 214 ``` 215 216 To specify the location in the initramfs, use `<sourcefile>:<destinationfile>`. 217 For example: 218 219 ```shell 220 u-root -files "root-fs/usr/bin/runc:usr/bin/run" 221 ``` 222 223 ## Getting Packages of TinyCore 224 225 Using the `tcz` command included in u-root, you can install tinycore linux 226 packages for things you want. 227 228 You can use QEMU NAT to allow you to fetch packages. Let's suppose, for example, 229 you want bash. Once u-root is running, you can do this: 230 231 ```shell 232 % tcz bash 233 ``` 234 235 The tcz command computes and fetches all dependencies. If you can't get to 236 tinycorelinux.net, or you want package fetching to be faster, you can run your 237 own server for tinycore packages. 238 239 You can do this to get a local server using the u-root srvfiles command: 240 241 ```shell 242 % srvfiles -p 80 -d path-to-local-tinycore-packages 243 ``` 244 245 Of course you have to fetch all those packages first somehow :-) 246 247 ## Build an Embeddable U-root 248 249 You can build this environment into a kernel as an initramfs, and further embed 250 that into firmware as a coreboot payload. 251 252 In the kernel and coreboot case, you need to configure ethernet. We have a 253 `dhclient` command that works for both ipv4 and ipv6. Since v6 does not yet work 254 that well for most people, a typical invocation looks like this: 255 256 ```shell 257 % dhclient -ipv4 -ipv6=false 258 ``` 259 260 Or, on newer linux kernels (> 4.x) boot with ip=dhcp in the command line, 261 assuming your kernel is configured to work that way. 262 263 ## Updating Dependencies 264 265 ```shell 266 # The latest released version of dep is required: 267 curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh 268 dep ensure 269 ``` 270 271 # Hardware 272 273 If you want to see u-root on real hardware, this 274 [board](https://www.pcengines.ch/apu2.htm) is a good start. 275 276 # Contributions 277 278 For information about contributing, including how we sign off commits, please 279 see [CONTRIBUTING.md](CONTRIBUTING.md). 280 281 Improving existing commands (e.g., additional currently unsupported flags) is 282 very welcome. In this case it is not even required to build an initramfs, just 283 enter the `cmds/` directory and start coding. A list of commands that are on the 284 roadmap can be found [here](roadmap.md).