{"id":13575501,"url":"https://github.com/lima-vm/socket_vmnet","last_synced_at":"2025-04-12T18:50:43.283Z","repository":{"id":43663605,"uuid":"490630627","full_name":"lima-vm/socket_vmnet","owner":"lima-vm","description":"vmnet.framework support for unmodified rootless QEMU (no dependency on VDE)","archived":false,"fork":false,"pushed_at":"2025-03-10T06:11:49.000Z","size":249,"stargazers_count":125,"open_issues_count":21,"forks_count":19,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-04-03T22:07:24.205Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lima-vm.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}},"created_at":"2022-05-10T09:33:53.000Z","updated_at":"2025-03-31T22:33:17.000Z","dependencies_parsed_at":"2024-01-14T03:48:41.319Z","dependency_job_id":"097b7123-e19b-42cd-b8b5-38fd8fd0d0a3","html_url":"https://github.com/lima-vm/socket_vmnet","commit_stats":{"total_commits":64,"total_committers":11,"mean_commits":5.818181818181818,"dds":0.28125,"last_synced_commit":"8513f80c74e429f209176a79a93d347f09fe975e"},"previous_names":[],"tags_count":13,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lima-vm%2Fsocket_vmnet","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lima-vm%2Fsocket_vmnet/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lima-vm%2Fsocket_vmnet/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lima-vm%2Fsocket_vmnet/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lima-vm","download_url":"https://codeload.github.com/lima-vm/socket_vmnet/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248618222,"owners_count":21134199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2024-08-01T15:01:01.618Z","updated_at":"2025-04-12T18:50:43.259Z","avatar_url":"https://github.com/lima-vm.png","language":"C","funding_links":[],"categories":["C"],"sub_categories":[],"readme":"# socket_vmnet: vmnet.framework support for rootless and VDE-less QEMU\n\n`socket_vmnet` provides [vmnet.framework](https://developer.apple.com/documentation/vmnet) support for QEMU.\n\n`socket_vmnet` does not require QEMU to run as the root user.\n\n(But `socket_vmnet` itself has to run as the root, in most cases.)\n\n`socket_vmnet` was forked from [`vde_vmnet`](https://github.com/lima-vm/vde_vmnet) v0.6.0.\nUnlike `vde_vmnet`, `socket_vmnet` does not depend on VDE.\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n\n- [Install](#install)\n  - [From binary](#from-binary)\n  - [From source](#from-source)\n  - [From Homebrew](#from-homebrew)\n  - [From MacPorts](#from-macports)\n- [Usage](#usage)\n  - [QEMU](#qemu)\n  - [Lima](#lima)\n- [Advanced usage](#advanced-usage)\n  - [Multi VM](#multi-vm)\n  - [Bridged mode](#bridged-mode)\n- [FAQs](#faqs)\n  - [Why does `socket_vmnet` require root?](#why-does-socket_vmnet-require-root)\n  - [Is it possible to run `socket_vmnet` with SETUID?](#is-it-possible-to-run-socket_vmnet-with-setuid)\n  - [How is socket_vmnet related to vde_vmnet?](#how-is-socket_vmnet-related-to-vde_vmnet)\n  - [How is socket_vmnet related to QEMU-builtin vmnet support?](#how-is-socket_vmnet-related-to-qemu-builtin-vmnet-support)\n  - [How to use static IP addresses?](#how-to-use-static-ip-addresses)\n  - [How to reserve DHCP addresses?](#how-to-reserve-dhcp-addresses)\n  - [IP address is not assigned](#ip-address-is-not-assigned)\n- [Links](#links)\n- [Troubleshooting](#troubleshooting)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Install\n\nRequires macOS 10.15 or later.\n\n### From binary\n\n```bash\nVERSION=\"$(curl -fsSL https://api.github.com/repos/lima-vm/socket_vmnet/releases/latest | jq -r .tag_name)\"\nFILE=\"socket_vmnet-${VERSION:1}-$(uname -m).tar.gz\"\n\n# Download the binary archive\ncurl -OSL \"https://github.com/lima-vm/socket_vmnet/releases/download/${VERSION}/${FILE}\"\n\n# (Optional) Attest the GitHub Artifact Attestation using GitHub's gh command (https://cli.github.com)\ngh attestation verify --owner=lima-vm \"${FILE}\"\n\n# (Optional) Preview the contents of the binary archive\ntar tzvf \"${FILE}\"\n\n# Install /opt/socket_vmnet from the binary archive\nsudo tar Cxzvf / \"${FILE}\" opt/socket_vmnet\n```\n\nThis downloads and installs the latest release from \u003chttps://github.com/lima-vm/socket_vmnet/releases\u003e.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eLaunchd (optional, not needed for Lima)\u003c/summary\u003e\n\n\u003cp\u003e\n\nTo install the launchd service:\n\n```bash\nSERVICE_ID=io.github.lima-vm.socket_vmnet\nsudo cp \"/opt/socket_vmnet/share/doc/socket_vmnet/launchd/$SERVICE_ID.plist\" \"/Library/LaunchDaemons/$SERVICE_ID.plist\"\nsudo launchctl bootstrap system \"/Library/LaunchDaemons/$SERVICE_ID.plist\"\nsudo launchctl enable system/$SERVICE_ID\nsudo launchctl kickstart -kp system/$SERVICE_ID\n```\n\nThe launchd unit file will be installed as `/Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.plist`.\n\nDefault configuration:\n\n| Config  | Value                          |\n| ------- | ------------------------------ |\n| Socket  | `/var/run/socket_vmnet`        |\n| Stdout  | `/var/log/socket_vmnet/stdout` |\n| Stderr  | `/var/log/socket_vmnet/stderr` |\n| Gateway | 192.168.105.1                  |\n\nTo uninstall the launchd service:\n\n```bash\nSERVICE_ID=io.github.lima-vm.socket_vmnet\nsudo launchctl bootout system \"/Library/LaunchDaemons/$SERVICE_ID.plist\" || true\nsudo rm -f \"/Library/LaunchDaemons/$SERVICE_ID.plist\"\n```\n\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n### From source\n\n```bash\nsudo make install.bin\n```\n\nThis installs binaries using `PREFIX=/opt/socket_vmnet`:\n\n- `/opt/socket_vmnet/bin/socket_vmnet`\n- `/opt/socket_vmnet/bin/socket_vmnet_client`\n\nYou can customize the install location using the `PREFIX` environment variable,\nhowever, it is highly recommended to set the prefix to a directory that can be\nonly written by the root. Note that `/usr/local/bin` is sometimes chowned for a\nnon-admin user, so `/usr/local` is _not_ an appropriate prefix.\n\nRun the following command to start the daemon:\n\n```bash\nsudo /opt/socket_vmnet/bin/socket_vmnet --vmnet-gateway=192.168.105.1 /var/run/socket_vmnet\n```\n\n\u003e [!TIP]\n\u003e `sudo make install` is also available in addition to `sudo make install.bin`.\n\u003e The former one installs the launchd service (see below) too.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eLaunchd (optional, not needed for Lima)\u003c/summary\u003e\n\n\u003cp\u003e\n\nTo install the launchd service:\n\n```bash\nsudo make install.launchd\n```\n\nThe launchd unit file will be installed as `/Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.plist`.\n\nDefault configuration:\n\n| Config  | Value                          |\n| ------- | ------------------------------ |\n| Socket  | `/var/run/socket_vmnet`        |\n| Stdout  | `/var/log/socket_vmnet/stdout` |\n| Stderr  | `/var/log/socket_vmnet/stderr` |\n| Gateway | 192.168.105.1                  |\n\nTo uninstall the launchd service:\n\n```bash\nsudo make uninstall.launchd\n```\n\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n### From Homebrew\n\n\u003cdetails\u003e\n\n\u003cp\u003e\n\n```bash\nbrew install socket_vmnet\n```\n\nThe binaries will be installed onto the following paths:\n\n- `${HOMEBREW_PREFIX}/opt/socket_vmnet/bin/socket_vmnet`\n- `${HOMEBREW_PREFIX}/opt/socket_vmnet/bin/socket_vmnet_client`\n\nThe `${HOMEBREW_PREFIX}` path defaults to `/opt/homebrew` on ARM, `/usr/local` on Intel.\n\nThe `${HOMEBREW_PREFIX}/opt/socket_vmnet` directory is usually symlinked to `../Cellar/socket_vmnet/${VERSION}`.\n\nRun the following command to start the daemon:\n\n```bash\nmkdir -p ${HOMEBREW_PREFIX}/var/run\nsudo ${HOMEBREW_PREFIX}/opt/socket_vmnet/bin/socket_vmnet --vmnet-gateway=192.168.105.1 ${HOMEBREW_PREFIX}/var/run/socket_vmnet\n```\n\n\u003e [!WARNING]\n\u003e Typically, the `socket_vmnet` binary in the `${HOMEBREW_PREFIX}` can be replaced by any user in the `admin` group.\n\n\u003cdetails\u003e\n\n\u003csummary\u003eLaunchd (optional, not needed for Lima)\u003c/summary\u003e\n\n\u003cp\u003e\n\nTo install the launchd service:\n\n```bash\n# sudo is necessary for the next line\nsudo ${HOMEBREW_PREFIX}/bin/brew services start socket_vmnet\n```\n\nThe launchd unit file will be installed as `/Library/LaunchDaemons/homebrew.mxcl.socket_vmnet.plist`.\n\nDefault configuration:\n\n| Config  | Value                                            |\n| ------- | ------------------------------------------------ |\n| Socket  | `${HOMEBREW_PREFIX}/var/run/socket_vmnet`        |\n| Stdout  | `${HOMEBREW_PREFIX}/var/log/socket_vmnet/stdout` |\n| Stderr  | `${HOMEBREW_PREFIX}/var/log/socket_vmnet/stderr` |\n| Gateway | 192.168.105.1                                    |\n\nTo uninstall the launchd service:\n\n```bash\nsudo ${HOMEBREW_PREFIX}/bin/brew services stop socket_vmnet\n```\n\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n### From MacPorts\n\n\u003cdetails\u003e\n\n\u003cp\u003e\n\n```bash\nsudo port install socket_vmnet\n```\n\nThe binaries will be installed onto the following paths:\n\n- `/opt/local/bin/socket_vmnet`\n- `/opt/local/bin/socket_vmnet_client`\n\nRun the following command to start the daemon manually:\n\n```bash\nsudo /opt/local/bin/socket_vmnet --vmnet-gateway=192.168.105.1  /var/run/socket_vmnet\n```\n\n\u003cdetails\u003e\n\n\u003csummary\u003eLaunchd (optional, not needed for Lima)\u003c/summary\u003e\n\n\u003cp\u003e\n\nTo install the launchd service:\n\n```bash\nsudo port load socket_vmnet\n```\n\nThe launchd unit file will be installed as\n`/Library/LaunchDaemons/org.macports.socket_vmnet.plist`.\n\nDefault configuration:\n\n| Config  | Value                       |\n| ------- | --------------------------- |\n| Socket  | `/var/run/socket_vmnet`     |\n| Stdout  | `/var/log/socket_vmnet.log` |\n| Gateway | 192.168.105.1               |\n\nTo uninstall the launchd service:\n\n```bash\nsudo port unload socket_vmnet\n```\n\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n\u003c/p\u003e\n\n\u003c/details\u003e\n\n## Usage\n\n### QEMU\n\nMake sure that the `socket_vmnet` daemon is running, and execute QEMU via `socket_vmnet_client` as follows:\n\n```console\n${HOMEBREW_PREFIX}/opt/socket_vmnet/bin/socket_vmnet_client \\\n  ${HOMEBREW_PREFIX}/var/run/socket_vmnet \\\n  qemu-system-x86_64 \\\n  -device virtio-net-pci,netdev=net0 -netdev socket,id=net0,fd=3 \\\n  -m 4096 -accel hvf -cdrom ubuntu-22.04-desktop-amd64.iso\n```\n\nThe guest IP is assigned by the DHCP server provided by macOS.\n\nThe guest is accessible to the internet, and the guest IP is accessible from the host.\n\nTo confirm, run `sudo apt-get update \u0026\u0026 sudo apt-get install -y apache2` in the guest, and access the guest IP via Safari on the host.\n\n### Lima\n\nLima (since v0.12.0) provides built-in support for `socket_vmnet`:\n\n```console\n$ limactl sudoers | sudo tee /etc/sudoers.d/lima\n$ limactl start --name=default template://vmnet\n```\n\nSee also https://github.com/lima-vm/lima/blob/master/docs/network.md\n\n## Advanced usage\n\n### Multi VM\n\nMultiple VMs can be connected to a single `socket_vmnet` instance.\n\nMake sure to specify unique MAC addresses to VMs: `-device virtio-net-pci,netdev=net0,mac=de:ad:be:ef:00:01` .\n\nNOTE: don't confuse MAC addresses of VMs with the MAC address of `socket_vmnet` itself that is printed as `vmnet_mac_address` in the debug log.\nYou do not need to configure (and you can't, currently) the MAC address of `socket_vmnet` itself.\n\n### Bridged mode\n\nSee [`./launchd/io.github.lima-vm.socket_vmnet.bridged.en0.plist`](./launchd/io.github.lima-vm.socket_vmnet.bridged.en0.plist).\n\nInstall:\n\n```bash\nBRIDGED=en0\nsed -e \"s@/opt@${HOMEBREW_PREFIX}/opt@g; s@/var@${HOMEBREW_PREFIX}/var@g; s@en0@${BRIDGED}@g\" ./launchd/io.github.lima-vm.socket_vmnet.bridged.en0.plist \\\n  | sudo tee /Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}.plist\nsudo launchctl bootstrap system /Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}.plist\nsudo launchctl enable system/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}\nsudo launchctl kickstart -kp system/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}\n```\n\nUse `${HOMEBREW_PREFIX}/var/run/socket_vmnet.bridged.en0` as the socket.\n\nUninstall:\n\n```bash\nBRIDGED=en0\nsudo launchctl bootout system /Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}.plist\nsudo rm /Library/LaunchDaemons/io.github.lima-vm.socket_vmnet.bridged.${BRIDGED}.plist\n```\n\n## FAQs\n\n### Why does `socket_vmnet` require root?\n\nRunning `socket_vmnet` without root could be possible by signing the `socket_vmnet` binary with `com.apple.vm.networking` entitlement.\n\nHowever, signing a binary with `com.apple.vm.networking` entitlement seems to require some contract with Apple.\n:disappointed:\n\n\u003e This entitlement is restricted to developers of virtualization software. To request this entitlement, contact your Apple representative.\n\nhttps://developer.apple.com/documentation/bundleresources/entitlements/com_apple_vm_networking\n\n### Is it possible to run `socket_vmnet` with SETUID?\n\nYes, but discouraged, as it allows non-root users to write arbitrary files, by specifying certain CLI args and environment variables.\n\nInstead, consider using launchd or sudo.\n\nSee [`./etc_sudoers.d/socket_vmnet`](./etc_sudoers.d/socket_vmnet) to allow running `sudo socket_vmnet` with reduced set of args and environment variables.\n\n### How is socket_vmnet related to vde_vmnet?\n\n`socket_vmnet` was forked from [`vde_vmnet`](https://github.com/lima-vm/vde_vmnet) v0.6.0.\nUnlike `vde_vmnet`, `socket_vmnet` does not depend on VDE.\n\n### How is socket_vmnet related to QEMU-builtin vmnet support?\n\nQEMU 7.1 added [the built-in support for vmnet](https://github.com/qemu/qemu/blob/v7.1.0/qapi/net.json#L626-L631).\n\nHowever, QEMU-builtin vmnet requires running the entire QEMU process as root.\n\nOn the other hand, `socket_vmnet` does not require the entire QEMU process to run as root, though `socket_vmnet` has to run as root.\n\n### How to use static IP addresses?\n\nWhen `--vmnet-gateway=IP` is set to \"192.168.105.1\", the whole subnet (192.168.105.2-192.168.105.254) is used as the DHCP range.\n\nTo use static IP addresses, limit the DHCP range with `--vmnet-dhcp-end=IP`.\n\nFor example, `--vmnet-gateway=192.168.105.1 --vmnet-dhcp-end=192.168.105.100` allows using `192.168.105.101-192.168.105.254`\nas non-DHCP static addresses.\n\n### How to reserve DHCP addresses?\n\n- Decide a unique MAC address for the VM, e.g. `de:ad:be:ef:00:01`.\n\n- Decide a reserved IP address, e.g., \"192.168.105.100\"\n\n- Create `/etc/bootptab` like this. Make sure not to drop the \"%%\" header.\n\n```bash\n# bootptab\n%%\n# hostname      hwtype  hwaddr              ipaddr          bootfile\ntmp-vm01        1       de:ad:be:ef:00:01   192.168.105.100\n```\n\n- Reload the DHCP daemon.\n\n```bash\nsudo /bin/launchctl kickstart -kp system/com.apple.bootpd\n```\n\n- Run QEMU with the MAC address: `-device virtio-net-pci,netdev=net0,mac=de:ad:be:ef:00:01` .\n\nNOTE: don't confuse MAC addresses of VMs with the MAC address of `socket_vmnet` itself that is printed as `vmnet_mac_address` in the debug log.\nYou do not need to configure (and you can't, currently) the MAC address of `socket_vmnet` itself.\n\n### IP address is not assigned\n\nTry the following commands:\n\n```console\nsudo /usr/libexec/ApplicationFirewall/socketfilterfw --remove /usr/libexec/bootpd\nsudo /usr/libexec/ApplicationFirewall/socketfilterfw --add /usr/libexec/bootpd\n/usr/libexec/ApplicationFirewall/socketfilterfw --unblock /usr/libexec/bootpd\n```\n\n## Links\n\n- https://developer.apple.com/documentation/vmnet\n- https://developer.apple.com/documentation/bundleresources/entitlements/com_apple_vm_networking\n- [`file:///Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks/vmnet.framework/Versions/Current/Headers/vmnet.h`](file:///Library/Developer/CommandLineTools/SDKs/MacOSX.sdk/System/Library/Frameworks/vmnet.framework/Versions/Current/Headers/vmnet.h)\n\n## Troubleshooting\n\n- To enable verbose debug logs, set the environment variable `DEBUG=1`.\n- When using launchd, logs are written to `/var/log/socket_vmnet/stderr`.\n  `/var/log/socket_vmnet/stdout` is not used and expected to be empty.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flima-vm%2Fsocket_vmnet","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flima-vm%2Fsocket_vmnet","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flima-vm%2Fsocket_vmnet/lists"}