NetBSD-UP 🚀#

A simple command-line tool to start NetBSD virtual machines using QEMU with sensible defaults.

✨ Features#

• 🖥️ Easy NetBSD VM setup: Launch NetBSD virtual machines with a single command
• 📥 Automatic ISO download: Downloads NetBSD ISO images from official CDN
• 🏷️ Version-aware: Specify NetBSD versions and automatically construct download URLs
• 🔄 Flexible input: Support for local ISO files, URLs, version numbers, or OCI registry images
• ⚙️ Configurable VM settings: Customize CPU, memory, cores, and disk options via CLI or configuration file
• ⚡ KVM acceleration: Automatically enables hardware virtualization for better performance
• 🌐 Port forwarding: Customizable port forwarding rules for network access
• 💻 Serial console: No GUI required - works entirely in terminal
• 🔧 VM Management: Start, stop, restart, inspect, remove, and list virtual machines
• 📊 VM Logging: Centralized logging with follow support for real-time monitoring
• 🔄 Background execution: Run VMs in detached mode for long-running tasks
• 💾 Persistent storage: SQLite database to track VM states and configurations
• 🏷️ Auto-naming: Automatic generation of unique VM names
• 🌉 Bridge networking: Support for custom network bridges
• 📦 OCI Registry Support: Pull, push, and tag VM images to/from OCI-compliant registries (GitHub Container Registry, Docker Hub, etc.)
• 🖼️ Image Management: List and remove local VM images
• 📝 Configuration File: Initialize and use vmconfig.toml for persistent VM settings
• 💽 Volume Management: Create, list, inspect, and remove persistent volumes
• 🔌 Volume Attachment: Attach persistent volumes to VMs for data storage
• 🌐 HTTP API: RESTful API for managing machines, images, and volumes programmatically

📋 Requirements#

• 🦕 Deno runtime
• 🖥️ QEMU with KVM support
• 📥 curl for downloading ISO images

🚚 Installation#

# Clone the repository
git clone https://github.com/tsirysndr/netbsd-up.git
cd netbsd-up

# Make it executable
chmod +x main.ts

Run the following command to install the CLI:

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

🎯 Usage#

⭐ Basic Usage#

Start a NetBSD 10.1 VM with default settings:

netbsd-up

🏷️ Specify NetBSD Version#

netbsd-up 10.1
netbsd-up 9.3

📁 Use Local ISO File#

netbsd-up /path/to/netbsd.iso

🌐 Download from Custom URL#

netbsd-up https://cdn.netbsd.org/pub/NetBSD/images/10.1/NetBSD-10.1-amd64.iso

� Pull from OCI Registry#

# Pull from GitHub Container Registry
netbsd-up ghcr.io/tsirysndr/netbsd:10.1

# Pull from Docker Hub
netbsd-up docker.io/username/netbsd:10.1

📋 Initialize Configuration File#

Create a vmconfig.toml file with default settings:

netbsd-up init

Then customize the file and start the VM:

netbsd-up

�🔧 VM Management Commands#

List all running VMs:

netbsd-up ps

List all VMs (including stopped):

netbsd-up ps --all

Start a stopped VM:

netbsd-up start <vm-name>

Start a VM in the background (detached):

netbsd-up start <vm-name> --detach

Stop a running VM:

netbsd-up stop <vm-name>

Restart a VM:

netbsd-up restart <vm-name>

Remove a VM:

netbsd-up rm <vm-name>

View VM logs:

netbsd-up logs <vm-name>

Follow VM logs in real-time:

netbsd-up logs <vm-name> --follow

Inspect VM details:

netbsd-up inspect <vm-name>

📦 OCI Registry Management#

Login to a registry:

netbsd-up login ghcr.io -u username
# Or with Docker Hub
netbsd-up login docker.io -u username

Pull a VM image:

netbsd-up pull ghcr.io/tsirysndr/netbsd:10.1

Push a VM image:

netbsd-up push ghcr.io/username/netbsd:10.1

