tsiry-sandratraina.com
A simple, zero-configuration script to quickly boot FreeBSD ISO images using QEMU
feat: enhance README with new features and HTTP API documentation
+143
-12
README.md
+143
-12
README.md
···
28
28
- ๐ท๏ธ **Auto-generated VM names**: Unique identifiers for easy VM management
29
29
- ๐๏ธ **Cross-platform support**: Works on both x86_64 and aarch64 architectures
30
30
- ๐ง **Background mode**: Run VMs in detached mode for headless operation
31
+
- ๐ **Run from images**: Create and run VMs directly from OCI registry images
32
+
- ๐พ **Install mode**: Persist changes to VM disk images with `--install` flag
31
33
32
34
### Network & Storage
33
35
···
35
37
- ๐ **Network bridge support**: Automatic bridge creation and management with
36
38
`--bridge`
37
39
- ๐ง **MAC address management**: Persistent MAC addresses for each VM
38
-
- ๏ฟฝ **Port forwarding**: Custom port mapping for network services with
40
+
- ๐ **Port forwarding**: Custom port mapping for network services with
39
41
`--port-forward`
40
-
- ๏ฟฝ๐พ **Persistent storage support**: Attach and auto-create disk images
42
+
- ๐พ **Persistent storage support**: Attach and auto-create disk images
41
43
- ๐๏ธ **Multiple disk formats**: Support for qcow2, raw, and other disk formats
42
44
- ๐ **Configurable disk sizes**: Specify disk image size on creation
45
+
- ๐๏ธ **Volume management**: Create, list, inspect, and remove persistent volumes
46
+
- ๐ **Volume attachment**: Attach volumes to VMs with `--volume` flag
43
47
44
48
### Convenience Features
45
49
···
68
72
`freebsd-up init`
69
73
- ๐ **Config Merging**: Command-line options override configuration file
70
74
settings
75
+
76
+
### HTTP API Server
77
+
78
+
- ๐ **RESTful API**: Built-in HTTP API server for remote VM management
79
+
- ๐ **Bearer Token Authentication**: Secure API access with token
80
+
authentication
81
+
- ๐ฅ๏ธ **Machine Management API**: Create, start, stop, and manage VMs via HTTP
82
+
- ๐๏ธ **Image Management API**: List, pull, push, and manage VM images via HTTP
83
+
- ๐พ **Volume Management API**: Create, list, inspect, and remove volumes via
84
+
HTTP
85
+
- ๐ง **Configurable Port**: Customize API server port with `--port` or
86
+
environment variable
87
+
- ๐ **CORS Support**: Built-in CORS support for web-based clients
71
88
72
89
- ๐ **Download and boot from URLs**: Automatically downloads ISO images from
73
90
remote URLs
···
257
274
```bash
258
275
freebsd-up push ghcr.io/tsirysndr/freebsd:15.0-BETA4
259
276
```
277
+
278
+
Run a VM from an OCI registry image:
279
+
280
+
```bash
281
+
freebsd-up run ghcr.io/tsirysndr/freebsd:15.0-BETA4
282
+
```
283
+
284
+
### Volume Management Commands
285
+
286
+
List all volumes:
287
+
288
+
```bash
289
+
freebsd-up volumes
290
+
```
291
+
292
+
Remove a volume:
293
+
294
+
```bash
295
+
freebsd-up volume rm volume-name
296
+
```
297
+
298
+
Inspect a volume:
299
+
300
+
```bash
301
+
freebsd-up volume inspect volume-name
302
+
```
303
+
304
+
Attach a volume to a VM:
305
+
306
+
```bash
307
+
freebsd-up start vm-name --volume my-volume
308
+
```
309
+
310
+
### Starting the API Server
311
+
312
+
Start the HTTP API server:
313
+
314
+
```bash
315
+
freebsd-up serve
316
+
```
317
+
318
+
Start the API server on a custom port:
319
+
320
+
```bash
321
+
freebsd-up serve --port 9000
322
+
```
323
+
324
+
Set a custom API token via environment variable:
325
+
326
+
```bash
327
+
export FREEBSD_UP_API_TOKEN=your-secret-token
328
+
freebsd-up serve
329
+
```
330
+
331
+
The API server provides RESTful endpoints for managing VMs, images, and volumes
332
+
remotely. It includes bearer token authentication for security and supports CORS
333
+
for web-based clients.
260
334
261
335
### Using Configuration Files
262
336
···
266
340
freebsd-up init
267
341
```
268
342
269
-
This creates a `freebsd-up.toml` file with default settings. Example
343
+
This creates a `vmconfig.toml` file with default settings. Example
270
344
configuration:
271
345
272
346
```toml
···
315
389
# Run VM in background (detached mode)
316
390
freebsd-up --detach 14.3-RELEASE
317
391
392
+
# Persist changes to disk (install mode)
393
+
freebsd-up --install 14.3-RELEASE
394
+
395
+
# Attach a volume to the VM
396
+
freebsd-up --volume my-data 14.3-RELEASE
397
+
318
398
# Download to specific location
319
399
freebsd-up --output ./downloads/freebsd.iso 15.0-BETA3
320
400
321
401
# Combine all options
322
-
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
402
+
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 --volume my-data --install --output ./my-freebsd.iso
323
403
````
324
404
325
405
### Get Help
···
355
435
356
436
### Network Options
357
437
438
+
### Network Options
439
+
358
440
- `-b, --bridge <name>` - Name of the network bridge to use (e.g., br0)
359
441
- `-p, --port-forward <mappings>` - Port forwarding rules in the format
360
442
hostPort:guestPort (comma-separated for multiple)
361
443
444
+
### Storage Options
445
+
446
+
- `-v, --volume <name>` - Name of the volume to attach to the VM (will be
447
+
created if it doesn't exist)
448
+
362
449
### Execution Options
363
450
364
451
- `-d, --detach` - Run VM in the background and print VM name
452
+
- `--install` - Persist changes to the VM disk image
365
453
366
454
### File Options
367
455
···
369
457
370
458
### Management Commands
371
459
372
-
- `init` - Initialize a VM configuration file (`freebsd-up.toml`) in the current
460
+
- `init` - Initialize a VM configuration file (`vmconfig.toml`) in the current
373
461
directory
374
462
- `ps [--all]` - List running VMs (use --all to include stopped VMs)
375
-
- `start <vm-name> [--detach]` - Start a specific VM by name (optionally in
376
-
background)
463
+
- `start <vm-name> [--detach] [-v, --volume <name>]` - Start a specific VM by
464
+
name (optionally in background, optionally attach a volume)
377
465
- `stop <vm-name>` - Stop a specific VM by name
378
466
- `restart <vm-name>` - Restart a specific VM by name
379
467
- `inspect <vm-name>` - Show detailed information about a VM
380
468
- `logs <vm-name> [--follow]` - View VM logs (optionally follow in real-time)
381
469
- `rm <vm-name>` - Remove a VM and its configuration from the database
470
+
- `run <image:tag> [options]` - Create and run a VM from an OCI registry image
382
471
- `images` - List all VM disk images
383
472
- `tag <vm-name> <image:tag>` - Tag a VM disk image for pushing to a registry
384
473
- `rmi <image-id>` - Remove a VM disk image
···
386
475
- `logout <registry>` - Logout from an OCI registry
387
476
- `pull <image:tag>` - Pull a VM disk image from an OCI registry
388
477
- `push <image:tag>` - Push a VM disk image to an OCI registry
478
+
- `volumes` - List all volumes
479
+
- `volume rm <volume-name>` - Remove a volume
480
+
- `volume inspect <volume-name>` - Inspect a volume
481
+
- `serve [--port <port>]` - Start the HTTP API server (default port: 8890)
389
482
390
483
### Help Options
391
484
···
419
512
# Run VM in background mode
420
513
freebsd-up --detach 14.3-RELEASE
421
514
515
+
# Persist changes to disk (install mode)
516
+
freebsd-up --install 14.3-RELEASE
517
+
518
+
# Attach a volume to the VM
519
+
freebsd-up --volume my-data 14.3-RELEASE
520
+
422
521
# Save ISO to specific location
423
522
freebsd-up --output ./isos/freebsd.iso https://example.com/freebsd.iso
424
523
425
-
# Combine multiple options with bridge networking, port forwarding, and persistent storage
426
-
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
524
+
# Combine multiple options with bridge networking, port forwarding, persistent storage, and volumes
525
+
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 --volume my-data --install --output ./downloads/ 14.3-RELEASE
427
526
428
527
# List all VMs (including stopped ones)
429
528
freebsd-up ps --all
···
431
530
# Start a previously created VM
432
531
freebsd-up start my-freebsd-vm
433
532
434
-
# Start a VM in background mode
435
-
freebsd-up start my-freebsd-vm --detach
533
+
# Start a VM in background mode with volume
534
+
freebsd-up start my-freebsd-vm --detach --volume my-data
436
535
437
536
# Stop a running VM
438
537
freebsd-up stop my-freebsd-vm
···
451
550
452
551
# Remove a VM
453
552
freebsd-up rm my-freebsd-vm
553
+
554
+
# Run a VM from an OCI registry image
555
+
freebsd-up run ghcr.io/tsirysndr/freebsd:15.0-BETA4
556
+
557
+
# List all volumes
558
+
freebsd-up volumes
559
+
560
+
# Remove a volume
561
+
freebsd-up volume rm my-volume
562
+
563
+
# Inspect a volume
564
+
freebsd-up volume inspect my-volume
565
+
566
+
# Start the HTTP API server
567
+
freebsd-up serve
568
+
569
+
# Start API server on custom port
570
+
freebsd-up serve --port 9000
454
571
```
455
572
456
573
## ๐ฅ๏ธ Console Setup
···
606
723
(see `src/db.ts`)
607
724
- **Image management**: OCI registry integration for sharing and distributing VM
608
725
images (see `src/images.ts`, `src/oras.ts`)
726
+
- **Volume management**: Persistent volume support for VM storage (see
727
+
`src/volumes.ts`)
728
+
- **HTTP API**: RESTful API server for remote VM management (see `src/api/`)
609
729
- **Configuration files**: TOML-based configuration for declarative VM setups
610
730
(see `src/config.ts`)
611
731
- **Effect-based error handling**: Functional error handling and async
···
649
769
โโโ state.ts # VM state management functions
650
770
โโโ types.ts # TypeScript type definitions
651
771
โโโ utils.ts # Core VM utilities and QEMU interface
772
+
โโโ volumes.ts # Volume management functions
773
+
โโโ api/ # HTTP API server
774
+
โ โโโ images.ts # Image management API endpoints
775
+
โ โโโ machines.ts # VM management API endpoints
776
+
โ โโโ volumes.ts # Volume management API endpoints
777
+
โ โโโ utils.ts # API utilities and helpers
778
+
โ โโโ mod.ts # API server entry point
652
779
โโโ subcommands/ # CLI subcommand implementations
653
780
โโโ images.ts # List images command
654
781
โโโ inspect.ts # VM inspection command
···
662
789
โโโ rm.ts # VM removal command
663
790
โโโ rmi.ts # Remove image command
664
791
โโโ run.ts # Run VM command
792
+
โโโ serve.ts # HTTP API server command
665
793
โโโ start.ts # VM start command
666
794
โโโ stop.ts # VM stop command
667
-
โโโ tag.ts # Tag image command
795
+
โโโ tag.ts # Tag image command
796
+
โโโ volume.ts # Volume management commands
668
797
```
669
798
670
799
### Dependencies
···
699
828
for error handling and async operations
700
829
- **[moniker](https://www.npmjs.com/package/moniker)** - Unique name generation
701
830
for VMs
831
+
- **[hono](https://www.npmjs.com/package/hono)** - Fast and lightweight web
832
+
framework for the HTTP API server
702
833
703
834
## ๐ค Contributing
704
835