tsiry-sandratraina.com
A convenient CLI tool to quickly spin up DragonflyBSD virtual machines using QEMU with sensible defaults.
Update README to enhance VM management and background execution details; add custom port forwarding options and clarify VM lifecycle commands
+112
-18
README.md
+112
-18
README.md
···
1
1
# dflybsd-up ≽༏≼
2
2
3
3
A convenient CLI tool to quickly spin up DragonflyBSD virtual machines using
4
-
QEMU with sensible defaults.
4
+
QEMU with sensible defaults. Includes comprehensive VM management capabilities
5
+
with database tracking, background execution, and flexible networking options.
5
6
6
7
7
8
···
23
24
- **🗃️ VM Management**: Track and manage multiple virtual machines with database
24
25
storage
25
26
- **🌐 Bridge Networking**: Support for bridge networking configurations
26
-
- **🔍 VM Inspection**: List, start, stop, and inspect virtual machines
27
+
- **🔍 VM Inspection**: List, start, stop, restart, and inspect virtual machines
28
+
- **📋 VM Management**: Remove VMs, view logs with follow mode, and background
29
+
execution
27
30
- **🏷️ Automatic MAC Assignment**: Unique MAC addresses generated for each VM
31
+
- **🔧 Custom Port Forwarding**: Flexible port mapping with multiple forwards
32
+
support
33
+
- **🔄 Background Mode**: Run VMs detached from terminal with logging support
28
34
29
35
## 📋 Prerequisites
30
36
···
71
77
# Use bridge networking
72
78
dflybsd-up --bridge br0
73
79
80
+
# Run VM in background (detached mode)
81
+
dflybsd-up --detach
82
+
83
+
# Custom port forwarding (forward host port 8080 to guest port 80)
84
+
dflybsd-up --port-forward 8080:80
85
+
86
+
# Multiple port forwards
87
+
dflybsd-up --port-forward 8080:80,3000:3000
88
+
74
89
# Combine options
75
90
dflybsd-up 6.4.2 \
76
91
--cpus 4 \
···
78
93
--image dragonfly.qcow2 \
79
94
--disk-format qcow2 \
80
95
--size 50G \
81
-
--bridge br0
96
+
--detach \
97
+
--port-forward 2222:22,8080:80
82
98
```
83
99
84
100
### VM Management Commands
···
92
108
93
109
# Start a previously created VM
94
110
dflybsd-up start my-vm
111
+
112
+
# Start a VM in background (detached mode)
113
+
dflybsd-up start my-vm --detach
95
114
96
115
# Stop a running VM
97
116
dflybsd-up stop my-vm
98
117
118
+
# Restart a VM
119
+
dflybsd-up restart my-vm
120
+
121
+
# Remove a VM (delete from database)
122
+
dflybsd-up rm my-vm
123
+
124
+
# View VM logs
125
+
dflybsd-up logs my-vm
126
+
127
+
# Follow VM logs in real-time
128
+
dflybsd-up logs my-vm --follow
129
+
99
130
# Inspect VM details
100
131
dflybsd-up inspect my-vm
101
132
```
102
133
103
134
## ⚙️ Options
104
135
105
-
| Option | Short | Description | Default |
106
-
| --------------- | ----- | ------------------------------------ | ----------------------- |
107
-
| `--output` | `-o` | Output path for downloaded ISO | Auto-generated from URL |
108
-
| `--cpu` | `-c` | CPU type to emulate | `host` |
109
-
| `--cpus` | `-C` | Number of CPU cores | `2` |
110
-
| `--memory` | `-m` | Amount of memory for VM | `2G` |
111
-
| `--image` | `-i` | Path to VM disk image | None |
112
-
| `--disk-format` | | Disk image format (qcow2, raw, etc.) | `raw` |
113
-
| `--size` | | Size of disk image to create | `20G` |
114
-
| `--bridge` | `-b` | Network bridge name for networking | None (uses NAT) |
136
+
| Option | Short | Description | Default |
137
+
| ---------------- | ----- | ------------------------------------------- | ----------------------- |
138
+
| `--output` | `-o` | Output path for downloaded ISO | Auto-generated from URL |
139
+
| `--cpu` | `-c` | CPU type to emulate | `host` |
140
+
| `--cpus` | `-C` | Number of CPU cores | `2` |
141
+
| `--memory` | `-m` | Amount of memory for VM | `2G` |
142
+
| `--image` | `-i` | Path to VM disk image | None |
143
+
| `--disk-format` | | Disk image format (qcow2, raw, etc.) | `raw` |
144
+
| `--size` | | Size of disk image to create | `20G` |
145
+
| `--bridge` | `-b` | Network bridge name for networking | None (uses NAT) |
146
+
| `--detach` | `-d` | Run VM in the background | `false` |
147
+
| `--port-forward` | `-p` | Custom port forwarding (hostPort:guestPort) | `2222:22` |
115
148
116
149
## 🔢 Version Format
117
150
···
138
171
139
172
This enables proper console redirection to your terminal.
140
173
141
-
## �️ Virtual Machine Management
174
+
## 🔍 VM Management & Background Execution
175
+
176
+
### Background Mode (Detached)
177
+
178
+
Run VMs in the background without blocking your terminal:
179
+
180
+
```bash
181
+
# Create and run VM in background
182
+
dflybsd-up --detach
183
+
184
+
# Start existing VM in background
185
+
dflybsd-up start my-vm --detach
186
+
187
+
# When running in background, you can:
188
+
dflybsd-up logs my-vm --follow # View real-time logs
189
+
dflybsd-up stop my-vm # Stop the VM
190
+
dflybsd-up restart my-vm # Restart the VM
191
+
```
192
+
193
+
### VM Lifecycle Management
194
+
195
+
- **Automatic Tracking**: Each VM is assigned a unique name and tracked in a
196
+
local SQLite database
197
+
- **Persistent State**: VM configurations are preserved between sessions
198
+
- **Status Monitoring**: Track running and stopped VMs with process IDs
199
+
- **Resource Information**: View CPU, memory, disk, and network configurations
200
+
for each VM
201
+
- **Log Management**: Each VM maintains its own log file for debugging and
202
+
monitoring
203
+
204
+
## 🗃️ Virtual Machine Management
142
205
143
206
The tool now includes database-backed VM management, allowing you to track and
144
207
manage multiple virtual machines:
···
155
218
### VM Commands
156
219
157
220
- `ps` - List virtual machines (use `--all` to include stopped VMs)
158
-
- `start <vm-name>` - Start a previously created VM
221
+
- `start <vm-name>` - Start a previously created VM (use `--detach` to run in
222
+
background)
159
223
- `stop <vm-name>` - Stop a running VM
224
+
- `restart <vm-name>` - Restart a VM (stop and start again)
225
+
- `rm <vm-name>` - Remove a VM from the database (does not delete disk images)
226
+
- `logs <vm-name>` - View VM logs (use `--follow` for real-time logs)
160
227
- `inspect <vm-name>` - View detailed VM information
161
228
162
229
## 🌐 Networking Options
···
165
232
166
233
By default, VMs use QEMU's user-mode networking with port forwarding:
167
234
168
-
- Host port 2222 → Guest port 22 (SSH)
235
+
- Host port 2222 → Guest port 22 (SSH) by default
236
+
- Custom port forwarding available with `--port-forward` option
169
237
- No additional configuration required
170
238
- Works without root privileges
239
+
240
+
#### Custom Port Forwarding
241
+
242
+
You can specify custom port forwarding rules:
243
+
244
+
```bash
245
+
# Forward host port 8080 to guest port 80
246
+
dflybsd-up --port-forward 8080:80
247
+
248
+
# Multiple port forwards (comma-separated)
249
+
dflybsd-up --port-forward 8080:80,3000:3000,2222:22
250
+
251
+
# Use with other options
252
+
dflybsd-up 6.4.2 --port-forward 8080:80 --memory 4G
253
+
```
171
254
172
255
### Bridge Networking
173
256
···
206
289
207
290
### NAT Networking (Default)
208
291
209
-
The VM automatically forwards host port 2222 to guest port 22. After configuring
210
-
SSH in your DragonflyBSD installation:
292
+
The VM automatically forwards host port 2222 to guest port 22 by default. You
293
+
can customize port forwarding with the `--port-forward` option. After
294
+
configuring SSH in your DragonflyBSD installation:
211
295
212
296
```bash
297
+
# Default SSH access (2222:22 forwarding)
213
298
ssh -p 2222 user@localhost
299
+
300
+
# Custom port forwarding
301
+
dflybsd-up --port-forward 2200:22
302
+
ssh -p 2200 user@localhost
303
+
304
+
# Access other services with custom forwarding
305
+
dflybsd-up --port-forward 2222:22,8080:80
306
+
# SSH: ssh -p 2222 user@localhost
307
+
# HTTP: http://localhost:8080
214
308
```
215
309
216
310
### Bridge Networking