Skip to content

Commit d4d9774

Browse files
release
1 parent 8ec4244 commit d4d9774

18 files changed

+1206
-1
lines changed

.gitignore

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# This file is part of https://github.com/random-archer/mkinitcpio-systemd-tool
2+
3+
#
4+
# eclipse meta data
5+
#
6+
.project
7+
8+
#
9+
# generated resources
10+
#
11+
/*/
12+
/*.xz
13+
/*.log
14+
15+
# version update marker file
16+
.PKGVER

LICENSE.md

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
##### This file is part of https://github.com/random-archer/mkinitcpio-systemd-tool
2+
3+
Licensed under the Apache License, Version 2.0 (the "License");
4+
you may not use this file except in compliance with the License.
5+
You may obtain a copy of the License at
6+
7+
http://www.apache.org/licenses/LICENSE-2.0
8+
9+
Unless required by applicable law or agreed to in writing, software
10+
distributed under the License is distributed on an "AS IS" BASIS,
11+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12+
See the License for the specific language governing permissions and
13+
limitations under the License.

README.md

Lines changed: 136 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,137 @@
1-
# mkinitcpio-systemd-tool
1+
##### This file is part of https://github.com/random-archer/mkinitcpio-systemd-tool
2+
3+
## mkinitcpio-systemd-tool
4+
5+
Never write another mkinitcpio hook again, use systemd-tool.
6+
7+
### Summary
8+
29
Provisioning tool for systemd in initramfs (systemd-tool)
10+
11+
Features:
12+
* initrd debugging
13+
* early network setup
14+
* remote ssh access in initrd
15+
* cryptsetup password answer over ssh
16+
* unified systemd + mkinitcpio configuration
17+
* automatic provisioning of binary and config resources
18+
* on-demand invocation of mkinitcpio scripts and in-line functions
19+
20+
mkinitcpio hook name: `systemd-tool`
21+
22+
### Example
23+
24+
Basic usage steps:
25+
26+
1) activate required hooks in `/etc/mkinitcpio.conf`:
27+
```
28+
HOOKS="base systemd systemd-tool"
29+
```
30+
31+
2) review, change and enable/disable provided default files:
32+
```
33+
/etc/systemd/network/initrd-*.network
34+
/etc/systemd/system/initrd-*.service
35+
/etc/systemd/system/initrd-*.sh
36+
```
37+
38+
3) build/review initrd and reboot
39+
```
40+
mkinitcpio -v -p linux > build.log
41+
reboot
42+
```
43+
44+
### Details
45+
46+
`makepkg/pacman` install actions:
47+
* provision default files included in this package into the `/etc`
48+
* specific folders are `/etc/mkinitcpio.d` and `/etc/systemd/{system,network}`
49+
50+
`mkinitcpio` install hook actions:
51+
* look in the `/etc/systemd/system`
52+
* include in initrd units containing marker `/etc/initrd-release`
53+
* activate transitively in initrd any discovered systemd service units
54+
* auto provision into initramfs resources declared in the initrd service units
55+
56+
### Provisioning Questions and Answers
57+
58+
what is the mkinitcpio hook entry provided by this package?
59+
* hook name: `systemd-tool`
60+
* minimum required hooks are: `base systemd systemd-tool`
61+
* recommended hooks are: `base systemd autodetect modconf block filesystems keyboard systemd-tool`
62+
63+
where can I find stable version of mkinitcpio-systemd-tool?
64+
* use releases https://github.com/random-archer/mkinitcpio-systemd-tool/releases
65+
66+
how can I enable my custom service unit in initrd?
67+
* add `[Unit]` entry `ConditionPathExists=/etc/initrd-release`
68+
69+
how can I disable my custom service unit in initrd?
70+
* alter the tag marker string, i.e.: `ConditionPathExists=/etc/xxx/initrd-release`
71+
72+
what is the purpose of `[X-SystemdTool]` section in service unit files?
73+
* see https://github.com/systemd/systemd/issues/3340
74+
* this section provides configuration interface for `mkinitcpio` provisioning actions
75+
* entries include: `InitrdBinary=`, `InitrdPath=`, `InitrdLink=`, `InitrdBuild=`, `InitrdCall=`
76+
77+
how can I auto-provision my custom service unit binaries into initramfs?
78+
* use `InitrdBinary=/path/target-exec` to provision service binary
79+
* also will be provisioned all `Exec*` entries such as `ExecStart=/bin/program`
80+
81+
how can I auto-provision my custom service unit resources into initramfs?
82+
* use `InitrdPath=/path/to/host/folder-or-file`
83+
84+
how can I relocate folder during provisioning?
85+
* not implemented, source and target folder must use the same location
86+
87+
how can I relocate file and/or change file mode during provisioning?
88+
* use `InitrdPath=/target-file source=/source-file mode=NNN`
89+
90+
how can I filter directory content during provisioning?
91+
* use `InitrdPath=/target-folder glob=*.example`
92+
93+
how can I provision optional folder or file?
94+
* use `InitrdPath=/target-file source=/source-file optional=yes`
95+
96+
is there a way to create empty folder or file?
97+
* for empty dir, use `InitrdPath=/path/target-folder/ create=yes` note trailing SLASH
98+
* for empty file, use `InitrdPath=/path/target-file create=yes` note NO trailing slash
99+
* in order to ignore existing host source, add `source=/some-invalid-path` argument
100+
101+
how can I provision a symbolic link?
102+
* use `InitrdLink=/path-to-link/link-name /path-to-target/target-name`
103+
* note that `/path-to-target/target-name` must be provisioned separately
104+
105+
can I invoke a provisioning script related to my service during mkinitcpio build time?
106+
* use `InitrdBuild=/path-to/script.sh command=function_name`
107+
108+
can I call a little provisioning script snippet during mkinitcpio build time?
109+
* check for available `mkinitcpio` functions in `/usr/lib/initcpio/functions.sh`
110+
* use `InitrdCall=inline-bash-code-here` to call these functions
111+
112+
how can I provide custom interactive user shell for ssh client
113+
* change sample shell file located in `/etc/systemd/system/initrd-shell.sh`
114+
115+
which ssh user keys are used by initramfs sshd server?
116+
* they come from host `/root/.ssh/authorized_keys`
117+
118+
### Shell Script Questions and Answers
119+
120+
there is a `initrd-shell.sh` script provided, what does it do?
121+
* it used as both interactive login shell and as a systemd service
122+
* when crypto disks are present, it acts as password agent
123+
* when in ssh console, it offers simple interactive menu
124+
* when in systemd service mode, it acts as service
125+
126+
how can I review `initrd-shell.sh` actions during last boot?
127+
* use `journalctl -b -t shell`
128+
129+
what does `CTRL-C` do to `initrd-shell.sh` in different modes?
130+
* while in `ssh console`, it will start a menu form `initrd-shell.sh`
131+
* while in `/dev/tty debug console`, it will exit from `initrd-shell.sh`
132+
* while in `/dev/console login console`, it will restart the `initrd-shell.sh` service
133+
134+
is there a silent or no-echo mode during password entry in `initrd-shell.sh`?
135+
* there are two ways to enter silent mode (see `systemd-ask-password.c`):
136+
* either by pressing `BACKSPACE` as first key or by pressing `TAB` at any time
137+
* then the prompt will show extra text: `(no echo)`

crypttab

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
# This file is part of https://github.com/random-archer/mkinitcpio-systemd-tool
2+
3+
# crypttab: mappings for encrypted partitions
4+
5+
# crypttab format:
6+
# https://wiki.archlinux.org/index.php/Dm-crypt/System_configuration#crypttab
7+
8+
# how crypttab is used by systemd
9+
# https://www.freedesktop.org/software/systemd/man/systemd-cryptsetup-generator.html
10+
11+
# to setup crypto disks in initramfs over ssh
12+
# manually provide here partition UUID with help of `lsblk`
13+
# then active initrd-cryptsetup.service as well as "ask password prompt" in shell.sh
14+
15+
# <name> <device> <password> <options>
16+
swap UUID=${UUID_SWAP} none luks
17+
root UUID=${UUID_ROOT} none luks

initrd-build.sh

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# This file is part of https://github.com/random-archer/mkinitcpio-systemd-tool
2+
3+
# mkinitcpio build time functions for X-SystemdTool/InitrdBuild
4+
# can use mkinitcpio /usr/lib/initcpio/functions.sh, for example :
5+
# $BUILDROOT - mkinitcpio image build destination dir
6+
# quiet() - output to console, depending on mkinitcpio "-v" option
7+
# plain() - output to console, always
8+
9+
# enforce specific login shell in /etc/passwd
10+
do_root_shell() {
11+
local shell="/bin/sh"
12+
local search="(root):([^:]*):([^:]*):([^:]*):([^:]*):([^:]*):([^:]*)"
13+
local replace="\1:\2:\3:\4:\5:\6:${shell}"
14+
local target="$BUILDROOT/etc/passwd"
15+
run_command sed -i -r -e "s|${search}|${replace}|" "$target"
16+
}
17+
18+
# remove optional entries form /etc/passwd /etc/shadow
19+
do_secret_clean() {
20+
local match="^root.*|^systemd.*"
21+
local target
22+
local target_list="$BUILDROOT/etc/passwd $BUILDROOT/etc/shadow"
23+
for target in $target_list ; do
24+
run_command sed -i -r -e "/${match}/!d" "$target"
25+
done
26+
}
27+
28+
# ensure dropbear server host keys
29+
do_ssh_host_keys() {
30+
31+
quiet "provide host server ssh keys"
32+
33+
mkdir -p "/etc/dropbear"
34+
35+
local keytype_list="rsa dsa ecdsa"
36+
local keytype source target
37+
for keytype in $keytype_list; do
38+
source=$(keypath_openssh "$keytype")
39+
target=$(keypath_dropbear $(keytype_dropbear "$keytype"))
40+
if [ -f "$target" ]; then
41+
quiet "provision existing dropbear host key: $target"
42+
else
43+
if [ -f "$source" ] ; then
44+
plain "convert openssh to dropbear host key: $target"
45+
run_command dropbearconvert openssh dropbear "$source" "$target"
46+
else
47+
plain "generate brand new dropbear host key: $target"
48+
run_command dropbearkey -t $(keytype_dropbear "$keytype") -f "$target"
49+
fi
50+
fi
51+
done
52+
53+
}
54+
55+
# location of server host keys used by openssh
56+
keypath_openssh() {
57+
local type=$1
58+
echo "/etc/ssh/ssh_host_${type}_key"
59+
}
60+
61+
# location of server host keys used by dropbear
62+
keypath_dropbear() {
63+
local type="$1"
64+
echo "/etc/dropbear/dropbear_${type}_host_key"
65+
}
66+
67+
# re-map ssh key type from openssh to dropbear
68+
keytype_dropbear() {
69+
local type="$1"
70+
[[ $type == "dsa" ]] && type="dss"
71+
echo "${type}"
72+
}
73+
74+
# safety wrapper for external commands
75+
run_command() {
76+
local command="$@"
77+
local result; result=$($command 2>&1); status=$?
78+
case "$status" in
79+
0) quiet "command success: $command\n$result\n"; return 0 ;;
80+
*) error "command failure ($status): $command \n$result\n" ; return 1 ;;
81+
esac
82+
}

initrd-cryptsetup.service

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# This file is part of https://github.com/random-archer/mkinitcpio-systemd-tool
2+
3+
# Configure crypto disks in initramfs
4+
5+
# Provides replacement for mkinitcpio hook "sd-encrypt" included in cryptsetup
6+
# https://www.archlinux.org/packages/core/x86_64/cryptsetup/
7+
# https://git.archlinux.org/svntogit/packages.git/tree/trunk/sd-encrypt?h=packages/cryptsetup
8+
9+
[Unit]
10+
Description=Initrd Cryptsetup Service
11+
Documentation=https://github.com/random-archer/mkinitcpio-systemd-tool/blob/master/README.md
12+
ConditionPathExists=/etc/initrd-release
13+
DefaultDependencies=no
14+
After=initrd-shell.service
15+
After=cryptsetup-pre.target
16+
Before=cryptsetup.target
17+
Requires=initrd-shell.service
18+
19+
[Service]
20+
# provides password agent
21+
ExecStart=/etc/systemd/system/initrd-shell.sh script_entry=service
22+
Restart=on-failure
23+
RestartSec=1s
24+
#RestartForceExitStatus=
25+
#RestartPreventExitStatus=
26+
StandardInput=tty
27+
StandardOutput=inherit
28+
StandardError=inherit
29+
TTYPath=/dev/console
30+
31+
[Install]
32+
WantedBy=sysinit.target
33+
34+
[X-SystemdTool]
35+
36+
# provision crypttab in initramfs
37+
InitrdPath=/etc/crypttab source=/etc/mkinitcpio.d/crypttab optional=yes
38+
39+
# include cryptsetup binaries
40+
InitrdBinary=/usr/bin/dmsetup
41+
InitrdCall=add_module dm-crypt
42+
InitrdCall=add_all_modules /crypto/
43+
44+
# include cryptsetup udev rules
45+
InitrdPath=/usr/lib/udev/rules.d/10-dm.rules
46+
InitrdPath=/usr/lib/udev/rules.d/11-dm-initramfs.rules source=/usr/lib/initcpio/udev/11-dm-initramfs.rules
47+
InitrdPath=/usr/lib/udev/rules.d/13-dm-disk.rules
48+
InitrdPath=/usr/lib/udev/rules.d/95-dm-notify.rules
49+
50+
# include systemd cryptsetup support
51+
InitrdPath=/usr/lib/systemd/system/cryptsetup.target
52+
InitrdPath=/usr/lib/systemd/system/cryptsetup-pre.target
53+
InitrdBinary=/usr/lib/systemd/systemd-cryptsetup
54+
InitrdBinary=/usr/lib/systemd/system-generators/systemd-cryptsetup-generator
55+
56+
# include systemd password agent support
57+
InitrdBinary=/usr/bin/systemd-ask-password
58+
InitrdBinary=/usr/lib/systemd/systemd-reply-password
59+
InitrdBinary=/usr/bin/systemd-tty-ask-password-agent

initrd-debug-progs.service

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
# This file is part of https://github.com/random-archer/mkinitcpio-systemd-tool
2+
3+
# Provision additional resources for the debug shell
4+
5+
[Unit]
6+
Description=Initrd Debug Progs Service
7+
Documentation=https://github.com/random-archer/mkinitcpio-systemd-tool/blob/master/README.md
8+
ConditionPathExists=/etc/initrd-release
9+
DefaultDependencies=no
10+
Before=initrd-debug-shell.service
11+
12+
[Service]
13+
Type=oneshot
14+
RemainAfterExit=true
15+
ExecStart=/bin/true
16+
17+
[Install]
18+
WantedBy=sysinit.target
19+
WantedBy=initrd-debug-shell.service
20+
21+
[X-SystemdTool]
22+
23+
# systemd tools
24+
InitrdBinary=/usr/bin/journalctl
25+
InitrdBinary=/usr/bin/systemd-analyze
26+
27+
# midnight commander
28+
InitrdBinary=/usr/bin/mc
29+
InitrdBinary=/usr/bin/mcedit
30+
InitrdBinary=/usr/bin/mcview
31+
InitrdPath=/etc/mc
32+
InitrdPath=/usr/lib/mc
33+
InitrdPath=/usr/share/mc
34+
InitrdBinary=/usr/bin/hostname
35+
36+
# terminal settings for ssh client
37+
#InitrdBinary=/bin/infocmp
38+
#InitrdPath=/usr/share/terminfo
39+
InitrdPath=/usr/share/terminfo/l/linux
40+
InitrdPath=/usr/share/terminfo/v/vt100
41+
InitrdPath=/usr/share/terminfo/x/xterm
42+
#InitrdPath=/usr/share/terminfo/x/xterm-color

0 commit comments

Comments
 (0)