dflybsd-up ≽༏≼

A convenient CLI tool to quickly spin up DragonflyBSD virtual machines using QEMU with sensible defaults. Includes comprehensive VM management capabilities with database tracking, background execution, and flexible networking options.

✨ Features

⚡ Quick Start: Launch DragonflyBSD with a single command
📥 Automatic ISO Download: Fetches DragonflyBSD ISO images automatically from official mirrors
🔢 Version Support: Specify any DragonflyBSD version (defaults to 6.4.2)
🎯 Flexible Input: Accepts version numbers, local ISO paths, or download URLs
💾 Smart Caching: Skips re-downloading already downloaded ISOs
🚀 KVM Acceleration: Leverages KVM for optimal performance
🔌 SSH Port Forwarding: Automatically forwards port 2222 to guest port 22
💻 Serial Console: Direct terminal access without graphical overhead
💿 Persistent Storage: Optional disk image support for persistent installations
⚙️ Customizable Resources: Configure CPU, memory, and disk settings
🗃️ VM Management: Track and manage multiple virtual machines with database storage
🌐 Bridge Networking: Support for bridge networking configurations
🔍 VM Inspection: List, start, stop, restart, and inspect virtual machines
📋 VM Operations: Remove VMs, view logs with follow mode, and background execution
🏷️ Automatic MAC Assignment: Unique MAC addresses generated for each VM
🔧 Custom Port Forwarding: Flexible port mapping with multiple forwards support
🔄 Background Mode: Run VMs detached from terminal with logging support
🐳 OCI Registry Support: Push and pull VM images to/from OCI-compliant registries (Docker Hub, GitHub Container Registry, etc.)
📦 Image Management: Tag, list, and remove local VM images
⚙️ Configuration Files: Define VM settings in a vmconfig.toml file for reproducible setups
🚀 Image-based VMs: Run VMs directly from saved or pulled images

📋 Prerequisites

Deno runtime
QEMU with KVM support (qemu-system-x86_64)
KVM kernel modules enabled

📦 Installation

deno install -A -g -r -f jsr:@tsiry/dflybsd-up

🚀 Usage

Basic Usage

# Launch with defaults (DragonflyBSD 6.4.2, 2 CPUs, 2GB RAM)
dflybsd-up

# Specify a version (automatically downloads the RELEASE ISO)
dflybsd-up 6.4.2

# Use a local ISO file
dflybsd-up /path/to/dragonflybsd.iso

# Download from a specific URL
dflybsd-up https://mirror-master.dragonflybsd.org/iso-images/dfly-x86_64-6.4.2_REL.iso

Advanced Options

# Custom CPU and memory configuration
dflybsd-up --cpu host --cpus 4 --memory 4G

# Specify output path for downloaded ISO
dflybsd-up 6.4.2 --output ~/isos/dragonfly.iso

# Use a persistent disk image with custom size
dflybsd-up --image dragonfly.img --disk-format raw --size 30G

# Use bridge networking
dflybsd-up --bridge br0

# Run VM in background (detached mode)
dflybsd-up --detach

# Custom port forwarding (forward host port 8080 to guest port 80)
dflybsd-up --port-forward 8080:80

# Multiple port forwards
dflybsd-up --port-forward 8080:80,3000:3000

# Combine options
dflybsd-up 6.4.2 \
  --cpus 4 \
  --memory 8G \
  --image dragonfly.qcow2 \
  --disk-format qcow2 \
  --size 50G \
  --detach \
  --port-forward 2222:22,8080:80

VM Management Commands

# List running virtual machines
dflybsd-up ps

# List all virtual machines (including stopped)
dflybsd-up ps --all

# Start a previously created VM
dflybsd-up start my-vm

# Start a VM in background (detached mode)
dflybsd-up start my-vm --detach

# Stop a running VM
dflybsd-up stop my-vm

# Restart a VM
dflybsd-up restart my-vm

# Remove a VM (delete from database)
dflybsd-up rm my-vm

# View VM logs
dflybsd-up logs my-vm

# Follow VM logs in real-time
dflybsd-up logs my-vm --follow

# Inspect VM details
dflybsd-up inspect my-vm

Configuration File Management

# Create a default VM configuration file (vmconfig.toml)
dflybsd-up init

# Edit the configuration file to customize VM settings
# Then start the VM using the configuration
dflybsd-up

OCI Registry Operations

