{"id":32405069,"url":"https://github.com/pallotron/pvmlab","last_synced_at":"2026-04-11T20:09:17.814Z","repository":{"id":319352172,"uuid":"1069810395","full_name":"pallotron/pvmlab","owner":"pallotron","description":"This project provides a command-line tool, pvmlab, to automate the setup of a simple virtual provisioning lab.","archived":false,"fork":false,"pushed_at":"2025-11-26T23:13:49.000Z","size":39483,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-29T17:59:49.755Z","etag":null,"topics":["apple","infrastructure","macos","provisioning","pxeboot","virtual-machine","virtuali"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pallotron.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-04T17:03:58.000Z","updated_at":"2025-11-26T23:13:53.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/pallotron/pvmlab","commit_stats":null,"previous_names":["pallotron/pvmlab"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/pallotron/pvmlab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pallotron%2Fpvmlab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pallotron%2Fpvmlab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pallotron%2Fpvmlab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pallotron%2Fpvmlab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pallotron","download_url":"https://codeload.github.com/pallotron/pvmlab/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pallotron%2Fpvmlab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31693303,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-11T13:07:20.380Z","status":"ssl_error","status_checked_at":"2026-04-11T13:06:47.903Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["apple","infrastructure","macos","provisioning","pxeboot","virtual-machine","virtuali"],"created_at":"2025-10-25T11:55:44.994Z","updated_at":"2026-04-11T20:09:17.809Z","avatar_url":"https://github.com/pallotron.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"images/pvmlab_logo.png\" alt=\"pvmlab logo\" width=\"500\"/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/pallotron/pvmlab/actions/workflows/go-test.yml\"\u003e\u003cimg src=\"https://github.com/pallotron/pvmlab/actions/workflows/go-test.yml/badge.svg\" alt=\"Go Test Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/pallotron/pvmlab/actions/workflows/integration-test.yml\"\u003e\u003cimg src=\"https://github.com/pallotron/pvmlab/actions/workflows/integration-test.yml/badge.svg\" alt=\"Integration Test Status\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://codecov.io/gh/pallotron/pvmlab\"\u003e\u003cimg src=\"https://codecov.io/gh/pallotron/pvmlab/graph/badge.svg\" alt=\"Codecov\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n# pvmlab: your local pxeboot virtual lab\n\nThis project provides a command-line tool, `pvmlab`, to automate the setup of a simple virtual provisioning lab on macOS. It uses `QEMU`, `socket_vmnet`, `cloud-init`, and `Docker` to create and manage an environment where multiple \"target\" VMs are deployed in a private virtual network and one VM functions as the \"provisioner\" VM offering pxeboot services and working as default gw for internet access for those VMs.\n\nAll generated artifacts (VM disks, ISOs, logs, etc.) are stored neatly in `~/.pvmlab/`, keeping the project repository clean.\n\n## Use Cases\n\nThis virtual lab is ideal for a variety of network-based provisioning and testing scenarios, such as:\n\n- **Testing OS Installers:** Develop and test automated OS installation configurations like Ubuntu Autoinstall, Debian Preseed, or Red Hat Kickstart. Or test your own ;)\n- **Developing Network Boot Environments:** Experiment with and develop iPXE scripts or other network boot setups.\n- **Simulating Bare-Metal Provisioning:** Mimic the process of provisioning physical servers in a fully virtualized, local environment.\n- **Network Service Testing:** Safely test DHCP, TFTP, and HTTP services in an isolated network.\n- **Playing with Kubernetes or Other Orchestration Tools:** Use the lab to experiment with cluster provisioning and management tools like kubernetes, Tinkerbell, Canonical MAAS, etc.\n- **Learning and Experimentation:** Provide a hands-on environment for learning about PXE boot, network automation, and cloud-init.\n\n## Core Concepts\n\n### Features\n\n- **Automated VM Creation:** Quickly create Ubuntu VMs from cloud images.\n- **Provisioner/Target Architecture:** Set up a dedicated \"provisioner\" VM to serve network resources (DHCP, PXE boot) to multiple \"target\" VMs.\n- **Private Networking:** Uses `socket_vmnet` to create an isolated virtual network for your lab environment.\n- **Dual-stack Networking:** Configure VMs with both IPv4 and IPv6 addresses on the private network.\n- **Direct SSH Access:** Connect directly to any VM (`provisioner` or `target`) with a single command.\n- **Simple CLI:** Manage the entire lab lifecycle with intuitive `pvmlab` commands.\n\n### Architecture\n\nFor a detailed explanation of the project's architecture, features, and VM roles, please see the [Architecture documentation](docs/architecture.md).\n\n## Getting Started\n\n### Installation\n\nTo install `pvmlab` on macOS, the recommended method is using Homebrew:\n\n1.  **Install with Homebrew:**\n\n    ```bash\n    brew tap pallotron/pvmlab\n    brew install pvmlab\n    sudo pvmlab system setup-launchd\n    ```\n\n    This will install `pvmlab` and all its dependencies (QEMU, cdrtools, socat, socket_vmnet, go, docker).\n\n### Manual Installation (Alternative)\n\nIf you prefer to install manually, or are on a different operating system, follow these steps:\n\n1.  **Install Dependencies:**\n    You must install the following dependencies manually. On macOS, you can use Homebrew for this:\n\n    ```bash\n    brew install qemu cdrtools socat socket_vmnet docker go\n    ```\n\n    \u003e **Note:** `docker` refers to the Docker CLI, which is included with Docker Desktop for Mac.\n\n2.  **Clone the Repository:**\n\n    ```bash\n    git clone https://github.com/pallotron/pvmlab.git\n    cd pvmlab\n    ```\n\n3.  **Build and Install:**\n    This command compiles the `pvmlab` CLI, builds the pxeboot stack Docker container, and sets up shell completion.\n\n    ```bash\n    make install\n    ```\n\n4. **Set up the Lab Environment:**\n   This command creates the `~/.pvmlab/` directory structure and generates an SSH key for accessing the VMs. It may require your `sudo` password to configure `socket_vmnet`.\n\n   ```bash\n   pvmlab setup\n   ```\n\n5. **Source Shell Completions (Optional but Recommended):**\n   The `make all` command attempts to install shell completions. If it doesn't work for your shell, you may need to source them manually. Either open a new terminal or reload your shell's rc file.\n   - For Zsh: `source ~/.zshrc`\n   - For Bash: `source ~/.bashrc`\n\nAfter installation, you can run the command as `pvmlab` from any directory.\n\n## Usage: A Typical Workflow\n\nHere is a step-by-step guide to a common workflow.\n\n### Step 1: Start the Network Service\n\nThis service manages the private virtual network. You may be prompted for your password.\nThe `make install` command should have already set this up for you, but run this commands to ensure.\n\n```bash\npvmlab socket_vmnet status\n# if not running, start it:\npvmlab socket_vmnet start\n```\n\n### Step 2: Create the VMs\n\nThis command downloads cloud images, creates VM disks, and generates cloud-init configurations.\n\nFirst, create the `provisioner` VM, which will serve network resources (DHCP, PXE boot) and act as the default gateway for other VMs:\n\n```bash\npvmlab provisioner create provisioner --ip 192.168.100.1/24 --ipv6 fd00:cafe:babe::1/64\n```\n\nThen, create your `target` VMs:\n\n```bash\npvmlab vm create client1\npvmlab vm create client2 --arch x86_64 --pxeboot\n```\n\nYou can create `x86_64` or `aarch64` VMs by specifying the `--arch` flag. By default, `aarch64` is used.\nYou can also use `--disk` (default) or `--pxeboot` flags to customize how the VM should boot.\n\n### Step 3: Manage the VMs\n\nOnce created, you can start, stop, and interact with your VMs.\n\n**Start VMs:**\n\n```bash\npvmlab vm start provisioner\npvmlab vm start client1\n```\n\nThe start command accepts `--interactive` mode, which attaches your terminal to the VM's console.\nYou can provide the `--wait` flag to block the terminal until the VM has reached `cloud-init.target`.\nProviding no flags starts the VM in the background. You can monitor logs via the `pvmlab vm logs` command (see below).\n\n**List VMs:**\n\n```bash\n❯ pvmlab vm list\n┌─────────────┬─────────┬───────────┬───────────────┬───────────────────┬───────────────────┬─────────┐\n│    NAME     │  ARCH   │ BOOT TYPE │  PRIVATE IP   │   PRIVATE IPV 6   │        MAC        │ STATUS  │\n├─────────────┼─────────┼───────────┼───────────────┼───────────────────┼───────────────────┼─────────┤\n│ client1     │ x86_64  │ disk      │ 192.168.100.2 │ fd00:cafe:babe::2 │ 0a:5d:ea:18:55:b6 │ Running │\n│ provisioner │ aarch64 │ disk      │ 192.168.100.1 │ fd00:cafe:babe::1 │ 62:a8:6a:f6:5b:3c │ Running │\n└─────────────┴─────────┴───────────┴───────────────┴───────────────────┴───────────────────┴─────────┘\n```\n\n**Access a VM's Shell:**\n\n```bash\n# Access the Provisioner VM\npvmlab vm shell provisioner\n\n# Access a Target VM\npvmlab vm shell client1\n```\n\n**Monitor Logs:**\n\n```bash\npvmlab vm logs provisioner\npvmlab vm logs client1\n```\n\n**Stop VMs:**\n\n```bash\npvmlab vm stop provisioner\npvmlab vm stop client1\n```\n\n### Step 4: Clean Up\n\nYou can clean up individual VMs or the entire lab environment.\n\n**Clean a single VM:**\nThis stops the VM and removes all its associated files from `~/.pvmlab/`.\n\n```bash\npvmlab vm clean provisioner\n```\n\n**Clean the entire lab:**\nThis removes everything, including the `socket_vmnet` service and the `~/.pvmlab/` directory.\n\n```bash\npvmlab clean\n```\n\n## Artifacts Directory\n\nAll files generated by `pvmlab` are stored in a hidden directory in your home folder to keep the project's working directory clean.\n\nThe structure of this directory is as follows:\n\n```shell\n~/.pvmlab/\n├── configs/        # Generated cloud-init ISO files (.iso) for each VM\n├── docker_images/  # Docker images saved as .tar files to be shared with the provisioner VM\n├── images/         # Downloaded cloud image templates, pxeboot assets, and rootfs images for pxeboot\n├── logs/           # VM console logs\n├── monitors/       # QEMU monitor sockets for interacting with the hypervisor\n├── pids/           # Process ID files for running VMs\n├── ssh/            # Generated SSH key pair (vm_rsa, vm_rsa.pub) for VM access\n└── vms/            # VM disk images (.qcow2) created from the base images\n```\n\n## Missing Features\n\nMissing features are being tracked as issues in the [GitHub repository](https://github.com/pallotron/pvmlab/issues). Please feel free to contribute!\n\n## Advanced Topics \u0026 Further Reading\n\nFor more detailed information, please refer to the documentation in the `docs/` directory:\n\n- **[CLI Command Reference](docs/cli_reference.md):** A full list of all commands and their flags.\n- **[Architecture](docs/architecture.md):** A detailed explanation of the project's design and components.\n- **[Interacting with the pxeboot Container](docs/pxeboot_container.md):** How to manage the pxeboot Docker container inside the provisioner VM.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpallotron%2Fpvmlab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpallotron%2Fpvmlab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpallotron%2Fpvmlab/lists"}