Tag a VM:

netbsd-up tag my-vm ghcr.io/username/netbsd:custom

Run a VM from an image:

netbsd-up run ghcr.io/tsirysndr/netbsd:10.1 --detach

List local images:

netbsd-up images

Remove a local image:

netbsd-up rmi ghcr.io/tsirysndr/netbsd:10.1

Logout from a registry:

netbsd-up logout ghcr.io

🖥️ Console Setup#

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

1. 🔧 Select option 3. Drop to boot prompt

2. ⚙️ Configure console output:

   consdev com0
   boot
   

This enables proper console redirection to your terminal.

⚙️ Advanced Configuration#

# Custom CPU, memory, and cores
netbsd-up --cpu host --memory 4G --cpus 4

# Save downloaded ISO to specific location
netbsd-up --output netbsd-10.1.iso

# Use existing disk image
netbsd-up --image vm-disk.img --disk-format qcow2

# Run VM in the background
netbsd-up --detach

# Custom port forwarding (SSH on port 2222, HTTP on port 8080)
netbsd-up --port-forward "2222:22,8080:80"

# Attach a volume to the VM
netbsd-up start my-vm --volume my-data-volume

# Combine multiple options
netbsd-up --memory 8G --cpus 4 --detach --port-forward "3000:3000"

🛠️ Command Line Options#

🔧 VM Management Commands#

📚 Examples#

⭐ Default NetBSD VM#

netbsd-up

Starts NetBSD 10.1 with 2 CPU cores and 2GB RAM.

🚀 High-Performance Setup#

netbsd-up --cpus 8 --memory 8G --cpu host --detach

🌐 Custom Port Forwarding#

# SSH on port 2222, web server on port 8080
netbsd-up --port-forward "2222:22,8080:80"

# Development setup with multiple ports
netbsd-up --port-forward "3000:3000,5432:5432" --detach

💾 Development Environment with Persistent Disk#

# Create a disk image first
qemu-img create -f qcow2 netbsd-dev.qcow2 20G

# Start VM with the disk
./main.ts --image netbsd-dev.qcow2 --disk-format qcow2

🔢 Specific versions#

netbsd-up 10.1
netbsd-up 9.4

� OCI Registry Examples#

# Pull and start a VM from GitHub Container Registry
netbsd-up ghcr.io/tsirysndr/netbsd:10.1

# Login to GitHub Container Registry
netbsd-up login ghcr.io -u username

# Tag an existing VM
netbsd-up tag my-vm ghcr.io/username/netbsd:custom

# Push the tagged VM to registry
netbsd-up push ghcr.io/username/netbsd:custom

# Run a VM from an image with custom settings
netbsd-up run ghcr.io/tsirysndr/netbsd:10.1 --memory 4G --cpus 4 --detach

📝 Configuration File Example#

# Initialize a VM configuration file
netbsd-up init

# Edit vmconfig.toml to customize settings
# Then start the VM using the config
netbsd-up

Example vmconfig.toml:

[vm]
iso = "https://cdn.netbsd.org/pub/NetBSD/images/10.1/NetBSD-10.1-amd64.iso"
cpu = "host"
cpus = 4
memory = "4G"

[network]
port_forward = "2222:22,8080:80"

[options]
detach = true

�🔄 Background Operations#

# Start VM in background
netbsd-up --detach

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

# Monitor VM logs
netbsd-up logs my-vm --follow

🔧 VM Management Examples#

# List all running VMs
netbsd-up ps

# List all VMs including stopped ones
netbsd-up ps --all

# Start a specific VM by name
netbsd-up start my-netbsd-vm

# Start a VM in the background
netbsd-up start my-netbsd-vm --detach

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

# Restart a VM
netbsd-up restart my-netbsd-vm

# Get detailed information about a VM
netbsd-up inspect my-netbsd-vm

# Remove a VM from the database
netbsd-up rm my-netbsd-vm

# View VM logs
netbsd-up logs my-netbsd-vm

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