# Login to a registry (e.g., Docker Hub, GitHub Container Registry)
dflybsd-up login ghcr.io --username your-username
# or pipe password
echo $GITHUB_TOKEN | dflybsd-up login ghcr.io --username your-username

# Tag a VM's disk image
dflybsd-up tag my-vm ghcr.io/username/my-dragonfly-vm:latest

# Push VM image to registry
dflybsd-up push ghcr.io/username/my-dragonfly-vm:latest

# Pull VM image from registry
dflybsd-up pull ghcr.io/username/my-dragonfly-vm:latest

# List local VM images
dflybsd-up images

# Remove a local VM image
dflybsd-up rmi ghcr.io/username/my-dragonfly-vm:latest

# Run a VM from a pulled image
dflybsd-up run ghcr.io/username/my-dragonfly-vm:latest

# Run with custom options
dflybsd-up run ghcr.io/username/my-dragonfly-vm:latest --cpus 4 --memory 8G --detach

# Logout from registry
dflybsd-up logout ghcr.io

⚙️ Options

Option	Short	Description	Default
`--output`	`-o`	Output path for downloaded ISO	Auto-generated from URL
`--cpu`	`-c`	CPU type to emulate	`host`
`--cpus`	`-C`	Number of CPU cores	`2`
`--memory`	`-m`	Amount of memory for VM	`2G`
`--image`	`-i`	Path to VM disk image	None
`--disk-format`		Disk image format (qcow2, raw, etc.)	`raw`
`--size`		Size of disk image to create	`20G`
`--bridge`	`-b`	Network bridge name for networking	None (uses NAT)
`--detach`	`-d`	Run VM in the background	`false`
`--port-forward`	`-p`	Custom port forwarding (hostPort:guestPort)	`2222:22`
`--install`		Persist changes to the VM disk image	`false`

📝 Configuration File

You can create a vmconfig.toml file to define default VM settings:

# Initialize a configuration file
dflybsd-up init

This creates a configuration file with the following structure:

[vm]
iso = "https://mirror-master.dragonflybsd.org/iso-images/dfly-x86_64-6.4.2_REL.iso"
# output = "./dfly-x86_64-6.4.2_REL.iso"
cpu = "host"
cpus = 2
memory = "2G"
# image = "dragonfly.qcow2"
disk_format = "qcow2"
size = "20G"

[network]
# bridge = "br0"
port_forward = "2222:22"

[options]
detach = false

When you run dflybsd-up without arguments, it will use the settings from this file. Command-line options override configuration file settings.

🔢 Version Format

Simply provide the version number (e.g., 6.4.2 or 6.2), and the tool will automatically construct the download URL for the corresponding RELEASE ISO.

Examples:

6.4.2 → downloads dfly-x86_64-6.4.2_REL.iso
6.2 → downloads dfly-x86_64-6.2_REL.iso
7.0 → downloads dfly-x86_64-7.0_REL.iso

🖥️ Console Setup

When DragonflyBSD boots, you'll see the boot menu. For the best experience with the serial console:

Select option 9. Escape to loader prompt (also ESC)
Configure console output:
```
set console=comconsole
boot
```

This enables proper console redirection to your terminal.

🔍 VM Management & Background Execution

Background Mode (Detached)

Run VMs in the background without blocking your terminal:

# Create and run VM in background
dflybsd-up --detach

# Start existing VM in background
dflybsd-up start my-vm --detach

# When running in background, you can:
dflybsd-up logs my-vm --follow    # View real-time logs
dflybsd-up stop my-vm             # Stop the VM
dflybsd-up restart my-vm          # Restart the VM

VM Lifecycle Management

Automatic Tracking: Each VM is assigned a unique name and tracked in a local SQLite database
Persistent State: VM configurations are preserved between sessions
Status Monitoring: Track running and stopped VMs with process IDs
Resource Information: View CPU, memory, disk, and network configurations for each VM
Log Management: Each VM maintains its own log file for debugging and monitoring

� OCI Registry Integration

The tool supports pushing and pulling VM images to/from OCI-compliant registries like Docker Hub, GitHub Container Registry (ghcr.io), and others.

Workflow

Create and configure a VM with desired settings
Tag the VM's disk image to create a reference
Login to a registry with your credentials
Push the image to share it with others
Pull images created by you or others to run pre-configured VMs

Example: Sharing a VM Image

