github.com/hugelgupf/u-root@v0.0.0-20191023214958-4807c632154c/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/diskboot) or [syslinux config files](pkg/syslinux) 20 are to make transition to LinuxBoot easier. 21 22 * A way to create very small Go programs using 23 [busybox mode](pkg/bb/README.md) or source mode (see below). 24 25 * A way to create initramfs (an archive of files) to use with Linux kernels. 26 27 # Creating Initramfs Archives 28 29 u-root can create an initramfs in two different modes: 30 31 * source mode includes Go toolchain binaries + simple shell + Go source files 32 in the initramfs archive. Tools are compiled from source on the fly by the 33 shell. 34 35 When you try to run a command that is not built, it is compiled first and 36 stored in tmpfs. From that point on, when you run the command, you get the 37 one in tmpfs. Don't worry: the Go compiler is pretty fast. 38 39 * bb mode: One busybox-like binary comprising all the Go tools you ask to 40 include. See [here for how it works](pkg/bb/README.md). 41 42 In this mode, u-root copies and rewrites the source of the tools you asked 43 to include to be able to compile everything into one busybox-like binary. 44 45 # SystemBoot 46 47 SystemBoot is a set of bootloaders written in Go. It is meant to be a 48 distribution for LinuxBoot to create a system firmware + bootloader. All of 49 these use `kexec` to boot. The commands are in [cmds/boot](cmds/boot). 50 51 * `pxeboot`: a network boot client that uses DHCP and HTTP or TFTP to get a 52 boot configuration which can be parsed as PXELinux or iPXE configuration 53 files to get a boot program. 54 55 * `fbnetboot`: a network boot client that uses DHCP and HTTP to get a boot 56 program based on Linux, and boots it. To be merged with `pxeboot`. 57 58 * `localboot`: a tool that finds bootable kernel configurations on the local 59 disks and boots them. 60 61 * `boot2`: similar to `localboot`, finds a bootable kernel configuration on 62 disk (GRUB or syslinux) and boots it. To be merged into `localboot`. 63 64 * `uinit`: a wrapper around `netboot` and `localboot` that just mimicks a 65 BIOS/UEFI BDS behaviour, by looping between network booting and local 66 booting. The name `uinit` is necessary to be picked up as boot program by 67 u-root. 68 69 This project started as a loose collection of programs in u-root by various 70 LinuxBoot contributors, as well as a personal experiment by 71 [Andrea Barberio](https://github.com/insomniacslk) that has since been merged 72 in. It is now an effort of a broader community and graduated to a real project 73 for system firmwares. 74 75 More detailed information about the build process for a full LinuxBoot firmware 76 image using u-root/systemboot and coreboot can be found in the 77 [LinuxBoot book](https://github.com/linuxboot/book) chapter 11, 78 [LinuxBoot using coreboot, u-root and systemboot](https://github.com/linuxboot/book/blob/master/11.coreboot.u-root.systemboot/README.md). 79 80 # Usage 81 82 Make sure your Go version is 1.12. Make sure your `GOPATH` is set up correctly. 83 84 Download and install u-root: 85 86 ```shell 87 go get github.com/u-root/u-root 88 ``` 89 90 You can now use the u-root command to build an initramfs. Here are some 91 examples: 92 93 ```shell 94 # Build a bb-mode cpio initramfs of all the Go cmds in ./cmds/core/... 95 u-root -build=bb 96 97 # Generate a bb-mode archive with bootloaders 98 u-root -build=bb core boot 99 100 # Generate a cpio archive named initramfs.cpio. 101 u-root -format=cpio -build=source -o initramfs.cpio 102 103 # Generate a bb-mode archive with only these given commands. 104 u-root -format=cpio -build=bb ./cmds/core/{init,ls,ip,dhclient,wget,cat} 105 ``` 106 107 `-format=cpio` and `-build=source` are the default flag values. The default set 108 of packages included is all packages in 109 `github.com/u-root/u-root/cmds/core/...`. 110 111 In addition to using paths to specify Go source packages to include, you may 112 also use Go package import paths (e.g. `golang.org/x/tools/imports`) to include 113 commands. Only the `main` package and its dependencies in those source 114 directories will be included. For example: 115 116 You can build the initramfs built by u-root into the kernel via the 117 `CONFIG_INITRAMFS_SOURCE` config variable or you can load it separately via an 118 option in for example Grub or the QEMU command line or coreboot config variable. 119 120 A good way to test the initramfs generated by u-root is with qemu: 121 122 ```shell 123 qemu-system-x86_64 -nographic -kernel path/to/kernel -initrd /tmp/initramfs.linux_amd64.cpio 124 ``` 125 126 Note that you do not have to build a special kernel on your own, it is 127 sufficient to use an existing one. Usually you can find one in `/boot`. 128 129 > NOTE: you can compress the initramfs but for xz compression, the kernel has 130 > some restrictions on the compression options and it is suggested to align the 131 > file to 512 byte boundaries `shell xz --check=crc32 -9 --lzma2=dict=1MiB 132 > --stdout /tmp/initramfs.linux_amd64.cpio \ | dd conv=sync bs=512 133 > of=/tmp/initramfs.linux_amd64.cpio.xz` 134 135 You may also include additional files in the initramfs using the `-files` flag. 136 If you add binaries with `-files` are listed, their ldd dependencies will be 137 included as well. As example for Debian, you want to add two kernel modules for 138 testing, executing your currently booted kernel: 139 140 > NOTE: these files will be placed in the `$HOME` dir in the initramfs. 141 142 ```shell 143 u-root -files "$HOME/hello.ko $HOME/hello2.ko" 144 qemu-system-x86_64 -kernel /boot/vmlinuz-$(uname -r) -initrd /tmp/initramfs.linux_amd64.cpio 145 ``` 146 147 To specify the location in the initramfs, use `<sourcefile>:<destinationfile>`. 148 For example: 149 150 ```shell 151 u-root -files "root-fs/usr/bin/runc:usr/bin/run" 152 ``` 153 154 ## Getting Packages of TinyCore 155 156 Using the `tcz` command included in u-root, you can install tinycore linux 157 packages for things you want. 158 159 You can use QEMU NAT to allow you to fetch packages. Let's suppose, for example, 160 you want bash. Once u-root is running, you can do this: 161 162 ```shell 163 % tcz bash 164 ``` 165 166 The tcz command computes and fetches all dependencies. If you can't get to 167 tinycorelinux.net, or you want package fetching to be faster, you can run your 168 own server for tinycore packages. 169 170 You can do this to get a local server using the u-root srvfiles command: 171 172 ```shell 173 % srvfiles -p 80 -d path-to-local-tinycore-packages 174 ``` 175 176 Of course you have to fetch all those packages first somehow :-) 177 178 ## Build an Embeddable U-root 179 180 You can build this environment into a kernel as an initramfs, and further embed 181 that into firmware as a coreboot payload. 182 183 In the kernel and coreboot case, you need to configure ethernet. We have a 184 `dhclient` command that works for both ipv4 and ipv6. Since v6 does not yet work 185 that well for most people, a typical invocation looks like this: 186 187 ```shell 188 % dhclient -ipv4 -ipv6=false 189 ``` 190 191 Or, on newer linux kernels (> 4.x) boot with ip=dhcp in the command line, 192 assuming your kernel is configured to work that way. 193 194 ## Updating Dependencies 195 196 ```shell 197 # The latest released version of dep is required: 198 curl https://raw.githubusercontent.com/golang/dep/master/install.sh | sh 199 dep ensure 200 ``` 201 202 # Hardware 203 204 If you want to see u-root on real hardware, this 205 [board](https://www.pcengines.ch/apu2.htm) is a good start. 206 207 # Contributions 208 209 For information about contributing, including how we sign off commits, please 210 see [CONTRIBUTING.md](CONTRIBUTING.md). 211 212 Improving existing commands (e.g., additional currently unsupported flags) is 213 very welcome. In this case it is not even required to build an initramfs, just 214 enter the `cmds/` directory and start coding. A list of commands that are on the 215 roadmap can be found [here](roadmap.md).