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
- ๐ท๏ธ **Auto-generated VM names**: Unique identifiers for easy VM management
29
- ๐๏ธ **Cross-platform support**: Works on both x86_64 and aarch64 architectures
30
- ๐ง **Background mode**: Run VMs in detached mode for headless operation
31
32
### Network & Storage
33
···
35
- ๐ **Network bridge support**: Automatic bridge creation and management with
36
`--bridge`
37
- ๐ง **MAC address management**: Persistent MAC addresses for each VM
38
-
- ๏ฟฝ **Port forwarding**: Custom port mapping for network services with
39
`--port-forward`
40
-
- ๏ฟฝ๐พ **Persistent storage support**: Attach and auto-create disk images
41
- ๐๏ธ **Multiple disk formats**: Support for qcow2, raw, and other disk formats
42
- ๐ **Configurable disk sizes**: Specify disk image size on creation
43
44
### Convenience Features
45
···
68
`freebsd-up init`
69
- ๐ **Config Merging**: Command-line options override configuration file
70
settings
71
72
- ๐ **Download and boot from URLs**: Automatically downloads ISO images from
73
remote URLs
···
257
```bash
258
freebsd-up push ghcr.io/tsirysndr/freebsd:15.0-BETA4
259
```
260
261
### Using Configuration Files
262
···
266
freebsd-up init
267
```
268
269
-
This creates a `freebsd-up.toml` file with default settings. Example
270
configuration:
271
272
```toml
···
315
# Run VM in background (detached mode)
316
freebsd-up --detach 14.3-RELEASE
317
318
# Download to specific location
319
freebsd-up --output ./downloads/freebsd.iso 15.0-BETA3
320
321
# 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
323
````
324
325
### Get Help
···
355
356
### Network Options
357
358
- `-b, --bridge <name>` - Name of the network bridge to use (e.g., br0)
359
- `-p, --port-forward <mappings>` - Port forwarding rules in the format
360
hostPort:guestPort (comma-separated for multiple)
361
362
### Execution Options
363
364
- `-d, --detach` - Run VM in the background and print VM name
365
366
### File Options
367
···
369
370
### Management Commands
371
372
-
- `init` - Initialize a VM configuration file (`freebsd-up.toml`) in the current
373
directory
374
- `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)
377
- `stop <vm-name>` - Stop a specific VM by name
378
- `restart <vm-name>` - Restart a specific VM by name
379
- `inspect <vm-name>` - Show detailed information about a VM
380
- `logs <vm-name> [--follow]` - View VM logs (optionally follow in real-time)
381
- `rm <vm-name>` - Remove a VM and its configuration from the database
382
- `images` - List all VM disk images
383
- `tag <vm-name> <image:tag>` - Tag a VM disk image for pushing to a registry
384
- `rmi <image-id>` - Remove a VM disk image
···
386
- `logout <registry>` - Logout from an OCI registry
387
- `pull <image:tag>` - Pull a VM disk image from an OCI registry
388
- `push <image:tag>` - Push a VM disk image to an OCI registry
389
390
### Help Options
391
···
419
# Run VM in background mode
420
freebsd-up --detach 14.3-RELEASE
421
422
# Save ISO to specific location
423
freebsd-up --output ./isos/freebsd.iso https://example.com/freebsd.iso
424
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
427
428
# List all VMs (including stopped ones)
429
freebsd-up ps --all
···
431
# Start a previously created VM
432
freebsd-up start my-freebsd-vm
433
434
-
# Start a VM in background mode
435
-
freebsd-up start my-freebsd-vm --detach
436
437
# Stop a running VM
438
freebsd-up stop my-freebsd-vm
···
451
452
# Remove a VM
453
freebsd-up rm my-freebsd-vm
454
```
455
456
## ๐ฅ๏ธ Console Setup
···
606
(see `src/db.ts`)
607
- **Image management**: OCI registry integration for sharing and distributing VM
608
images (see `src/images.ts`, `src/oras.ts`)
609
- **Configuration files**: TOML-based configuration for declarative VM setups
610
(see `src/config.ts`)
611
- **Effect-based error handling**: Functional error handling and async
···
649
โโโ state.ts # VM state management functions
650
โโโ types.ts # TypeScript type definitions
651
โโโ utils.ts # Core VM utilities and QEMU interface
652
โโโ subcommands/ # CLI subcommand implementations
653
โโโ images.ts # List images command
654
โโโ inspect.ts # VM inspection command
···
662
โโโ rm.ts # VM removal command
663
โโโ rmi.ts # Remove image command
664
โโโ run.ts # Run VM command
665
โโโ start.ts # VM start command
666
โโโ stop.ts # VM stop command
667
-
โโโ tag.ts # Tag image command
668
```
669
670
### Dependencies
···
699
for error handling and async operations
700
- **[moniker](https://www.npmjs.com/package/moniker)** - Unique name generation
701
for VMs
702
703
## ๐ค Contributing
704
···
28
- ๐ท๏ธ **Auto-generated VM names**: Unique identifiers for easy VM management
29
- ๐๏ธ **Cross-platform support**: Works on both x86_64 and aarch64 architectures
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
33
34
### Network & Storage
35
···
37
- ๐ **Network bridge support**: Automatic bridge creation and management with
38
`--bridge`
39
- ๐ง **MAC address management**: Persistent MAC addresses for each VM
40
+
- ๐ **Port forwarding**: Custom port mapping for network services with
41
`--port-forward`
42
+
- ๐พ **Persistent storage support**: Attach and auto-create disk images
43
- ๐๏ธ **Multiple disk formats**: Support for qcow2, raw, and other disk formats
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
47
48
### Convenience Features
49
···
72
`freebsd-up init`
73
- ๐ **Config Merging**: Command-line options override configuration file
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
88
89
- ๐ **Download and boot from URLs**: Automatically downloads ISO images from
90
remote URLs
···
274
```bash
275
freebsd-up push ghcr.io/tsirysndr/freebsd:15.0-BETA4
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.
334
335
### Using Configuration Files
336
···
340
freebsd-up init
341
```
342
343
+
This creates a `vmconfig.toml` file with default settings. Example
344
configuration:
345
346
```toml
···
389
# Run VM in background (detached mode)
390
freebsd-up --detach 14.3-RELEASE
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
+
398
# Download to specific location
399
freebsd-up --output ./downloads/freebsd.iso 15.0-BETA3
400
401
# Combine all options
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
403
````
404
405
### Get Help
···
435
436
### Network Options
437
438
+
### Network Options
439
+
440
- `-b, --bridge <name>` - Name of the network bridge to use (e.g., br0)
441
- `-p, --port-forward <mappings>` - Port forwarding rules in the format
442
hostPort:guestPort (comma-separated for multiple)
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
+
449
### Execution Options
450
451
- `-d, --detach` - Run VM in the background and print VM name
452
+
- `--install` - Persist changes to the VM disk image
453
454
### File Options
455
···
457
458
### Management Commands
459
460
+
- `init` - Initialize a VM configuration file (`vmconfig.toml`) in the current
461
directory
462
- `ps [--all]` - List running VMs (use --all to include stopped VMs)
463
+
- `start <vm-name> [--detach] [-v, --volume <name>]` - Start a specific VM by
464
+
name (optionally in background, optionally attach a volume)
465
- `stop <vm-name>` - Stop a specific VM by name
466
- `restart <vm-name>` - Restart a specific VM by name
467
- `inspect <vm-name>` - Show detailed information about a VM
468
- `logs <vm-name> [--follow]` - View VM logs (optionally follow in real-time)
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
471
- `images` - List all VM disk images
472
- `tag <vm-name> <image:tag>` - Tag a VM disk image for pushing to a registry
473
- `rmi <image-id>` - Remove a VM disk image
···
475
- `logout <registry>` - Logout from an OCI registry
476
- `pull <image:tag>` - Pull a VM disk image from an OCI registry
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)
482
483
### Help Options
484
···
512
# Run VM in background mode
513
freebsd-up --detach 14.3-RELEASE
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
+
521
# Save ISO to specific location
522
freebsd-up --output ./isos/freebsd.iso https://example.com/freebsd.iso
523
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
526
527
# List all VMs (including stopped ones)
528
freebsd-up ps --all
···
530
# Start a previously created VM
531
freebsd-up start my-freebsd-vm
532
533
+
# Start a VM in background mode with volume
534
+
freebsd-up start my-freebsd-vm --detach --volume my-data
535
536
# Stop a running VM
537
freebsd-up stop my-freebsd-vm
···
550
551
# Remove a VM
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
571
```
572
573
## ๐ฅ๏ธ Console Setup
···
723
(see `src/db.ts`)
724
- **Image management**: OCI registry integration for sharing and distributing VM
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/`)
729
- **Configuration files**: TOML-based configuration for declarative VM setups
730
(see `src/config.ts`)
731
- **Effect-based error handling**: Functional error handling and async
···
769
โโโ state.ts # VM state management functions
770
โโโ types.ts # TypeScript type definitions
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
779
โโโ subcommands/ # CLI subcommand implementations
780
โโโ images.ts # List images command
781
โโโ inspect.ts # VM inspection command
···
789
โโโ rm.ts # VM removal command
790
โโโ rmi.ts # Remove image command
791
โโโ run.ts # Run VM command
792
+
โโโ serve.ts # HTTP API server command
793
โโโ start.ts # VM start command
794
โโโ stop.ts # VM stop command
795
+
โโโ tag.ts # Tag image command
796
+
โโโ volume.ts # Volume management commands
797
```
798
799
### Dependencies
···
828
for error handling and async operations
829
- **[moniker](https://www.npmjs.com/package/moniker)** - Unique name generation
830
for VMs
831
+
- **[hono](https://www.npmjs.com/package/hono)** - Fast and lightweight web
832
+
framework for the HTTP API server
833
834
## ๐ค Contributing
835