-
Notifications
You must be signed in to change notification settings - Fork 187
/
README.md
249 lines (193 loc) · 10.2 KB
/
README.md
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
<!-- DO NOT EDIT, generated by make README.md -->
# The Void Linux live image/rootfs generator and installer
## Overview
This repository contains several utilities:
* [*mklive.sh*](#mklivesh) - The Void Linux live image generator for x86
* [*build-x86-images.sh*](#build-x86-imagessh) - Wrapper script to generate bootable
and installable live images for x86
* [*mkrootfs.sh*](#mkrootfssh) - The Void Linux rootfs generator for all platforms
* [*mkplatformfs.sh*](#mkplatformfssh) - The Void Linux filesystem tool to produce
a rootfs for a particular platform
* [*mkimage.sh*](#mkimagesh) - The Void Linux image generator for ARM platforms
* [*mknet.sh*](#mknetsh) - Script to generate netboot tarballs for Void
* *installer.sh* - The Void Linux el-cheapo installer for x86
* *release.sh* - interacts with GitHub CI to generate and sign images for releases
### Workflow
#### Generating x86 live ISOs
To generate a live ISO like the officially-published ones, use
[*build-x86-images.sh*](#build-x86-imagessh). To generate a more basic live ISO
(which does not include things like `void-installer`), use [*mklive.sh*](#mklivesh).
#### Generating ROOTFS tarballs
ROOTFS tarballs contain a basic Void Linux root filesystem without a kernel.
These can be useful for doing a [chroot install](https://docs.voidlinux.org/installation/guides/chroot.html)
or for [chroots and containers](https://docs.voidlinux.org/config/containers-and-vms/chroot.html).
Use [*mkrootfs.sh*](#mkrootfssh) to generate a Void Linux ROOTFS.
#### Generating platform-specific tarballs
Platform-specific ROOTFS tarballs, or PLATFORMFS tarballs, contain a basic Void
Linux root filesystem including a kernel. These are commonly used for bootstrapping
ARM systems or other environments that require platform-specific kernels, like
Raspberry Pis.
First create a ROOTFS for the desired architecture, then use
[*mkplatformfs.sh*](#mkplatformfssh) to generate a Void Linux PLATFORMFS.
#### Generating ARM images
Platform-specific filesystem images contain a basic filesystem layout (`/` and
`/boot` partitions), ready to be copied to the target drive with `dd`. despite
the naming, they are not traditional "live" images like those available on x86
platforms, and do not need installation like live ISOs.
To generate these images, first create a PLATFORMFS for the desired platform,
then use [*mkimage.sh*](#mkimagesh) to generate the image.
## Dependencies
Note that void-mklive is not guaranteed to work on distributions other than Void
Linux, or in containers.
* Compression type for the initramfs image (by default: liblz4 for lz4, xz)
* xbps>=0.45
* qemu-user-static binaries (for mkrootfs)
* bash
## Kernel Command-line Parameters
`void-mklive`-based live images support several kernel command-line arguments
that can change the behavior of the live system:
- `live.autologin` will skip the initial login screen on `tty1`.
- `live.user` will change the username of the non-root user from the default
`anon`. The password remains `voidlinux`.
- `live.shell` sets the default shell for the non-root user in the live environment.
- `live.accessibility` enables accessibility features like the console screenreader
`espeakup` in the live environment.
- `console` can be set to `ttyS0`, `hvc0`, or `hvsi0` to enable `agetty` on that
serial console.
- `locale.LANG` will set the `LANG` environment variable. Defaults to `en_US.UTF-8`.
- `vconsole.keymap` will set the console keymap. Defaults to `us`.
### Examples:
- `live.autologin live.user=foo live.shell=/bin/bash` would create the user `foo`
with the default shell `/bin/bash` on boot, and log them in automatically on `tty1`
- `live.shell=/bin/bash` would set the default shell for the `anon` user to `/bin/bash`
- `console=ttyS0 vconsole.keymap=cf` would enable `ttyS0` and set the keymap in
the console to `cf`
- `locale.LANG=fr_CA.UTF-8` would set the live system's language to `fr_CA.UTF-8`
## Usage
### build-x86-images.sh
```
Usage: build-x86-images.sh [options ...] [-- mklive options ...]
Wrapper script around mklive.sh for several standard flavors of live images.
Adds void-installer and other helpful utilities to the generated images.
OPTIONS
-a <arch> Set XBPS_ARCH in the image
-b <variant> One of base, enlightenment, xfce, mate, cinnamon, gnome, kde,
lxde, or lxqt (default: base). May be specified multiple times
to build multiple variants
-d <date> Override the datestamp on the generated image (YYYYMMDD format)
-t <arch-date-variant>
Equivalent to setting -a, -b, and -d
-r <repo> Use this XBPS repository. May be specified multiple times
-h Show this help and exit
-V Show version and exit
Other options can be passed directly to mklive.sh by specifying them after the --.
See mklive.sh -h for more details.
```
### mklive.sh
```
Usage: mklive.sh [options]
Generates a basic live ISO image of Void Linux. This ISO image can be written
to a CD/DVD-ROM or any USB stick.
To generate a more complete live ISO image, use build-x86-images.sh.
OPTIONS
-a <arch> Set XBPS_ARCH in the ISO image
-b <system-pkg> Set an alternative base package (default: base-system)
-r <repo> Use this XBPS repository. May be specified multiple times
-c <cachedir> Use this XBPS cache directory (default: ./xbps-cachedir-<arch>)
-k <keymap> Default keymap to use (default: us)
-l <locale> Default locale to use (default: en_US.UTF-8)
-i <lz4|gzip|bzip2|xz>
Compression type for the initramfs image (default: xz)
-s <gzip|lzo|xz> Compression type for the squashfs image (default: xz)
-o <file> Output file name for the ISO image (default: automatic)
-p "<pkg> ..." Install additional packages in the ISO image
-g "<pkg> ..." Ignore packages when building the ISO image
-I <includedir> Include directory structure under given path in the ROOTFS
-S "<service> ..." Enable services in the ISO image
-C "<arg> ..." Add additional kernel command line arguments
-T <title> Modify the bootloader title (default: Void Linux)
-v linux<version> Install a custom Linux version on ISO image (default: linux metapackage)
-K Do not remove builddir
-h Show this help and exit
-V Show version and exit
```
### mkrootfs.sh
```
Usage: mkrootfs.sh [options] <arch>
Generate a Void Linux ROOTFS tarball for the specified architecture.
Supported architectures:
i686, i686-musl, x86_64, x86_64-musl,
armv5tel, armv5tel-musl, armv6l, armv6l-musl, armv7l, armv7l-musl
aarch64, aarch64-musl,
mipsel, mipsel-musl,
ppc, ppc-musl, ppc64le, ppc64le-musl, ppc64, ppc64-musl
OPTIONS
-b <system-pkg> Set an alternative base-system package (default: base-container-full)
-c <cachedir> Set XBPS cache directory (default: ./xbps-cachedir-<arch>)
-C <file> Full path to the XBPS configuration file
-r <repo> Use this XBPS repository. May be specified multiple times
-o <file> Filename to write the ROOTFS to (default: automatic)
-x <num> Number of threads to use for image compression (default: dynamic)
-h Show this help and exit
-V Show version and exit
```
### mkplatformfs.sh
```
Usage: mkplatformfs.sh [options] <platform> <rootfs-tarball>
Generates a platform-specific ROOTFS tarball from a generic Void Linux ROOTFS
generated by mkrootfs.sh.
Supported platforms: i686, x86_64, GCP,
rpi-armv6l, rpi-armv7l, rpi-aarch64,
pinebookpro, pinephone, rock64
OPTIONS
-b <system-pkg> Set an alternative base-system package (default: base-system)
-c <cachedir> Set the XBPS cache directory (default: ./xbps-cachedir-<arch>)
-C <file> Full path to the XBPS configuration file
-k <cmd> Call '<cmd> <ROOTFSPATH>' after building the ROOTFS
-n Do not compress the image, instead print out the ROOTFS directory
-o <file> Filename to write the PLATFORMFS archive to (default: automatic)
-p "<pkg> ..." Additional packages to install into the ROOTFS
-r <repo> Use this XBPS repository. May be specified multiple times
-x <num> Number of threads to use for image compression (default: dynamic)
-h Show this help and exit
-V Show version and exit
```
### mkimage.sh
```
Usage: mkimage.sh [options] <platformfs-tarball>
Generates a filesystem image suitable for writing with dd from a PLATFORMFS
tarball generated by mkplatformfs.sh. The filesystem layout is configurable,
but customization of the installed system should be done when generating the
PLATFORMFS. The resulting image will have 2 partitions, /boot and /.
OPTIONS
-b <fstype> /boot filesystem type (default: vfat)
-B <bsize> /boot filesystem size (default: 256MiB)
-r <fstype> / filesystem type (default: ext4)
-s <totalsize> Total image size (default: 2GiB)
-o <output> Image filename (default: guessed automatically)
-x <num> Number of threads to use for image compression (default: dynamic)
-h Show this help and exit
-V Show version and exit
Accepted size suffixes: KiB, MiB, GiB, TiB, EiB.
The <platformfs-tarball> argument expects a tarball generated by mkplatformfs.sh.
The platform is guessed automatically by its name.
```
### mknet.sh
```
Usage: mknet.sh [options] <rootfs-tarball>
Generates a network-bootable tarball from a Void Linux ROOTFS generated by mkrootfs.
OPTIONS
-r <repo> Use this XBPS repository. May be specified multiple times
-c <cachedir> Use this XBPS cache directory (default: )
-i <lz4|gzip|bzip2|xz>
Compression type for the initramfs image (default: xz)
-o <file> Output file name for the netboot tarball (default: automatic)
-K linux<version> Install a custom Linux version on ISO image (default: linux metapackage)
-k <keymap> Default keymap to use (default: us)
-l <locale> Default locale to use (default: en_US.UTF-8)
-C "<arg> ..." Add additional kernel command line arguments
-T <title> Modify the bootloader title (default: Void Linux)
-S <image> Set a custom splash image for the bootloader (default: data/splash.png)
-h Show this help and exit
-V Show version and exit
```