Skip to main content
Deno 2 is finally here πŸŽ‰οΈ
Learn more

🐑 openbsd-up

release JSR deno module deno compatibility

A comprehensive CLI tool to manage OpenBSD virtual machines using QEMU with minimal fuss. Create, start, stop, and manage multiple OpenBSD VMs with persistent state tracking.

Preview

✨ Features

  • πŸš€ Quick Start: Launch OpenBSD VMs with a single command
  • πŸ“¦ Auto-Download: Automatically fetches OpenBSD ISO images from official CDN
  • πŸ”’ Version Support: Specify any OpenBSD version (e.g., 7.8, 6.4)
  • πŸ’Ύ Flexible Storage: Support for persistent disk images in multiple formats with auto-creation
  • βš™οΈ Configurable: Customize CPU, memory, cores, and more
  • 🌐 Network Ready: Support for both NAT (SSH port forwarding) and bridge networking
  • οΏ½ Port Forwarding: Custom port mapping with --port-forward option
  • οΏ½πŸ“ Serial Console: Direct terminal access via -nographic mode
  • πŸ—ƒοΈ VM Management: Persistent state tracking with SQLite database
  • πŸ“‹ VM Lifecycle: Start, stop, restart, list, and inspect VMs with unique names
  • πŸ—‘οΈ VM Cleanup: Remove VMs from tracking with rm command
  • πŸ“Š Logs Management: View and follow VM logs in real-time
  • πŸ”„ Background Mode: Run VMs detached with --detach option
  • 🎯 Smart Detection: Automatically detects existing disk images to avoid data loss
  • πŸ”— Bridge Support: Automatic bridge network creation and QEMU configuration

πŸ› οΈ Requirements

  • Deno runtime
  • QEMU with KVM support (qemu-system-x86_64)
  • curl for downloading ISOs
  • sudo access (for bridge networking only)

πŸ“₯ Installation

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

🎯 Usage

Basic Examples

# Launch latest default version (7.8) - creates a new VM with random name
openbsd-up

# Launch specific OpenBSD version
openbsd-up 7.6

# Use local ISO file
openbsd-up /path/to/openbsd.iso

# Download from custom URL
openbsd-up https://cdn.openbsd.org/pub/OpenBSD/7.8/amd64/install78.iso

VM Management

# List running VMs
openbsd-up ps

# List all VMs (including stopped)
openbsd-up ps --all

# Start a specific VM by name or ID
openbsd-up start my-vm-name

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

# Stop a running VM
openbsd-up stop my-vm-name

# Restart a VM
openbsd-up restart my-vm-name

# Remove a VM from state tracking
openbsd-up rm my-vm-name

# Inspect VM details and configuration
openbsd-up inspect my-vm-name

# View VM logs
openbsd-up logs my-vm-name

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

Advanced Configuration

# Custom VM with persistent disk (auto-created if needed)
openbsd-up 7.8 \
  --cpus 4 \
  --memory 4G \
  --cpu host \
  --image disk.img \
  --disk-format qcow2 \
  --size 40G

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

# Bridge networking (requires sudo)
openbsd-up 7.8 --bridge br0

# Custom port forwarding (host:guest port mappings)
openbsd-up 7.8 --port-forward 8080:80,3000:3000

# Save downloaded ISO to specific location
openbsd-up 7.8 --output ~/isos/openbsd-78.iso

πŸŽ›οΈ Command Line Options

Global Options

Option Short Description Default
--output -o Output path for downloaded ISO Auto-generated
--cpu -c CPU type to emulate host
--cpus -C Number of CPU cores 2
--memory -m RAM allocation 2G
--image -i Path to persistent disk image None
--disk-format Disk format (qcow2, raw, etc.) raw
--size Size of disk image to create if it doesn’t exist 20G
--bridge -b Name of the network bridge to use for networking (e.g., br0) None
--detach -d Run VM in the background and print VM name false
--port-forward -p Port forwarding rules (hostPort:guestPort, comma-separated) None

Subcommands

Command Description Example
ps List virtual machines openbsd-up ps --all
start <name> Start a stopped VM by name or ID openbsd-up start my-vm
stop <name> Stop a running VM by name or ID openbsd-up stop my-vm
restart <name> Restart a VM by name or ID openbsd-up restart my-vm
rm <name> Remove a VM from state tracking openbsd-up rm my-vm
inspect <name> Show detailed VM information and configuration openbsd-up inspect my-vm
logs <name> View VM logs openbsd-up logs my-vm