# Create a VM with persistent storage
dflybsd-up 6.4.2 --image dragonfly.qcow2 --size 30G

# Configure your DragonflyBSD installation as desired
# (install packages, configure services, etc.)

# Stop the VM and tag it
dflybsd-up stop <vm-name>
dflybsd-up tag <vm-name> ghcr.io/username/my-dragonfly-setup:v1

# Login to GitHub Container Registry
echo $GITHUB_TOKEN | dflybsd-up login ghcr.io --username username

# Push the image
dflybsd-up push ghcr.io/username/my-dragonfly-setup:v1

# Others can now pull and run your image
dflybsd-up pull ghcr.io/username/my-dragonfly-setup:v1
dflybsd-up run ghcr.io/username/my-dragonfly-setup:v1

Supported Registries

GitHub Container Registry: ghcr.io
Docker Hub: docker.io or just the image name (e.g., username/image:tag)
Any OCI-compliant registry that supports the OCI Distribution Specification

�🗃️ Virtual Machine Management

The tool now includes database-backed VM management, allowing you to track and manage multiple virtual machines:

VM Lifecycle

Automatic Tracking: Each VM is assigned a unique name and tracked in a local SQLite database
Persistent State: VM configurations are preserved between sessions
Status Monitoring: Track running and stopped VMs with process IDs
Resource Information: View CPU, memory, and disk configurations for each VM

VM Commands

ps - List virtual machines (use --all to include stopped VMs)
start <vm-name> - Start a previously created VM (use --detach to run in background)
stop <vm-name> - Stop a running VM
restart <vm-name> - Restart a VM (stop and start again)
rm <vm-name> - Remove a VM from the database (does not delete disk images)
logs <vm-name> - View VM logs (use --follow for real-time logs)
inspect <vm-name> - View detailed VM information

🌐 Networking Options

Default NAT Networking

By default, VMs use QEMU's user-mode networking with port forwarding:

Host port 2222 → Guest port 22 (SSH) by default
Custom port forwarding available with --port-forward option
No additional configuration required
Works without root privileges

Custom Port Forwarding

You can specify custom port forwarding rules:

# Forward host port 8080 to guest port 80
dflybsd-up --port-forward 8080:80

# Multiple port forwards (comma-separated)
dflybsd-up --port-forward 8080:80,3000:3000,2222:22

# Use with other options
dflybsd-up 6.4.2 --port-forward 8080:80 --memory 4G

Advanced Bridge Networking

For more advanced networking scenarios, use bridge networking:

# Use an existing bridge
dflybsd-up --bridge br0

# The tool will create the bridge if it doesn't exist (requires sudo)

Benefits of bridge networking:

VMs get IP addresses on your local network
Direct network access without port forwarding
Better performance for network-intensive applications
Supports multiple VMs on the same network segment

💿 Creating a Persistent Disk

To install DragonflyBSD persistently:

# Create a disk image (done automatically with --image if image doesn't exist)
dflybsd-up 6.4.2 --image dragonfly.qcow2 --disk-format qcow2 --size 30G

# Use --install flag to persist changes to the disk image
dflybsd-up 6.4.2 --image dragonfly.qcow2 --disk-format qcow2 --install

# Or manually create with qemu-img
qemu-img create -f qcow2 dragonfly.qcow2 20G

# Launch with the disk attached
dflybsd-up 6.4.2 --image dragonfly.qcow2 --disk-format qcow2

The --install option ensures that changes made during the VM session are written to the disk image, making them persistent across reboots.

🔐 SSH Access

NAT Networking (Default)

The VM automatically forwards host port 2222 to guest port 22 by default. You can customize port forwarding with the --port-forward option. After configuring SSH in your DragonflyBSD installation:

# Default SSH access (2222:22 forwarding)
ssh -p 2222 user@localhost

# Custom port forwarding
dflybsd-up --port-forward 2200:22
ssh -p 2200 user@localhost

# Access other services with custom forwarding
dflybsd-up --port-forward 2222:22,8080:80
# SSH: ssh -p 2222 user@localhost
# HTTP: http://localhost:8080

Bridge Networking

With bridge networking, the VM gets its own IP address on your network. You can SSH directly to the VM's IP:

ssh user@<vm-ip-address>

📄 License

See LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Note

This tool is designed for development and testing purposes. For production DragonflyBSD deployments, consider using proper installation methods.

tsirysndr/dragonflybsd-up