tsiry-sandratraina.com / freebsd-up
A simple, zero-configuration script to quickly boot FreeBSD ISO images using QEMU
1
fork

Configure Feed

Select the types of activity you want to include in your feed.

Enhance README.md with new features and commands for image and configuration management

- Added sections for Image Management & OCI Registry Support, detailing commands for listing, tagging, and managing VM disk images.
- Introduced Configuration Management section with examples for initializing and using configuration files.
- Improved formatting and clarity throughout the document, including command examples and descriptions.
- Updated prerequisites and dependencies to reflect new features and libraries.

Tsiry Sandratraina e07509e9 cadd3aac

+162 -36
+162 -36
README.md
··· 16 16 ### Core VM Management 17 17 18 18 - ๐Ÿ—๏ธ **Full VM lifecycle management**: Create, start, stop, restart, inspect, and remove 19 - VMs 19 + 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 38 - ๏ฟฝ **Port forwarding**: Custom port mapping for network services with `--port-forward` 39 39 - ๏ฟฝ๐Ÿ’พ **Persistent storage support**: Attach and auto-create disk images ··· 42 42 43 43 ### Convenience Features 44 44 45 + ### Image Management & OCI Registry Support 46 + 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 53 + 54 + ### Configuration Management 55 + 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 60 + 45 61 - ๐Ÿ”— **Download and boot from URLs**: Automatically downloads ISO images from 46 - remote URLs 62 + remote URLs 47 63 - ๐Ÿ“ **Local file support**: Boot from local ISO files 48 64 - ๐Ÿท๏ธ **Version shortcuts**: Simply specify a version like `14.3-RELEASE` to 49 - auto-download 65 + auto-download 50 66 - ๐ŸŽฏ **Smart defaults**: Run without arguments to boot the latest stable release 51 - (FreeBSD 14.3-RELEASE) 67 + (FreeBSD 14.3-RELEASE) 52 68 - โšก **Zero configuration**: Works out of the box with sensible defaults 53 69 - ๐Ÿ–ฅ๏ธ **Serial console**: Configured for headless operation with stdio console 54 70 - ๐Ÿ’พ **Smart caching**: Automatically skips re-downloading existing ISO files 55 71 - ๐Ÿ†˜ **Help support**: Built-in help with `--help` or `-h` flags 56 72 - โš™๏ธ **Configurable VM options**: Customize CPU type, core count, memory 57 - allocation 73 + allocation 58 74 - ๐Ÿ“ **Enhanced CLI**: Powered by [Cliffy](http://cliffy.io/) for robust 59 - command-line parsing 75 + command-line parsing 60 76 61 77 ## ๐Ÿ“‹ Prerequisites 62 78 ··· 187 203 freebsd-up logs vm-name --follow 188 204 ``` 189 205 190 - ```` 191 - ### Customize VM Configuration 206 + ### Image Management Commands 207 + 208 + List VM disk images: 209 + 210 + ```bash 211 + freebsd-up images 212 + ``` 213 + 214 + Tag a VM disk image: 215 + 216 + ```bash 217 + freebsd-up tag vm-name registry.example.com/myimage:latest 218 + ``` 219 + 220 + Remove a VM disk image: 221 + 222 + ```bash 223 + freebsd-up rmi image-id 224 + ``` 225 + 226 + Login to OCI registry: 227 + 228 + ```bash 229 + freebsd-up login -u username -p password registry.example.com 230 + ``` 231 + 232 + Logout from OCI registry: 233 + 234 + ```bash 235 + freebsd-up logout registry.example.com 236 + ``` 237 + 238 + Pull an image from OCI registry: 239 + 240 + ```bash 241 + freebsd-up pull registry.example.com/myimage:latest 242 + ``` 243 + 244 + Push an image to OCI registry: 245 + 246 + ```bash 247 + freebsd-up push registry.example.com/myimage:latest 248 + ``` 249 + 250 + ### Using Configuration Files 251 + 252 + Initialize a configuration file in your project: 253 + 254 + ```bash 255 + freebsd-up init 256 + ``` 257 + 258 + This creates a `freebsd-up.toml` file with default settings. Example configuration: 259 + 260 + ```toml 261 + [vm] 262 + iso = "https://download.freebsd.org/releases/amd64/amd64/ISO-IMAGES/14.3/FreeBSD-14.3-RELEASE-amd64-disc1.iso" 263 + cpu = "host" 264 + cpus = 2 265 + memory = "2G" 266 + image = "./freebsd-disk.qcow2" 267 + disk_format = "qcow2" 268 + size = "20G" 269 + 270 + [network] 271 + bridge = "br0" 272 + port_forward = "8080:80,2222:22" 273 + 274 + [options] 275 + detach = false 276 + ``` 277 + 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 192 281 193 282 Specify custom CPU type, core count, memory allocation, persistent storage, networking, and port forwarding: 194 283 ··· 219 308 220 309 # Combine all options 221 310 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 222 - ```` 311 + ``` 223 312 224 313 ### Get Help 225 314 ··· 248 337 - `-m, --memory <size>` - Amount of memory for the VM (default: `2G`) 249 338 - `-i, --image <path>` - Path to VM disk image for persistent storage 250 339 - `--disk-format <format>` - Disk image format: qcow2, raw, etc. (default: 251 - `raw`) 340 + `raw`) 252 341 - `-s, --size <size>` - Size of disk image to create if it doesn't exist 253 - (default: `20G`) 342 + (default: `20G`) 254 343 255 344 ### Network Options 256 345 ··· 267 356 268 357 ### Management Commands 269 358 359 + - `init` - Initialize a VM configuration file (`freebsd-up.toml`) in the current directory 270 360 - `ps [--all]` - List running VMs (use --all to include stopped VMs) 271 361 - `start <vm-name> [--detach]` - Start a specific VM by name (optionally in background) 272 362 - `stop <vm-name>` - Stop a specific VM by name ··· 274 364 - `inspect <vm-name>` - Show detailed information about a VM 275 365 - `logs <vm-name> [--follow]` - View VM logs (optionally follow in real-time) 276 366 - `rm <vm-name>` - Remove a VM and its configuration from the database 367 + - `images` - List all VM disk images 368 + - `tag <vm-name> <image:tag>` - Tag a VM disk image for pushing to a registry 369 + - `rmi <image-id>` - Remove a VM disk image 370 + - `login -u <username> -p <password> <registry>` - Login to an OCI registry 371 + - `logout <registry>` - Logout from an OCI registry 372 + - `pull <image:tag>` - Pull a VM disk image from an OCI registry 373 + - `push <image:tag>` - Push a VM disk image to an OCI registry 277 374 278 375 ### Help Options 279 376 ··· 347 444 serial console: 348 445 349 446 1. **Select option `3. Escape to loader prompt`** 447 + 350 448 2. **Configure console output:** 351 - ``` 352 - set console="comconsole" 353 - boot 354 - ``` 449 + 450 + ```sh 451 + set console="comconsole" 452 + boot 453 + ``` 355 454 356 455 This enables proper console redirection to your terminal. 357 456 ··· 363 462 - **Memory**: 2GB RAM (configurable with `--memory`) 364 463 - **Cores**: 2 virtual CPUs (configurable with `--cpus`) 365 464 - **Storage**: ISO-only by default; optional persistent disk (configurable with 366 - `--image`) 465 + `--image`) 367 466 - **Network**: User mode networking with SSH forwarding (host:2222 โ†’ guest:22) 368 - or bridge networking with `--bridge` 467 + or bridge networking with `--bridge` 369 468 - **Port Forwarding**: Configurable port mappings with `--port-forward` 370 469 - **Console**: Enhanced serial console via stdio with proper signal handling 371 470 - **Default Version**: FreeBSD 14.3-RELEASE (when no arguments provided) ··· 489 588 490 589 - **Modular design**: Core functionality split into separate modules in `src/` 491 590 - **Database integration**: SQLite database for persistent VM state management 492 - (see `src/db.ts`) 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`) 594 + - **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 493 598 - **Subcommand structure**: Dedicated commands for VM lifecycle operations in 494 - `src/subcommands/` 599 + `src/subcommands/` 495 600 - **Network management**: Automatic bridge setup and MAC address assignment in 496 - `src/network.ts` 601 + `src/network.ts` 497 602 - **State tracking**: Comprehensive VM state persistence across restarts in 498 - `src/state.ts` 603 + `src/state.ts` 499 604 500 605 ### Supported Version Formats 501 606 ··· 511 616 512 617 ## ๐Ÿ“ Project Structure 513 618 514 - ``` 619 + ```ini 515 620 freebsd-up/ 516 621 โ”œโ”€โ”€ main.ts # CLI entry point with Cliffy command routing 517 622 โ”œโ”€โ”€ deno.json # Deno configuration with dependencies 518 623 โ”œโ”€โ”€ deno.lock # Dependency lock file 519 624 โ”œโ”€โ”€ README.md # This file 520 625 โ””โ”€โ”€ src/ # Core functionality modules 626 + โ”œโ”€โ”€ config.ts # Configuration file parsing and management 521 627 โ”œโ”€โ”€ constants.ts # Configuration constants 522 628 โ”œโ”€โ”€ context.ts # Application context and database setup 523 629 โ”œโ”€โ”€ db.ts # Database schema and migrations 630 + โ”œโ”€โ”€ images.ts # Image management functions 631 + โ”œโ”€โ”€ migrations.ts # Database migration utilities 524 632 โ”œโ”€โ”€ network.ts # Network bridge management 633 + โ”œโ”€โ”€ oras.ts # OCI registry operations via ORAS 525 634 โ”œโ”€โ”€ state.ts # VM state management functions 526 635 โ”œโ”€โ”€ types.ts # TypeScript type definitions 527 636 โ”œโ”€โ”€ utils.ts # Core VM utilities and QEMU interface 528 637 โ””โ”€โ”€ subcommands/ # CLI subcommand implementations 638 + โ”œโ”€โ”€ images.ts # List images command 529 639 โ”œโ”€โ”€ inspect.ts # VM inspection command 640 + โ”œโ”€โ”€ login.ts # OCI registry login command 641 + โ”œโ”€โ”€ logout.ts # OCI registry logout command 530 642 โ”œโ”€โ”€ logs.ts # VM logging command 531 643 โ”œโ”€โ”€ ps.ts # VM listing command 644 + โ”œโ”€โ”€ pull.ts # Pull image from registry command 645 + โ”œโ”€โ”€ push.ts # Push image to registry command 532 646 โ”œโ”€โ”€ restart.ts # VM restart command 533 647 โ”œโ”€โ”€ rm.ts # VM removal command 648 + โ”œโ”€โ”€ rmi.ts # Remove image command 649 + โ”œโ”€โ”€ run.ts # Run VM command 534 650 โ”œโ”€โ”€ start.ts # VM start command 535 - โ””โ”€โ”€ stop.ts # VM stop command 651 + โ”œโ”€โ”€ stop.ts # VM stop command 652 + โ””โ”€โ”€ tag.ts # Tag image command 536 653 ``` 537 654 538 655 ### Dependencies ··· 540 657 The project uses the following key dependencies: 541 658 542 659 - **[@paralleldrive/cuid2](https://www.npmjs.com/package/@paralleldrive/cuid2)** - 543 - Unique ID generation for VMs 660 + Unique ID generation for VMs 544 661 - **[@cliffy/command](https://jsr.io/@cliffy/command)** - Modern command-line 545 - argument parsing and subcommands 662 + argument parsing and subcommands 663 + - **[@cliffy/flags](https://jsr.io/@cliffy/flags)** - Command-line flag parsing 664 + - **[@cliffy/prompt](https://jsr.io/@cliffy/prompt)** - Interactive prompts for CLI 546 665 - **[@cliffy/table](https://jsr.io/@cliffy/table)** - Formatted table output for 547 - VM listings 666 + VM listings 548 667 - **[@db/sqlite](https://jsr.io/@db/sqlite)** - SQLite database for VM state 549 - persistence 668 + persistence 550 669 - **[@soapbox/kysely-deno-sqlite](https://jsr.io/@soapbox/kysely-deno-sqlite)** - 551 - SQLite dialect for Kysely 670 + SQLite dialect for Kysely 671 + - **[@es-toolkit/es-toolkit](https://jsr.io/@es-toolkit/es-toolkit)** - Modern 672 + utility functions (replacing lodash) 673 + - **[@std/io](https://jsr.io/@std/io)** - Standard I/O utilities 674 + - **[@std/path](https://jsr.io/@std/path)** - Path manipulation utilities 675 + - **[@std/toml](https://jsr.io/@std/toml)** - TOML configuration file parsing 676 + - **[@zod/zod](https://jsr.io/@zod/zod)** - TypeScript-first schema validation 552 677 - **[kysely](https://www.npmjs.com/package/kysely)** - Type-safe SQL query 553 - builder 678 + builder 554 679 - **[chalk](https://www.npmjs.com/package/chalk)** - Terminal styling and colors 555 680 - **[dayjs](https://www.npmjs.com/package/dayjs)** - Date formatting and 556 - manipulation 557 - - **[lodash](https://www.npmjs.com/package/lodash)** - Utility functions 681 + manipulation 682 + - **[effect](https://www.npmjs.com/package/effect)** - Functional effect system for 683 + error handling and async operations 558 684 - **[moniker](https://www.npmjs.com/package/moniker)** - Unique name generation 559 - for VMs 685 + for VMs 560 686 561 687 ## ๐Ÿค Contributing 562 688