tsiry-sandratraina.com
A simple, zero-configuration script to quickly boot FreeBSD ISO images using QEMU
Refactor README.md for improved formatting and clarity
- Adjusted line breaks for better readability in core VM management, network & storage, image management, and configuration management sections.
- Enhanced descriptions for commands and options to maintain consistency and clarity.
- Updated example commands to reflect the latest image versions.
- Improved overall structure and formatting for better user experience.
+73
-57
README.md
+73
-57
README.md
···
15
15
16
16
### Core VM Management
17
17
18
-
- ๐๏ธ **Full VM lifecycle management**: Create, start, stop, restart, inspect, and remove
19
-
VMs
18
+
- ๐๏ธ **Full VM lifecycle management**: Create, start, stop, restart, inspect,
19
+
and remove VMs
20
20
- ๐พ **Persistent state tracking**: SQLite database stores VM configurations and
21
-
state
21
+
state
22
22
- ๐ **VM listing and monitoring**: View running and stopped VMs with detailed
23
-
information
23
+
information
24
24
- ๐ **VM inspection**: Get detailed information about any managed VM
25
25
- ๐ **VM logging**: View and follow VM logs with built-in log management
26
26
- ๐ **VM restart**: Gracefully restart VMs with preserved configuration
27
27
- ๐๏ธ **VM removal**: Clean removal of VMs from the database
28
28
- ๐ท๏ธ **Auto-generated VM names**: Unique identifiers for easy VM management
29
-
- ๐๏ธ __Cross-platform support__: Works on both x86_64 and aarch64 architectures
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
31
32
32
### Network & Storage
33
33
34
34
- ๐ **Flexible networking**: Support for both user-mode and bridge networking
35
35
- ๐ **Network bridge support**: Automatic bridge creation and management with
36
-
`--bridge`
36
+
`--bridge`
37
37
- ๐ง **MAC address management**: Persistent MAC addresses for each VM
38
-
- ๏ฟฝ **Port forwarding**: Custom port mapping for network services with `--port-forward`
38
+
- ๏ฟฝ **Port forwarding**: Custom port mapping for network services with
39
+
`--port-forward`
39
40
- ๏ฟฝ๐พ **Persistent storage support**: Attach and auto-create disk images
40
41
- ๐๏ธ **Multiple disk formats**: Support for qcow2, raw, and other disk formats
41
42
- ๐ **Configurable disk sizes**: Specify disk image size on creation
···
44
45
45
46
### Image Management & OCI Registry Support
46
47
47
-
- ๐ฆ **OCI Registry Integration**: Pull and push VM disk images to OCI-compatible registries
48
-
- ๐๏ธ **Image Management**: List, tag, and remove VM disk images with `images`, `tag`, and `rmi` commands
49
-
- ๐ **Registry Authentication**: Login and logout from OCI registries with `login` and `logout` commands
50
-
- ๐ **Image Sharing**: Share VM configurations and disk images across teams and environments
51
-
- ๐ฅ **Pull from Registry**: Download pre-configured VM images from remote registries
52
-
- ๐ค **Push to Registry**: Upload VM disk images to remote registries for distribution
48
+
- ๐ฆ **OCI Registry Integration**: Pull and push VM disk images to
49
+
OCI-compatible registries
50
+
- ๐๏ธ **Image Management**: List, tag, and remove VM disk images with `images`,
51
+
`tag`, and `rmi` commands
52
+
- ๐ **Registry Authentication**: Login and logout from OCI registries with
53
+
`login` and `logout` commands
54
+
- ๐ **Image Sharing**: Share VM configurations and disk images across teams and
55
+
environments
56
+
- ๐ฅ **Pull from Registry**: Download pre-configured VM images from remote
57
+
registries
58
+
- ๐ค **Push to Registry**: Upload VM disk images to remote registries for
59
+
distribution
53
60
54
61
### Configuration Management
55
62
56
-
- ๐ **Configuration Files**: Support for TOML-based VM configuration files with `freebsd-up.toml`
57
-
- โ๏ธ **Declarative VM Setup**: Define VM settings in configuration files for reproducible environments
58
-
- ๐ง **Init Command**: Generate default configuration files with `freebsd-up init`
59
-
- ๐ **Config Merging**: Command-line options override configuration file settings
63
+
- ๐ **Configuration Files**: Support for TOML-based VM configuration files with
64
+
`freebsd-up.toml`
65
+
- โ๏ธ **Declarative VM Setup**: Define VM settings in configuration files for
66
+
reproducible environments
67
+
- ๐ง **Init Command**: Generate default configuration files with
68
+
`freebsd-up init`
69
+
- ๐ **Config Merging**: Command-line options override configuration file
70
+
settings
60
71
61
72
- ๐ **Download and boot from URLs**: Automatically downloads ISO images from
62
-
remote URLs
73
+
remote URLs
63
74
- ๐ **Local file support**: Boot from local ISO files
64
75
- ๐ท๏ธ **Version shortcuts**: Simply specify a version like `14.3-RELEASE` to
65
-
auto-download
76
+
auto-download
66
77
- ๐ฏ **Smart defaults**: Run without arguments to boot the latest stable release
67
-
(FreeBSD 14.3-RELEASE)
78
+
(FreeBSD 14.3-RELEASE)
68
79
- โก **Zero configuration**: Works out of the box with sensible defaults
69
80
- ๐ฅ๏ธ **Serial console**: Configured for headless operation with stdio console
70
81
- ๐พ **Smart caching**: Automatically skips re-downloading existing ISO files
71
82
- ๐ **Help support**: Built-in help with `--help` or `-h` flags
72
83
- โ๏ธ **Configurable VM options**: Customize CPU type, core count, memory
73
-
allocation
84
+
allocation
74
85
- ๐ **Enhanced CLI**: Powered by [Cliffy](http://cliffy.io/) for robust
75
-
command-line parsing
86
+
command-line parsing
76
87
77
88
## ๐ Prerequisites
78
89
···
238
249
Pull an image from OCI registry:
239
250
240
251
```bash
241
-
freebsd-up pull registry.example.com/myimage:latest
252
+
freebsd-up pull ghcr.io/tsirysndr/freebsd:15.0-BETA4
242
253
```
243
254
244
255
Push an image to OCI registry:
245
256
246
257
```bash
247
-
freebsd-up push registry.example.com/myimage:latest
258
+
freebsd-up push ghcr.io/tsirysndr/freebsd:15.0-BETA4
248
259
```
249
260
250
261
### Using Configuration Files
···
255
266
freebsd-up init
256
267
```
257
268
258
-
This creates a `freebsd-up.toml` file with default settings. Example configuration:
269
+
This creates a `freebsd-up.toml` file with default settings. Example
270
+
configuration:
259
271
260
272
```toml
261
273
[vm]
···
275
287
detach = false
276
288
```
277
289
278
-
Command-line options will override configuration file settings, allowing you to customize VMs on a per-run basis while maintaining defaults in the config file.
279
-
280
-
```sh
290
+
Command-line options will override configuration file settings, allowing you to
291
+
customize VMs on a per-run basis while maintaining defaults in the config file.
281
292
293
+
````sh
282
294
Specify custom CPU type, core count, memory allocation, persistent storage, networking, and port forwarding:
283
295
284
296
```bash
···
308
320
309
321
# Combine all options
310
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
311
-
```
323
+
````
312
324
313
325
### Get Help
314
326
···
337
349
- `-m, --memory <size>` - Amount of memory for the VM (default: `2G`)
338
350
- `-i, --image <path>` - Path to VM disk image for persistent storage
339
351
- `--disk-format <format>` - Disk image format: qcow2, raw, etc. (default:
340
-
`raw`)
352
+
`raw`)
341
353
- `-s, --size <size>` - Size of disk image to create if it doesn't exist
342
-
(default: `20G`)
354
+
(default: `20G`)
343
355
344
356
### Network Options
345
357
346
358
- `-b, --bridge <name>` - Name of the network bridge to use (e.g., br0)
347
-
- `-p, --port-forward <mappings>` - Port forwarding rules in the format hostPort:guestPort (comma-separated for multiple)
359
+
- `-p, --port-forward <mappings>` - Port forwarding rules in the format
360
+
hostPort:guestPort (comma-separated for multiple)
348
361
349
362
### Execution Options
350
363
···
356
369
357
370
### Management Commands
358
371
359
-
- `init` - Initialize a VM configuration file (`freebsd-up.toml`) in the current directory
372
+
- `init` - Initialize a VM configuration file (`freebsd-up.toml`) in the current
373
+
directory
360
374
- `ps [--all]` - List running VMs (use --all to include stopped VMs)
361
-
- `start <vm-name> [--detach]` - Start a specific VM by name (optionally in background)
375
+
- `start <vm-name> [--detach]` - Start a specific VM by name (optionally in
376
+
background)
362
377
- `stop <vm-name>` - Stop a specific VM by name
363
378
- `restart <vm-name>` - Restart a specific VM by name
364
379
- `inspect <vm-name>` - Show detailed information about a VM
···
462
477
- **Memory**: 2GB RAM (configurable with `--memory`)
463
478
- **Cores**: 2 virtual CPUs (configurable with `--cpus`)
464
479
- **Storage**: ISO-only by default; optional persistent disk (configurable with
465
-
`--image`)
480
+
`--image`)
466
481
- **Network**: User mode networking with SSH forwarding (host:2222 โ guest:22)
467
-
or bridge networking with `--bridge`
482
+
or bridge networking with `--bridge`
468
483
- **Port Forwarding**: Configurable port mappings with `--port-forward`
469
484
- **Console**: Enhanced serial console via stdio with proper signal handling
470
485
- **Default Version**: FreeBSD 14.3-RELEASE (when no arguments provided)
···
588
603
589
604
- **Modular design**: Core functionality split into separate modules in `src/`
590
605
- **Database integration**: SQLite database for persistent VM state management
591
-
(see `src/db.ts`)
592
-
- **Image management**: OCI registry integration for sharing and distributing VM images
593
-
(see `src/images.ts`, `src/oras.ts`)
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`)
594
609
- **Configuration files**: TOML-based configuration for declarative VM setups
595
-
(see `src/config.ts`)
596
-
- **Effect-based error handling**: Functional error handling and async operations using
597
-
the Effect library for robust error management
610
+
(see `src/config.ts`)
611
+
- **Effect-based error handling**: Functional error handling and async
612
+
operations using the Effect library for robust error management
598
613
- **Subcommand structure**: Dedicated commands for VM lifecycle operations in
599
-
`src/subcommands/`
614
+
`src/subcommands/`
600
615
- **Network management**: Automatic bridge setup and MAC address assignment in
601
-
`src/network.ts`
616
+
`src/network.ts`
602
617
- **State tracking**: Comprehensive VM state persistence across restarts in
603
-
`src/state.ts`
618
+
`src/state.ts`
604
619
605
620
### Supported Version Formats
606
621
···
657
672
The project uses the following key dependencies:
658
673
659
674
- **[@paralleldrive/cuid2](https://www.npmjs.com/package/@paralleldrive/cuid2)** -
660
-
Unique ID generation for VMs
675
+
Unique ID generation for VMs
661
676
- **[@cliffy/command](https://jsr.io/@cliffy/command)** - Modern command-line
662
-
argument parsing and subcommands
677
+
argument parsing and subcommands
663
678
- **[@cliffy/flags](https://jsr.io/@cliffy/flags)** - Command-line flag parsing
664
-
- **[@cliffy/prompt](https://jsr.io/@cliffy/prompt)** - Interactive prompts for CLI
679
+
- **[@cliffy/prompt](https://jsr.io/@cliffy/prompt)** - Interactive prompts for
680
+
CLI
665
681
- **[@cliffy/table](https://jsr.io/@cliffy/table)** - Formatted table output for
666
-
VM listings
682
+
VM listings
667
683
- **[@db/sqlite](https://jsr.io/@db/sqlite)** - SQLite database for VM state
668
-
persistence
684
+
persistence
669
685
- **[@soapbox/kysely-deno-sqlite](https://jsr.io/@soapbox/kysely-deno-sqlite)** -
670
-
SQLite dialect for Kysely
686
+
SQLite dialect for Kysely
671
687
- **[@es-toolkit/es-toolkit](https://jsr.io/@es-toolkit/es-toolkit)** - Modern
672
-
utility functions (replacing lodash)
688
+
utility functions (replacing lodash)
673
689
- **[@std/io](https://jsr.io/@std/io)** - Standard I/O utilities
674
690
- **[@std/path](https://jsr.io/@std/path)** - Path manipulation utilities
675
691
- **[@std/toml](https://jsr.io/@std/toml)** - TOML configuration file parsing
676
692
- **[@zod/zod](https://jsr.io/@zod/zod)** - TypeScript-first schema validation
677
693
- **[kysely](https://www.npmjs.com/package/kysely)** - Type-safe SQL query
678
-
builder
694
+
builder
679
695
- **[chalk](https://www.npmjs.com/package/chalk)** - Terminal styling and colors
680
696
- **[dayjs](https://www.npmjs.com/package/dayjs)** - Date formatting and
681
-
manipulation
682
-
- **[effect](https://www.npmjs.com/package/effect)** - Functional effect system for
683
-
error handling and async operations
697
+
manipulation
698
+
- **[effect](https://www.npmjs.com/package/effect)** - Functional effect system
699
+
for error handling and async operations
684
700
- **[moniker](https://www.npmjs.com/package/moniker)** - Unique name generation
685
-
for VMs
701
+
for VMs
686
702
687
703
## ๐ค Contributing
688
704