blob: 89da6c137fa387f1045bf0d6623bd1e5b82633cd (
plain) (
blame)
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
|
# `KVM Lab Workflow`
**Purpose:**
Fast creation of disposable or persistent KVM labs with strong isolation,
no host contamination, and reversible state management.
---
## Directory Layout
```
/var/lib/libvirt/images/
├── base/
│ ├── debian13-template.qcow2
│ └── work01-base-YYYY-MM-DD_HHMMSS.qcow2
├── overlays/
│ └── work01.qcow2
├── lab/
│ └── <lab-name>.qcow2
├── whonix/
│ ├── Whonix-Gateway-*.qcow2
│ └── Whonix-Workstation-*.qcow2
└── archive/
```
---
## Installed Tools
| Script | Location | Purpose |
| --------------------- | ---------------------------------- | -------------------------------- |
| `kvm-lab-create` | `~/.local/bin/kvm-lab-create` | Create lab VMs from chosen base |
| `kvm-lab-destroy` | `~/.local/bin/kvm-lab-destroy` | Destroy lab VM + disk safely |
| `kvm-promote-to-base` | `~/.local/bin/kvm-promote-to-base` | Freeze any VM into reusable base |
| `kvm--lab-status` | `~/.local/bin/kvm-lab-status` | Prints the current status |
Ensure:
```
echo $PATH | grep "$HOME/.local/bin"
```
---
## Core Concepts
| Term | Meaning |
| ---------- | ------------------------------------------------ |
| Base image | Immutable qcow2 used as parent for new labs |
| Overlay | Writable qcow2 layer for a specific VM |
| Promote | Freeze a VM’s current disk state into a new base |
---
## Normal Workflow
### 1. Promote a VM into a base
Freeze current VM state for reuse.
```
virsh -c qemu:///system shutdown work01
kvm-promote-to-base work01
```
Creates:
```
/var/lib/libvirt/images/base/work01-base-YYYY-MM-DD_HHMMSS.qcow2
```
---
### 2. Create a new lab
From template:
```
kvm-lab-create lab10 --base template --start
```
From newest work01 base:
```
kvm-lab-create lab11 --base work01 --start
```
From specific base:
```
kvm-lab-create lab12 --base /var/lib/libvirt/images/base/work01-base-2026-01-09_150905.qcow2 --start
```
---
### 3. Destroy a lab safely
```
kvm-lab-destroy lab11
```
**Guards enforced:**
* Only deletes VMs whose disks are under `/var/lib/libvirt/images/lab/`
* Refuses to touch `work01`, template, Whonix, or base images
---
## Debugging & Verification
List all VMs:
```
virsh -c qemu:///system list --all
```
Check disk chain:
```
sudo qemu-img info --backing-chain /var/lib/libvirt/images/lab/lab10.qcow2
```
Confirm no base corruption:
```
sudo qemu-img info /var/lib/libvirt/images/base/work01-base-*.qcow2
```
---
## Invariants (Never Broken)
* `work01` remains intact
* Base images are never modified
* Lab VMs cannot access host or other VMs
* No filesystem passthrough
* All labs use NAT-only `default` network
---
## Recovery
Delete a bad base:
```
sudo rm /var/lib/libvirt/images/base/<base-file>.qcow2
```
Delete a stuck lab:
```
kvm-lab-destroy <lab-name>
```
---
## Philosophy
> **One-way operations**
> Promote → Create → Destroy
> Host always stays clean.
|
