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