{"id":13510743,"url":"https://github.com/meffie/virt-lab","last_synced_at":"2026-04-24T10:31:53.182Z","repository":{"id":148072960,"uuid":"200721771","full_name":"meffie/virt-lab","owner":"meffie","description":"Install and remove sets of guests on a local kvm hypervisor using cloud-init images","archived":false,"fork":false,"pushed_at":"2020-04-06T20:12:07.000Z","size":117,"stargazers_count":1,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-12-25T22:34:00.882Z","etag":null,"topics":["ansible","centos7","cloud-init","kvm","libvirt","ubuntu"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/meffie.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}},"created_at":"2019-08-05T20:10:03.000Z","updated_at":"2023-04-16T18:35:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"f81e8605-c7a0-4786-9d54-d25421b14329","html_url":"https://github.com/meffie/virt-lab","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/meffie/virt-lab","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meffie%2Fvirt-lab","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meffie%2Fvirt-lab/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meffie%2Fvirt-lab/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meffie%2Fvirt-lab/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/meffie","download_url":"https://codeload.github.com/meffie/virt-lab/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/meffie%2Fvirt-lab/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32218932,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-24T10:26:35.452Z","status":"ssl_error","status_checked_at":"2026-04-24T10:25:27.643Z","response_time":64,"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":["ansible","centos7","cloud-init","kvm","libvirt","ubuntu"],"created_at":"2024-08-01T02:01:52.570Z","updated_at":"2026-04-24T10:31:53.166Z","avatar_url":"https://github.com/meffie.png","language":"Python","funding_links":[],"categories":["Python","ansible"],"sub_categories":[],"readme":"# Virtual Linux Lab\n\nInstall virtual machines on a local KVM hypervisor with cloud-init images, and\nthen optionally run Ansible [playbooks](playbooks/README.md) to configure the\nnew guests. Guests are grouped into sets called **labs**, which are defined in\nan INI-style configuration file.  MAC addresses assigned to guests are saved\nand reused for the next generation.\n\n`virt-lab` can be useful for spinning up clusters of guests on your local linux\nsystem for testing or development.\n\n`virt-lab` is a wrapper of the very nice [`kvm-install-vm`][1] shell script by\nGiovanni Torres to download and install cloud-init images. `kvm-install-vm` is\nincluded in this repo within a git submodule to make installation slightly\neasier.\n\n## Usage\n\n    usage: virt-lab \u003ccommand\u003e [\u003cname\u003e] [\u003coptions\u003e]\n    \n    Commands:\n      create \u003cname\u003e     create guests (alias: new)\n      destroy \u003cname\u003e    destroy guests (alias: rm)\n      start \u003cname\u003e      start guests\n      stop \u003cname\u003e       shutdown guests\n      info \u003cname\u003e       show lab and guest status (alias: show)\n      inventory \u003cname\u003e  generate ansible dynamic inventory\n      list              list labs (alias: ls)\n      help              show help\n      version           show version\n    \n    Install and remove guests on a local kvm hypervisor using cloud-init images.\n\n## KVM Setup\n\nA local KVM hypervisor must be installed and running along with `libvirt`\nbefore `virt-lib` can be run. An Ansible playbook to install the local KVM\nhypervisor and the required libvirt tools is provided in the `kvm` directory.\nBe sure you are able to connect to the locally running libvirt daemon, e.g.,\n`virsh list --all`, before proceeding.\n\nIt is also possible to use Xen as a local hypervisor for virt-lab images. See\nthe \"Advanced\" `kvm-install-vm` configuration options for more information.\n\n## Installation\n\nInstall `virt-lab` with the following commands, running as a non-root user:\n\n    $ make update\n    $ make install\n\n### Ubuntu notes\n\nYou may encounter an error message on Ubuntu when attempting create a guest\nwith a custom disk size:\n\n    - Resizing the disk to 20G ... ERR: Could not resize disk.\n\nThis happens because current versions of [Ubuntu][2] distribute linux images as\nunreadable by regular users, which breaks the ability of libguestfs to modify\nguest images.  This can be fixed by overriding the file permission settings of\nthe linux kernel images on Ubuntu.\n\nUse the following `dpkg-statoverride` command to make your linux images\nreadable by non-root users, allowing you to modify your guest images:\n\n    $ for image in /boot/vmlinu*; do sudo dpkg-statoverride --update --add root root 0644 $image || true; done\n\nYou will need to override new kernel images *everytime* the kernel is upgraded.\n\n## Configuration\n\nThe guest sets, called **labs**, are defined in INI-style configuration file.\nPlace the virt-lab configuration in the `.virt-lab` directory in the user's\nhome directory.  `virt-lab` will load the configuration from all files ending\nwith `.cfg` in the `~/.virt-lab` configuration directory.\n\nThe section names specify the **lab** names available to the `virt-lab`\ncommands.  Lab names are limited to ASCII alphanumeric characters and the\nunderscore (`'_'`) character. The options for a given section specify the guest\nconfiguration for each guest in the **lab**.  It is possible to override values\nfor a specific guest by providing a subsections in the INI file in the form\n`\u003clab\u003e.\u003cnumber\u003e`. Guest numbers start with 1.\n\nOption names are:\n\n| Option     | Description               | Default |\n| ---------- | ------------------------- | ------- |\n| desc       | lab description           | none |\n| autostart  | enable guest autostart    | true |\n| bridge     | bridge interface          | virbr0 |\n| cpus       | number of cpus            | 1 |\n| disksize   | disk size (GB)            | 10 |\n| distro     | distro name               | centos7 |\n| domain     | DNS domain                | example.com |\n| feature    | cpu model / feature       | host |\n| gateway    | virtual network gateway   | 192.168.122.1 |\n| graphics   | graphics type             | spice |\n| image      | custom image (qcow2)      | none |\n| images     | number and type of guests | 3 |\n| key        | ssh public key            | `$HOME/.ssh/id_rsa.pub` |\n| mac        | mac address               | previous value if one, auto-assigned otherwise |\n| memory     | memory (MB)               | 1024 |\n| namefmt    | guest name format         | `{lab}{guest:02d}` |\n| port       | console port              | auto-assigned |\n| postcreate | command run after lab is created | none |\n| scriptname | command run after guest is created | none |\n| timezone   | timezone name             | US/Eastern |\n| user       | additional username       | current login username |\n| imagedir   | image directory           | `$HOME/virt/images` |\n| vardir     | guest data directory      | `$HOME/virt/var` |\n| vmdir      | data directory            | `$HOME/virt/vms` |\n| scriptdir  | custom script directory   | `$HOME/virt/scripts` |\n| playbookdir | Ansible playbooks        | `$HOME/virt/playbooks` |\n\n\n## Distributions\n\nThe distro option specifies which cload-init image will be downloaded and\ninstalled for a guest.  The following are currently supported:\n\n| Name            | Description                         | Login    |\n| --------------- | ----------------------------------- | -------- |\n| amazon2         | Amazon Linux 2                      | ec2-user |\n| centos7         | CentOS 7                            | centos   |\n| centos7-atomic  | CentOS 7 Atomic Host                | centos   |\n| centos6         | CentOS 6                            | centos   |\n| debian9         | Debian 9 (Stretch)                  | debian   |\n| fedora29        | Fedora 29                           | fedora   |\n| fedora29-atomic | Fedora 29 Atomic Host               | fedora   |\n| fedora30        | Fedora 30                           | fedora   |\n| ubuntu1604      | Ubuntu 16.04 LTS (Xenial Xerus)     | ubuntu   |\n| ubuntu1804      | Ubuntu 18.04 LTS (Bionic Beaver)    | ubuntu   |\n\n# Playbooks\n\nSee the [playbooks](playbooks/README.md) for information on how to run one or\nmore Ansible playbooks on the set of newly created guests.\n\n# Examples\n\nHere is an example configuration file.\n\n    $ cat $HOME/.virt-lab/my.cfg\n    [test]\n    guests = 6\n    desc = My test environment\n    distro = centos7\n    key =  ~/.ssh/mykey.pub\n    domain = example.com\n    bridge = vlbr0\n    gateway = 192.168.123.1\n    # Setup local name resolution for the new guests. (Assumes you have systemd-resolve)\n    postcreate = systemd-resolve --interface {bridge} --set-dns {gateway} --set-domain {domain}\n\n    [dev]\n    guests = 3\n    desc = Guests for development\n    distro = debian\n    postcreate = ansible-playbook -i {scriptdir}/inventory.sh -i myvars myplaybook.yaml\n\n    [dev.1]\n    distro = centos6\n    disksize = 20\n\nList the configured labs.\n\n    $ virt-lab list\n    - name: test\n      desc: My test environment\n      guests:\n      - test01: centos7, undefined\n      - test02: centos7, undefined\n      - test03: centos7, undefined\n      - test04: centos7, undefined\n      - test05: centos7, undefined\n\n    - name: dev\n      desc: Guests for development\n      guests:\n      - dev01: centos6, undefined\n      - dev02: debian, undefined\n      - dev03: debian, undefined\n\nCreate the \"test\" lab.\n\n    $ virt-lab create test\n     [info]: creating guest test01\n    - Copying cloud image (CentOS-7-x86_64-GenericCloud.qcow2) ...\n    ...\n    - DONE\n    [info]: creating guest test02\n    ...\n    - DONE\n    [info]: creating guest test03\n    ...\n    - DONE\n    [info]: creating guest test04\n    ...\n    - DONE\n    [info]: creating guest test05\n    ...\n    - DONE\n\n    $ virt lab list\n    - name: test\n      desc: My test environment\n      guests:\n      - test01: centos7, running\n      - test02: centos7, running\n      - test03: centos7, running\n      - test04: centos7, running\n      - test05: centos7, running\n\n    - name: dev\n      desc: Guests for development\n      guests:\n      - dev01: centos6, undefined\n      - dev02: debian, undefined\n      - dev03: debian, undefined\n\n\nTo destroy the guests after the tests have been run.\n\n    $ virt-lab destroy test\n    [info]: destroying guest test01\n    - Destroying test01 domain ...\n    ...\n    [info]: destroying guest test05\n\n\n[1]: https://github.com/giovtorres/kvm-install-vm\n[2]: https://bugs.launchpad.net/ubuntu/+source/linux/+bug/759725\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeffie%2Fvirt-lab","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmeffie%2Fvirt-lab","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmeffie%2Fvirt-lab/lists"}