πŸ–₯️ Console Setup

When OpenBSD boots, you’ll see the boot loader prompt, enter the following command:

set tty com0
boot

πŸ”Œ Networking

The tool supports two networking modes:

NAT Mode (Default)

  • SSH Port Forward: localhost:2222 β†’ VM port 22 (default)
  • Custom Port Forwarding: Configure with --port-forward option
  • Network Device: Intel E1000 emulated NIC
  • No special privileges required

Custom Port Forwarding Examples

# Forward host port 8080 to VM port 80
openbsd-up 7.8 --port-forward 8080:80

# Multiple port forwards
openbsd-up 7.8 --port-forward 8080:80,3000:3000,2222:22

# Access services after VM is running
curl http://localhost:8080  # Access VM's port 80
ssh -p 2222 user@localhost  # SSH to VM

Bridge Mode

  • Direct Bridge Access: VM gets IP from bridge network
  • Network Device: Intel E1000 emulated NIC with custom MAC
  • Requires sudo privileges for QEMU bridge access
  • Automatically creates bridge network if it doesn’t exist
  • Sets up QEMU bridge configuration in /etc/qemu/bridge.conf

Connect via SSH after installation:

# NAT mode
ssh -p 2222 user@localhost

# Bridge mode (use VM's actual IP)
ssh user@<vm-ip-address>

�️ VM State Management

openbsd-up automatically tracks VM state using a SQLite database stored in ~/.openbsd-up/state.sqlite. Each VM gets:

  • Unique ID: Auto-generated CUID for reliable identification
  • Random Name: Human-readable names (e.g., ancient-butterfly) for easy reference
  • Persistent Config: CPU, memory, disk, and network settings preserved
  • Status Tracking: RUNNING/STOPPED status with process ID tracking
  • MAC Address: Consistent network identity across restarts

The state database allows you to:

  • Resume VMs exactly as configured
  • List all VMs with their current status
  • Start/stop VMs by name or ID
  • Inspect detailed VM configurations

πŸ’‘ Tips

  • 🐏 Allocate at least 2GB RAM for smooth installation
  • πŸ’Ώ ISOs are cached - re-running with same version skips download
  • πŸ“€ Disk images are auto-created if --image path doesn’t exist
  • πŸ”’ Tool detects non-empty disk images and skips ISO mounting to prevent data loss
  • 🏷️ Use VM names for easy management: openbsd-up start my-web-server
  • πŸŒ‰ Bridge networking requires sudo but provides direct network access
  • πŸ“Š Use openbsd-up ps --all to see both running and stopped VMs
  • πŸ”„ Use --detach mode to run VMs in the background
  • πŸ”— Configure custom port forwarding with --port-forward host:guest
  • πŸ“ Monitor VM activity with openbsd-up logs <name> --follow
  • πŸ—‘οΈ Clean up unused VMs with openbsd-up rm <name>

Creating Persistent VMs

# Create a VM with persistent storage
openbsd-up 7.8 --image my-server.qcow2 --disk-format qcow2 --size 40G

# Run a VM in the background
openbsd-up 7.8 --detach --image background-vm.img

# Set up a web server VM with port forwarding
openbsd-up 7.8 --image webserver.qcow2 --port-forward 8080:80,8443:443

# Later, restart the same VM (no ISO needed for installed systems)
openbsd-up start <vm-name>

# Monitor the VM logs
openbsd-up logs <vm-name> --follow

πŸ”§ Architecture

Built with modern TypeScript and Deno, featuring:

  • CLI Framework: Cliffy for robust command-line interface
  • Database: SQLite with Kysely query builder for type-safe operations
  • State Management: Persistent VM state tracking with migrations
  • Dependencies: Minimal runtime dependencies, leveraging Deno’s built-in capabilities
  • Unique IDs: CUID2 for collision-resistant VM identifiers
  • Human Names: Moniker for memorable VM names

πŸ“„ License

See LICENSE file for details. Licensed under Mozilla Public License v2.0.

🀝 Contributing

Issues and pull requests welcome!

Made with 🐑 for OpenBSD enthusiasts