{"id":32523991,"url":"https://github.com/ucphhpc/configure-vm-image","last_synced_at":"2026-07-01T23:32:33.693Z","repository":{"id":241569737,"uuid":"804265278","full_name":"ucphhpc/configure-vm-image","owner":"ucphhpc","description":"This tool can be used for configuring virtual machine images ","archived":false,"fork":false,"pushed_at":"2026-05-28T14:39:33.000Z","size":194,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-28T16:21:40.039Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/ucphhpc.png","metadata":{"files":{"readme":"README.rst","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,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-05-22T09:11:11.000Z","updated_at":"2026-05-28T14:41:34.000Z","dependencies_parsed_at":"2024-06-03T10:24:42.798Z","dependency_job_id":null,"html_url":"https://github.com/ucphhpc/configure-vm-image","commit_stats":null,"previous_names":["ucphhpc/configure-vm-image","rasmunk/configure-vm-image"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/ucphhpc/configure-vm-image","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fconfigure-vm-image","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fconfigure-vm-image/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fconfigure-vm-image/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fconfigure-vm-image/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ucphhpc","download_url":"https://codeload.github.com/ucphhpc/configure-vm-image/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ucphhpc%2Fconfigure-vm-image/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35027341,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":[],"created_at":"2025-10-28T08:32:30.477Z","updated_at":"2026-07-01T23:32:33.683Z","avatar_url":"https://github.com/ucphhpc.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"==================\nconfigure-vm-image\n==================\n\n.. image:: https://img.shields.io/pypi/pyversions/configure-vm-image.svg\n    :target: https://img.shields.io/pypi/pyversions/configure-vm-image\n.. image:: https://badge.fury.io/py/configure-vm-image.svg\n    :target: https://badge.fury.io/py/configure-vm-image\n\nThis package can be used for configuring existing virtual machine images.\nVirtual machine images can be either downloaded straight from a distribution provider (see cloud_init_images_) or generated via tools such as the `gen-vm-image \u003chttps://github.com/ucphhpc/gen-vm-image\u003e`_.\n\n------------\nDependencies\n------------\n\nThe following dependencies are required to be installed on the system to use the ``configure-vm-image`` command:\n\n    - `genisoimage \u003chttps://linux.die.net/man/1/genisoimage\u003e`_\n    - `virt-sysprep \u003chttps://linux.die.net/man/1/virt-sysprep\u003e`_\n\nHow to install each of these for a given distribution can be found at `pkgs.org \u003chttps://pkgs.org/\u003e`_.\nDependency install scripts for various distributions can be found in the ``dep`` root directory of this package.\n\n-------\nInstall\n-------\n\nThe tool itself can be installed either via pip::\n\n    pip install configure-vm-image\n\nor by cloning the repository and running the following command in the root directory::\n\n    make install\n\nIf no argument is given to the ``make install`` command, the package will be installed inside a virtual environment called ``venv`` in the root directory of the package.\nThe ``VENV_NAME`` argument can be used to specify a different name for the virtual environment inwhich the package is installed.\n\n-----\nUsage\n-----\n\nUpon installation, the ``configure-vm-image`` command is installed and can be used to configure an existing virtual machine image.\nTo generate such an image, the `gen-vm-image \u003chttps://github.com/ucphhpc/gen-vm-image\u003e`_ tool is available.\n\nTo configure the existing image itself, ``configure-vm-image`` uses the `cloud-init \u003chttps://cloudinit.readthedocs.io/en/latest/index.html\u003e`_ tool to customize the image.\n`cloud-init \u003chttps://cloudinit.readthedocs.io/en/latest/index.html\u003e`_ itself achives this by running a set of scripts upon image boot that utilises a set of preset configuration files.\nThese configuration files includes::\n\n    - user-data\n    - meta-data\n    - vendor-data\n    - network-config\n\n.. _help_output:\n\nTherefore, the ``configure-vm-image`` tool attempts to load each of these files when launched from the given parameter set paths for each of them.\nThe parameter names for these can be discovered by running the command with the ``--help`` flag::\n\n    usage: configure_image.py [-h]\n        [--version]\n        [--image-format CONFIGURE_ARGUMENT_IMAGE_FORMAT]\n        [--config-user-data-path CONFIGURE_ARGUMENT_USER_DATA_PATH]\n        [--config-meta-data-path CONFIGURE_ARGUMENT_META_DATA_PATH]\n        [--config-vendor-data-path CONFIGURE_ARGUMENT_VENDOR_DATA_PATH]\n        [--config-network-config-path CONFIGURE_ARGUMENT_NETWORK_CONFIG_PATH]\n        [--configure-vm-orchestrator CONFIGURE_ARGUMENT_CONFIGURE_VM_ORCHESTRATOR]\n        [--configure-vm-name CONFIGURE_ARGUMENT_CONFIGURE_VM_NAME]\n        [--cloud-init-iso-output-path CONFIGURE_ARGUMENT_CLOUD_INIT_ISO_OUTPUT_PATH]\n        [--configure-vm-log-path CONFIGURE_ARGUMENT_CONFIGURE_VM_LOG_PATH]\n        [--configure-vm-template-path CONFIGURE_ARGUMENT_CONFIGURE_VM_TEMPLATE_PATH]\n        [--configure-vm-template-values KEY=VALUE]\n        [--reset-operations CONFIGURE_ARGUMENT_RESET_OPERATIONS]\n        [--verbose]\n        [--verbose-reset]\n        image_path\n\n        options:\n        -h, --help            show this help message and exit\n        --version, -V         Print the version of the program\n\n        Configure Virtual Machine Image:\n        image_path            The path to the image that is to be configured.\n        --image-format CONFIGURE_ARGUMENT_IMAGE_FORMAT\n                                The format of the image that is to be configured. The tool tries to automatically discover this if not set.\n                                (default: None)\n        --config-user-data-path CONFIGURE_ARGUMENT_USER_DATA_PATH\n                                The path to the cloud-init user-data configuration file.\n                                (default: cloud-init/user-data)\n        --config-meta-data-path CONFIGURE_ARGUMENT_META_DATA_PATH\n                                The path to the cloud-init meta-data configuration file.\n                                (default: cloud-init/meta-data)\n        --config-vendor-data-path CONFIGURE_ARGUMENT_VENDOR_DATA_PATH\n                                The path to the cloud-init vendor-data configuration file.\n                                (default: cloud-init/vendor-data)\n        --config-network-config-path CONFIGURE_ARGUMENT_NETWORK_CONFIG_PATH\n                                The path to the cloud-init network-config configuration file that is used to configure the network settings of the image.\n                                (default: cloud-init/network-config)\n        --configure-vm-orchestrator CONFIGURE_ARGUMENT_CONFIGURE_VM_ORCHESTRATOR, -cv-orch CONFIGURE_ARGUMENT_CONFIGURE_VM_ORCHESTRATOR\n                                The orchestrator to use when provisioning the virtual machine that is used to configure a particular virtual machine image.\n                                (default: libvirt-provider)\n        --configure-vm-name CONFIGURE_ARGUMENT_CONFIGURE_VM_NAME, -cv-name CONFIGURE_ARGUMENT_CONFIGURE_VM_NAME\n                                The name of the VM that is used to configure the image.\n                                (default: configure-vm-image)\n        --cloud-init-iso-output-path CONFIGURE_ARGUMENT_CLOUD_INIT_ISO_OUTPUT_PATH, -ci-output CONFIGURE_ARGUMENT_CLOUD_INIT_ISO_OUTPUT_PATH\n                                The path to the cloud-init output iso image file that is generated based on the data defined in the user-data, meta-data, vendor-data, and network-config files. This seed iso file is then subsequently used to configure the defined input image.\n                                (default: cloud-init/cidata.iso)\n        --configure-vm-log-path CONFIGURE_ARGUMENT_CONFIGURE_VM_LOG_PATH, -cv-log CONFIGURE_ARGUMENT_CONFIGURE_VM_LOG_PATH\n                                The path to the log file that is used to log the output of the configuring VM.\n                                (default: tmp/configure-vm.log)\n        --configure-vm-template-path CONFIGURE_ARGUMENT_CONFIGURE_VM_TEMPLATE_PATH, -cv-tp CONFIGURE_ARGUMENT_CONFIGURE_VM_TEMPLATE_PATH\n                                The path to the template file that is used to configure the VM.\n                                (default: res/configure-vm-template.xml.j2)\n        --configure-vm-template-values KEY=VALUE, -cv-tv KEY=VALUE\n                                An additional set of comma seperated key=value pair arguments that should be passed to the --configure-vm-template-path. If a value contains spaces, you should define it with quotes.\n                                (default: [])\n        --reset-operations CONFIGURE_ARGUMENT_RESET_OPERATIONS, -ro CONFIGURE_ARGUMENT_RESET_OPERATIONS\n                                The operations to perform during the reset operation.\n                                (default: defaults,-ssh-userdir)\n        --verbose, -v         Flag to enable verbose output. (default: False)\n        --verbose-reset, -vr  Flag to enable verbose output during the reset. (default: False)\n\nAs can be gathered from the help output, ``configure-vm-image`` expects that each of these `cloud-init \u003chttps://cloudinit.readthedocs.io/en/latest/index.html\u003e`_ configuration files are present in a ``cloud-init`` directory in the current path when ``configure-vm-image`` is executed.\nIf any of these configuration files are not present, the tool will skip that particular configuration file and continue on even if none are given.\nThis means that the tool can be used to configure an image with only a subset of the configuration files or none at all.\n\n.. _cloud_init_images:\n\n-----------------\nCloud-init Images\n-----------------\n\nMost distributions have a publically available cloud-init image that can be downloaded. A subset highlight of these can be found below.\n\n- `Rocky \u003chttps://download.rockylinux.org/pub/rocky/\u003e`_\n- `Debian \u003chttps://cloud.debian.org/images/cloud/\u003e`_\n- `Ubuntu \u003chttps://cloud-images.ubuntu.com/\u003e`_\n- `Fedora \u003chttps://mirrors.dotsrc.org/fedora-enchilada/linux/releases/39/Cloud/\u003e`_\n\n-------------\nBasic Example\n-------------\n\nIn this example, we will configure an existing virtual machine image with a basic cloud-init configuration.\nThis includes creating a ``default_user`` with sudo capabilities that can authenticate via the console with a password.\nAn example of such configuration can be found in the ``examples/basic-cloud-init`` directory of this package.\nTo use this, we can create a symlink of it in the root directory of the repo::\n\n    ln -s examples/basic-cloud-init cloud-init\n\nSubsequently, you can adjust the configuration files to your liking and in accordance with the `cloud-init \u003chttps://cloudinit.readthedocs.io/en/latest/index.html\u003e`_ documentation.\n\nAfter this has been prepared, \nBut, before we can begin, we need to install the dependencies for the tool::\n    \n    ./dep/\u003cdistro\u003e/install-dep.sh\n\nWith this in place, we can now configure the image by running the following command::\n\n    configure-vm-image \u003cpath_to_image\u003e\n\nThis will both generate a cloud-init ISO image and launch a virtual machine that mounts said ISO and the disk image to be configured.\nUpon launch, the output of the configuring VM will be logged to the log file specified with the ``--configure-vm-log-path`` parameter,\nwhich default can be seen in the ``help`` output above in help_output_. Additional output from the ``configure-vm-image`` tool can also be produced with the ``--verbose`` flag\nas also highlighted in the help output.\n\n\n------------------------\nAdditional Disks Example\n------------------------\n\nBeyond the simple example, where a single disk image is configured, ``configure-vm-image`` can also be used to partition and format additional disks beyond the primary vm image disk.\nThis can be achived by using the ``cloud-init`` feature of `disk_setup \u003chttps://cloudinit.readthedocs.io/en/latest/reference/modules.html#disk-setup\u003e`_ and `fs_setup \u003chttps://cloudinit.readthedocs.io/en/latest/reference/modules.html#disk-setup\u003e`_.\nAn example of such a cloud-init configuration can be found in the ``examples/disk-setup-cloud-init`` directory of this package.\nIn the example, three additional disks are expected to be present in the VM at the specified device paths, namely:\n\n    - /dev/vdb\n    - /dev/vdc\n    - /dev/vdd\n\nTo ensure this, the VM template file (as specified with ``--configure-vm-template``) should be adjusted to include these disks::\n\n    \u003cdevices\u003e\n    ...\n    \u003cdisk type='file' device='disk'\u003e\n        \u003cdriver name='qemu' type='raw'/\u003e\n        \u003csource file='{{disk2_path}}'/\u003e\n        \u003ctarget dev='vdb' bus='virtio'/\u003e\n    \u003c/disk\u003e\n    \u003cdisk type='file' device='disk'\u003e\n        \u003cdriver name='qemu' type='raw'/\u003e\n        \u003csource file='{{disk3_path}}'/\u003e\n        \u003ctarget dev='vdc' bus='virtio'/\u003e\n    \u003c/disk\u003e\n    \u003cdisk type='file' device='disk'\u003e\n        \u003cdriver name='qemu' type='raw'/\u003e\n        \u003csource file='{{disk4_path}}'/\u003e\n        \u003ctarget dev='vdd' bus='virtio'/\u003e\n    \u003c/disk\u003e\n    ...\n    \u003c/devices\u003e\n\nHere it is important to match the target device names with the device paths specified in the cloud-init configuration file.\nAfter this has been prepared, the cloud-init configuration files can be symlinked to the root directory of the repo::\n\n    ln -s examples/disk-setup-cloud-init cloud-init\n\nOnce this is complete, the ``configure-vm-image`` tool can be run with the nessesary template values that specify the paths to the additional disk images::\n\n    configure-vm-image \u003cpath_to_image\u003e --configure-vm-template-values disk2_path=\u003cpath_to_disk2\u003e disk3_path=\u003cpath_to_disk3\u003e disk4_path=\u003cpath_to_disk4\u003e\n\nThis will configure the image with the additional disks as specified in the cloud-init configuration file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucphhpc%2Fconfigure-vm-image","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fucphhpc%2Fconfigure-vm-image","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fucphhpc%2Fconfigure-vm-image/lists"}