Skip to content

Commit 23a5883

Browse files
committed
docs: how to load device-mapper modules for the dm targets
Spell out modprobe + dmsetup targets verify, the linux-modules-extra fallback for stripped cloud kernels, and persisting via modules-load.d - the missing_dm_targets boot failure points here.
1 parent f340571 commit 23a5883

1 file changed

Lines changed: 26 additions & 3 deletions

File tree

docs/cookbook/intro.md

Lines changed: 26 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -96,12 +96,35 @@ The host kernel must provide:
9696
the `uid_gid_range` configuration).
9797
- **cgroup v2** - the unified hierarchy mounted at `/sys/fs/cgroup`. v1-only
9898
hosts are not supported.
99-
- **device-mapper targets** `snapshot`, `thin`, and `thin-pool` - load the
100-
`dm_snapshot` and `dm_thin_pool` modules (`modprobe dm_snapshot
101-
dm_thin_pool`). Hyper refuses to start its device helper without them.
99+
- **device-mapper targets** `snapshot`, `thin`, and `thin-pool` - from the
100+
`dm_snapshot` (provides `snapshot`) and `dm_thin_pool` (provides `thin` and
101+
`thin-pool`) modules. Hyper refuses to start without all three; on boot it
102+
fails with `{:missing_dm_targets, [...]}` listing whichever are absent.
102103
- **loop devices** - the `loop` module, used to attach layer images as block
103104
devices.
104105

106+
Load the modules and confirm the targets are present:
107+
108+
```sh
109+
sudo modprobe dm_snapshot dm_thin_pool loop
110+
sudo dmsetup targets # must list snapshot, thin, and thin-pool
111+
```
112+
113+
If `modprobe` reports the module is missing, the running kernel lacks it -
114+
minimal cloud images often strip device-mapper. On Debian/Ubuntu, install the
115+
extra modules for the running kernel, then load them:
116+
117+
```sh
118+
sudo apt-get install -y linux-modules-extra-$(uname -r)
119+
sudo modprobe dm_snapshot dm_thin_pool loop
120+
```
121+
122+
Make the modules load on every boot:
123+
124+
```sh
125+
printf 'dm_snapshot\ndm_thin_pool\nloop\n' | sudo tee /etc/modules-load.d/hyper.conf
126+
```
127+
105128
#### Privileged setup
106129

107130
- The **setuid-root device helper** (`hyper-suidhelper`) must be installed.

0 commit comments

Comments
 (0)