🖼️ Image Management Examples#

# List all local VM images
netbsd-up images

# Remove a local VM image
netbsd-up rmi ghcr.io/tsirysndr/netbsd:10.1

# Pull a VM image from registry
netbsd-up pull ghcr.io/tsirysndr/netbsd:10.1

# Tag a VM for pushing to registry
netbsd-up tag my-vm ghcr.io/username/netbsd:custom

# Push a VM image to registry
netbsd-up push ghcr.io/username/netbsd:custom

# Logout from registry
netbsd-up logout ghcr.io

💽 Volume Management Examples#

# List all volumes
netbsd-up volumes

# Start a VM with a volume attached
netbsd-up start my-vm --volume my-data-volume

# Run a VM from an image with a volume
netbsd-up run ghcr.io/tsirysndr/netbsd:10.1 --volume db-storage

# Inspect a volume
netbsd-up volume inspect my-data-volume

# Remove a volume
netbsd-up volume rm my-data-volume

🌐 HTTP API Examples#

# Start the API server
netbsd-up serve

# Start on custom port
netbsd-up serve --port 9000

# List all machines via API
curl -H "Authorization: Bearer your-token" http://localhost:8892/machines

# Start a machine via API
curl -X POST -H "Authorization: Bearer your-token" \
  http://localhost:8892/machines/my-vm/start

# List all volumes via API
curl -H "Authorization: Bearer your-token" http://localhost:8892/volumes

🌐 Networking#

The VM supports flexible networking configurations:

🔌 Default Networking#

• 🌐 QEMU's user-mode networking (no special privileges required)
• 🔑 No default port forwarding (use --port-forward for specific needs)

🔧 Custom Port Forwarding#

Use the --port-forward option to map host ports to guest ports:

# SSH access on port 2222
netbsd-up --port-forward "2222:22"

# Multiple port mappings
netbsd-up --port-forward "2222:22,8080:80,3000:3000"

🌉 Bridge Networking#

For advanced networking, use bridge mode (requires sudo):

netbsd-up --bridge br0

📋 Version Format#

NetBSD-UP recognizes version strings in the format:

• 🔢 MAJOR.MINOR (e.g., 10.1, 9.3)

⚡ The tool automatically constructs the download URL for the official NetBSD release ISO.

⚙️ Default Settings#

• 🏷️ NetBSD Version: 10.1
• 🖥️ CPU: host (uses host CPU features)
• 💾 Memory: 2GB
• ⚡ CPU Cores: 2
• 💿 Disk Format: raw
• 💾 Disk Size: 20GB (when creating new disk images)
• 🌐 Network: User-mode with SSH forwarding
• 🏷️ VM Names: Auto-generated unique names using random words

💾 Data Storage#

NetBSD-UP uses a SQLite database (~/.netbsd-up/state.sqlite) to track virtual machine states, configurations, and volumes. The database stores:

• VM names and unique identifiers
• CPU, memory, and disk configurations
• Network settings (bridge, MAC addresses, port forwarding)
• Current status (RUNNING, STOPPED) with timestamps
• Creation and update timestamps
• Process IDs for running VMs
• Log file locations for each VM
• Volume information and attachments

📊 VM Logging#

All VM output is automatically logged to ~/.netbsd-up/logs/<vm-name>.log. You can:

• View logs: netbsd-up logs <vm-name>
• Follow logs in real-time: netbsd-up logs <vm-name> --follow
• Access logs directly from the filesystem

� OCI Registry Support#

NetBSD-UP supports pulling and pushing VM images to OCI-compliant registries such as GitHub Container Registry (ghcr.io), Docker Hub (docker.io), and others. This enables sharing and distributing pre-configured NetBSD VMs.

🔐 Authentication#

# Login to GitHub Container Registry
netbsd-up login ghcr.io -u username

# Login to Docker Hub
netbsd-up login docker.io -u username

# Logout from a registry
netbsd-up logout ghcr.io

📥 Pulling Images#

