A simple, zero-configuration script to quickly boot FreeBSD ISO images using QEMU
Update README.md to enhance feature descriptions and add VM management commands
+202
-50
+202
-50
README.md
+202
-50
README.md
···
1
1
# FreeBSD-Up 🚀
2
2
3
-
A simple, zero-configuration script to quickly boot FreeBSD ISO images using
4
-
QEMU. Perfect for testing, development, or learning FreeBSD without complex
5
-
setup.
3
+
A comprehensive FreeBSD virtual machine management tool built with Deno and
4
+
QEMU. Effortlessly create, manage, and run FreeBSD VMs with persistent state
5
+
tracking, network bridging support, and zero-configuration defaults.
6
6
7
7
8
8
9
9
## ✨ Features
10
10
11
+
### Core VM Management
12
+
13
+
- 🏗️ **Full VM lifecycle management**: Create, start, stop, and inspect VMs
14
+
- 💾 **Persistent state tracking**: SQLite database stores VM configurations and
15
+
state
16
+
- 📊 **VM listing and monitoring**: View running and stopped VMs with detailed
17
+
information
18
+
- 🔍 **VM inspection**: Get detailed information about any managed VM
19
+
- 🏷️ **Auto-generated VM names**: Unique identifiers for easy VM management
20
+
21
+
### Network & Storage
22
+
23
+
- 🌐 **Flexible networking**: Support for both user-mode and bridge networking
24
+
- 🔗 **Network bridge support**: Automatic bridge creation and management with
25
+
`--bridge`
26
+
- 🖧 **MAC address management**: Persistent MAC addresses for each VM
27
+
- 💾 **Persistent storage support**: Attach and auto-create disk images
28
+
- 🗂️ **Multiple disk formats**: Support for qcow2, raw, and other disk formats
29
+
- 📏 **Configurable disk sizes**: Specify disk image size on creation
30
+
31
+
### Convenience Features
32
+
11
33
- 🔗 **Download and boot from URLs**: Automatically downloads ISO images from
12
34
remote URLs
13
35
- 📁 **Local file support**: Boot from local ISO files
···
17
39
(FreeBSD 14.3-RELEASE)
18
40
- ⚡ **Zero configuration**: Works out of the box with sensible defaults
19
41
- 🖥️ **Serial console**: Configured for headless operation with stdio console
20
-
- 🌐 **Network ready**: Pre-configured with SSH port forwarding (host:2222 →
21
-
guest:22)
22
42
- 💾 **Smart caching**: Automatically skips re-downloading existing ISO files
23
43
- 🆘 **Help support**: Built-in help with `--help` or `-h` flags
24
44
- ⚙️ **Configurable VM options**: Customize CPU type, core count, memory
25
-
allocation, and persistent storage
26
-
- 💾 **Persistent storage support**: Attach disk images for data persistence
27
-
- 🗂️ **Multiple disk formats**: Support for qcow2, raw, and other disk formats
45
+
allocation
28
46
- 📝 **Enhanced CLI**: Powered by [Cliffy](http://cliffy.io/) for robust
29
47
command-line parsing
30
48
···
101
119
freebsd-up /path/to/your/freebsd.iso
102
120
```
103
121
122
+
### VM Management Commands
123
+
124
+
List all running VMs:
125
+
126
+
```bash
127
+
freebsd-up ps
128
+
```
129
+
130
+
List all VMs (including stopped):
131
+
132
+
```bash
133
+
freebsd-up ps --all
134
+
```
135
+
136
+
Start a specific VM:
137
+
138
+
```bash
139
+
freebsd-up start vm-name
140
+
```
141
+
142
+
Stop a specific VM:
143
+
144
+
```bash
145
+
freebsd-up stop vm-name
146
+
```
147
+
148
+
Inspect VM details:
149
+
150
+
```bash
151
+
freebsd-up inspect vm-name
152
+
```
153
+
154
+
freebsd-up /path/to/your/freebsd.iso
155
+
156
+
````
104
157
### Customize VM Configuration
105
158
106
-
Specify custom CPU type, core count, memory allocation, and persistent storage:
159
+
Specify custom CPU type, core count, memory allocation, persistent storage, and networking:
107
160
108
161
```bash
109
162
# Custom CPU and memory
···
115
168
# Attach a disk image for persistent storage
116
169
freebsd-up --drive ./freebsd-disk.img --disk-format qcow2 14.3-RELEASE
117
170
171
+
# Create disk image with specific size
172
+
freebsd-up --drive ./freebsd-disk.qcow2 --disk-format qcow2 --size 50G 14.3-RELEASE
173
+
174
+
# Use bridge networking (requires sudo)
175
+
freebsd-up --bridge br0 14.3-RELEASE
176
+
118
177
# Download to specific location
119
178
freebsd-up --output ./downloads/freebsd.iso 15.0-BETA3
120
179
121
180
# Combine all options
122
-
freebsd-up --cpu qemu64 --cpus 2 --memory 1G --drive ./my-disk.qcow2 --disk-format qcow2 --output ./my-freebsd.iso
123
-
```
181
+
freebsd-up --cpu qemu64 --cpus 2 --memory 1G --drive ./my-disk.qcow2 --disk-format qcow2 --size 30G --bridge br0 --output ./my-freebsd.iso
182
+
````
124
183
125
184
### Get Help
126
185
···
142
201
143
202
FreeBSD-Up supports several command-line options for customization:
144
203
204
+
### VM Configuration Options
205
+
145
206
- `-c, --cpu <type>` - CPU type to emulate (default: `host`)
146
207
- `-C, --cpus <number>` - Number of CPU cores (default: `2`)
147
208
- `-m, --memory <size>` - Amount of memory for the VM (default: `2G`)
148
209
- `-d, --drive <path>` - Path to VM disk image for persistent storage
149
210
- `--disk-format <format>` - Disk image format: qcow2, raw, etc. (default:
150
211
`raw`)
212
+
- `-s, --size <size>` - Size of disk image to create if it doesn't exist
213
+
(default: `20G`)
214
+
215
+
### Network Options
216
+
217
+
- `-b, --bridge <name>` - Name of the network bridge to use (e.g., br0)
218
+
219
+
### File Options
220
+
151
221
- `-o, --output <path>` - Output path for downloaded ISO files
222
+
223
+
### Management Commands
224
+
225
+
- `ps [--all]` - List running VMs (use --all to include stopped VMs)
226
+
- `start <vm-name>` - Start a specific VM by name
227
+
- `stop <vm-name>` - Stop a specific VM by name
228
+
- `inspect <vm-name>` - Show detailed information about a VM
229
+
230
+
### Help Options
231
+
152
232
- `-h, --help` - Show help information
153
233
- `-V, --version` - Show version information
154
234
···
167
247
# Attach a persistent disk image
168
248
freebsd-up --drive ./freebsd-storage.qcow2 --disk-format qcow2 14.3-RELEASE
169
249
250
+
# Create a larger disk image automatically
251
+
freebsd-up --drive ./freebsd-big.qcow2 --disk-format qcow2 --size 100G 14.3-RELEASE
252
+
253
+
# Use bridge networking for better network performance
254
+
freebsd-up --bridge br0 14.3-RELEASE
255
+
170
256
# Save ISO to specific location
171
257
freebsd-up --output ./isos/freebsd.iso https://example.com/freebsd.iso
172
258
173
-
# Combine multiple options with persistent storage
174
-
freebsd-up --cpu host --cpus 4 --memory 8G --drive ./vm-disk.qcow2 --disk-format qcow2 --output ./downloads/ 14.3-RELEASE
259
+
# Combine multiple options with bridge networking and persistent storage
260
+
freebsd-up --cpu host --cpus 4 --memory 8G --drive ./vm-disk.qcow2 --disk-format qcow2 --size 50G --bridge br0 --output ./downloads/ 14.3-RELEASE
261
+
262
+
# List all VMs (including stopped ones)
263
+
freebsd-up ps --all
264
+
265
+
# Start a previously created VM
266
+
freebsd-up start my-freebsd-vm
267
+
268
+
# Stop a running VM
269
+
freebsd-up stop my-freebsd-vm
270
+
271
+
# Get detailed information about a VM
272
+
freebsd-up inspect my-freebsd-vm
175
273
```
176
274
177
275
## 🖥️ Console Setup
···
197
295
- **Cores**: 2 virtual CPUs (configurable with `--cpus`)
198
296
- **Storage**: ISO-only by default; optional persistent disk (configurable with
199
297
`--drive`)
200
-
- **Network**: User mode networking with SSH forwarding
298
+
- **Network**: User mode networking with SSH forwarding (host:2222 → guest:22)
299
+
or bridge networking with `--bridge`
201
300
- **Console**: Enhanced serial console via stdio with proper signal handling
202
301
- **Default Version**: FreeBSD 14.3-RELEASE (when no arguments provided)
302
+
- **State Management**: Persistent VM state stored in SQLite database
303
+
- **Auto-naming**: VMs get unique names for easy management
304
+
305
+
### Networking Modes
306
+
307
+
FreeBSD-Up supports two networking modes:
308
+
309
+
1. **User Mode (Default)**: Port forwarding for SSH access (host:2222 →
310
+
guest:22)
311
+
2. **Bridge Mode**: Direct network access via bridge interface (requires
312
+
`--bridge` and sudo)
313
+
314
+
### VM State Management
315
+
316
+
All VMs are tracked in a local SQLite database with the following information:
317
+
318
+
- VM name and unique ID
319
+
- Hardware configuration (CPU, memory, cores)
320
+
- Network settings (bridge, MAC address)
321
+
- Storage configuration
322
+
- Current status (RUNNING, STOPPED)
323
+
- Process ID (when running)
324
+
- Creation timestamp
203
325
204
326
### Available CPU Types
205
327
···
245
367
246
368
### Creating Disk Images
247
369
248
-
Before using the `--drive` option, you may need to create a disk image:
370
+
Before using the `--drive` option, you may need to create a disk image.
371
+
FreeBSD-Up can automatically create disk images for you:
249
372
250
373
```bash
251
-
# Create a 20GB qcow2 disk image
374
+
# Automatically create a 20GB qcow2 disk image (default size)
375
+
freebsd-up --drive ./freebsd-data.qcow2 --disk-format qcow2 14.3-RELEASE
376
+
377
+
# Create a larger 50GB disk image
378
+
freebsd-up --drive ./freebsd-large.qcow2 --disk-format qcow2 --size 50G 14.3-RELEASE
379
+
380
+
# Manually create disk images with qemu-img
252
381
qemu-img create -f qcow2 freebsd-data.qcow2 20G
382
+
qemu-img create -f raw freebsd-data.img 10G
383
+
```
253
384
254
-
# Create a 10GB raw disk image
255
-
qemu-img create -f raw freebsd-data.img 10G
385
+
### Setting up Bridge Networking
386
+
387
+
For bridge networking, you need to set up a bridge interface first:
388
+
389
+
```bash
390
+
# Create a bridge interface (requires root)
391
+
sudo ip link add br0 type bridge
392
+
sudo ip link set br0 up
393
+
394
+
# Add your network interface to the bridge
395
+
sudo ip link set eth0 master br0
396
+
397
+
# Then use FreeBSD-Up with bridge networking
398
+
freebsd-up --bridge br0 14.3-RELEASE
256
399
```
400
+
401
+
Note: Bridge networking requires sudo privileges and FreeBSD-Up will
402
+
automatically create the bridge if it doesn't exist.
257
403
258
404
### Advanced Customization
259
405
260
406
To modify other VM settings, edit the QEMU arguments in the `runQemu` function
261
-
in `main.ts`:
407
+
in `src/utils.ts`. The main.ts file now serves as the CLI entry point with
408
+
subcommand routing.
262
409
263
-
```typescript
264
-
const cmd = new Deno.Command("qemu-system-x86_64", {
265
-
args: [
266
-
"-enable-kvm",
267
-
"-cpu",
268
-
options.cpu,
269
-
"-m",
270
-
options.memory,
271
-
"-smp",
272
-
options.cpus.toString(), // Number of CPU cores
273
-
"-chardev",
274
-
"stdio,id=con0,signal=off", // Enhanced console handling
275
-
"-serial",
276
-
"chardev:con0",
277
-
// Conditional drive attachment for persistent storage
278
-
...(options.drive
279
-
? [
280
-
"-drive",
281
-
`file=${options.drive},format=${options.diskFormat},if=virtio`,
282
-
]
283
-
: []),
284
-
// ... other options
285
-
],
286
-
// ...
287
-
});
288
-
```
410
+
Key architecture changes:
411
+
412
+
- **Modular design**: Core functionality split into separate modules in `src/`
413
+
- **Database integration**: SQLite database for persistent VM state management
414
+
- **Subcommand structure**: Dedicated commands for VM lifecycle operations
415
+
- **Network management**: Automatic bridge setup and MAC address assignment
416
+
- **State tracking**: Comprehensive VM state persistence across restarts
289
417
290
418
### Supported Version Formats
291
419
···
303
431
304
432
```
305
433
freebsd-up/
306
-
├── main.ts # Main script with Cliffy CLI integration
307
-
├── deno.json # Deno configuration with dependencies
308
-
├── deno.lock # Dependency lock file
309
-
└── README.md # This file
434
+
├── main.ts # CLI entry point with Cliffy command routing
435
+
├── deno.json # Deno configuration with dependencies
436
+
├── deno.lock # Dependency lock file
437
+
├── README.md # This file
438
+
└── src/ # Core functionality modules
439
+
├── constants.ts # Configuration constants
440
+
├── context.ts # Application context and database setup
441
+
├── db.ts # Database schema and migrations
442
+
├── network.ts # Network bridge management
443
+
├── state.ts # VM state management functions
444
+
├── types.ts # TypeScript type definitions
445
+
├── utils.ts # Core VM utilities and QEMU interface
446
+
└── subcommands/ # CLI subcommand implementations
447
+
├── inspect.ts # VM inspection command
448
+
├── ps.ts # VM listing command
449
+
├── start.ts # VM start command
450
+
└── stop.ts # VM stop command
310
451
```
311
452
312
453
### Dependencies
···
314
455
The project uses the following key dependencies:
315
456
316
457
- **[@cliffy/command](https://jsr.io/@cliffy/command)** - Modern command-line
317
-
argument parsing
458
+
argument parsing and subcommands
459
+
- **[@cliffy/table](https://jsr.io/@cliffy/table)** - Formatted table output for
460
+
VM listings
461
+
- **[@db/sqlite](https://jsr.io/@db/sqlite)** - SQLite database for VM state
462
+
persistence
463
+
- **[kysely](https://www.npmjs.com/package/kysely)** - Type-safe SQL query
464
+
builder
318
465
- **[chalk](https://www.npmjs.com/package/chalk)** - Terminal styling and colors
466
+
- **[dayjs](https://www.npmjs.com/package/dayjs)** - Date formatting and
467
+
manipulation
468
+
- **[lodash](https://www.npmjs.com/package/lodash)** - Utility functions
469
+
- **[moniker](https://www.npmjs.com/package/moniker)** - Unique name generation
470
+
for VMs
319
471
320
472
## 🤝 Contributing
321
473