##// END OF EJS Templates
pullback from pull
Unknown -
r697:0797db4e7989
parent child
Show More
@@ -1,571 +1,572
1 1 # rpi23-gen-image
2 2 ## Introduction
3 3 `rpi23-gen-image.sh` is an advanced Debian Linux bootstrapping shell script for generating Debian OS images for all Raspberry Pi computers. The script at this time supports the bootstrapping of the Debian (armhf/armel) releases `stretch` and `buster`. Raspberry Pi 0/1/2/3/4 images are generated for 32-bit mode only. Raspberry Pi 3 supports 64-bit images that can be generated using custom configuration parameters (```templates/rpi3-stretch-arm64-4.14.y```).
4 4
5 5 ## Build dependencies
6 6 The following list of Debian packages must be installed on the build system because they are essentially required for the bootstrapping process. The script will check if all required packages are installed and missing packages will be installed automatically if confirmed by the user.
7 7
8 8 ```debootstrap debian-archive-keyring qemu-user-static binfmt-support dosfstools rsync bmap-tools whois git bc psmisc dbus sudo```
9 9
10 10 It is recommended to configure the `rpi23-gen-image.sh` script to build and install the latest Raspberry Pi Linux kernel. For the Raspberry 3 this is mandatory. Kernel compilation and linking will be performed on the build system using an ARM (armhf/armel/aarch64) cross-compiler toolchain.
11 11
12 12 The script has been tested using the default `crossbuild-essential-armhf` and `crossbuild-essential-armel` toolchain meta packages on Debian Linux `stretch` build systems. Please check the [Debian CrossToolchains Wiki](https://wiki.debian.org/CrossToolchains) for further information.
13 13
14 14 ## Command-line parameters
15 15 The script accepts certain command-line parameters to enable or disable specific OS features, services and configuration settings. These parameters are passed to the `rpi23-gen-image.sh` script via (simple) shell-variables. Unlike environment shell-variables (simple) shell-variables are defined at the beginning of the command-line call of the `rpi23-gen-image.sh` script.
16 16
17 17 ##### Command-line examples:
18 18 ```shell
19 19 ENABLE_UBOOT=true ./rpi23-gen-image.sh
20 20 ENABLE_CONSOLE=false ENABLE_IPV6=false ./rpi23-gen-image.sh
21 21 ENABLE_WM=xfce4 ENABLE_FBTURBO=true ENABLE_MINBASE=true ./rpi23-gen-image.sh
22 22 ENABLE_HARDNET=true ENABLE_IPTABLES=true /rpi23-gen-image.sh
23 23 APT_SERVER=ftp.de.debian.org APT_PROXY="http://127.0.0.1:3142/" ./rpi23-gen-image.sh
24 24 ENABLE_MINBASE=true ./rpi23-gen-image.sh
25 25 BUILD_KERNEL=true ENABLE_MINBASE=true ENABLE_IPV6=false ./rpi23-gen-image.sh
26 26 BUILD_KERNEL=true KERNELSRC_DIR=/tmp/linux ./rpi23-gen-image.sh
27 27 ENABLE_MINBASE=true ENABLE_REDUCE=true ENABLE_MINGPU=true BUILD_KERNEL=true ./rpi23-gen-image.sh
28 28 ENABLE_CRYPTFS=true CRYPTFS_PASSWORD=changeme EXPANDROOT=false ENABLE_MINBASE=true ENABLE_REDUCE=true ENABLE_MINGPU=true BUILD_KERNEL=true ./rpi23-gen-image.sh
29 29 RELEASE=stretch BUILD_KERNEL=true ./rpi23-gen-image.sh
30 30 RPI_MODEL=3 ENABLE_WIRELESS=true ENABLE_MINBASE=true BUILD_KERNEL=true ./rpi23-gen-image.sh
31 31 RELEASE=stretch RPI_MODEL=3 ENABLE_WIRELESS=true ENABLE_MINBASE=true BUILD_KERNEL=true ./rpi23-gen-image.sh
32 32 ```
33 33
34 34 ## Configuration template files
35 35 To avoid long lists of command-line parameters and to help to store the favourite parameter configurations the `rpi23-gen-image.sh` script supports so called configuration template files (`CONFIG_TEMPLATE`=template). These are simple text files located in the `./templates` directory that contain the list of configuration parameters that will be used. New configuration template files can be added to the `./templates` directory.
36 36
37 37 ##### Command-line examples:
38 38 ```shell
39 39 CONFIG_TEMPLATE=rpi3stretch ./rpi23-gen-image.sh
40 40 CONFIG_TEMPLATE=rpi2stretch ./rpi23-gen-image.sh
41 41 ```
42 42
43 43 ## Supported parameters and settings
44 44 #### APT settings:
45 45 ##### `APT_SERVER`="ftp.debian.org"
46 46 Set Debian packages server address. Choose a server from the list of Debian worldwide [mirror sites](https://www.debian.org/mirror/list). Using a nearby server will probably speed-up all required downloads within the bootstrapping process.
47 47
48 48 ##### `APT_PROXY`=""
49 49 Set Proxy server address. Using a local Proxy-Cache like `apt-cacher-ng` will speed-up the bootstrapping process because all required Debian packages will only be downloaded from the Debian mirror site once. If `apt-cacher-ng` is running on default `http://127.0.0.1:3142` it is autodetected and you don't need to set this.
50 50
51 51 ##### `KEEP_APT_PROXY`=false
52 52 Keep the APT_PROXY settings used in the bootsrapping process in the generated image.
53 53
54 54 ##### `APT_INCLUDES`=""
55 55 A comma-separated list of additional packages to be installed by debootstrap during bootstrapping.
56 56
57 57 ##### `APT_INCLUDES_LATE`=""
58 58 A comma-separated list of additional packages to be installed by apt after bootstrapping and after APT sources are set up. This is useful for packages with pre-depends, which debootstrap do not handle well.
59 59
60 60 ---
61 61
62 62 #### General system settings:
63 63 ##### `SET_ARCH`=32
64 64 Set Architecture to default 32bit. If you want to compile 64-bit (RPI3/RPI3+/RPI4) set it to `64`. This option will set every needed cross-compiler or board specific option for a successful build.
65 65
66 66 ##### `RPI_MODEL`=2
67 67 Specify the target Raspberry Pi hardware model. The script at this time supports the following Raspberry Pi models:
68 68 - `0` = Raspberry Pi 0 and Raspberry Pi 0 W
69 69 - `1` = Raspberry Pi 1 model A and B
70 70 - `1P` = Raspberry Pi 1 model B+ and A+
71 71 - `2` = Raspberry Pi 2 model B
72 72 - `3` = Raspberry Pi 3 model B
73 73 - `3P` = Raspberry Pi 3 model B+
74 74 - `4` = Raspberry Pi 4 model B
75 75
76 76 ##### `RELEASE`="buster"
77 77 Set the desired Debian release name. The script at this time supports the bootstrapping of the Debian releases `stretch` and `buster`.
78 78
79 79 ##### `RELEASE_ARCH`="armhf"
80 80 Set the desired Debian release architecture.
81 81
82 82 ##### `HOSTNAME`="rpi$RPI_MODEL-$RELEASE"
83 83 Set system hostname. It's recommended that the hostname is unique in the corresponding subnet.
84 84
85 85 ##### `PASSWORD`="raspberry"
86 86 Set system `root` password. It's **STRONGLY** recommended that you choose a custom password.
87 87
88 88 ##### `USER_PASSWORD`="raspberry"
89 89 Set password for the created non-root user `USER_NAME`=pi. Ignored if `ENABLE_USER`=false. It's **STRONGLY** recommended that you choose a custom password.
90 90
91 91 ##### `DEFLOCAL`="en_US.UTF-8"
92 92 Set default system locale. This setting can also be changed inside the running OS using the `dpkg-reconfigure locales` command. Please note that on using this parameter the script will automatically install the required packages `locales`, `keyboard-configuration` and `console-setup`.
93 93
94 94 ##### `TIMEZONE`="Europe/Berlin"
95 95 Set default system timezone. All available timezones can be found in the `/usr/share/zoneinfo/` directory. This setting can also be changed inside the running OS using the `dpkg-reconfigure tzdata` command.
96 96
97 97 ##### `EXPANDROOT`=true
98 98 Expand the root partition and filesystem automatically on first boot.
99 99
100 100 ##### `ENABLE_DPHYSSWAP`=true
101 101 Enable swap. The size of the swapfile is chosen relative to the size of the root partition. It'll use the `dphys-swapfile` package for that.
102 102
103 103 ##### `ENABLE_QEMU`=false
104 104 Generate kernel (`vexpress_defconfig`), file system image (`qcow2`) and DTB files that can be used for QEMU full system emulation (`vexpress-A15`). The output files are stored in the `$(pwd)/images/qemu` directory. You can find more information about running the generated image in the QEMU section of this readme file.
105 105
106 106 ---
107 107
108 108 #### Keyboard settings:
109 109 These options are used to configure keyboard layout in `/etc/default/keyboard` for console and Xorg. These settings can also be changed inside the running OS using the `dpkg-reconfigure keyboard-configuration` command.
110 110
111 111 ##### `XKB_MODEL`=""
112 112 Set the name of the model of your keyboard type.
113 113
114 114 ##### `XKB_LAYOUT`=""
115 115 Set the supported keyboard layout(s).
116 116
117 117 ##### `XKB_VARIANT`=""
118 118 Set the supported variant(s) of the keyboard layout(s).
119 119
120 120 ##### `XKB_OPTIONS`=""
121 121 Set extra xkb configuration options.
122 122
123 123 ---
124 124
125 125 #### Networking settings (DHCP):
126 126 This parameter is used to set up networking auto-configuration in `/etc/systemd/network/eth.network`. The default location of network configuration files in the Debian `stretch` release was changed to `/lib/systemd/network`.`
127 127
128 128 ##### `ENABLE_DHCP`=true
129 129 Set the system to use DHCP. This requires an DHCP server.
130 130
131 131 ---
132 132
133 133 #### Networking settings (static):
134 134 These parameters are used to set up a static networking configuration in `/etc/systemd/network/eth.network`. The following static networking parameters are only supported if `ENABLE_DHCP` was set to `false`. The default location of network configuration files in the Debian `stretch` release was changed to `/lib/systemd/network`.
135 135
136 136 ##### `NET_ADDRESS`=""
137 137 Set a static IPv4 or IPv6 address and its prefix, separated by "/", eg. "192.169.0.3/24".
138 138
139 139 ##### `NET_GATEWAY`=""
140 140 Set the IP address for the default gateway.
141 141
142 142 ##### `NET_DNS_1`=""
143 143 Set the IP address for the first DNS server.
144 144
145 145 ##### `NET_DNS_2`=""
146 146 Set the IP address for the second DNS server.
147 147
148 148 ##### `NET_DNS_DOMAINS`=""
149 149 Set the default DNS search domains to use for non fully qualified hostnames.
150 150
151 151 ##### `NET_NTP_1`=""
152 152 Set the IP address for the first NTP server.
153 153
154 154 ##### `NET_NTP_2`=""
155 155 Set the IP address for the second NTP server.
156 156
157 157 ---
158 158
159 159 #### Basic system features:
160 160 ##### `ENABLE_CONSOLE`=true
161 161 Enable serial console interface. Recommended if no monitor or keyboard is connected to the RPi2/3. In case of problems fe. if the network (auto) configuration failed - the serial console can be used to access the system. On RPI `0` `3` `3P` the CPU speed is locked at lowest speed.
162 162
163 163 ##### `ENABLE_PRINTK`=false
164 164 Enables printing kernel messages to konsole. printk is `3 4 1 3` as in raspbian.
165 165
166 166 ##### `ENABLE_BLUETOOTH`=false
167 167 Enable onboard Bluetooth interface on the RPi0/3/3P. See: [Configuring the GPIO serial port on Raspbian jessie and stretch](https://spellfoundry.com/2016/05/29/configuring-gpio-serial-port-raspbian-jessie-including-pi-3/).
168 168
169 169 ##### `ENABLE_MINIUART_OVERLAY`=false
170 170 Enable Bluetooth to use this. Adds overlay to swap UART0 with UART1. Enabling (slower) Bluetooth and full speed serial console. - RPI `0` `3` `3P` have a fast `hardware UART0` (ttyAMA0) and a `mini UART1` (ttyS0)! RPI `1` `1P` `2` only have a `hardware UART0`. `UART0` is considered better, because is faster and more stable than `mini UART1`. By default the Bluetooth modem is mapped to the `hardware UART0` and `mini UART` is used for console. The `mini UART` is a problem for the serial console, because its baudrate depends on the CPU frequency, which is changing on runtime. Resulting in a volatile baudrate and thus in an unusable serial console.
171 171
172 172 ##### `ENABLE_TURBO`=false
173 173 Enable Turbo mode. This setting locks cpu at the highest frequency. As setting ENABLE_CONSOLE=true locks RPI to lowest CPU speed, this is can be used additionally to lock cpu hat max speed. Need a good power supply and probably cooling for the Raspberry PI.
174 174
175 175 ##### `ENABLE_I2C`=false
176 176 Enable I2C interface on the RPi 0/1/2/3. Please check the [RPi 0/1/2/3 pinout diagrams](https://elinux.org/RPi_Low-level_peripherals) to connect the right GPIO pins.
177 177
178 178 ##### `ENABLE_SPI`=false
179 179 Enable SPI interface on the RPi 0/1/2/3. Please check the [RPi 0/1/2/3 pinout diagrams](https://elinux.org/RPi_Low-level_peripherals) to connect the right GPIO pins.
180 180
181 181 ##### `ENABLE_IPV6`=true
182 182 Enable IPv6 support. The network interface configuration is managed via systemd-networkd.
183 183
184 184 ##### `ENABLE_SSHD`=true
185 185 Install and enable OpenSSH service. The default configuration of the service doesn't allow `root` to login. Please use the user `pi` instead and `su -` or `sudo` to execute commands as root.
186 186
187 187 ##### `ENABLE_NONFREE`=false
188 188 Allow the installation of non-free Debian packages that do not comply with the DFSG. This is required to install closed-source firmware binary blobs.
189 189
190 190 ##### `ENABLE_WIRELESS`=false
191 191 Download and install the [closed-source firmware binary blob](https://github.com/RPi-Distro/firmware-nonfree/raw/master/brcm) that is required to run the internal wireless interface of the Raspberry Pi model `3`. This parameter is ignored if the specified `RPI_MODEL` is not `3`.
192 192
193 193 ##### `ENABLE_RSYSLOG`=true
194 194 If set to false, disable and uninstall rsyslog (so logs will be available only in journal files)
195 195
196 196 ##### `ENABLE_SOUND`=true
197 197 Enable sound hardware and install Advanced Linux Sound Architecture.
198 198
199 199 ##### `ENABLE_HWRANDOM`=true
200 200 Enable Hardware Random Number Generator. Strong random numbers are important for most network-based communications that use encryption. It's recommended to be enabled.
201 201
202 202 ##### `ENABLE_MINGPU`=false
203 203 Minimize the amount of shared memory reserved for the GPU. It doesn't seem to be possible to fully disable the GPU.
204 204
205 205 ##### `ENABLE_DBUS`=true
206 206 Install and enable D-Bus message bus. Please note that systemd should work without D-bus but it's recommended to be enabled.
207 207
208 208 ##### `ENABLE_XORG`=false
209 209 Install Xorg open-source X Window System.
210 210
211 211 ##### `ENABLE_WM`=""
212 212 Install a user-defined window manager for the X Window System. To make sure all X related package dependencies are getting installed `ENABLE_XORG` will automatically get enabled if `ENABLE_WM` is used. The `rpi23-gen-image.sh` script has been tested with the following list of window managers: `blackbox`, `openbox`, `fluxbox`, `jwm`, `dwm`, `xfce4`, `awesome`.
213 213
214 214 ##### `ENABLE_SYSVINIT`=false
215 215 Support for halt,init,poweroff,reboot,runlevel,shutdown,telinit commands
216 216
217 217 ---
218 218
219 219 #### Advanced system features:
220 220 ##### `ENABLE_KEYGEN`=false
221 221 Recover your lost codec license
222 222
223 223 ##### `ENABLE_SYSTEMDSWAP`=false
224 224 Enables [Systemd-swap service](https://github.com/Nefelim4ag/systemd-swap). Usefull if `KERNEL_ZSWAP` is enabled.
225 225
226 226 ##### `ENABLE_MINBASE`=false
227 227 Use debootstrap script variant `minbase` which only includes essential packages and apt. This will reduce the disk usage by about 65 MB.
228 228
229 229 ##### `ENABLE_REDUCE`=false
230 230 Reduce the disk space usage by deleting packages and files. See `REDUCE_*` parameters for detailed information.
231 231
232 232 ##### `ENABLE_UBOOT`=false
233 Replace the default RPi 0/1/2/3/4 second stage bootloader (bootcode.bin) with [U-Boot bootloader](https://git.denx.de/?p=u-boot.git;a=summary). U-Boot can boot images via the network using the BOOTP/TFTP protocol.
233 Replace the default RPi 0/1/2/3 second stage bootloader (bootcode.bin) with [U-Boot bootloader](https://git.denx.de/?p=u-boot.git;a=summary). U-Boot can boot images via the network using the BOOTP/TFTP protocol.
234 RPI4 needs tbd
234 235
235 236 ##### `UBOOTSRC_DIR`=""
236 237 Path to a directory (`u-boot`) of [U-Boot bootloader sources](https://git.denx.de/?p=u-boot.git;a=summary) that will be copied, configured, build and installed inside the chroot.
237 238
238 239 ##### `ENABLE_FBTURBO`=false
239 240 Install and enable the [hardware accelerated Xorg video driver](https://github.com/ssvb/xf86-video-fbturbo) `fbturbo`. Please note that this driver is currently limited to hardware accelerated window moving and scrolling.
240 241
241 242 ##### `FBTURBOSRC_DIR`=""
242 243 Path to a directory (`xf86-video-fbturbo`) of [hardware accelerated Xorg video driver sources](https://github.com/ssvb/xf86-video-fbturbo) that will be copied, configured, build and installed inside the chroot.
243 244
244 245 ##### `ENABLE_VIDEOCORE`=false
245 246 Install and enable the [ARM side libraries for interfacing to Raspberry Pi GPU](https://github.com/raspberrypi/userland) `vcgencmd`. Please note that this driver is currently limited to hardware accelerated window moving and scrolling.
246 247
247 248 ##### `VIDEOCORESRC_DIR`=""
248 249 Path to a directory (`userland`) of [ARM side libraries for interfacing to Raspberry Pi GPU](https://github.com/raspberrypi/userland) that will be copied, configured, build and installed inside the chroot.
249 250
250 251 ##### `ENABLE_NEXMON`=false
251 252 Install and enable the [Source code for a C-based firmware patching framework for Broadcom/Cypress WiFi chips that enables you to write your own firmware patches, for example, to enable monitor mode with radiotap headers and frame injection](https://github.com/seemoo-lab/nexmon.git).
252 253
253 254 ##### `NEXMONSRC_DIR`=""
254 255 Path to a directory (`nexmon`) of [Source code for ARM side libraries for interfacing to Raspberry Pi GPU](https://github.com/raspberrypi/userland) that will be copied, configured, build and installed inside the chroot.
255 256
256 257 ##### `ENABLE_IPTABLES`=false
257 258 Enable iptables IPv4/IPv6 firewall. Simplified ruleset: Allow all outgoing connections. Block all incoming connections except to OpenSSH service.
258 259
259 260 ##### `ENABLE_USER`=true
260 261 Create non-root user with password `USER_PASSWORD`=raspberry. Unless overridden with `USER_NAME`=user, the username will be `pi`.
261 262
262 263 ##### `USER_NAME`=pi
263 264 Non-root user to create. Ignored if `ENABLE_USER`=false
264 265
265 266 ##### `ENABLE_ROOT`=false
266 267 Set root user password so root login will be enabled
267 268
268 269 ##### `ENABLE_HARDNET`=false
269 270 Enable IPv4/IPv6 network stack hardening settings.
270 271
271 272 ##### `ENABLE_SPLITFS`=false
272 273 Enable having root partition on an USB drive by creating two image files: one for the `/boot/firmware` mount point, and another for `/`.
273 274
274 275 ##### `CHROOT_SCRIPTS`=""
275 276 Path to a directory with scripts that should be run in the chroot before the image is finally built. Every executable file in this directory is run in lexicographical order.
276 277
277 278 ##### `ENABLE_INITRAMFS`=false
278 279 Create an initramfs that that will be loaded during the Linux startup process. `ENABLE_INITRAMFS` will automatically get enabled if `ENABLE_CRYPTFS`=true. This parameter will be ignored if `BUILD_KERNEL`=false.
279 280
280 281 ##### `ENABLE_IFNAMES`=true
281 282 Enable automatic assignment of predictable, stable network interface names for all local Ethernet, WLAN interfaces. This might create complex and long interface names.
282 283
283 284 ##### `ENABLE_SPLASH`=true
284 285 Enable default Raspberry Pi boot up rainbow splash screen.
285 286
286 287 ##### `ENABLE_LOGO`=true
287 288 Enable default Raspberry Pi console logo (image of four raspberries in the top left corner).
288 289
289 290 ##### `ENABLE_SILENT_BOOT`=false
290 291 Set the verbosity of console messages shown during boot up to a strict minimum.
291 292
292 293 ##### `DISABLE_UNDERVOLT_WARNINGS`=
293 294 Disable RPi2/3 under-voltage warnings and overlays. Setting the parameter to `1` will disable the warning overlay. Setting it to `2` will additionally allow RPi2/3 turbo mode when low-voltage is present.
294 295
295 296 ---
296 297
297 298 #### SSH settings:
298 299 ##### `SSH_ENABLE_ROOT`=false
299 300 Enable password-based root login via SSH. This may be a security risk with the default password set, use only in trusted environments. `ENABLE_ROOT` must be set to `true`.
300 301
301 302 ##### `SSH_DISABLE_PASSWORD_AUTH`=false
302 303 Disable password-based SSH authentication. Only public key based SSH (v2) authentication will be supported.
303 304
304 305 ##### `SSH_LIMIT_USERS`=false
305 306 Limit the users that are allowed to login via SSH. Only allow user `USER_NAME`=pi and root if `SSH_ENABLE_ROOT`=true to login. This parameter will be ignored if `dropbear` SSH is used (`REDUCE_SSHD`=true).
306 307
307 308 ##### `SSH_ROOT_PUB_KEY`=""
308 309 Add SSH (v2) public key(s) from specified file to `authorized_keys` file to enable public key based SSH (v2) authentication of user `root`. The specified file can also contain multiple SSH (v2) public keys. SSH protocol version 1 is not supported. `ENABLE_ROOT` **and** `SSH_ENABLE_ROOT` must be set to `true`.
309 310
310 311 ##### `SSH_USER_PUB_KEY`=""
311 312 Add SSH (v2) public key(s) from specified file to `authorized_keys` file to enable public key based SSH (v2) authentication of user `USER_NAME`=pi. The specified file can also contain multiple SSH (v2) public keys. SSH protocol version 1 is not supported.
312 313
313 314 ---
314 315
315 316 #### Kernel compilation:
316 317 ##### `BUILD_KERNEL`=true
317 318 Build and install the latest RPi 0/1/2/3/4 Linux kernel. The default RPi 0/1/2/3/ kernel configuration is used most of the time.
318 319 ENABLE_NEXMON - Changes Kernel Source to [https://github.com/Re4son/](Kali Linux Kernel)
319 320 Precompiled 32bit kernel for RPI0/1/2/3 by [https://github.com/hypriot/](hypriot)
320 321 Precompiled 64bit kernel for RPI3/4 by [https://github.com/sakaki-/](sakaki)
321 322
322 323
323 324 ##### `CROSS_COMPILE`="arm-linux-gnueabihf-"
324 325 This sets the cross-compile environment for the compiler.
325 326
326 327 ##### `KERNEL_ARCH`="arm"
327 328 This sets the kernel architecture for the compiler.
328 329
329 330 ##### `KERNEL_IMAGE`="kernel7.img"
330 331 Name of the image file in the boot partition. If not set, `KERNEL_IMAGE` will be set to "kernel8.img" automatically if building for arm64.
331 332
332 333 ##### `KERNEL_BRANCH`=""
333 334 Name of the requested branch from the GIT location for the RPi Kernel. Default is using the current default branch from the GIT site.
334 335
335 336 ##### `QEMU_BINARY`="/usr/bin/qemu-arm-static"
336 337 Sets the QEMU enviornment for the Debian archive. If not set, `QEMU_BINARY` will be set to "/usr/bin/qemu-aarch64-static" automatically if building for arm64.
337 338
338 339 ##### `KERNEL_DEFCONFIG`="bcm2709_defconfig"
339 340 Sets the default config for kernel compiling. If not set, `KERNEL_DEFCONFIG` will be set to "bcmrpi3\_defconfig" automatically if building for arm64.
340 341
341 342 ##### `KERNEL_REDUCE`=false
342 343 Reduce the size of the generated kernel by removing unwanted devices, network and filesystem drivers (experimental).
343 344
344 345 ##### `KERNEL_THREADS`=1
345 346 Number of parallel kernel building threads. If the parameter is left untouched the script will automatically determine the number of CPU cores to set the number of parallel threads to speed the kernel compilation.
346 347
347 348 ##### `KERNEL_HEADERS`=true
348 349 Install kernel headers with the built kernel.
349 350
350 351 ##### `KERNEL_MENUCONFIG`=false
351 352 Start `make menuconfig` interactive menu-driven kernel configuration. The script will continue after `make menuconfig` was terminated.
352 353
353 354 ##### `KERNEL_OLDDEFCONFIG`=false
354 355 Run `make olddefconfig` to automatically set all new kernel configuration options to their recommended default values.
355 356
356 357 ##### `KERNEL_CCACHE`=false
357 358 Compile the kernel using ccache. This speeds up kernel recompilation by caching previous compilations and detecting when the same compilation is being done again.
358 359
359 360 ##### `KERNEL_REMOVESRC`=true
360 361 Remove all kernel sources from the generated OS image after it was built and installed.
361 362
362 363 ##### `KERNELSRC_DIR`=""
363 364 Path to a directory (`linux`) of [RaspberryPi Linux kernel sources](https://github.com/raspberrypi/linux) that will be copied, configured, build and installed inside the chroot.
364 365
365 366 ##### `KERNELSRC_CLEAN`=false
366 367 Clean the existing kernel sources directory `KERNELSRC_DIR` (using `make mrproper`) after it was copied to the chroot and before the compilation of the kernel has started. This parameter will be ignored if no `KERNELSRC_DIR` was specified or if `KERNELSRC_PREBUILT`=true.
367 368
368 369 ##### `KERNELSRC_CONFIG`=true
369 370 Run `make bcm2709_defconfig` (and optional `make menuconfig`) to configure the kernel sources before building. This parameter is automatically set to `true` if no existing kernel sources directory was specified using `KERNELSRC_DIR`. This parameter is ignored if `KERNELSRC_PREBUILT`=true.
370 371
371 372 ##### `KERNELSRC_USRCONFIG`=""
372 373 Copy own config file to kernel `.config`. If `KERNEL_MENUCONFIG`=true then running after copy.
373 374
374 375 ##### `KERNELSRC_PREBUILT`=false
375 376 With this parameter set to true the script expects the existing kernel sources directory to be already successfully cross-compiled. The parameters `KERNELSRC_CLEAN`, `KERNELSRC_CONFIG`, `KERNELSRC_USRCONFIG` and `KERNEL_MENUCONFIG` are ignored and no kernel compilation tasks are performed.
376 377
377 378 ##### `RPI_FIRMWARE_DIR`=""
378 379 The directory (`firmware`) containing a local copy of the firmware from the [RaspberryPi firmware project](https://github.com/raspberrypi/firmware). Default is to download the latest firmware directly from the project.
379 380
380 381 ##### `KERNEL_DEFAULT_GOV`="ONDEMAND"
381 382 Set the default cpu governor at kernel compilation. Supported values are: PERFORMANCE POWERSAVE USERSPACE ONDEMAND CONSERVATIVE SCHEDUTIL
382 383
383 384 ##### `KERNEL_NF`=false
384 385 Enable Netfilter modules as kernel modules
385 386
386 387 ##### `KERNEL_VIRT`=false
387 388 Enable Kernel KVM support (/dev/kvm)
388 389
389 390 ##### `KERNEL_ZSWAP`=false
390 391 Enable Kernel Zswap support. Best use on high RAM load and mediocre CPU load usecases
391 392
392 393 ##### `KERNEL_BPF`=true
393 394 Allow attaching eBPF programs to a cgroup using the bpf syscall (CONFIG_BPF_SYSCALL CONFIG_CGROUP_BPF) [systemd compilations about it - File /lib/systemd/system/systemd-journald.server:36 configures an IP firewall (IPAddressDeny=all), but the local system does not support BPF/cgroup based firewalls]
394 395
395 396 ##### `KERNEL_SECURITY`=false
396 397 Enables Apparmor, integrity subsystem, auditing.
397 398
398 399 ##### `KERNEL_BTRFS`="false"
399 400 enable btrfs kernel support
400 401
401 402 ##### `KERNEL_POEHAT`="false"
402 403 enable Enable RPI POE HAT fan kernel support
403 404
404 405 ##### `KERNEL_NSPAWN`="false"
405 406 Enable per-interface network priority control - for systemd-nspawn
406 407
407 408 ##### `KERNEL_DHKEY`="true"
408 409 Diffie-Hellman operations on retained keys - required for >keyutils-1.6
409 410
410 411 ---
411 412
412 413 #### Reduce disk usage:
413 414 The following list of parameters is ignored if `ENABLE_REDUCE`=false.
414 415
415 416 ##### `REDUCE_APT`=true
416 417 Configure APT to use compressed package repository lists and no package caching files.
417 418
418 419 ##### `REDUCE_DOC`=true
419 420 Remove all doc files (harsh). Configure APT to not include doc files on future `apt-get` package installations.
420 421
421 422 ##### `REDUCE_MAN`=true
422 423 Remove all man pages and info files (harsh). Configure APT to not include man pages on future `apt-get` package installations.
423 424
424 425 ##### `REDUCE_VIM`=false
425 426 Replace `vim-tiny` package by `levee` a tiny vim clone.
426 427
427 428 ##### `REDUCE_BASH`=false
428 429 Remove `bash` package and switch to `dash` shell (experimental).
429 430
430 431 ##### `REDUCE_HWDB`=true
431 432 Remove PCI related hwdb files (experimental).
432 433
433 434 ##### `REDUCE_SSHD`=true
434 435 Replace `openssh-server` with `dropbear`.
435 436
436 437 ##### `REDUCE_LOCALE`=true
437 438 Remove all `locale` translation files.
438 439
439 440 ---
440 441
441 442 #### Encrypted root partition:
442 443 ##### `ENABLE_CRYPTFS`=false
443 444 Enable full system encryption with dm-crypt. Setup a fully LUKS encrypted root partition (aes-xts-plain64:sha512) and generate required initramfs. The /boot directory will not be encrypted. This parameter will be ignored if `BUILD_KERNEL`=false. `ENABLE_CRYPTFS` is experimental. SSH-to-initramfs is currently not supported but will be soon - feel free to help.
444 445
445 446 ##### `CRYPTFS_PASSWORD`=""
446 447 Set password of the encrypted root partition. This parameter is mandatory if `ENABLE_CRYPTFS`=true.
447 448
448 449 ##### `CRYPTFS_MAPPING`="secure"
449 450 Set name of dm-crypt managed device-mapper mapping.
450 451
451 452 ##### `CRYPTFS_CIPHER`="aes-xts-plain64"
452 453 Set cipher specification string. `aes-xts*` ciphers are strongly recommended.
453 454
454 455 ##### `CRYPTFS_HASH`=sha512
455 456 Hash function and size to be used
456 457
457 458 ##### `CRYPTFS_XTSKEYSIZE`=512
458 459 Sets key size in bits. The argument has to be a multiple of 8.
459 460
460 461 ##### `CRYPTFS_DROPBEAR`=false
461 462 Enable Dropbear Initramfs support
462 463
463 464 ##### `CRYPTFS_DROPBEAR_PUBKEY`=""
464 465 Provide path to dropbear Public RSA-OpenSSH Key
465 466
466 467 ---
467 468
468 469 #### Build settings:
469 470 ##### `BASEDIR`=$(pwd)/images/${RELEASE}
470 471 Set a path to a working directory used by the script to generate an image.
471 472
472 473 ##### `IMAGE_NAME`=${BASEDIR}/${DATE}-${KERNEL_ARCH}-${KERNEL_BRANCH}-rpi${RPI_MODEL}-${RELEASE}-${RELEASE_ARCH}
473 474 Set a filename for the output file(s). Note: the script will create $IMAGE_NAME.img if `ENABLE_SPLITFS`=false or $IMAGE_NAME-frmw.img and $IMAGE_NAME-root.img if `ENABLE_SPLITFS`=true. Note 2: If the KERNEL_BRANCH is not set, the word "CURRENT" is used.
474 475
475 476 ## Understanding the script
476 477 The functions of this script that are required for the different stages of the bootstrapping are split up into single files located inside the `bootstrap.d` directory. During the bootstrapping every script in this directory gets executed in lexicographical order:
477 478
478 479 | Script | Description |
479 480 | --- | --- |
480 481 | `10-bootstrap.sh` | Debootstrap basic system |
481 482 | `11-apt.sh` | Setup APT repositories |
482 483 | `12-locale.sh` | Setup Locales and keyboard settings |
483 484 | `13-kernel.sh` | Build and install RPi 0/1/2/3 Kernel |
484 485 | `14-fstab.sh` | Setup fstab and initramfs |
485 486 | `15-rpi-config.sh` | Setup RPi 0/1/2/3 config and cmdline |
486 487 | `20-networking.sh` | Setup Networking |
487 488 | `21-firewall.sh` | Setup Firewall |
488 489 | `30-security.sh` | Setup Users and Security settings |
489 490 | `31-logging.sh` | Setup Logging |
490 491 | `32-sshd.sh` | Setup SSH and public keys |
491 492 | `41-uboot.sh` | Build and Setup U-Boot |
492 493 | `42-fbturbo.sh` | Build and Setup fbturbo Xorg driver |
493 494 | `43-videocore.sh` | Build and Setup videocore libraries |
494 495 | `50-firstboot.sh` | First boot actions |
495 496 | `99-reduce.sh` | Reduce the disk space usage |
496 497
497 498 All the required configuration files that will be copied to the generated OS image are located inside the `files` directory. It is not recommended to modify these configuration files manually.
498 499
499 500 | Directory | Description |
500 501 | --- | --- |
501 502 | `apt` | APT management configuration files |
502 503 | `boot` | Boot and RPi 0/1/2/3 configuration files |
503 504 | `dpkg` | Package Manager configuration |
504 505 | `etc` | Configuration files and rc scripts |
505 506 | `firstboot` | Scripts that get executed on first boot |
506 507 | `initramfs` | Initramfs scripts |
507 508 | `iptables` | Firewall configuration files |
508 509 | `locales` | Locales configuration |
509 510 | `modules` | Kernel Modules configuration |
510 511 | `mount` | Fstab configuration |
511 512 | `network` | Networking configuration files |
512 513 | `sysctl.d` | Swapping and Network Hardening configuration |
513 514 | `xorg` | fbturbo Xorg driver configuration |
514 515
515 516 ## Custom packages and scripts
516 517 Debian custom packages, i.e. those not in the debian repositories, can be installed by placing them in the `packages` directory. They are installed immediately after packages from the repositories are installed. Any dependencies listed in the custom packages will be downloaded automatically from the repositories. Do not list these custom packages in `APT_INCLUDES`.
517 518
518 519 Scripts in the custom.d directory will be executed after all other installation is complete but before the image is created.
519 520
520 521 ## Logging of the bootstrapping process
521 522 All information related to the bootstrapping process and the commands executed by the `rpi23-gen-image.sh` script can easily be saved into a logfile. The common shell command `script` can be used for this purpose:
522 523
523 524 ```shell
524 525 script -c 'APT_SERVER=ftp.de.debian.org ./rpi23-gen-image.sh' ./build.log
525 526 ```
526 527
527 528 ## Flashing the image file
528 529 After the image file was successfully created by the `rpi23-gen-image.sh` script it can be copied to the microSD card that will be used by the RPi 0/1/2/3 computer. This can be performed by using the tools `bmaptool` or `dd`. Using `bmaptool` will probably speed-up the copy process because `bmaptool` copies more wisely than `dd`.
529 530
530 531 ##### Flashing examples:
531 532 ```shell
532 533 bmaptool copy ./images/buster/2017-01-23-rpi3-buster.img /dev/mmcblk0
533 534 dd bs=4M if=./images/buster/2017-01-23-rpi3-buster.img of=/dev/mmcblk0
534 535 ```
535 536 If you have set `ENABLE_SPLITFS`, copy the `-frmw` image on the microSD card, then the `-root` one on the USB drive:
536 537 ```shell
537 538 bmaptool copy ./images/buster/2017-01-23-rpi3-buster-frmw.img /dev/mmcblk0
538 539 bmaptool copy ./images/buster/2017-01-23-rpi3-buster-root.img /dev/sdc
539 540 ```
540 541
541 542 ## QEMU emulation
542 543 Start QEMU full system emulation:
543 544 ```shell
544 545 qemu-system-arm -m 2048M -M vexpress-a15 -cpu cortex-a15 -kernel kernel7.img -no-reboot -dtb vexpress-v2p-ca15_a7.dtb -sd ${IMAGE_NAME}.qcow2 -append "root=/dev/mmcblk0p2 rw rootfstype=ext4 console=tty1"
545 546 ```
546 547
547 548 Start QEMU full system emulation and output to console:
548 549 ```shell
549 550 qemu-system-arm -m 2048M -M vexpress-a15 -cpu cortex-a15 -kernel kernel7.img -no-reboot -dtb vexpress-v2p-ca15_a7.dtb -sd ${IMAGE_NAME}.qcow2 -append "root=/dev/mmcblk0p2 rw rootfstype=ext4 console=ttyAMA0,115200 init=/bin/systemd" -serial stdio
550 551 ```
551 552
552 553 Start QEMU full system emulation with SMP and output to console:
553 554 ```shell
554 555 qemu-system-arm -m 2048M -M vexpress-a15 -cpu cortex-a15 -smp cpus=2,maxcpus=2 -kernel kernel7.img -no-reboot -dtb vexpress-v2p-ca15_a7.dtb -sd ${IMAGE_NAME}.qcow2 -append "root=/dev/mmcblk0p2 rw rootfstype=ext4 console=ttyAMA0,115200 init=/bin/systemd" -serial stdio
555 556 ```
556 557
557 558 Start QEMU full system emulation with cryptfs, initramfs and output to console:
558 559 ```shell
559 560 qemu-system-arm -m 2048M -M vexpress-a15 -cpu cortex-a15 -kernel kernel7.img -no-reboot -dtb vexpress-v2p-ca15_a7.dtb -sd ${IMAGE_NAME}.qcow2 -initrd "initramfs-${KERNEL_VERSION}" -append "root=/dev/mapper/secure cryptdevice=/dev/mmcblk0p2:secure rw rootfstype=ext4 console=ttyAMA0,115200 init=/bin/systemd" -serial stdio
560 561 ```
561 562
562 563 ## External links and references
563 564 * [Debian worldwide mirror sites](https://www.debian.org/mirror/list)
564 565 * [Debian Raspberry Pi 2 Wiki](https://wiki.debian.org/RaspberryPi2)
565 566 * [Debian CrossToolchains Wiki](https://wiki.debian.org/CrossToolchains)
566 567 * [Official Raspberry Pi Firmware on github](https://github.com/raspberrypi/firmware)
567 568 * [Official Raspberry Pi Kernel on github](https://github.com/raspberrypi/linux)
568 569 * [U-BOOT git repository](https://git.denx.de/?p=u-boot.git;a=summary)
569 570 * [Xorg DDX driver fbturbo](https://github.com/ssvb/xf86-video-fbturbo)
570 571 * [RPi3 Wireless interface firmware](https://github.com/RPi-Distro/firmware-nonfree/tree/master/brcm)
571 572 * [Collabora RPi2 Kernel precompiled](https://repositories.collabora.co.uk/debian/)
@@ -1,118 +1,120
1 #!/bin/sh
1 #
2 2 # Setup fstab and initramfs
3 3 #
4 4
5 5 # Load utility functions
6 6 . ./functions.sh
7 7
8 8 # Install and setup fstab
9 9 install_readonly files/mount/fstab "${ETC_DIR}/fstab"
10 10
11 #USB BOOT /boot on sda1 / on sda2
12 if [ "$ENABLE_USBBOOT" = true ] && [ "$ENABLE_CRYPTFS" = false ]; then
13 sed -i "s/mmcblk0p1/sda1/" "${ETC_DIR}/fstab"
14 sed -i "s/mmcblk0p2/sda2/" "${ETC_DIR}/fstab"
15 fi
16
17 # Add usb/sda disk root partition to fstab
18 if [ "$ENABLE_SPLITFS" = true ] && [ "$ENABLE_CRYPTFS" = false ]; then
19 sed -i "s/mmcblk0p2/sda1/" "${ETC_DIR}/fstab"
20 fi
21
22 11 # Generate initramfs file
23 12 if [ "$ENABLE_INITRAMFS" = true ] ; then
24 13 if [ "$ENABLE_CRYPTFS" = true ] ; then
25 14
26 15 # Include initramfs scripts to auto expand encrypted root partition
27 16 if [ "$EXPANDROOT" = true ] ; then
28 17 install_exec files/initramfs/expand_encrypted_rootfs "${ETC_DIR}/initramfs-tools/scripts/init-premount/expand_encrypted_rootfs"
29 18 install_exec files/initramfs/expand-premount "${ETC_DIR}/initramfs-tools/scripts/local-premount/expand-premount"
30 19 install_exec files/initramfs/expand-tools "${ETC_DIR}/initramfs-tools/hooks/expand-tools"
31 20 fi
32 21
33 22 # Replace fstab root partition with encrypted partition mapping
34 23 sed -i "s/mmcblk0p2/mapper\/${CRYPTFS_MAPPING}/" "${ETC_DIR}/fstab"
35 24
36 25 # Add encrypted partition to crypttab and fstab
37 26 install_readonly files/mount/crypttab "${ETC_DIR}/crypttab"
38 27 echo "${CRYPTFS_MAPPING} /dev/mmcblk0p2 none luks,initramfs" >> "${ETC_DIR}/crypttab"
39 28
40 29 if [ "$ENABLE_USBBOOT" = true ] && [ "$ENABLE_SPLITFS" = false ]; then
41 30 sed -i "s/mmcblk0p1/sda1/" "${ETC_DIR}/fstab"
42 31 # Add usb/sda2 disk to crypttab
43 32 sed -i "s/mmcblk0p2/sda2/" "${ETC_DIR}/crypttab"
44 33 fi
45 34
46 35 # Add encrypted root partition to fstab and crypttab
47 36 if [ "$ENABLE_SPLITFS" = true ] && [ "$ENABLE_USBBOOT" = false ]; then
48 37 # Add usb/sda1 disk to crypttab
49 38 sed -i "s/mmcblk0p2/sda1/" "${ETC_DIR}/crypttab"
50 39 fi
51 40
52 41 if [ "$CRYPTFS_DROPBEAR" = true ]; then
53 42 if [ "$ENABLE_DHCP" = false ] ; then
54 43 # Get cdir from NET_ADDRESS e.g. 24
55 44 cdir=$(printf "%s" "${NET_ADDRESS}" | cut -d '/' -f2)
56 45
57 46 # Convert cdir ro netmask e.g. 24 to 255.255.255.0
58 47 NET_MASK=$(cdr2mask "$cdir")
59 48
60 49 # Write static ip settings to "${ETC_DIR}"/initramfs-tools/initramfs.conf
50 # ip=<client-ip>:<server-ip>:<gw-ip>:<netmask>:<hostname>:<device>:<autoconf>
61 51 sed -i "\$a\nIP=${NET_ADDRESS}::${NET_GATEWAY}:${NET_MASK}:${HOSTNAME}:" "${ETC_DIR}"/initramfs-tools/initramfs.conf
52 else
53 sed -i "\$a\nIP=::::${HOSTNAME}::dhcp" "${ETC_DIR}"/initramfs-tools/initramfs.conf
62 54 fi
63 55
64 56 if [ -n "$CRYPTFS_DROPBEAR_PUBKEY" ] && [ -f "$CRYPTFS_DROPBEAR_PUBKEY" ] ; then
65 57 install_readonly "${CRYPTFS_DROPBEAR_PUBKEY}" "${ETC_DIR}"/dropbear-initramfs/id_rsa.pub
66 58 cat "${ETC_DIR}"/dropbear-initramfs/id_rsa.pub >> "${ETC_DIR}"/dropbear-initramfs/authorized_keys
67 59 else
68 60 # Create key
69 61 chroot_exec /usr/bin/dropbearkey -t rsa -f /etc/dropbear-initramfs/id_rsa.dropbear
70 62
71 63 # Convert dropbear key to openssh key
72 64 chroot_exec /usr/lib/dropbear/dropbearconvert dropbear openssh /etc/dropbear-initramfs/id_rsa.dropbear /etc/dropbear-initramfs/id_rsa
73 65
74 66 # Get Public Key Part
75 67 chroot_exec /usr/bin/dropbearkey -y -f /etc/dropbear-initramfs/id_rsa.dropbear | chroot_exec tee /etc/dropbear-initramfs/id_rsa.pub
76 68
77 69 # Delete unwanted lines
78 70 sed -i '/Public/d' "${ETC_DIR}"/dropbear-initramfs/id_rsa.pub
79 71 sed -i '/Fingerprint/d' "${ETC_DIR}"/dropbear-initramfs/id_rsa.pub
80 72
81 73 # Trust the new key
82 74 cat "${ETC_DIR}"/dropbear-initramfs/id_rsa.pub > "${ETC_DIR}"/dropbear-initramfs/authorized_keys
83 75
84 76 # Save Keys - convert with putty from rsa/openssh to puttkey
85 77 cp -f "${ETC_DIR}"/dropbear-initramfs/id_rsa "${BASEDIR}"/dropbear_initramfs_key.rsa
86 78
87 79 # Get unlock script
88 80 install_exec files/initramfs/crypt_unlock.sh "${ETC_DIR}"/initramfs-tools/hooks/crypt_unlock.sh
89 81
90 82 # Enable Dropbear inside initramfs
91 83 printf "#\n# DROPBEAR: [ y | n ]\n#\n\nDROPBEAR=y\n" >> "${ETC_DIR}/initramfs-tools/initramfs.conf"
92 84
93 85 # Enable Dropbear inside initramfs
94 86 sed -i "54 i sleep 5" "${R}"/usr/share/initramfs-tools/scripts/init-premount/dropbear
95 87 fi
96 88 # CRYPTFSDROPBEAR=false
97 89 else
98 90 # Disable SSHD inside initramfs
99 91 printf "#\n# DROPBEAR: [ y | n ]\n#\n\nDROPBEAR=n\n" >> "${ETC_DIR}/initramfs-tools/initramfs.conf"
100 92 fi
101 93
102 94 # Add cryptsetup modules to initramfs
103 95 #printf "#\n# CRYPTSETUP: [ y | n ]\n#\n\nCRYPTSETUP=y\n" >> "${ETC_DIR}/initramfs-tools/conf-hook"
104 96
105 97 # Dummy mapping required by mkinitramfs
106 98 echo "0 1 crypt "${CRYPTFS_CIPHER}" ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff 0 7:0 4096" | chroot_exec dmsetup create "${CRYPTFS_MAPPING}"
107 99
108 100 # Generate initramfs with encrypted root partition support
109 101 chroot_exec mkinitramfs -o "/boot/firmware/initramfs-${KERNEL_VERSION}" "${KERNEL_VERSION}"
110 102
111 103 # Remove dummy mapping
112 104 chroot_exec cryptsetup close "${CRYPTFS_MAPPING}"
113 105 # CRYPTFS=false
114 106 else
107 #USB BOOT /boot on sda1 / on sda2
108 if [ "$ENABLE_USBBOOT" = true ] ; then
109 sed -i "s/mmcblk0p1/sda1/" "${ETC_DIR}/fstab"
110 sed -i "s/mmcblk0p2/sda2/" "${ETC_DIR}/fstab"
111 fi
112
113 # Add usb/sda disk root partition to fstab
114 if [ "$ENABLE_SPLITFS" = true ] ; then
115 sed -i "s/mmcblk0p2/sda1/" "${ETC_DIR}/fstab"
116 fi
115 117 # Generate initramfs without encrypted root partition support
116 118 chroot_exec mkinitramfs -o "/boot/firmware/initramfs-${KERNEL_VERSION}" "${KERNEL_VERSION}"
117 119 fi
118 120 fi
General Comments 0
Vous devez vous connecter pour laisser un commentaire. Se connecter maintenant