# Pull from GitHub Container Registry
netbsd-up pull ghcr.io/tsirysndr/netbsd:10.1

# Start a VM directly from registry
netbsd-up ghcr.io/tsirysndr/netbsd:10.1

# Run a VM from an image with custom settings
netbsd-up run ghcr.io/tsirysndr/netbsd:10.1 --memory 4G --cpus 4

📤 Pushing Images#

# Tag an existing VM
netbsd-up tag my-vm ghcr.io/username/netbsd:custom

# Push the tagged VM to registry
netbsd-up push ghcr.io/username/netbsd:custom

🖼️ Image Management#

# List local images
netbsd-up images

# Remove a local image
netbsd-up rmi ghcr.io/tsirysndr/netbsd:10.1

📝 VM Configuration File#

NetBSD-UP supports using a vmconfig.toml file for persistent VM configuration. This is useful for reproducible VM setups.

Creating a Configuration File#

netbsd-up init

This creates a vmconfig.toml file with default settings:

[vm]
iso = "https://cdn.netbsd.org/pub/NetBSD/images/10.1/NetBSD-10.1-amd64.iso"
cpu = "host"
cpus = 2
memory = "2G"

[network]

[options]

Using the Configuration File#

Simply run netbsd-up in the directory containing vmconfig.toml:

netbsd-up

CLI options will override configuration file settings.

💽 Volume Management#

NetBSD-UP supports persistent volumes that can be attached to VMs for data storage. Volumes are stored as disk images in ~/.netbsd-up/volumes/ and persist independently of VM lifecycles.

Creating and Using Volumes#

Volumes are automatically created when you attach them to a VM:

# Start a VM with a volume (volume is created if it doesn't exist)
netbsd-up start my-vm --volume my-data-volume

# Run a new VM from an image with an attached volume
netbsd-up run ghcr.io/tsirysndr/netbsd:10.1 --volume db-storage

Managing Volumes#

# List all volumes
netbsd-up volumes

# Inspect a volume
netbsd-up volume inspect my-data-volume

# Remove a volume
netbsd-up volume rm my-data-volume

Volume Features#

• 📦 Persistent Storage: Volumes persist independently of VMs
• 🔄 Reusable: Attach the same volume to different VMs
• 💾 Automatic Creation: Volumes are created on first use
• 📊 Tracking: All volumes are tracked in the SQLite database

🌐 HTTP API#

NetBSD-UP includes a RESTful HTTP API for programmatic management of machines, images, and volumes. The API is protected by bearer token authentication.

Starting the API Server#

# Start on default port (8892)
netbsd-up serve

# Start on custom port
netbsd-up serve --port 9000

# Set API token via environment variable
export NETBSD_UP_API_TOKEN="your-secure-token"
netbsd-up serve

If no NETBSD_UP_API_TOKEN is set, a random token will be generated and displayed.

API Endpoints#

The API provides the following endpoints:

Machines#

• GET /machines - List all machines
• GET /machines/:id - Get machine details
• POST /machines - Create a new machine
• POST /machines/:id/start - Start a machine
• POST /machines/:id/stop - Stop a machine
• POST /machines/:id/restart - Restart a machine
• DELETE /machines/:id - Remove a machine

Images#

• GET /images - List all images
• GET /images/:name - Get image details
• POST /images/pull - Pull an image from registry
• POST /images/push - Push an image to registry
• DELETE /images/:name - Remove an image

Volumes#

• GET /volumes - List all volumes
• GET /volumes/:name - Get volume details
• POST /volumes - Create a volume
• DELETE /volumes/:name - Remove a volume

API Authentication#

All API endpoints require bearer token authentication:

# Example API request
curl -H "Authorization: Bearer your-token" http://localhost:8892/machines

Environment Variables#

• NETBSD_UP_API_TOKEN - Set the API authentication token
• NETBSD_UP_PORT - Set the default API server port

📄 License#

See LICENSE file for details.

Contributing 🤝#

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