{"id":13844803,"url":"https://github.com/giovtorres/kvm-install-vm","last_synced_at":"2025-05-15T17:04:09.765Z","repository":{"id":20526666,"uuid":"84863065","full_name":"giovtorres/kvm-install-vm","owner":"giovtorres","description":"Bash script to build local virtual machines using KVM/libvirt and cloud-init.","archived":false,"fork":false,"pushed_at":"2025-03-22T18:37:47.000Z","size":231,"stargazers_count":333,"open_issues_count":12,"forks_count":164,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-11T23:57:43.530Z","etag":null,"topics":["amazon-linux","centos","centos-atomic","cloud-init","debian","fedora","fedora-atomic","kvm","libvirt","ubuntu","virt-install","xen"],"latest_commit_sha":null,"homepage":"","language":"Shell","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/giovtorres.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}},"created_at":"2017-03-13T18:53:09.000Z","updated_at":"2025-04-09T17:58:30.000Z","dependencies_parsed_at":"2023-02-17T17:05:16.820Z","dependency_job_id":"cefc7d4c-d37e-4b17-9433-f8b7980e965b","html_url":"https://github.com/giovtorres/kvm-install-vm","commit_stats":null,"previous_names":[],"tags_count":25,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giovtorres%2Fkvm-install-vm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giovtorres%2Fkvm-install-vm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giovtorres%2Fkvm-install-vm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/giovtorres%2Fkvm-install-vm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/giovtorres","download_url":"https://codeload.github.com/giovtorres/kvm-install-vm/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254384982,"owners_count":22062422,"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":["amazon-linux","centos","centos-atomic","cloud-init","debian","fedora","fedora-atomic","kvm","libvirt","ubuntu","virt-install","xen"],"created_at":"2024-08-04T17:02:57.475Z","updated_at":"2025-05-15T17:04:09.721Z","avatar_url":"https://github.com/giovtorres.png","language":"Shell","funding_links":[],"categories":["Shell (473)","HarmonyOS","Shell","ubuntu"],"sub_categories":["Windows Manager"],"readme":"## kvm-install-vm\n\nA bash wrapper around virt-install to build virtual machines on a local KVM\nhypervisor.  You can run it as a normal user which will use `qemu:///session` to\nconnect locally to your KVM domains.\n\nTested on the latest Fedora.\n\n### Prerequisites\n\nYou need to have the KVM hypervisor installed, along with a few other packages (naming of packages can differ on other distributions):\n\n- genisoimage or mkisofs\n- virt-install\n- libguestfs-tools-c\n- qemu-img\n- libvirt-client\n- libosinfo\n\nTo install the dependencies, run:\n\n- Fedora example:\n\n```\nsudo dnf -y install genisoimage virt-install libguestfs-tools-c qemu-img libvirt-client wget libosinfo\n```\n\n- Ubuntu example:\n\n```\nsudo apt install -y genisoimage virtinst libguestfs-tools qemu-utils libvirt-clients wget libosinfo-bin\n```\n\nIf you want to resolve guests by their hostnames, install the `libvirt-nss` package:\n\n- Fedora example:\n\n```\nsudo dnf -y install libvirt-nss\n```\n\n- Ubuntu example:\n\n```\nsudo apt install -y libnss-libvirt\n```\n\nThen, add `libvirt` and `libvirt_guest` to list of **hosts** databases in\n`/etc/nsswitch.conf`.  See [here](https://libvirt.org/nss.html) for more\ninformation.\n\n### Usage\n\n```\n$ kvm-install-vm help\nNAME\n    kvm-install-vm - Install virtual guests using cloud-init on a local KVM\n    hypervisor.\n\nSYNOPSIS\n    kvm-install-vm COMMAND [OPTIONS]\n\nDESCRIPTION\n    A bash wrapper around virt-install to build virtual machines on a local KVM\n    hypervisor. You can run it as a normal user which will use qemu:///session\n    to connect locally to your KVM domains.\n\nCOMMANDS\n    help    - show this help or help for a subcommand\n    create  - create a new guest domain\n    list    - list all domains, running and stopped\n    remove  - delete a guest domain\n```\n\n#### Creating Guest VMs\n\n```\n$ kvm-install-vm help create\nNAME\n    kvm-install-vm create [COMMANDS] [OPTIONS] VMNAME\n\nDESCRIPTION\n    Create a new guest domain.\n\nCOMMANDS\n    help - show this help\n\nOPTIONS\n    -a          Autostart             (default: false)\n    -b          Bridge                (default: virbr0)\n    -c          Number of vCPUs       (default: 1)\n    -d          Disk Size (GB)        (default: 10)\n    -D          DNS Domain            (default: example.local)\n    -f          CPU Model / Feature   (default: host)\n    -g          Graphics type         (default: spice)\n    -h          Display help\n    -i          Custom QCOW2 Image\n    -k          SSH Public Key        (default: $HOME/.ssh/id_rsa.pub)\n    -l          Location of Images    (default: $HOME/virt/images)\n    -L          Location of VMs       (default: $HOME/virt/vms)\n    -m          Memory Size (MB)      (default: 1024)\n    -M          Mac address           (default: auto-assigned)\n    -p          Console port          (default: auto)\n    -s          Custom shell script\n    -t          Linux Distribution    (default: centos8)\n    -T          Timezone              (default: US/Eastern)\n    -u          Custom user           (default: $USER)\n    -y          Assume yes to prompts (default: false)\n    -n          Assume no to prompts  (default: false)\n    -v          Be verbose\n\nDISTRIBUTIONS\n    NAME            DESCRIPTION                         LOGIN\n    amazon2         Amazon Linux 2                      ec2-user\n    centos8         CentOS 8                            centos\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    debian10        Debian 10 (Buster)                  debian\n    fedora29        Fedora 29                           fedora\n    fedora29-atomic Fedora 29 Atomic Host               fedora\n    fedora30        Fedora 30                           fedora\n    fedora31        Fedora 31                           fedora\n    fedora32        Fedora 32                           fedora\n    opensuse15      OpenSUSE Leap 15.2                  opensuse\n    ubuntu1604      Ubuntu 16.04 LTS (Xenial Xerus)     ubuntu\n    ubuntu1804      Ubuntu 18.04 LTS (Bionic Beaver)    ubuntu\n    ubuntu2004      Ubuntu 20.04 LTS (Focal Fossa)      ubuntu\n\nEXAMPLES\n    kvm-install-vm create foo\n        Create VM with the default parameters: CentOS 8, 1 vCPU, 1GB RAM, 10GB\n        disk capacity.\n\n    kvm-install-vm create -c 2 -m 2048 -d 20 foo\n        Create VM with custom parameters: 2 vCPUs, 2GB RAM, and 20GB disk\n        capacity.\n\n    kvm-install-vm create -t debian9 foo\n        Create a Debian 9 VM with the default parameters.\n\n    kvm-install-vm create -T UTC foo\n        Create a default VM with UTC timezone.\n```\n\n#### Deleting a Guest Domain\n\n```\n$ kvm-install-vm help remove\nNAME\n    kvm-install-vm remove [COMMANDS] VMNAME\n\nDESCRIPTION\n    Destroys (stops) and undefines a guest domain.  This also remove the\n    associated storage pool.\n\nCOMMANDS\n    help - show this help\n\nEXAMPLE\n    kvm-install-vm remove foo\n        Remove (destroy and undefine) a guest domain.  WARNING: This will\n        delete the guest domain and any changes made inside it!\n```\n\n#### Attaching a new disk\n\n```\n$ kvm-install-vm help attach-disk\nNAME\n    kvm-install-vm attach-disk [OPTIONS] [COMMANDS] VMNAME\n\nDESCRIPTION\n    Attaches a new disk to a guest domain.\n\nCOMMANDS\n    help - show this help\n\nOPTIONS\n    -d SIZE     Disk size (GB)\n    -f FORMAT   Disk image format       (default: qcow2)\n    -s IMAGE    Source of disk device\n    -t TARGET   Disk device target\n\nEXAMPLE\n    kvm-install-vm attach-disk -d 10 -s example-5g.qcow2 -t vdb foo\n        Attach a 10GB disk device named example-5g.qcow2 to the foo guest\n        domain.\n```\n\n### Setting Custom Defaults\n\nCopy the `.kivrc` file to your $HOME directory to set custom defaults.  This is\nconvenient if you find yourself repeatedly setting the same options on the\ncommand line, like the distribution or the number of vCPUs.\n\nOptions are evaluated in the following order:\n\n- Default options set in the script\n- Custom options set in `.kivrc`\n- Option flags set on the command line\n\n### Notes\n\n1. This script will download a qcow2 cloud image from the respective\n   distribution's download site.  See script for URLs.\n\n2. If using libvirt-nss, keep in mind that DHCP leases take some time to\n   expire, so if you create a VM, delete it, and recreate another VM with the\n   same name in a short period of time, there will be two DHCP leases for the\n   same host and its hostname will likely not resolve until the old lease\n   expires.\n\n3. The Operating System information database (osinfo-db) provides Operating\n   System specific information needed to create guests for the various systems\n   supported by `kvm-install-vm`.  The database files provided by your package\n   manager may be out of date and not provide definitions for recent Operating\n   System versions. If you encounter the following error message, you may need\n   to update the database files:\n   `ERR: Unknown OS variant '\u003cname\u003e'. Please update your osinfo-db.`\n   If you have already updated your system, and the osinfo-db is still to old,\n   then you can use the `osinfo-db-import` tool with the `--local` option, to\n   install an up-to-date database in your home directory which will not\n   conflict with your package manager files. The `osinfo-db-import` tool is\n   provided by the rpm/deb packages `osinfo-db-tools`.\n   See https://libosinfo.org/download for more information.\n\n### Testing\n\nTests are written using [Bats](https://github.com/sstephenson/bats).  To\nexecute the tests, run `./test.sh` in the root directory of the project.\n\n### Use Cases\n\nIf you don't need to use Docker or Vagrant, don't want to make changes to a\nproduction machine, or just want to spin up one or more VMs locally to test\nthings like:\n\n- high availability\n- clustering\n- package installs\n- preparing for exams\n- checking for system defaults\n- anything else you would do with a VM\n\n...then this wrapper could be useful for you.\n\n### Troubleshooting\n\nIf you will encounter something similar:\n\n```\nERR: Unknown OS variant 'fedora31'. Please update your osinfo-db.  See https://libosinfo.org/download for more information.\n```\n\nThen you need to update the DB in libosinfo.\nCheck the url and select the latest date ( https://releases.pagure.org/libosinfo/ )\n\n```\nwget -O \"/tmp/osinfo-db.tar.xz\" https://releases.pagure.org/libosinfo/osinfo-db-20200515.tar.xz\nsudo osinfo-db-import --local \"/tmp/osinfo-db.tar.xz\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiovtorres%2Fkvm-install-vm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgiovtorres%2Fkvm-install-vm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgiovtorres%2Fkvm-install-vm/lists"}