{"id":14155593,"url":"https://github.com/pmem/run_qemu","last_synced_at":"2025-09-05T20:40:27.331Z","repository":{"id":37884937,"uuid":"345753726","full_name":"pmem/run_qemu","owner":"pmem","description":"A script to create bootable OS images, and run qemu with a locally built kernel.","archived":false,"fork":false,"pushed_at":"2025-06-13T14:30:30.000Z","size":238,"stargazers_count":69,"open_issues_count":12,"forks_count":28,"subscribers_count":14,"default_branch":"main","last_synced_at":"2025-09-01T11:25:33.767Z","etag":null,"topics":["linux","linux-kernel","mkosi","qemu"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"cc0-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pmem.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":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-03-08T18:22:31.000Z","updated_at":"2025-08-17T20:17:02.000Z","dependencies_parsed_at":"2023-11-07T04:02:44.482Z","dependency_job_id":"efbeecc6-d5ce-472c-853e-6b9112b4e80e","html_url":"https://github.com/pmem/run_qemu","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pmem/run_qemu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmem%2Frun_qemu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmem%2Frun_qemu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmem%2Frun_qemu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmem%2Frun_qemu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pmem","download_url":"https://codeload.github.com/pmem/run_qemu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pmem%2Frun_qemu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273817454,"owners_count":25173612,"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","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"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":["linux","linux-kernel","mkosi","qemu"],"created_at":"2024-08-17T08:04:10.996Z","updated_at":"2025-09-05T20:40:27.307Z","avatar_url":"https://github.com/pmem.png","language":"Shell","funding_links":[],"categories":["linux"],"sub_categories":[],"readme":"# Requirements\n - mkosi\n   - e.g. `dnf install mkosi`\n - `qemu-system-x86_64`\n - rsync\n - dracut\n - enabled virtualization (KVM)\n - nopasswd sudo preferred, or run as root, or enter passwords into the prompt\n several times\n - `argbash` to generate the argument parser lib (using `parser_generator.m4`)\n\n## mkosi\n\nFinding an mkosi version compatible with your operating system version and\nparticular test configuration can sometimes be challenging. First, try the\nversion packaged with your operating system. This will indirectly install\nmkosi dependencies (which have surprisingly not changed that much across\nmkosi versions). If that OS-provided mkosi version does not work for you,\ncheck the long mkosi section below.\n\n# Installation\n - symlink the `run_qemu.sh` script into somewhere in your `PATH`\n   - e.g. `ln -s ~/git/run_qemu/run_qemu.sh ~/bin/run_qemu.sh`\n - **Note:** Supporting files in this repo are required to be in the same\n   location as the script, after any symlink resolution. Copying just the\n   script itself will not work.\n - **Bash Completion**\n   - Copy or symlink the `run_qemu` file into the default bash completions dir\n   - The completions directory can be found using:\n       `pkg-config --variable=completionsdir bash-completion`\n\n\n# Usage Notes\n - Run this from the top level of a Linux kernel tree\n   - e.g. `run_qemu.sh --cxl --git-qemu`\n - The script can/will:\n   - Build the kernel with whatever .config is present\n     (It is up to the user to manage the .config)\n   - Create a rootfs image with the chosen distro using `mkosi`\n   - Perform some basic setup on the rootfs, including installing the kernel,\n     utilities (such as `ndctl`), and other convenience operations such as\n     copying `.ssh/*.pub` keys for easy access, and your `~/.bashrc`\n     etc.\n   - Boot qemu with the newly compiled kernel provided on the qemu command line,\n     and using the rootfs image above\n   - Various options influence the qemu command line generated - there are\n     options to select NUMA config, NVDIMMs, NVME devices, CXL devices etc.\n - More detailed CLI help is available with `run_qemu.sh --help`\n - Once qemu starts, in nographic mode, the Linux console 'takes over' the\n   terminal. To interact with it, the following are useful:\n   - `Ctrl-a c` : switch between the qemu monitor prompt `(qemu)` and console\n   - `Ctrl-a x` : kill qemu and exit\n - `mkosi` creates a package cache in `mkosi.cache/`  If a cache is present,\n   it will always use only that, and never go over the network even if newer\n   packages are available. To force re-fetching everything, remove this\n   directory, or --rebuild=wipe which removes the `builddir` entirely.\n - Which `qemu` to use can be overridden from the environment:\n       `qemu=/path/to/qemu/build/qemu-system-x86_64 ./run_qemu.sh [options]`\n - List of variables that have overrides via `env`:\n     - `qemu`\n     - `gdb`\n     - `distro`\n     - `rev`\n     - `builddir`\n     - `ndctl`\n - To use the 'hostfwd' network, put this in your `.ssh/config`:\n\n       Host rq\n         Hostname localhost\n         User root\n         Port 10022\n         StrictHostKeyChecking no\n         UserKnownHostsFile /dev/null\n\n    And then `ssh rq`. You may need to open port 10022 on any local firewalls.\n - The root password for the guest VM is `root` by default but note many Linux\n   distributions restrict remote root access in various ways. The serial console\n   automatically logs in, and a password isn't required.\n\n## CXL Usage\n\nThe script enables generating a sane QEMU commandline for instantiating a basic CXL topology. Since QEMU support for CXL isn't yet upstream, `--git-qemu` is additionally required. The CXL related options are:\n- `--cxl`: Enables a simple CXL topology with:\n  - single host bridge\n    - 512M window size at 0x4c00000000\n    - Bus #52\n  - single root port\n  - single Type 3 device\n    - Persistent 256M\n  - simple label storage area\n- --cxl-debug: Add any and all flags for extra debug (kernel and QEMU)\n- --cxl-hb: Turn q35 into a CXL capable Host bridge. Don't use this option unless you're working on support for this.\n- --cxl-test-run: Attempt to do a sanity test of the kernel and QEMU configuration.\n\n## DAX Usage\n\n- --dax-debug: Add any and all flags for extra debug of dax modules (kernel)\n\n### Kernel config\n- Make sure to Turn on CXL related options in the kernel's .config:\n```\n$ grep -i cxl .config\nCONFIG_CXL_BUS=y\nCONFIG_CXL_PCI=m\nCONFIG_CXL_MEM_RAW_COMMANDS=y\nCONFIG_CXL_ACPI=m\nCONFIG_CXL_PMEM=m\nCONFIG_CXL_MEM=m\nCONFIG_CXL_PORT=y\nCONFIG_CXL_SUSPEND=y\n```\n\nThe following is a way to check basic sanity within the QEMU guest:\n```shell\nlspci  | grep '3[45]:00'\n34:00.0 PCI bridge: Intel Corporation Device 7075\n35:00.0 Memory controller [0502]: Intel Corporation Device 0d93 (rev 01)\n\nreadlink -f /sys/bus/cxl/devices/mem0\n/sys/devices/pci0000:34/0000:34:00.0/0000:35:00.0/mem0\n```\n\n# mkosi\n\n## run mkosi from source\n\nThere are many variables (OS distro and version for host and build\nmachine, mkosi version, python dependencies,...) and no solution works\nin every situation. `pipx` offers a relatively good compatibility and\nsimplicity trade-off, so it is explained first and in most detail but\nif this does not work then there are alternatives mentioned below.\n\n```\nsudo dnf install mkosi\nsudo dnf remove --noautoremove mkosi # keep mkosi dependencies installed\ngit clone https://github.com/systemd/mkosi\ncd mkosi\n# Make sure everything is clean when re-using an existing clone\ngit status --ignored\npipx install --system-site-packages --editable .\npipx list\nmkosi --version\nexport mkosi_bin=$(type -ap mkosi)\n```\n\nDefining `mkosi_bin` is required because `run_qemu.sh` runs mkosi as root\n(`sudo $mkosi_bin`) but `pipx` installs in a subdirectory of your\n`$HOME` which is not in root's `PATH`. Installing mkosi as root is not\nrecommended and does not even work for various, complex reasons.\n\nIf you get a \"module mkosi not found\" error with some mkosi versions, define\n`$mkosi_bin` like this instead:\n```\nexport mkosi_bin=\"$HOME\"/.local/share/pipx/venvs/mkosi/bin/mkosi\n\"$mkosi_bin\" --version\n```\n\nTo select a specific `mkosi` release:\n\n```\n$ cd mkosi\n$ git checkout vNN # where vNN is the release desired\n```\n\nThanks to the `--editable` option, there's no need to re-run `pipx` when\nusing git to switch between different mkosi versions... **unless** some\nmkosi dependencies change! If you experience any mkosi error or have any\ndoubt then use `pipx` to `uninstall` and re-install.\n\nAlternatively, can try to add `mkosi/bin/mkosi` to your PATH or a create a\nsymlink to it instead of using `pipx`. This seems to work with mkosi\nreleases v15 and above.\n\n`mkosi/README.md` describes more installation alternatives. Note they can\ndiffer across mkosi versions.\n\n\n## mkosi v15+ (Fedora 39+)\n\nmkosi v15 made a lot of backwards-incompatible changes. run_qemu has\nconfiguration files for both mkosi v14- and mkosi v15+ now but please\nreport any bug.\n\nTo mitigate this, Fedora 40 packages both mkosi 14 and 22. So, it is not\nrequired to clone and and run mkosi from source to switch between these\ntwo versions. Instead:\n\n```\n# dnf remove --noautoremove mkosi\n# dnf install mkosi14\n```\n\nFedora 41 has stopped packaging mkosi14.\n\n\n### mkosi configuration files in run_qemu\n\nFortunately, the location of mkosi configuration files changed at the same\nv15 time. So `run_qemu.sh` creates a different mkosi configuration folder depending\non which mkosi version is detected: `qbuild/mkosi.default.d/*.conf` for\nversion 14 and before versus  `qbuild/mkosi.conf.d/*.conf` for version 15\nand above.\n\nWhile no such major break of backwards compatibility has happened after v15\n(yet?), mkosi development is very fast-paced. Various Linux distributions come\nwith various mkosi versions. So try to keep mkosi configuration(s) as simple as\npossible to avoid accidentally breaking someone else using a different mkosi\nversion. Rely on mkosi default values as much as possible.\n\nFortunately, most mkosi versions are thoroughly documented and you can\neasily check the documentation of any version without installing anything.\n\n- For versions 14 and before, use this syntax:\n  https://github.com/systemd/mkosi/blob/v14/man/mkosi.1\n- For versions between 15 and 24 go to:\n  https://github.com/systemd/mkosi/blob/v15/mkosi/resources/mkosi.md\n- For versions 25 and above:\n  https://github.com/systemd/mkosi/blob/v25/mkosi/resources/man/mkosi.1.md\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmem%2Frun_qemu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpmem%2Frun_qemu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpmem%2Frun_qemu/lists"}