tsiry-sandratraina.com / netbsd-up
A simple command-line tool to start NetBSD virtual machines using QEMU with sensible defaults.
fork atom

feat: add volume management and HTTP API documentation to README

tsiry-sandratraina.com b582711b ee6329d3

+191 -30
unified split
+191 -30
README.md
··· 17 17 - ๐Ÿ“ฅ **Automatic ISO download**: Downloads NetBSD ISO images from official CDN 18 18 - ๐Ÿท๏ธ **Version-aware**: Specify NetBSD versions and automatically construct 19 19 download URLs 20 - - ๐Ÿ”„ **Flexible input**: Support for local ISO files, URLs, version numbers, or OCI registry images 20 + - ๐Ÿ”„ **Flexible input**: Support for local ISO files, URLs, version numbers, or 21 + OCI registry images 21 22 - โš™๏ธ **Configurable VM settings**: Customize CPU, memory, cores, and disk 22 23 options via CLI or configuration file 23 24 - โšก **KVM acceleration**: Automatically enables hardware virtualization for ··· 33 34 configurations 34 35 - ๐Ÿท๏ธ **Auto-naming**: Automatic generation of unique VM names 35 36 - ๐ŸŒ‰ **Bridge networking**: Support for custom network bridges 36 - - ๐Ÿ“ฆ **OCI Registry Support**: Pull, push, and tag VM images to/from OCI-compliant registries (GitHub Container Registry, Docker Hub, etc.) 37 + - ๐Ÿ“ฆ **OCI Registry Support**: Pull, push, and tag VM images to/from 38 + OCI-compliant registries (GitHub Container Registry, Docker Hub, etc.) 37 39 - ๐Ÿ–ผ๏ธ **Image Management**: List and remove local VM images 38 - - ๐Ÿ“ **Configuration File**: Initialize and use `vmconfig.toml` for persistent VM settings 40 + - ๐Ÿ“ **Configuration File**: Initialize and use `vmconfig.toml` for persistent 41 + VM settings 42 + - ๐Ÿ’ฝ **Volume Management**: Create, list, inspect, and remove persistent volumes 43 + - ๐Ÿ”Œ **Volume Attachment**: Attach persistent volumes to VMs for data storage 44 + - ๐ŸŒ **HTTP API**: RESTful API for managing machines, images, and volumes 45 + programmatically 39 46 40 47 ## ๐Ÿ“‹ Requirements 41 48 ··· 260 267 # Custom port forwarding (SSH on port 2222, HTTP on port 8080) 261 268 netbsd-up --port-forward "2222:22,8080:80" 262 269 270 + # Attach a volume to the VM 271 + netbsd-up start my-vm --volume my-data-volume 272 + 263 273 # Combine multiple options 264 274 netbsd-up --memory 8G --cpus 4 --detach --port-forward "3000:3000" 265 275 ``` ··· 279 289 | `--detach` | `-d` | Run VM in the background and print VM name | `false` | 280 290 | `--port-forward` | `-p` | Port forwarding rules (format: hostPort:guestPort) | None | 281 291 | `--install` | | Persist changes to the VM disk image | `false` | 292 + | `--volume` | `-v` | Name of the volume to attach to the VM | None | 282 293 283 294 ## ๐Ÿ”ง VM Management Commands 284 295 285 - | Command | Description | 286 - | -------------------------------- | ------------------------------------------------------- | 287 - | `netbsd-up init` | Initialize a default VM configuration file | 288 - | `netbsd-up ps` | List all running virtual machines | 289 - | `netbsd-up ps --all` | List all virtual machines (including stopped) | 290 - | `netbsd-up start <name>` | Start a stopped virtual machine | 291 - | `netbsd-up start <name> -d` | Start a virtual machine in background (detached) | 292 - | `netbsd-up stop <name>` | Stop a running virtual machine | 293 - | `netbsd-up restart <name>` | Restart a virtual machine | 294 - | `netbsd-up inspect <name>` | Show detailed information about a VM | 295 - | `netbsd-up rm <name>` | Remove a virtual machine from database | 296 - | `netbsd-up logs <name>` | View logs for a virtual machine | 297 - | `netbsd-up logs <name> -f` | Follow logs in real-time | 298 - | `netbsd-up pull <image>` | Pull VM image from OCI registry | 299 - | `netbsd-up push <image>` | Push VM image to OCI registry | 300 - | `netbsd-up tag <vm-name> <image>`| Tag a VM with an image name | 301 - | `netbsd-up run <image>` | Create and run a VM from an image | 302 - | `netbsd-up images` | List all local VM images | 303 - | `netbsd-up rmi <image>` | Remove a local VM image | 304 - | `netbsd-up login <registry>` | Authenticate to an OCI registry | 305 - | `netbsd-up logout <registry>` | Logout from an OCI registry | 296 + | Command | Description | 297 + | --------------------------------- | ------------------------------------------------ | 298 + | `netbsd-up init` | Initialize a default VM configuration file | 299 + | `netbsd-up ps` | List all running virtual machines | 300 + | `netbsd-up ps --all` | List all virtual machines (including stopped) | 301 + | `netbsd-up start <name>` | Start a stopped virtual machine | 302 + | `netbsd-up start <name> -d` | Start a virtual machine in background (detached) | 303 + | `netbsd-up start <name> -v <vol>` | Start a VM and attach a volume | 304 + | `netbsd-up stop <name>` | Stop a running virtual machine | 305 + | `netbsd-up restart <name>` | Restart a virtual machine | 306 + | `netbsd-up inspect <name>` | Show detailed information about a VM | 307 + | `netbsd-up rm <name>` | Remove a virtual machine from database | 308 + | `netbsd-up logs <name>` | View logs for a virtual machine | 309 + | `netbsd-up logs <name> -f` | Follow logs in real-time | 310 + | `netbsd-up pull <image>` | Pull VM image from OCI registry | 311 + | `netbsd-up push <image>` | Push VM image to OCI registry | 312 + | `netbsd-up tag <vm-name> <image>` | Tag a VM with an image name | 313 + | `netbsd-up run <image>` | Create and run a VM from an image | 314 + | `netbsd-up run <image> -v <vol>` | Run a VM from an image with an attached volume | 315 + | `netbsd-up images` | List all local VM images | 316 + | `netbsd-up rmi <image>` | Remove a local VM image | 317 + | `netbsd-up login <registry>` | Authenticate to an OCI registry | 318 + | `netbsd-up logout <registry>` | Logout from an OCI registry | 319 + | `netbsd-up volumes` | List all volumes | 320 + | `netbsd-up volume rm <name>` | Remove a volume | 321 + | `netbsd-up volume inspect <name>` | Inspect a volume | 322 + | `netbsd-up serve` | Start the HTTP API server | 323 + | `netbsd-up serve -p <port>` | Start the HTTP API server on a specific port | 306 324 307 325 ## ๐Ÿ“š Examples 308 326 ··· 462 480 netbsd-up logout ghcr.io 463 481 ``` 464 482 483 + ### ๐Ÿ’ฝ Volume Management Examples 484 + 485 + ```bash 486 + # List all volumes 487 + netbsd-up volumes 488 + 489 + # Start a VM with a volume attached 490 + netbsd-up start my-vm --volume my-data-volume 491 + 492 + # Run a VM from an image with a volume 493 + netbsd-up run ghcr.io/tsirysndr/netbsd:10.1 --volume db-storage 494 + 495 + # Inspect a volume 496 + netbsd-up volume inspect my-data-volume 497 + 498 + # Remove a volume 499 + netbsd-up volume rm my-data-volume 500 + ``` 501 + 502 + ### ๐ŸŒ HTTP API Examples 503 + 504 + ```bash 505 + # Start the API server 506 + netbsd-up serve 507 + 508 + # Start on custom port 509 + netbsd-up serve --port 9000 510 + 511 + # List all machines via API 512 + curl -H "Authorization: Bearer your-token" http://localhost:8892/machines 513 + 514 + # Start a machine via API 515 + curl -X POST -H "Authorization: Bearer your-token" \ 516 + http://localhost:8892/machines/my-vm/start 517 + 518 + # List all volumes via API 519 + curl -H "Authorization: Bearer your-token" http://localhost:8892/volumes 520 + ``` 521 + 465 522 ## ๐ŸŒ Networking 466 523 467 524 The VM supports flexible networking configurations: ··· 514 571 ## ๐Ÿ’พ Data Storage 515 572 516 573 NetBSD-UP uses a SQLite database (`~/.netbsd-up/state.sqlite`) to track virtual 517 - machine states and configurations. The database stores: 574 + machine states, configurations, and volumes. The database stores: 518 575 519 576 - VM names and unique identifiers 520 577 - CPU, memory, and disk configurations ··· 523 580 - Creation and update timestamps 524 581 - Process IDs for running VMs 525 582 - Log file locations for each VM 583 + - Volume information and attachments 526 584 527 585 ### ๐Ÿ“Š VM Logging 528 586 ··· 536 594 ## ๏ฟฝ OCI Registry Support 537 595 538 596 NetBSD-UP supports pulling and pushing VM images to OCI-compliant registries 539 - such as GitHub Container Registry (ghcr.io), Docker Hub (docker.io), and 540 - others. This enables sharing and distributing pre-configured NetBSD VMs. 597 + such as GitHub Container Registry (ghcr.io), Docker Hub (docker.io), and others. 598 + This enables sharing and distributing pre-configured NetBSD VMs. 541 599 542 600 ### ๐Ÿ” Authentication 543 601 ··· 587 645 588 646 ## ๐Ÿ“ VM Configuration File 589 647 590 - NetBSD-UP supports using a `vmconfig.toml` file for persistent VM 591 - configuration. This is useful for reproducible VM setups. 648 + NetBSD-UP supports using a `vmconfig.toml` file for persistent VM configuration. 649 + This is useful for reproducible VM setups. 592 650 593 651 ### Creating a Configuration File 594 652 ··· 620 678 621 679 CLI options will override configuration file settings. 622 680 623 - ## ๏ฟฝ๐Ÿ“„ License 681 + ## ๐Ÿ’ฝ Volume Management 682 + 683 + NetBSD-UP supports persistent volumes that can be attached to VMs for data 684 + storage. Volumes are stored as disk images in `~/.netbsd-up/volumes/` and 685 + persist independently of VM lifecycles. 686 + 687 + ### Creating and Using Volumes 688 + 689 + Volumes are automatically created when you attach them to a VM: 690 + 691 + ```bash 692 + # Start a VM with a volume (volume is created if it doesn't exist) 693 + netbsd-up start my-vm --volume my-data-volume 694 + 695 + # Run a new VM from an image with an attached volume 696 + netbsd-up run ghcr.io/tsirysndr/netbsd:10.1 --volume db-storage 697 + ``` 698 + 699 + ### Managing Volumes 700 + 701 + ```bash 702 + # List all volumes 703 + netbsd-up volumes 704 + 705 + # Inspect a volume 706 + netbsd-up volume inspect my-data-volume 707 + 708 + # Remove a volume 709 + netbsd-up volume rm my-data-volume 710 + ``` 711 + 712 + ### Volume Features 713 + 714 + - ๐Ÿ“ฆ **Persistent Storage**: Volumes persist independently of VMs 715 + - ๐Ÿ”„ **Reusable**: Attach the same volume to different VMs 716 + - ๐Ÿ’พ **Automatic Creation**: Volumes are created on first use 717 + - ๐Ÿ“Š **Tracking**: All volumes are tracked in the SQLite database 718 + 719 + ## ๐ŸŒ HTTP API 720 + 721 + NetBSD-UP includes a RESTful HTTP API for programmatic management of machines, 722 + images, and volumes. The API is protected by bearer token authentication. 723 + 724 + ### Starting the API Server 725 + 726 + ```bash 727 + # Start on default port (8892) 728 + netbsd-up serve 729 + 730 + # Start on custom port 731 + netbsd-up serve --port 9000 732 + 733 + # Set API token via environment variable 734 + export NETBSD_UP_API_TOKEN="your-secure-token" 735 + netbsd-up serve 736 + ``` 737 + 738 + If no `NETBSD_UP_API_TOKEN` is set, a random token will be generated and 739 + displayed. 740 + 741 + ### API Endpoints 742 + 743 + The API provides the following endpoints: 744 + 745 + #### Machines 746 + 747 + - `GET /machines` - List all machines 748 + - `GET /machines/:id` - Get machine details 749 + - `POST /machines` - Create a new machine 750 + - `POST /machines/:id/start` - Start a machine 751 + - `POST /machines/:id/stop` - Stop a machine 752 + - `POST /machines/:id/restart` - Restart a machine 753 + - `DELETE /machines/:id` - Remove a machine 754 + 755 + #### Images 756 + 757 + - `GET /images` - List all images 758 + - `GET /images/:name` - Get image details 759 + - `POST /images/pull` - Pull an image from registry 760 + - `POST /images/push` - Push an image to registry 761 + - `DELETE /images/:name` - Remove an image 762 + 763 + #### Volumes 764 + 765 + - `GET /volumes` - List all volumes 766 + - `GET /volumes/:name` - Get volume details 767 + - `POST /volumes` - Create a volume 768 + - `DELETE /volumes/:name` - Remove a volume 769 + 770 + ### API Authentication 771 + 772 + All API endpoints require bearer token authentication: 773 + 774 + ```bash 775 + # Example API request 776 + curl -H "Authorization: Bearer your-token" http://localhost:8892/machines 777 + ``` 778 + 779 + ### Environment Variables 780 + 781 + - `NETBSD_UP_API_TOKEN` - Set the API authentication token 782 + - `NETBSD_UP_PORT` - Set the default API server port 783 + 784 + ## ๐Ÿ“„ License 624 785 625 786 See [LICENSE](LICENSE) file for details. 626 787