{"id":40819733,"url":"https://github.com/cc-api/cvm-image-rewriter","last_synced_at":"2026-01-21T21:46:48.547Z","repository":{"id":239099673,"uuid":"797653297","full_name":"cc-api/cvm-image-rewriter","owner":"cc-api","description":"CVM image customization tool for confidential computing environment","archived":false,"fork":false,"pushed_at":"2025-02-05T08:31:13.000Z","size":49,"stargazers_count":2,"open_issues_count":0,"forks_count":6,"subscribers_count":10,"default_branch":"main","last_synced_at":"2025-02-05T09:30:29.673Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cc-api.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":"2024-05-08T08:58:51.000Z","updated_at":"2025-02-05T08:31:18.000Z","dependencies_parsed_at":"2024-05-10T02:27:05.139Z","dependency_job_id":"65dd215e-d082-4395-9c7d-ab038563731c","html_url":"https://github.com/cc-api/cvm-image-rewriter","commit_stats":null,"previous_names":["cc-api/cvm-image-rewriter"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cc-api/cvm-image-rewriter","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-api%2Fcvm-image-rewriter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-api%2Fcvm-image-rewriter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-api%2Fcvm-image-rewriter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-api%2Fcvm-image-rewriter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cc-api","download_url":"https://codeload.github.com/cc-api/cvm-image-rewriter/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cc-api%2Fcvm-image-rewriter/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28644149,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-21T21:29:11.980Z","status":"ssl_error","status_checked_at":"2026-01-21T21:24:31.872Z","response_time":86,"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":[],"created_at":"2026-01-21T21:46:48.468Z","updated_at":"2026-01-21T21:46:48.538Z","avatar_url":"https://github.com/cc-api.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Confidential VM Customization Tool\n\nThis tool is plugin-based and used to customize the confidential VM guest to meet user-specific requirements and [CIMA](https://github.com/cc-api/container-integrity-measurement-agent) deployment requirements.\n\nIt provides below plugins with different functions supported.\n\n| Name | Descriptions | Required for CIMA deployment |\n| ---- | ------------ | ------------ |\n| 01-resize-image | Resize the input qcow2 image | N |\n| 02-motd-welcome | Customize the login welcome message | N |\n| 03-netplan | Customize the netplan.yaml | N |\n| 04-user-authkey | Add auth key for user login instead of password | N |\n| 05-readonly-data | Fix some file permission to ready-only | N |\n| 06-install-tdx-guest-kernel | Install user-specified TDX guest kernel | Y |\n| 07-device-permission | Set the permission for device node | Y |\n| 08-cima-uds-directory-permission | Set the permission for CIMA UDS directory | Y |\n| 09-cima-vsock-port | Prepare a VM sockets port for CIMA | Y |\n| 60-initrd-update | Update the initrd image | N |\n| 97-sample | Plugin customization example | N |\n| 98-ima-enable-simple | Enable IMA (Integrity Measurement Architecture) feature | N |\n\n\n## How to Run the tool\n\n### Prerequisite\n\n1. This tool has been tested on `Ubuntu 22.04`, `Ubuntu 23.10`, `Ubuntu 24.04` and `Debian 10`. It is recommend to run the tool on the TDX host prepared following [Configuration](https://github.com/cc-api/confidential-cloud-native-primitives?tab=readme-ov-file#configuration).\n\n2. This tool can run on bare metal or within a virtual machine with steps described in the section [Run in Nested VM](#run-in-nested-vm-optional).\n\n3. Please install the following packages on Ubuntu/Debian host.\n\n    ```\n    sudo apt install qemu-utils guestfs-tools virtinst genisoimage libvirt-daemon-system libvirt-daemon\n    ```\n    If `guestfs-tools` is not available in your distribution, you may need to install some additional packages on Debian.\n\n    ```\n    sudo apt-get install guestfsd libguestfs-tools\n    ```\n\n4. Ensure current login user is in the group of libvirt.\n\n    ```\n    sudo usermod -aG libvirt $USER\n    ```\n\n5. Ensure read permission on `/boot/vmlinuz-$(uname-r)`.\n\n    ```\n    sudo chmod o+r /boot/vmlinuz-*\n    ```\n\n6. The version of cloud-init is required \u003e 23.0, so if the host distro could not\nprovide such cloud-init tool, you have to install it manually. For example, on a\ndebian 10 system, the version of default cloud-init is 20.0. Please do following\nsteps:\n    ```\n    wget http://ftp.cn.debian.org/debian/pool/main/c/cloud-init/cloud-init_23.3.1-1_all.deb\n    sudo dpkg -i cloud-init_23.3.1-1_all.deb\n    ```\n\n7. If it is running with `libvirt/virt-daemon` hypervisor, then:\n\n  - In file `/etc/libvirt/qemu.conf`, make sure `user` and `group` is `root` or\n    current user.\n  - If need customize the connection URL, you can specify via `-s` like `-s /var/run/libvirt/libvirt-sock`,\n    please make sure the current user belongs to the libvirt group via the following commands:\n    ```\n    sudo usermod -aG libvirt $USER\n    sudo systemctl daemon-reload\n    sudo systemctl restart libvirtd\n    ```\n\n8. Please start the net `default` for libvirt via:\n\n    ```\n    virsh net-start default\n    ```\n\n### Run the tool\n\nThe tool supports parameters as below.\n```\n$ ./run.sh -h\nUsage: run.sh [OPTION]...\nRequired\n  -i \u003cguest image\u003e          Specify initial guest image file\nOptional\n  -t \u003cnumber of minutes\u003e    Specify the timeout of rewriting, 3 minutes default,\n                            If enabling IMA, recommend timeout \u003e6 minutes\n  -s \u003cconnection socket\u003e    Default connection URI is qemu:///system,\n                            if install libvirt, you can specify to \"/var/run/libvirt/libvirt-sock\"\n                            then the corresponding URI is \"qemu+unix:///system?socket=/var/run/libvirt/libvirt-sock\"\n  -n                        Silent running for virt-install with no output\n  -h                        Show usage\n```\n\nRun below commands to generate an `output.qcow2` under current directory. The default user name is `tdx`. The password is `123456`.\n\nIf you want to skip some plugins, create a file named \"NOT_RUN\" in the directory of the plugin.\n\n```\n# E.g. Skip plugin 98\n$ touch plugins/98-ima-enable-simple/NOT_RUN\n\n# Run the tool with an initial guest image and set timeout as 10 minutes.\n$ ./run.sh -i \u003cinitial guest image\u003e -t 10\n```\n\n**NOTE:**\n  - All plugins need to be executed in numerical order.\n  - Plugin 06, 07, 08 and 09 are required for CIMA deployment.\n  - Plugin 60 requires copying or generating all files to the root directory first. When users customize plugins, please ensure that the plugin number with this requirement is placed before 60.\n  - Plugin 98 needs to be executed after all other plugins have completed. The number of the user-customized plugin must be before 98.\n\n\nAfter the tool is executed successfully, the output will be as below.\n\n```\nSUCCESS: Complete cloud-init...\n...\nSUCCESS: Success to create guest image tools/cvm-image-rewriter/output.qcow2...\n...\nSUCCESS: Complete.\n```\n\n\n### Boot a VM\n\nAfter  is running successfully, you can boot a VM using the generated `output.qcow2` using `qemu-test.sh` or `start-virt.sh`.\n\n- Boot TD or normal VM using `qemu-test.sh`.\n\n  ```\n  # Boot a TD\n  $ sudo ./qemu-test.sh -i output.qcow2 -b grub -q vsock\n\n  # Boot a normal VM\n  $ sudo ./qemu-test.sh -i output.qcow2 -b grub -t efi\n  ```\n\n- Boot TD using `start-virt.sh`.\n\n  ```\n  $ sudo ./start-virt.sh -h\n  Usage: start-virt.sh [OPTION]...\n    -i \u003cguest image file\u003e     Default is tdx-guest-ubuntu22.04.qcow2 under current directory\n    -n \u003cguest name\u003e           Name of TD guest\n    -t \u003ctemplate file\u003e        Default is ./tdx-libvirt-ubuntu-host.xml.template\n    -f                        Force recreate\n    -v \u003cvcpu number\u003e          VM vCPU number\n    -m \u003cmemory size in GB\u003e    VM memory size in GB\n    -h                        Show this help\n  ```\n\n  For example:\n  ```\n  # Boot a TD with specified name and CPU/memory\n  $ sudo ./qemu-test.sh -i output.qcow2 -n \u003clibvirt domain name\u003e -v \u003cvCPU number\u003e -m \u003cmemory size in GiB\u003e\n  ```\n\n### Run in Nested VM (Optional)\n\nThis tool can also be run in a guest VM on the host, in case that users need to prepare a clean host environment.  \n\n1. Enable Nested Virtualization\n\nGiven that some plugins will consume more time in a low-performance guest VM, it is recommended to enable nested virtualization feature on the host.\n\nFirst, check if the nested virtualization is enabled. If the file `/sys/module/kvm_intel/parameters/nested` show `Y` or `1`, it indicates that the feature is enabled. \n\n```\ncat /sys/module/kvm_intel/parameters/nested\n```\n\nIf the feature is not enabled, create the file ` /etc/modprobe.d/kvm.conf`, appending `options kvm_intel nested=1` to it and reboot the host.\n\n```\necho \"options kvm_intel nested=1\" \u003e /etc/modprobe.d/kvm.conf\n```\n\n2. Launch the guest VM\n\nWhen we launch the guest VM, it is recommended to allocate more than `8G` memory for the guest VM, because this tool will occupy at least `4G` memory. And more CPU cores will improve the guest VM performance, typically the number of CPU cores is at least `4`.\n\n3. Install dependencies\n\nAt last, install dependencies in the guest VM before running this tools.\n\nIt is an example for a basic Ubuntu 22.04 guest VM.\n\n```\nsudo apt install qemu-utils libguestfs-tools virtinst genisoimage cloud-init qemu-kvm libvirt-daemon-system\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcc-api%2Fcvm-image-rewriter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcc-api%2Fcvm-image-rewriter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcc-api%2Fcvm-image-rewriter/lists"}