{"id":26418332,"url":"https://github.com/dskad/qemu-ga-container","last_synced_at":"2025-06-18T03:04:11.409Z","repository":{"id":38190117,"uuid":"424833044","full_name":"dskad/qemu-ga-container","owner":"dskad","description":"Build files for the containerized qemu guest agent. Used to send commands and retrieve data from VM operating systems such as CoreOS or Flatcar linux","archived":false,"fork":false,"pushed_at":"2025-05-30T22:47:14.000Z","size":37,"stargazers_count":13,"open_issues_count":2,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-31T09:29:52.771Z","etag":null,"topics":["containers","coreos","docker","flatcar-linux","qemu","qemu-guest-agent","qemu-kvm","virtualization"],"latest_commit_sha":null,"homepage":"","language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dskad.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2021-11-05T05:01:28.000Z","updated_at":"2025-05-30T22:46:56.000Z","dependencies_parsed_at":"2025-05-31T00:11:31.123Z","dependency_job_id":"e0bc0f31-b28b-47f3-85f9-bc63ad68edc4","html_url":"https://github.com/dskad/qemu-ga-container","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/dskad/qemu-ga-container","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dskad%2Fqemu-ga-container","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dskad%2Fqemu-ga-container/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dskad%2Fqemu-ga-container/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dskad%2Fqemu-ga-container/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dskad","download_url":"https://codeload.github.com/dskad/qemu-ga-container/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dskad%2Fqemu-ga-container/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260477915,"owners_count":23015063,"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":["containers","coreos","docker","flatcar-linux","qemu","qemu-guest-agent","qemu-kvm","virtualization"],"created_at":"2025-03-18T01:17:40.429Z","updated_at":"2025-06-18T03:04:06.392Z","avatar_url":"https://github.com/dskad.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# QEMU Guest Agent Container Image\n\n## Overview\n\nThis container is designed to run on a minimal container operating system like CoreOS or\nFlatcar Linux, running under QEMU/KVM, Proxmox, or other libvirt based virtual machine.\nThese operating systems often don't have a package management system to easily install the agent.\n\n## Quick Start\n\nEnable the QEMU Guest Agent Channel in the VM configuration.\n| VM Host                        | Enable Guest Agent                                            |\n| ------------------------------ | ------------------------------------------------------------- |\n| QEMU / Virtual Machine Manager | Add the `Guest Agent Channel` device (org.qemu.guest_agent.0) |\n| Proxmox                        | Enable the `QEMU Guest Agent` option                          |\n\n### Docker on Fedora CoreOS\n\n```bash\ndocker run --rm -d --name qemu-ga \\\n  -v /etc/os-release:/etc/os-release:ro \\\n  --device /dev/virtio-ports/org.qemu.guest_agent.0:/dev/virtio-ports/org.qemu.guest_agent.0 \\\n  --net=host \\\n  --uts=host \\\n  docker.io/danskadra/qemu-ga\n```\n\nThis will allow the Guest Agent to retrieve the OS information, host name, and IP addresses of the\ncontainer's Host VM.\n\n## Advanced Functionality\n\nIf more functionality is required from the Guest Agent, such as reboot and shutdown of non-ACPI VMs,\nthe following can be used. (This example is for CoreOS)\n\n```bash\ndocker run --rm -d --name qemu-ga \\\n  -v /dev:/dev \\\n  -v /etc/os-release:/etc/os-release:ro \\\n  -v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket \\\n  -v /sys/fs/cgroup:/sys/fs/cgroup \\\n  -v /sbin/shutdown:/sbin/shutdown \\\n  -v /bin/systemctl:/bin/systemctl \\\n  -v /usr/lib/systemd:/usr/lib/systemd \\\n  -v /lib64:/lib64 \\\n  --privileged \\\n  --uts=host \\\n  --net=host \\\n  docker.io/danskadra/qemu-ga -v\n```\n\n⚠ **This is less secure, since the container is now running in privileged mode and generally has\nfull access to the host VM.**\n\nQEMU Guest Agent falls back on using the `/sbin/shutdown` command to execute reboots and shutdowns.\nOn a Systemd based OS like CoreOS, `shutdown` is symlinked to the `systemctl` command. For the container\nto execute these commands, they need to be mapped into the container as well as the socket and cgroup\ndependencies that Systemd requires.\n\n```bash\n-v /var/run/dbus/system_bus_socket:/var/run/dbus/system_bus_socket \\\n-v /sys/fs/cgroup:/sys/fs/cgroup \\\n-v /sbin/shutdown:/sbin/shutdown \\\n-v /bin/systemctl:/bin/systemctl \\\n```\n\n## Resolving Dependency Issues\n\nThere is a problem with bind mounting commands into a container when the host's OS and the container's\nbase OS don't match. Compiled commands are linked against specific versions of GCC and other library\nfiles. The versions of these library files vary from distribution to distribution and even from\ndifferent versions of the same distribution.\n\nIn the example above, this means that the mounted systemctl command from CoreOS into this Alpine\nbased container will not run because the container is missing the dependant libraries from the host VM.\n\nThe hacky solution is to bind mount the required libraries into the container as well. Use the `ldd`\ncommand to discover the mounted command's dependencies. (Run this on the host VM, not the container)\n\n```bash\nldd /bin/systemctl\n        linux-vdso.so.1 (0x00007ffd2117d000)\n        libsystemd-shared-251.11-2.fc37.so =\u003e /usr/lib/systemd/libsystemd-shared-251.11-2.fc37.so (0x00007f8d1d600000)\n        libgcc_s.so.1 =\u003e /lib64/libgcc_s.so.1 (0x00007f8d1da85000)\n        libc.so.6 =\u003e /lib64/libc.so.6 (0x00007f8d1d423000)\n        libacl.so.1 =\u003e /lib64/libacl.so.1 (0x00007f8d1da7b000)\n        libblkid.so.1 =\u003e /lib64/libblkid.so.1 (0x00007f8d1da42000)\n        libcap.so.2 =\u003e /lib64/libcap.so.2 (0x00007f8d1da36000)\n        libcrypt.so.2 =\u003e /lib64/libcrypt.so.2 (0x00007f8d1d9fc000)\n        libkmod.so.2 =\u003e /lib64/libkmod.so.2 (0x00007f8d1d9de000)\n        liblz4.so.1 =\u003e /lib64/liblz4.so.1 (0x00007f8d1d9bb000)\n        libmount.so.1 =\u003e /lib64/libmount.so.1 (0x00007f8d1d974000)\n        libcrypto.so.3 =\u003e /lib64/libcrypto.so.3 (0x00007f8d1ce00000)\n        libp11-kit.so.0 =\u003e /lib64/libp11-kit.so.0 (0x00007f8d1d2ee000)\n        libpam.so.0 =\u003e /lib64/libpam.so.0 (0x00007f8d1d960000)\n        libseccomp.so.2 =\u003e /lib64/libseccomp.so.2 (0x00007f8d1d2ce000)\n        libselinux.so.1 =\u003e /lib64/libselinux.so.1 (0x00007f8d1d2a1000)\n        libzstd.so.1 =\u003e /lib64/libzstd.so.1 (0x00007f8d1cd4b000)\n        liblzma.so.5 =\u003e /lib64/liblzma.so.5 (0x00007f8d1d26d000)\n        libm.so.6 =\u003e /lib64/libm.so.6 (0x00007f8d1cc6b000)\n        /lib64/ld-linux-x86-64.so.2 (0x00007f8d1daf1000)\n        libattr.so.1 =\u003e /lib64/libattr.so.1 (0x00007f8d1d956000)\n        libz.so.1 =\u003e /lib64/libz.so.1 (0x00007f8d1d253000)\n        libffi.so.8 =\u003e /lib64/libffi.so.8 (0x00007f8d1d247000)\n        libaudit.so.1 =\u003e /lib64/libaudit.so.1 (0x00007f8d1cc3d000)\n        libeconf.so.0 =\u003e /lib64/libeconf.so.0 (0x00007f8d1d23c000)\n        libpcre2-8.so.0 =\u003e /lib64/libpcre2-8.so.0 (0x00007f8d1cba0000)\n        libcap-ng.so.0 =\u003e /lib64/libcap-ng.so.0 (0x00007f8d1d230000)\n ```\n\nIn this case, this version of CoreOS's systemctl requires libraries located in `/lib64` and\n`/usr/lib/systemd/libsystemd-shared-251.11-2.fc37.so`. Because the Alpine container doesn't have\nthe `/lib64` or `usr/lib/systemd` directories, it's safe and easier to mount the whole directory\nfrom the host VM instead of each library individually.\n\n```bash\n-v /sbin/shutdown:/sbin/shutdown\n-v /bin/systemctl:/bin/systemctl\n-v /usr/lib/systemd:/usr/lib/systemd\n-v /lib64:/lib64\n```\n\n**Note:** If the host VM's shutdown command or systemctl are linked to libraries in the `/lib` or `/usr/lib`\ndirectories, which exist in the Alpine container, it may be necessary to bind mount each individual\ndependant library it to the same directory in the container.\n\n## Useful Options\n\n| Option                                               | Descriptopn                                          |\n| ---------------------------------------------------- | ---------------------------------------------------- |\n| `-v /etc/os-release:/etc/os-release:ro`              | Read only access to VM OS info                       |\n| `--device [VirtIO Serial Port]:[VirtIO Serial Port]` | (**Required**) Agent communication to host VM        |\n| `--uts=host`                                         | Allows Guest Agent to read VM hostname               |\n| `--net=host`                                         | Allows Guest Agent to read network info from host VM |\n\n## Security Considerations\n\nThe QEMU Guest Agent is designed to interact directly with the host operating system.\nTo allow access to the host while running the Guest Agent inside of a container, the\ncontainer may be run with extended capabilities. Generally this is accomplished by\nusing the `--privileged` command option. This grants far more capabilities to the\ncontainer than is needed by the use case presented here. i.e. Retrieving IP addresses,\nhost names, OS versions, etc, for visibility to the KVM host.\n\nSecurity can be improved by replacing the `--privileged` option with the `--device`\noption and bind mounting a volumes to specific files. This can be used to limit access\nto only the VirtIO Guest Agent device, instead of all the devices in /dev or other\ncapabilities granted by `--privileged`.\n\nIf more interaction with the host VM is required, such as rebooting and shutting down the VM, more access\nwill be required. This will be by either using the `--privileged` option or using the `--cap-add` option\nto add specific capabilities to the container.\n\n## Additional Info\n\n- [Container GitHub Repo](https://github.com/dskad/qemu-ga-container)\n- [Docker Hub Repo](https://hub.docker.com/r/danskadra/qemu-ga)\n- [QEMU Guest Agent Protocol Reference](https://qemu.readthedocs.io/en/latest/interop/qemu-ga-ref.html)\n- [Docker Run Reference](https://docs.docker.com/engine/reference/run/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdskad%2Fqemu-ga-container","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdskad%2Fqemu-ga-container","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdskad%2Fqemu-ga-container/lists"}