{"id":19378822,"url":"https://github.com/linbit/virter","last_synced_at":"2025-04-12T15:37:06.960Z","repository":{"id":41105333,"uuid":"248599047","full_name":"LINBIT/virter","owner":"LINBIT","description":"Virter is a command line tool for simple creation and cloning of virtual machines based on libvirt","archived":false,"fork":false,"pushed_at":"2025-04-02T08:29:52.000Z","size":999,"stargazers_count":257,"open_issues_count":7,"forks_count":17,"subscribers_count":9,"default_branch":"master","last_synced_at":"2025-04-02T09:32:34.121Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","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/LINBIT.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":"2020-03-19T20:31:36.000Z","updated_at":"2025-03-31T17:50:33.000Z","dependencies_parsed_at":"2023-10-04T13:17:43.837Z","dependency_job_id":"6c483f1d-dcc1-43a7-a092-5685f691ef80","html_url":"https://github.com/LINBIT/virter","commit_stats":{"total_commits":498,"total_committers":15,"mean_commits":33.2,"dds":0.7409638554216867,"last_synced_commit":"fa0e6c1069d1b08e7a2524fd0991da0f6bd2564f"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LINBIT%2Fvirter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LINBIT%2Fvirter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LINBIT%2Fvirter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LINBIT%2Fvirter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LINBIT","download_url":"https://codeload.github.com/LINBIT/virter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248590483,"owners_count":21129827,"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-11-10T09:07:29.888Z","updated_at":"2025-04-12T15:37:06.937Z","avatar_url":"https://github.com/LINBIT.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Virter\n\nVirter is a command line tool for simple creation and cloning of virtual\nmachines.\n\nVirter supports VMs running standard general purpose distributions such as\nCentOS and Ubuntu. It is especially useful for development and testing of\nprojects which cannot use containers due to kernel dependencies, such as\n[DRBD](https://github.com/LINBIT/drbd) and\n[LINSTOR](https://github.com/LINBIT/linstor-server).\n\n## Quick Start\n\nFirst install and set up [libvirt](https://libvirt.org/index.html). Then\ndownload one of the [releases](https://github.com/LINBIT/virter/releases).\nVirter is packaged as a single binary, so just put that into `/usr/local/bin` and\nyou are ready to use Virter:\n\n```\nvirter image pull alma-8 # also would be auto-pulled in next step\nvirter vm run --name alma-8-hello --id 100 --wait-ssh alma-8\nvirter vm ssh alma-8-hello\nvirter vm rm alma-8-hello\n```\nIn the above example, the virter \"ID\" is the index into the possible IPs\nwithin the IP range of the network definition.  For a typical 192.x.y.z/24\nnet definition, the virter \"ID\" would be z, or 100 in this case.\n\nDepending on your host distribution and libvirt installation, you may need to:\n* [Set up a storage pool](#libvirt-storage-pool); and/or\n* [Configure AppArmor](#apparmor).\n\n## Usage\n\nFor usage just run `virter help`.\n\nAdditional options that may be helpful when using `virter vm run`:\n\n* List all available images: `virter image ls --available`\n\n* Using a provisioning file: `--provision /root/alma8.toml`\n\n* Adding additional disk(s):\n`--disk \"name=disk1,size=20GiB,format=qcow2,bus=virtio\"`\n\n* Adding a bridged interface\n`--nic \"type=bridge,source=br0,mac=1a:2b:3c:4d:5e:01\"`\n\n* Adding a NAT'ed interface:\n`--nic \"type=network,source=default,mac=1a:2b:3c:4d:5e:01\"`\n\nOther examples are provided in the [examples](./examples) directory. See the\nREADME files for the individual examples.\n\nThere is also additional [documentation for the provisioning\nfeature](./doc/provisioning.md). This is useful for defining new images. These\nimages can be used to start clusters of cloned VMs.\n\n## Installation Details\n\nVirter requires:\n\n* A running libvirt daemon on the host where it is run\n* When container provisioning is used: A container runtime.\n  Currently, Virter supports `docker` and `podman`.\n\nConfiguration is read by default from `~/.config/virter/virter.toml`.\n\nWhen starting Virter for the first time, a default configuration file will be\ngenerated, including documentation about the various flags.\n\n### Container runtime\n\nSelect the container runtime by setting `container.provider` to either `docker` or `podman`.\n\n#### podman\n\nVirter communicates with `podman` via it's REST-API. Make sure the API socket is available.\n\nThis may be done by:\n\n* Starting podman via systemd: `systemctl --user start podman.socket` (use `systemctl --user enable --now podman.socket` to make this permanent)\n* Start podman manually: `podman system service`\n\n### Network domain\n\nIf you require DNS resolution from your VMs to return correct FQDNs, add the\n`domain` to your libvirt network definition:\n\n```\n\u003cnetwork\u003e\n  ...\n  \u003cdomain name='test'/\u003e\n  ...\n\u003c/network\u003e\n```\n\nBy default, Virter uses the libvirt network named `default`.\n\nCheck out [`doc/networks.md`](./doc/networks.md) for more details on VM networking.\n\n### Connecting with `ssh`\n\nSSH can be configured for convenient access to virtual machines created by Virter.\nSee [`doc/ssh.md`](./doc/ssh.md) for details.\n\n### DHCP Leases\n\nLibvirt produces some weird behavior when MAC or IP addresses are reused while\nthere is still an active DHCP lease for them. This can result in a new VM\ngetting assigned a random IP instead of the IP corresponding to its ID.\n\nTo work around this, Virter tries to execute the `dhcp_release` utility in\norder to release the DHCP lease from libvirt's DHCP server when a VM is\nremoved. This utility has to be run by the root user, so Virter executes\nit using `sudo`.\n\nIf execution fails (for example because the utility is not installed or the\nsudo rules are not set up correctly), the error is ignored by Virter.\n\nSo, to make Virter work more reliably, especially when you are running lots\nof VMs in a short amount of time, you should install the `dhcp_release` utility\n(usually packaged as `dnsmasq-utils`). Additionally, you should make sure that\nyour user can run `dhcp_release` as root, for example by using a sudo rule like\nthis:\n\n```\n%libvirt ALL=(ALL) NOPASSWD: /usr/bin/dhcp_release\n```\n\nThis allows all users in the group libvirt to run the `dhcp_release` utility\nwithout being prompted for a password.\n\n### Console logs\n\nThe `--console` argument to `virter vm run` causes serial output from the VM to\nbe saved to a file. This file is created with the current user as the owner.\nHowever, it is written to by libvirt, so it needs to located on a filesystem to\nwhich libvirt can write. NFS mounts generally cannot be used due to\n`root_squash`.\n\nIn addition, when the VM generates a lot of output, this can trigger `virtlogd`\nto roll the log file over, which creates a file owned by root (assuming\n`virtlogd` is running as root). To prevent this, increase `max_size` in\n`/etc/libvirt/virtlogd.conf`.\n\n### libvirt storage pool\n\nVirter requires a libvirt storage pool for its images and VM volumes. By\ndefault, it expects a pool named `default`. Some libvirt distributions\nconfigure this pool automatically. Some, such as the standard packages on\nUbuntu Focal, do not. If the pool does not exist, create it like this:\n\n```\nvirsh pool-define-as --name default --type dir --target /var/lib/libvirt/images\nvirsh pool-autostart default\nvirsh pool-start default\n```\n\n### AppArmor\n\nOn some distributions, AppArmor denies access to `/var/lib/libvirt/images` by default.\nThis leads to messages in dmesg along the lines of:\n\n```\n[ 4274.237593] audit: type=1400 audit(1598348576.161:102): apparmor=\"DENIED\" operation=\"open\" profile=\"libvirt-d84ef9d7-a7ad-4388-bd5d-cfc3a3db28a6\" name=\"/var/lib/libvirt/images/centos-8\" pid=14918 comm=\"qemu-system-x86\" requested_mask=\"r\" denied_mask=\"r\" fsuid=64055 ouid=64055\n```\n\nThis can be circumvented by overriding the AppArmor abstraction for that directory:\n\n```\ncat \u003c\u003cEOF \u003e\u003e /etc/apparmor.d/local/abstractions/libvirt-qemu\n/var/lib/libvirt/images/* rwk,\n# required for QEMU accessing UEFI nvram variables\n/usr/share/OVMF/* rk,\nowner /var/lib/libvirt/qemu/nvram/*_VARS.fd rwk,\nowner /var/lib/libvirt/qemu/nvram/*_VARS.ms.fd rwk,\nEOF\nsystemctl restart apparmor.service\nsystemctl restart libvirtd.service\n```\n\n## Architecture\n\nVirter connects to the libvirt daemon for all the heavy lifting. It supplies\nbootstrap configuration to the VMs using `cloud-init` volumes, so that the\nhostname is set and SSH access is possible.\n\n## Building from source\n\nIf you want to test the latest unstable version of Virter, you can build the\ngit version from sources:\n\n```\ngit clone https://github.com/LINBIT/virter\ncd virter\ngo build .\n```\n\n## Comparison to other tools\n\n### `virsh`\n\nVirter is good for starting and cloning `cloud-init` based VMs. `virsh` is\nuseful for more detailed libvirt management. They work well together.\n\n### `virt-install`\n\n`virt-install` is built for images that use conventional installers. Virter\nuses `cloud-init`, making it simpler to use and quicker to start a fresh VM.\n\n### Running VMs in AWS/GCP/OpenNebula\n\nVirter is local to a single host making snapshot/restore/clone operations very\nefficient. Virter could be thought of as cloud provisioning for your local\nmachine.\n\n### Vagrant\n\nVirter and Vagrant have essentially the same goal. Virter is more tightly\nintegrated with the Linux virtualization stack, resulting in better\nsnapshot/restore/clone support.\n\n### Multipass\n\nVirter and Multipass have similar goals, but Multipass is Ubuntu specific.\n\n### Docker\n\nVirter is like Docker for VMs. The user experience of the tools is generally\nsimilar. Docker containers share the host kernel, whereas Virter starts VMs\nwith their own kernel.\n\n### Kata Containers\n\nVirter starts VMs running a variety of Linux distributions, whereas Kata\nContainers uses a specific guest that then runs containers.\n\n### Weave Ignite\n\nIgnite has very strong requirements on the guest, so it cannot be used for\nrunning standard distributions.\n\n## Development\n\nVirter is a standard go project using modules.\nGo 1.13+ is supported.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinbit%2Fvirter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinbit%2Fvirter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinbit%2Fvirter/lists"}