github.com/andrewsun2898/u-root@v6.0.1-0.20200616011413-4b2895c1b815+incompatible/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 * A way to compile many Go programs into a single binary with 17 [busybox mode](pkg/bb/README.md). 18 19 * A way to create initramfs (an archive of files) to use with Linux kernels. 20 21 * Go bootloaders that use `kexec` to boot Linux or multiboot kernels such as 22 ESXi, Xen, or tboot. They are meant to be used with 23 [LinuxBoot](https://www.linuxboot.org). With that, parsers for 24 [GRUB config files](pkg/boot/grub) or 25 [syslinux config files](pkg/boot/syslinux) are to make transition to 26 LinuxBoot easier. 27 28 # Usage 29 30 Make sure your Go version is 1.13. Make sure your `GOPATH` is set up correctly. 31 32 Download and install u-root: 33 34 ```shell 35 go get github.com/u-root/u-root 36 ``` 37 38 You can now use the u-root command to build an initramfs. Here are some 39 examples: 40 41 ```shell 42 # Build an initramfs of all the Go cmds in ./cmds/core/... (default) 43 u-root 44 45 # Generate an archive with bootloaders 46 # 47 # core and boot are templates that expand to sets of commands 48 u-root core boot 49 50 # Generate an archive with only these given commands 51 u-root ./cmds/core/{init,ls,ip,dhclient,wget,cat,elvish} 52 53 # Generate an archive with a tool outside of u-root 54 u-root ./cmds/core/{init,ls,elvish} github.com/u-root/cpu/cmds/cpud 55 ``` 56 57 The default set of packages included is all packages in 58 `github.com/u-root/u-root/cmds/core/...`. 59 60 In addition to using paths to specify Go source packages to include, you may 61 also use Go package import paths (e.g. `golang.org/x/tools/imports`) to include 62 commands. Only the `main` package and its dependencies in those source 63 directories will be included. For example: 64 65 You can build the initramfs built by u-root into the kernel via the 66 `CONFIG_INITRAMFS_SOURCE` config variable or you can load it separately via an 67 option in for example Grub or the QEMU command line or coreboot config variable. 68 69 ## Extra Files 70 71 You may also include additional files in the initramfs using the `-files` flag. 72 If you add binaries with `-files` are listed, their ldd dependencies will be 73 included as well. As example for Debian, you want to add two kernel modules for 74 testing, executing your currently booted kernel: 75 76 > NOTE: these files will be placed in the `$HOME` dir in the initramfs. 77 78 ```shell 79 u-root -files "$HOME/hello.ko $HOME/hello2.ko" 80 qemu-system-x86_64 -kernel /boot/vmlinuz-$(uname -r) -initrd /tmp/initramfs.linux_amd64.cpio 81 ``` 82 83 To specify the location in the initramfs, use `<sourcefile>:<destinationfile>`. 84 For example: 85 86 ```shell 87 u-root -files "root-fs/usr/bin/runc:usr/bin/run" 88 ``` 89 90 ## Init and Uinit 91 92 u-root has a very simple (exchangable) init system controlled by the `-initcmd` 93 and `-uinitcmd` command-line flags. 94 95 * `-initcmd` determines what `/init` is symlinked to. `-initcmd` may be a 96 u-root command name or a symlink target. 97 * `-uinitcmd` is run by the default u-root [init](cmds/core/init) after some 98 basic file system setup. There is no default, users should optionally supply 99 their own. `-uinitcmd` may be a u-root command name with arguments or a 100 symlink target with arguments. 101 * After running a uinit (if there is one), [init](cmds/core/init) will start a 102 shell determined by the `-defaultsh` argument. 103 104 We expect most users to keep their `-initcmd` as [init](cmds/core/init), but to 105 supply their own uinit for additional initialization or to immediately load 106 another operating system. 107 108 All three command-line args accept both a u-root command name or a target 109 symlink path. **Only `-uinitcmd` accepts command-line arguments, however.** For 110 example, 111 112 ```bash 113 u-root -uinitcmd="echo Go Gopher" ./cmds/core/{init,echo,elvish} 114 115 cpio -ivt < /tmp/initramfs.linux_amd64.cpio 116 # ... 117 # lrwxrwxrwx 0 root root 12 Dec 31 1969 bin/uinit -> ../bbin/echo 118 # lrwxrwxrwx 0 root root 9 Dec 31 1969 init -> bbin/init 119 120 qemu-system-x86_64 -kernel $KERNEL -initramfs /tmp/initramfs.linux_amd64.cpio -nographic -append "console=ttyS0" 121 # ... 122 # [ 0.848021] Freeing unused kernel memory: 896K 123 # 2020/05/01 04:04:39 Welcome to u-root! 124 # _ 125 # _ _ _ __ ___ ___ | |_ 126 # | | | |____| '__/ _ \ / _ \| __| 127 # | |_| |____| | | (_) | (_) | |_ 128 # \__,_| |_| \___/ \___/ \__| 129 # 130 # Go Gopher 131 # ~/> 132 ``` 133 134 The command you name must be present in the command set. The following will *not 135 work*: 136 137 ```bash 138 u-root -uinitcmd="echo Go Gopher" ./cmds/core/{init,elvish} 139 # 2020/04/30 21:05:57 could not create symlink from "bin/uinit" to "echo": command or path "echo" not included in u-root build: specify -uinitcmd="" to ignore this error and build without a uinit 140 ``` 141 142 You can also refer to non-u-root-commands; they will be added as symlinks. We 143 don't presume to know whether your symlink target is correct or not. 144 145 This will build, but not work unless you add a /bin/foobar to the initramfs. 146 147 ```bash 148 u-root -uinitcmd="/bin/foobar Go Gopher" ./cmds/core/{init,elvish} 149 ``` 150 151 This will boot the same as the above. 152 153 ```bash 154 u-root -uinitcmd="/bin/foobar Go Gopher" -files /bin/echo:bin/foobar ./cmds/core/{init,elvish} 155 ``` 156 157 This will bypass the regular u-root init and just launch a shell: 158 159 ```bash 160 u-root -initcmd=elvish ./cmds/core/{elvish,ls} 161 162 cpio -ivt < /tmp/initramfs.linux_amd64.cpio 163 # ... 164 # lrwxrwxrwx 0 root root 9 Dec 31 1969 init -> bbin/elvish 165 166 qemu-system-x86_64 -kernel $KERNEL -initramfs /tmp/initramfs.linux_amd64.cpio -nographic -append "console=ttyS0" 167 # ... 168 # [ 0.848021] Freeing unused kernel memory: 896K 169 # failed to put myself in foreground: ioctl: inappropriate ioctl for device 170 # ~/> 171 ``` 172 173 (It fails to do that because some initialization is missing when the shell is 174 started without a proper init.) 175 176 ## Cross Compilation (targeting different architectures and OSes) 177 178 Cross-OS and -architecture compilation comes for free with Go. In fact, every PR 179 to the u-root repo is built against the following architectures: amd64, x86 180 (i.e. 32bit), mipsle, armv7, arm64, and ppc64le. 181 182 Further, we run integration tests on linux/amd64, freebsd/amd64 and linux/arm64, 183 using several CI systems. If you need to add another CI system, processor or OS, 184 please let us know. 185 186 To cross compile for an ARM, on Linux: 187 188 ```shell 189 GOARCH=arm u-root 190 ``` 191 192 If you are on OSX, and wish to build for Linux on AMD64: 193 194 ```shell 195 GOOS=linux GOARCH=amd64 u-root 196 ``` 197 198 ## Testing in QEMU 199 200 A good way to test the initramfs generated by u-root is with qemu: 201 202 ```shell 203 qemu-system-x86_64 -nographic -kernel path/to/kernel -initrd /tmp/initramfs.linux_amd64.cpio 204 ``` 205 206 Note that you do not have to build a special kernel on your own, it is 207 sufficient to use an existing one. Usually you can find one in `/boot`. 208 209 If you quickly need to obtain a kernel, for example, when you are on a non-Linux 210 system, you can assemble a URL to download one through Arch Linux's 211 [iPXE menu file](https://www.archlinux.org/releng/netboot/archlinux.ipxe). It 212 would download from `${mirrorurl}iso/${release}/arch/boot/x86_64/vmlinuz`, so 213 just search for a mirror URL you prefer and a release version, for example, 214 `http://mirror.rackspace.com/archlinux/iso/2019.10.01/arch/boot/x86_64/vmlinuz`. 215 216 ### Framebuffer 217 218 For framebuffer support, append a VESA mode via the `vga` kernel parameter: 219 220 ```shell 221 qemu-system-x86_64 \ 222 -kernel path/to/kernel \ 223 -initrd /tmp/initramfs.linux_amd64.cpio \ 224 -append "vga=786" 225 ``` 226 227 For a list of modes, refer to the 228 [Linux kernel documentation](https://github.com/torvalds/linux/blob/master/Documentation/fb/vesafb.rst#how-to-use-it). 229 230 ### Entropy / Random Number Generator 231 232 Some utilities, e.g., `dhclient`, require entropy to be present. For a speedy 233 virtualized random number generator, the kernel should have the following: 234 235 ``` 236 CONFIG_VIRTIO_PCI=y 237 CONFIG_HW_RANDOM_VIRTIO=y 238 CONFIG_CRYPTO_DEV_VIRTIO=y 239 ``` 240 241 Then you can run your kernel in QEMU with a `virtio-rng-pci` device: 242 243 ```sh 244 qemu-system-x86_64 \ 245 -device virtio-rng-pci \ 246 -kernel vmlinuz \ 247 -initrd /tmp/initramfs.linux_amd64.cpio 248 ``` 249 250 In addition, you can pass your host's RNG: 251 252 ```sh 253 qemu-system-x86_64 \ 254 -object rng-random,filename=/dev/urandom,id=rng0 \ 255 -device virtio-rng-pci,rng=rng0 \ 256 -kernel vmlinuz \ 257 -initrd /tmp/initramfs.linux_amd64.cpio 258 ``` 259 260 ## SystemBoot 261 262 SystemBoot is a set of bootloaders written in Go. It is meant to be a 263 distribution for LinuxBoot to create a system firmware + bootloader. All of 264 these use `kexec` to boot. The commands are in [cmds/boot](cmds/boot). 265 266 * `pxeboot`: a network boot client that uses DHCP and HTTP or TFTP to get a 267 boot configuration which can be parsed as PXELinux or iPXE configuration 268 files to get a boot program. 269 270 * `fbnetboot`: a network boot client that uses DHCP and HTTP to get a boot 271 program based on Linux, and boots it. To be merged with `pxeboot`. 272 273 * `localboot`: a tool that finds bootable kernel configurations on the local 274 disks and boots them. 275 276 * `boot2`: similar to `localboot`, finds a bootable kernel configuration on 277 disk (GRUB or syslinux) and boots it. To be merged into `localboot`. 278 279 * `systemboot`: a wrapper around `fbnetboot` and `localboot` that just mimicks 280 a BIOS/UEFI BDS behaviour, by looping between network booting and local 281 booting. Use `-uinitcmd` argument to the u-root build tool to make it the 282 boot program. 283 284 This project started as a loose collection of programs in u-root by various 285 LinuxBoot contributors, as well as a personal experiment by 286 [Andrea Barberio](https://github.com/insomniacslk) that has since been merged 287 in. It is now an effort of a broader community and graduated to a real project 288 for system firmwares. 289 290 More detailed information about the build process for a full LinuxBoot firmware 291 image using u-root/systemboot and coreboot can be found in the 292 [LinuxBoot book](https://github.com/linuxboot/book) chapter about 293 [LinuxBoot using coreboot, u-root and systemboot](https://github.com/linuxboot/book/blob/master/coreboot.u-root.systemboot/README.md). 294 295 You can build systemboot like this: 296 297 ```sh 298 u-root -build=bb -uinitcmd=systemboot core github.com/u-root/u-root/cmds/boot/{systemboot,localboot,fbnetboot} 299 ``` 300 301 ## Compression 302 303 You can compress the initramfs. However, for xz compression, the kernel has some 304 restrictions on the compression options and it is suggested to align the file to 305 512 byte boundaries: 306 307 ```shell 308 xz --check=crc32 -9 --lzma2=dict=1MiB \ 309 --stdout /tmp/initramfs.linux_amd64.cpio \ 310 | dd conv=sync bs=512 \ 311 of=/tmp/initramfs.linux_amd64.cpio.xz 312 ``` 313 314 ## Getting Packages of TinyCore 315 316 Using the `tcz` command included in u-root, you can install tinycore linux 317 packages for things you want. 318 319 You can use QEMU NAT to allow you to fetch packages. Let's suppose, for example, 320 you want bash. Once u-root is running, you can do this: 321 322 ```shell 323 % tcz bash 324 ``` 325 326 The tcz command computes and fetches all dependencies. If you can't get to 327 tinycorelinux.net, or you want package fetching to be faster, you can run your 328 own server for tinycore packages. 329 330 You can do this to get a local server using the u-root srvfiles command: 331 332 ```shell 333 % srvfiles -p 80 -d path-to-local-tinycore-packages 334 ``` 335 336 Of course you have to fetch all those packages first somehow :-) 337 338 ## Build an Embeddable U-root 339 340 You can build this environment into a kernel as an initramfs, and further embed 341 that into firmware as a coreboot payload. 342 343 In the kernel and coreboot case, you need to configure ethernet. We have a 344 `dhclient` command that works for both ipv4 and ipv6. Since v6 does not yet work 345 that well for most people, a typical invocation looks like this: 346 347 ```shell 348 % dhclient -ipv4 -ipv6=false 349 ``` 350 351 Or, on newer linux kernels (> 4.x) boot with ip=dhcp in the command line, 352 assuming your kernel is configured to work that way. 353 354 ## Build Modes 355 356 u-root can create an initramfs in two different modes: 357 358 * source mode includes Go toolchain binaries + simple shell + Go source files 359 in the initramfs archive. Tools are compiled from source on the fly by the 360 shell. 361 362 When you try to run a command that is not built, it is compiled first and 363 stored in tmpfs. From that point on, when you run the command, you get the 364 one in tmpfs. Don't worry: the Go compiler is pretty fast. 365 366 * bb mode: One busybox-like binary comprising all the Go tools you ask to 367 include. See [here for how it works](pkg/bb/README.md). 368 369 In this mode, u-root copies and rewrites the source of the tools you asked 370 to include to be able to compile everything into one busybox-like binary. 371 372 ## Updating Dependencies 373 374 ```shell 375 # The latest released version of dep is required: 376 curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh 377 dep ensure 378 ``` 379 380 # Hardware 381 382 If you want to see u-root on real hardware, this 383 [board](https://www.pcengines.ch/apu2.htm) is a good start. 384 385 # Contributions 386 387 For information about contributing, including how we sign off commits, please 388 see [CONTRIBUTING.md](CONTRIBUTING.md). 389 390 Improving existing commands (e.g., additional currently unsupported flags) is 391 very welcome. In this case it is not even required to build an initramfs, just 392 enter the `cmds/` directory and start coding. A list of commands that are on the 393 roadmap can be found [here](roadmap.md).