tsiry-sandratraina.com
A simple, zero-configuration script to quickly boot FreeBSD ISO images using QEMU
Enhance README.md to include VM restart and logging features
+73
-10
README.md
+73
-10
README.md
···
15
15
16
16
### Core VM Management
17
17
18
-
- ๐๏ธ **Full VM lifecycle management**: Create, start, stop, inspect, and remove
18
+
- ๐๏ธ **Full VM lifecycle management**: Create, start, stop, restart, inspect, and remove
19
19
VMs
20
20
- ๐พ **Persistent state tracking**: SQLite database stores VM configurations and
21
21
state
22
22
- ๐ **VM listing and monitoring**: View running and stopped VMs with detailed
23
23
information
24
24
- ๐ **VM inspection**: Get detailed information about any managed VM
25
+
- ๐ **VM logging**: View and follow VM logs with built-in log management
26
+
- ๐ **VM restart**: Gracefully restart VMs with preserved configuration
25
27
- ๐๏ธ **VM removal**: Clean removal of VMs from the database
26
28
- ๐ท๏ธ **Auto-generated VM names**: Unique identifiers for easy VM management
27
29
- ๐๏ธ **Cross-platform support**: Works on both x86_64 and aarch64 architectures
30
+
- ๐ง **Background mode**: Run VMs in detached mode for headless operation
28
31
29
32
### Network & Storage
30
33
···
32
35
- ๐ **Network bridge support**: Automatic bridge creation and management with
33
36
`--bridge`
34
37
- ๐ง **MAC address management**: Persistent MAC addresses for each VM
35
-
- ๐พ **Persistent storage support**: Attach and auto-create disk images
38
+
- ๏ฟฝ **Port forwarding**: Custom port mapping for network services with `--port-forward`
39
+
- ๏ฟฝ๐พ **Persistent storage support**: Attach and auto-create disk images
36
40
- ๐๏ธ **Multiple disk formats**: Support for qcow2, raw, and other disk formats
37
41
- ๐ **Configurable disk sizes**: Specify disk image size on creation
38
42
···
165
169
freebsd-up rm vm-name
166
170
```
167
171
172
+
Restart a VM:
173
+
174
+
```bash
175
+
freebsd-up restart vm-name
176
+
```
177
+
178
+
View VM logs:
179
+
180
+
```bash
181
+
freebsd-up logs vm-name
182
+
```
183
+
184
+
Follow VM logs in real-time:
185
+
186
+
```bash
187
+
freebsd-up logs vm-name --follow
188
+
```
189
+
168
190
````
169
191
### Customize VM Configuration
170
192
171
-
Specify custom CPU type, core count, memory allocation, persistent storage, and networking:
193
+
Specify custom CPU type, core count, memory allocation, persistent storage, networking, and port forwarding:
172
194
173
195
```bash
174
196
# Custom CPU and memory
···
185
207
186
208
# Use bridge networking (requires sudo)
187
209
freebsd-up --bridge br0 14.3-RELEASE
210
+
211
+
# Configure port forwarding for specific services
212
+
freebsd-up --port-forward 8080:80,2222:22 14.3-RELEASE
213
+
214
+
# Run VM in background (detached mode)
215
+
freebsd-up --detach 14.3-RELEASE
188
216
189
217
# Download to specific location
190
218
freebsd-up --output ./downloads/freebsd.iso 15.0-BETA3
191
219
192
220
# Combine all options
193
-
freebsd-up --cpu qemu64 --cpus 2 --memory 1G --image ./my-disk.qcow2 --disk-format qcow2 --size 30G --bridge br0 --output ./my-freebsd.iso
221
+
freebsd-up --cpu qemu64 --cpus 2 --memory 1G --image ./my-disk.qcow2 --disk-format qcow2 --size 30G --bridge br0 --port-forward 8080:80,2222:22 --detach --output ./my-freebsd.iso
194
222
````
195
223
196
224
### Get Help
···
227
255
### Network Options
228
256
229
257
- `-b, --bridge <name>` - Name of the network bridge to use (e.g., br0)
258
+
- `-p, --port-forward <mappings>` - Port forwarding rules in the format hostPort:guestPort (comma-separated for multiple)
259
+
260
+
### Execution Options
261
+
262
+
- `-d, --detach` - Run VM in the background and print VM name
230
263
231
264
### File Options
232
265
···
235
268
### Management Commands
236
269
237
270
- `ps [--all]` - List running VMs (use --all to include stopped VMs)
238
-
- `start <vm-name>` - Start a specific VM by name
271
+
- `start <vm-name> [--detach]` - Start a specific VM by name (optionally in background)
239
272
- `stop <vm-name>` - Stop a specific VM by name
273
+
- `restart <vm-name>` - Restart a specific VM by name
240
274
- `inspect <vm-name>` - Show detailed information about a VM
275
+
- `logs <vm-name> [--follow]` - View VM logs (optionally follow in real-time)
241
276
- `rm <vm-name>` - Remove a VM and its configuration from the database
242
277
243
278
### Help Options
···
266
301
# Use bridge networking for better network performance
267
302
freebsd-up --bridge br0 14.3-RELEASE
268
303
304
+
# Configure port forwarding for web and SSH access
305
+
freebsd-up --port-forward 8080:80,2222:22 14.3-RELEASE
306
+
307
+
# Run VM in background mode
308
+
freebsd-up --detach 14.3-RELEASE
309
+
269
310
# Save ISO to specific location
270
311
freebsd-up --output ./isos/freebsd.iso https://example.com/freebsd.iso
271
312
272
-
# Combine multiple options with bridge networking and persistent storage
273
-
freebsd-up --cpu host --cpus 4 --memory 8G --image ./vm-disk.qcow2 --disk-format qcow2 --size 50G --bridge br0 --output ./downloads/ 14.3-RELEASE
313
+
# Combine multiple options with bridge networking, port forwarding, and persistent storage
314
+
freebsd-up --cpu host --cpus 4 --memory 8G --image ./vm-disk.qcow2 --disk-format qcow2 --size 50G --bridge br0 --port-forward 8080:80,2222:22 --detach --output ./downloads/ 14.3-RELEASE
274
315
275
316
# List all VMs (including stopped ones)
276
317
freebsd-up ps --all
277
318
278
319
# Start a previously created VM
279
320
freebsd-up start my-freebsd-vm
321
+
322
+
# Start a VM in background mode
323
+
freebsd-up start my-freebsd-vm --detach
280
324
281
325
# Stop a running VM
282
326
freebsd-up stop my-freebsd-vm
283
327
328
+
# Restart a VM
329
+
freebsd-up restart my-freebsd-vm
330
+
284
331
# Get detailed information about a VM
285
332
freebsd-up inspect my-freebsd-vm
286
333
334
+
# View VM logs
335
+
freebsd-up logs my-freebsd-vm
336
+
337
+
# Follow VM logs in real-time
338
+
freebsd-up logs my-freebsd-vm --follow
339
+
287
340
# Remove a VM
288
341
freebsd-up rm my-freebsd-vm
289
342
```
···
313
366
`--image`)
314
367
- **Network**: User mode networking with SSH forwarding (host:2222 โ guest:22)
315
368
or bridge networking with `--bridge`
369
+
- **Port Forwarding**: Configurable port mappings with `--port-forward`
316
370
- **Console**: Enhanced serial console via stdio with proper signal handling
317
371
- **Default Version**: FreeBSD 14.3-RELEASE (when no arguments provided)
318
372
- **State Management**: Persistent VM state stored in SQLite database
319
373
- **Auto-naming**: VMs get unique names for easy management
374
+
- **Background Mode**: Support for detached execution with `--detach`
320
375
321
376
### Networking Modes
322
377
···
375
430
freebsd-up --cpus 4
376
431
377
432
# Add persistent storage
378
-
freebsd-up --image ./freebsd-data.qcow2 --disk-format qcow2
433
+
freebsd-up --image ./freebsd-data.qcow2 --disk-format qcow2 14.3-RELEASE
379
434
380
-
# Combine options with persistent storage
381
-
freebsd-up --cpu host --cpus 4 --memory 8G --image ./vm-storage.qcow2 --disk-format qcow2 14.3-RELEASE
435
+
# Configure port forwarding for web server and SSH
436
+
freebsd-up --port-forward 8080:80,2222:22 14.3-RELEASE
437
+
438
+
# Run in background mode
439
+
freebsd-up --detach 14.3-RELEASE
440
+
441
+
# Combine options with persistent storage and port forwarding
442
+
freebsd-up --cpu host --cpus 4 --memory 8G --image ./vm-storage.qcow2 --disk-format qcow2 --port-forward 8080:80,2222:22 --detach 14.3-RELEASE
382
443
```
383
444
384
445
### Creating Disk Images
···
466
527
โโโ utils.ts # Core VM utilities and QEMU interface
467
528
โโโ subcommands/ # CLI subcommand implementations
468
529
โโโ inspect.ts # VM inspection command
530
+
โโโ logs.ts # VM logging command
469
531
โโโ ps.ts # VM listing command
532
+
โโโ restart.ts # VM restart command
470
533
โโโ rm.ts # VM removal command
471
534
โโโ start.ts # VM start command
472
535
โโโ stop.ts # VM stop command