├── .editorconfig ├── .envrc ├── .github ├── FUNDING.yml ├── ISSUE_TEMPLATE │ ├── bug_report.md │ └── feature_request.md ├── Logo.bmp ├── apple.png ├── dependabot.yml ├── logo.png ├── pull_request_template.md ├── tux.png └── workflows │ ├── flake-checker.yml │ ├── flake-updater.yml │ ├── lint-pr.yml │ ├── lint-shellcheck.yml │ ├── publish-release.yml │ ├── test-build-quickemu.yml │ └── test-quickget.yml ├── .gitignore ├── .gitmodules ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── LICENSE ├── README.md ├── SECURITY.md ├── chunkcheck ├── debian ├── changelog ├── control ├── copyright ├── install ├── rules └── source │ └── format ├── devshell.nix ├── docs ├── Makefile ├── pandoc-man.mk ├── quickemu.1 ├── quickemu.1.md ├── quickemu_conf.5 ├── quickemu_conf.5.md ├── quickget.1 └── quickget.1.md ├── flake.lock ├── flake.nix ├── package.nix ├── quickemu ├── quickget └── quickreport /.editorconfig: -------------------------------------------------------------------------------- 1 | root = true 2 | 3 | [quickemu] 4 | charset = utf-8 5 | end_of_line = lf 6 | insert_final_newline = true 7 | indent_style = space 8 | indent_size = 2 9 | trim_trailing_whitespace = true 10 | 11 | [quickget] 12 | charset = utf-8 13 | end_of_line = lf 14 | insert_final_newline = true 15 | indent_style = space 16 | indent_size = 4 17 | trim_trailing_whitespace = true 18 | 19 | [*.md] 20 | trim_trailing_whitespace = false 21 | -------------------------------------------------------------------------------- /.envrc: -------------------------------------------------------------------------------- 1 | use flake -------------------------------------------------------------------------------- /.github/FUNDING.yml: -------------------------------------------------------------------------------- 1 | # These are supported funding model platforms 2 | 3 | github: [flexiondotorg, philclifford, lj3954] 4 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/bug_report.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Bug report 3 | about: Create a report to help us improve 4 | title: 'bug: description of the bug you encountered' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **I confirm this bug has not already been reported** 11 | - [ ] I have searched the issues and this bug has not been reported previously 12 | 13 | **Describe the bug** 14 | A clear and concise description of what the bug is. 15 | 16 | **To Reproduce** 17 | Steps to reproduce the behaviour: 18 | 1. Run `quickemu` with arguments '...' 19 | 2. See error 20 | 21 | **Expected behaviour** 22 | A clear and concise description of what you expected to happen. 23 | 24 | **Quickemu output** 25 | Run `quickemu` or `quickemu` and include the output of the failure below: 26 | 27 |
28 | Quickemu output 29 | 30 | ```text 31 | quickemu/quickget output here 32 | ``` 33 |
34 | 35 | **System information** 36 | Run `quickreport` and include the output here; if you can't run `quickreport`, 37 | please provide the output of the following: 38 | 39 |
40 | Quickreport output 41 | 42 | ```text 43 | quickreport output here 44 | ``` 45 |
46 | 47 | **Screenshots** 48 | If applicable, add screenshots to help explain your problem. 49 | 50 | **Additional context** 51 | Add any other context about the problem here. 52 | -------------------------------------------------------------------------------- /.github/ISSUE_TEMPLATE/feature_request.md: -------------------------------------------------------------------------------- 1 | --- 2 | name: Feature request 3 | about: Suggest an idea for this project 4 | title: 'feat: describe the feature you are requesting' 5 | labels: '' 6 | assignees: '' 7 | 8 | --- 9 | 10 | **I confirm this feature has not been previously requested** 11 | - [ ] I have searched the issues and this feature has not previously been requested 12 | 13 | **Is your feature request related to a problem? Please describe.** 14 | A clear and concise description of what the problem is. Ex. I'm always frustrated when [...] 15 | 16 | **Describe the solution you'd like** 17 | A clear and concise description of what you want to happen. 18 | 19 | **Describe alternatives you've considered** 20 | A clear and concise description of any alternative solutions or features you've considered. 21 | 22 | **Additional context** 23 | Add any other context or screenshots about the feature request here. 24 | -------------------------------------------------------------------------------- /.github/Logo.bmp: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/quickemu-project/quickemu/c6c75e6550b19237d6ed3f3eede845f23a5c85ab/.github/Logo.bmp -------------------------------------------------------------------------------- /.github/apple.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/quickemu-project/quickemu/c6c75e6550b19237d6ed3f3eede845f23a5c85ab/.github/apple.png -------------------------------------------------------------------------------- /.github/dependabot.yml: -------------------------------------------------------------------------------- 1 | version: 2 2 | updates: 3 | - package-ecosystem: "github-actions" 4 | directory: "/" 5 | schedule: 6 | # Check for updates to GitHub Actions every week 7 | interval: "weekly" -------------------------------------------------------------------------------- /.github/logo.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/quickemu-project/quickemu/c6c75e6550b19237d6ed3f3eede845f23a5c85ab/.github/logo.png -------------------------------------------------------------------------------- /.github/pull_request_template.md: -------------------------------------------------------------------------------- 1 | # Description 2 | 3 | Please include a summary of the changes along with any relevant motivation and context. 4 | 5 | 6 | 7 | - Closes # 8 | - Fixes # 9 | - Resolves # 10 | 11 | ## Type of change 12 | 13 | 14 | 15 | - [ ] Bug fix (non-breaking change which fixes an issue) 16 | - [ ] New feature (non-breaking change which adds functionality) 17 | - [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected) 18 | - [ ] Packaging (updates the packaging) 19 | - [ ] Documentation (updates the documentation) 20 | 21 | # Checklist: 22 | 23 | - [ ] I have performed a self-review of my code 24 | - [ ] I have tested my code in common scenarios and confirmed there are no regressions 25 | - [ ] I have added comments to my code, particularly in hard-to-understand sections 26 | - [ ] I have made corresponding changes to the documentation (*remove if no documentation changes were required*) 27 | -------------------------------------------------------------------------------- /.github/tux.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/quickemu-project/quickemu/c6c75e6550b19237d6ed3f3eede845f23a5c85ab/.github/tux.png -------------------------------------------------------------------------------- /.github/workflows/flake-checker.yml: -------------------------------------------------------------------------------- 1 | name: Flake ❄️ Checker ✅ 2 | 3 | on: 4 | push: 5 | branches: 6 | - master 7 | schedule: 8 | - cron: '42 0 * * 6' 9 | workflow_dispatch: 10 | 11 | jobs: 12 | flake-checker: 13 | name: Flake Checker 14 | runs-on: ubuntu-22.04 15 | steps: 16 | - uses: actions/checkout@v4 17 | with: 18 | fetch-depth: 0 19 | - uses: DeterminateSystems/nix-installer-action@v17 20 | - uses: DeterminateSystems/magic-nix-cache-action@v9 21 | - uses: DeterminateSystems/flake-checker-action@v9 22 | -------------------------------------------------------------------------------- /.github/workflows/flake-updater.yml: -------------------------------------------------------------------------------- 1 | name: Flake ❄️ Lock 🔒️ Updater ✨ 2 | 3 | on: 4 | schedule: 5 | - cron: '37 13 14,28 * *' 6 | workflow_dispatch: 7 | 8 | jobs: 9 | lock-updater: 10 | name: Flake Lock Updater 11 | runs-on: ubuntu-22.04 12 | steps: 13 | - uses: actions/checkout@v4 14 | with: 15 | fetch-depth: 0 16 | - uses: DeterminateSystems/nix-installer-action@v17 17 | - uses: DeterminateSystems/magic-nix-cache-action@v9 18 | - uses: DeterminateSystems/update-flake-lock@v25 19 | with: 20 | pr-title: "chore: update flake.lock" 21 | -------------------------------------------------------------------------------- /.github/workflows/lint-pr.yml: -------------------------------------------------------------------------------- 1 | name: "Lint Pull Request 🐙" 2 | 3 | on: 4 | pull_request_target: 5 | types: 6 | - opened 7 | - edited 8 | - synchronize 9 | 10 | permissions: 11 | pull-requests: read 12 | 13 | jobs: 14 | main: 15 | name: Validate pull request title 16 | runs-on: ubuntu-22.04 17 | steps: 18 | - uses: amannn/action-semantic-pull-request@v5 19 | env: 20 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 21 | with: 22 | # If the PR only contains a single commit, the action will validate that 23 | # it matches the configured pattern. 24 | validateSingleCommit: true 25 | # Related to `validateSingleCommit` you can opt-in to validate that the PR 26 | # title matches a single commit to avoid confusion. 27 | validateSingleCommitMatchesPrTitle: true 28 | -------------------------------------------------------------------------------- /.github/workflows/lint-shellcheck.yml: -------------------------------------------------------------------------------- 1 | name: "Lint Shellcheck 🐚" 2 | 3 | on: 4 | pull_request: 5 | branches: '**' 6 | workflow_dispatch: 7 | 8 | jobs: 9 | shellcheck: 10 | name: Shellcheck 11 | runs-on: ubuntu-22.04 12 | steps: 13 | - uses: actions/checkout@v4 14 | - name: Run ShellCheck 15 | uses: ludeeus/action-shellcheck@master 16 | with: 17 | format: gcc 18 | severity: warning 19 | -------------------------------------------------------------------------------- /.github/workflows/publish-release.yml: -------------------------------------------------------------------------------- 1 | name: Publish Release 🏷️ 2 | 3 | on: 4 | push: 5 | tags: 6 | - "v?[0-9]+.[0-9]+.[0-9]+*" 7 | workflow_dispatch: 8 | inputs: 9 | tag: 10 | description: "The existing tag to publish" 11 | type: "string" 12 | required: true 13 | 14 | jobs: 15 | version-check: 16 | name: "Check versions ⚖️" 17 | runs-on: ubuntu-22.04 18 | steps: 19 | - uses: actions/checkout@v4 20 | with: 21 | fetch-depth: 0 22 | - name: "Compare App and Git versions 🟰" 23 | env: 24 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 25 | run: | 26 | APP_VERSION=$(grep "^readonly VERSION" quickemu | cut -d'"' -f2) 27 | GIT_VERSION=$(git describe --tags | cut -d'-' -f1) 28 | echo "App version: ${REL_VERSION}" 29 | echo "Git version: ${GIT_VERSION}" 30 | if [ "${APP_VERSION}" != "${GIT_VERSION}" ]; then 31 | echo "ERROR! Version mismatch."; 32 | exit 1 33 | fi 34 | 35 | draft-release: 36 | needs: [version-check] 37 | name: "Draft Release 📥️" 38 | runs-on: ubuntu-22.04 39 | steps: 40 | - uses: actions/checkout@v4 41 | - name: Create release ${{ github.ref }} as a draft 42 | env: 43 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 44 | run: | 45 | gh release create "${{ github.ref }}" --draft --generate-notes 46 | 47 | build-release: 48 | needs: [draft-release] 49 | name: "Build Release 👨‍🔧" 50 | runs-on: ubuntu-22.04 51 | steps: 52 | - uses: actions/checkout@v4 53 | - name: Build and Upload .deb 54 | env: 55 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 56 | run: | 57 | sudo apt-get -y update 58 | sudo apt-get -y install debhelper devscripts 59 | REL_VER=$(grep "^readonly VERSION" quickemu | cut -d'"' -f2) 60 | rm debian/changelog 61 | dch --package quickemu --newversion="${REL_VER}-1" --distribution=unstable "New upstream release." --create 62 | dpkg-buildpackage --build=binary --no-check-builddeps --compression=gzip 63 | gh release upload "${{ github.ref }}" "../quickemu_${REL_VER}-1_all.deb" --clobber 64 | 65 | publish-release: 66 | needs: [build-release] 67 | name: "Publish Release 📤️" 68 | runs-on: ubuntu-22.04 69 | steps: 70 | - uses: actions/checkout@v4 71 | - name: Publish release ${{ github.ref }} 72 | env: 73 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 74 | run: | 75 | if [ "$(gh release view "${{ github.ref }}" --json assets --template '{{len .assets}}')" -lt 0 ]; then 76 | exit 1 77 | fi 78 | gh release edit "${{ github.ref }}" --draft=false 79 | 80 | publish-flakehub: 81 | needs: [version-check] 82 | name: "Publish FlakeHub ❄️" 83 | runs-on: "ubuntu-22.04" 84 | permissions: 85 | id-token: "write" 86 | contents: "read" 87 | steps: 88 | - uses: "actions/checkout@v4" 89 | with: 90 | ref: "${{ (inputs.tag != null) && format('refs/tags/{0}', inputs.tag) || '' }}" 91 | - uses: "DeterminateSystems/nix-installer-action@main" 92 | - uses: "DeterminateSystems/magic-nix-cache-action@main" 93 | - uses: "DeterminateSystems/flakehub-push@main" 94 | with: 95 | visibility: "public" 96 | name: "quickemu-project/quickemu" 97 | tag: "${{ inputs.tag }}" 98 | 99 | publish-ppa: 100 | needs: [version-check] 101 | name: "Publish PPA 📦️" 102 | runs-on: ubuntu-22.04 103 | steps: 104 | - name: "Checkout 🥡" 105 | uses: actions/checkout@v4 106 | env: 107 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 108 | - name: "Import gpg key 🔑" 109 | uses: crazy-max/ghaction-import-gpg@v6 110 | with: 111 | gpg_private_key: ${{ secrets.PPA_GPG_PRIVATE_KEY }} 112 | passphrase: ${{ secrets.PPA_GPG_PASSPHRASE }} 113 | - name: "Install dependencies 💾" 114 | run: | 115 | sudo apt-get -y update 116 | sudo apt-get -y install debhelper-compat distro-info dput devscripts 117 | - name: "Upload to PPA ⤴️" 118 | env: 119 | DEBEMAIL: ${{ secrets.DEBEMAIL }} 120 | DEBFULLNAME: ${{ secrets.DEBFULLNAME }} 121 | run: | 122 | REL_VER=$(grep "^readonly VERSION" quickemu | cut -d'"' -f2) 123 | STAMP=$(date +%y%j.%H%M) 124 | for CODENAME in $(distro-info --supported); do 125 | rm debian/changelog 126 | dch --package quickemu --newversion="${REL_VER}-1~${CODENAME}${STAMP}" --distribution=${CODENAME} "New upstream release." --create 127 | dpkg-buildpackage -d -S -sa 128 | dput ppa:flexiondotorg/quickemu ../quickemu_${REL_VER}-1~${CODENAME}${STAMP}_source.changes 129 | done 130 | -------------------------------------------------------------------------------- /.github/workflows/test-build-quickemu.yml: -------------------------------------------------------------------------------- 1 | name: Test build quickemu 🚧 2 | 3 | on: 4 | pull_request: 5 | branches: 6 | - master 7 | paths: 8 | - quickemu 9 | - quickget 10 | - debian/** 11 | - flake.nix 12 | - package.nix 13 | push: 14 | branches: 15 | - master 16 | paths: 17 | - quickemu 18 | - quickget 19 | - debian/** 20 | - flake.nix 21 | - package.nix 22 | workflow_dispatch: 23 | 24 | # TODO: arm64 runner 25 | # https://github.blog/changelog/2024-06-03-actions-arm-based-linux-and-windows-runners-are-now-in-public-beta/ 26 | 27 | jobs: 28 | test-deb-build: 29 | runs-on: ubuntu-22.04 30 | steps: 31 | - name: "Checkout 🥡" 32 | uses: actions/checkout@v4 33 | - name: "Build & Test .deb 🍥" 34 | env: 35 | GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} 36 | run: | 37 | sudo apt-get -y update 38 | sudo apt-get -y install debhelper devscripts 39 | REL_VER=$(grep "^readonly VERSION" quickemu | cut -d'"' -f2) 40 | rm debian/changelog 41 | dch --package quickemu --newversion="${REL_VER}-1" --distribution=unstable "New upstream release." --create 42 | dpkg-buildpackage --build=binary --no-check-builddeps --compression=gzip 43 | sudo apt-get -y install ../quickemu_${REL_VER}-1_all.deb 44 | quickemu --help 45 | quickget --help 46 | 47 | test-nix-build: 48 | runs-on: ubuntu-22.04 49 | permissions: 50 | id-token: "write" 51 | contents: "read" 52 | steps: 53 | - name: "Checkout 🥡" 54 | uses: "actions/checkout@v4" 55 | - name: "Install Nix ❄️" 56 | uses: "DeterminateSystems/nix-installer-action@v17" 57 | - name: "Enable Magic Nix Cache 🪄" 58 | uses: "DeterminateSystems/magic-nix-cache-action@v9" 59 | - name: "Build & Test .nix ❄️" 60 | run: | 61 | nix build .#quickemu 62 | tree ./result 63 | ./result/bin/quickemu --help 64 | ./result/bin/quickget --help 65 | ./result/bin/quickreport 66 | # Text a VM if the Nix Installer successfully enabled KVM 67 | if [ $DETERMINATE_NIX_KVM -eq 1 ]; then 68 | ./result/bin/quickget alpine v3.20 69 | ./result/bin/quickemu --vm alpine-v3.20.conf --display none 70 | sleep 5 71 | if pgrep -F ./alpine-v3.20/alpine-v3.20.pid; then 72 | echo "Test VM is running" 73 | else 74 | echo "Test VM is not running" 75 | exit 1 76 | fi 77 | # Test a few more quickemu commands to clean up 78 | ./result/bin/quickemu --vm alpine-v3.20.conf --kill 79 | ./result/bin/quickemu --vm alpine-v3.20.conf --delete-disk 80 | ./result/bin/quickemu --vm alpine-v3.20.conf --delete-vm 81 | fi 82 | 83 | -------------------------------------------------------------------------------- /.github/workflows/test-quickget.yml: -------------------------------------------------------------------------------- 1 | name: "Test quickget 🧪" 2 | 3 | on: 4 | workflow_dispatch: 5 | push: 6 | branches: 7 | - master 8 | paths: 9 | - quickget 10 | pull_request: 11 | branches: 12 | - '**' 13 | paths: 14 | - quickget 15 | 16 | jobs: 17 | quickget-tests: 18 | name: "Run quickget tests 👟" 19 | runs-on: ubuntu-22.04 20 | steps: 21 | - uses: actions/checkout@v4 22 | - name: "Install dependencies 📦️" 23 | run: | 24 | sudo apt-get -y update 25 | sudo apt-get -y install curl qemu-utils 26 | - name: "List OS variants 📃" 27 | run: | 28 | mkdir -p results 29 | ./quickget --list | tail -n +2 | tee results/list.txt 30 | - name: "Check OS downloads 💿️" 31 | run: | 32 | mkdir -p results 33 | ./quickget --check | tee results/check.txt 34 | - name: "Display results 📊" 35 | run: | 36 | WINDOWS=$(grep -c "windows-" results/check.txt) 37 | FAILED=$(grep -c ^FAIL results/check.txt) 38 | SKIPPED=$(grep -c ^SKIP results/check.txt) 39 | PASSED=$(grep -c ^PASS results/check.txt) 40 | CHECKED=$((WINDOWS + FAILED + SKIPPED + PASSED)) 41 | echo -e "\nResults:" 42 | echo -e "- CHECKED:\t${CHECKED}" 43 | echo -e "- PASSED:\t${PASSED}" 44 | echo -e "- SKIPPED:\t${SKIPPED}\t(of which ${WINDOWS} are Windows)" 45 | echo -e "- FAILED:\t${FAILED}\n" 46 | grep ^FAIL results/check.txt | tee results/failed.txt 47 | VARIATIONS=$(wc -l results/list.txt | cut -d' ' -f 1) 48 | DOWNLOADS=$(wc -l results/check.txt | cut -d' ' -f 1) 49 | echo 50 | echo "Compare OS variations with downloads:" 51 | echo -e "- Variations:\t${VARIATIONS}" 52 | echo -e "- Downloads:\t${DOWNLOADS}" 53 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | *.chunklist 2 | *.conf 3 | *.dmg 4 | *.fd 5 | *.fixed 6 | *.img 7 | *.iso 8 | *.ISO 9 | *.lock 10 | !flake.lock 11 | *.log 12 | *.markdownlint.jsonc 13 | *.markdownlint.yaml 14 | *.msi 15 | *.part 16 | *.permall 17 | *.pid 18 | *.ports 19 | *.qcow2 20 | *.sh 21 | *.sock 22 | *.xml 23 | *.zs-old 24 | .direnv/ 25 | -------------------------------------------------------------------------------- /.gitmodules: -------------------------------------------------------------------------------- 1 | [submodule "build-docs"] 2 | path = build-docs 3 | url = https://github.com/philclifford/quickemu-docs.git 4 | -------------------------------------------------------------------------------- /CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Contributor Covenant Code of Conduct 2 | 3 | ## Our Pledge 4 | 5 | We as members, contributors, and leaders pledge to make participation in our 6 | community a harassment-free experience for everyone, regardless of age, body 7 | size, visible or invisible disability, ethnicity, sex characteristics, gender 8 | identity and expression, level of experience, education, socio-economic status, 9 | nationality, personal appearance, race, religion, or sexual identity 10 | and orientation. 11 | 12 | We pledge to act and interact in ways that contribute to an open, welcoming, 13 | diverse, inclusive, and healthy community. 14 | 15 | ## Our Standards 16 | 17 | Examples of behaviour that contributes to a positive environment for our 18 | community include: 19 | 20 | * Demonstrating empathy and kindness toward other people 21 | * Being respectful of differing opinions, viewpoints, and experiences 22 | * Giving and gracefully accepting constructive feedback 23 | * Accepting responsibility and apologizing to those affected by our mistakes, 24 | and learning from the experience 25 | * Focusing on what is best not just for us as individuals, but for the 26 | overall community 27 | 28 | Examples of unacceptable behaviour include: 29 | 30 | * The use of sexualized language or imagery, and sexual attention or 31 | advances of any kind 32 | * Trolling, insulting or derogatory comments, and personal or political attacks 33 | * Public or private harassment 34 | * Publishing others' private information, such as a physical or email 35 | address, without their explicit permission 36 | * Other conduct which could reasonably be considered inappropriate in a 37 | professional setting 38 | 39 | ## Enforcement Responsibilities 40 | 41 | Community leaders are responsible for clarifying and enforcing our standards of 42 | acceptable behaviour and will take appropriate and fair corrective action in 43 | response to any behaviour that they deem inappropriate, threatening, offensive, 44 | or harmful. 45 | 46 | Community leaders have the right and responsibility to remove, edit, or reject 47 | comments, commits, code, wiki edits, issues, and other contributions that are 48 | not aligned to this Code of Conduct, and will communicate reasons for moderation 49 | decisions when appropriate. 50 | 51 | ## Scope 52 | 53 | This Code of Conduct applies within all community spaces, and also applies when 54 | an individual is officially representing the community in public spaces. 55 | Examples of representing our community include using an official e-mail address, 56 | posting via an official social media account, or acting as an appointed 57 | representative at an online or offline event. 58 | 59 | ## Enforcement 60 | 61 | Instances of abusive, harassing, or otherwise unacceptable behaviour may be 62 | reported to the community leaders responsible for enforcement at 63 | #quickemu channel on Discord. 64 | All complaints will be reviewed and investigated promptly and fairly. 65 | 66 | All community leaders are obligated to respect the privacy and security of the 67 | reporter of any incident. 68 | 69 | ## Enforcement Guidelines 70 | 71 | Community leaders will follow these Community Impact Guidelines in determining 72 | the consequences for any action they deem in violation of this Code of Conduct: 73 | 74 | ### 1. Correction 75 | 76 | **Community Impact**: Use of inappropriate language or other behaviour deemed 77 | unprofessional or unwelcome in the community. 78 | 79 | **Consequence**: A private, written warning from community leaders, providing 80 | clarity around the nature of the violation and an explanation of why the 81 | behaviour was inappropriate. A public apology may be requested. 82 | 83 | ### 2. Warning 84 | 85 | **Community Impact**: A violation through a single incident or series 86 | of actions. 87 | 88 | **Consequence**: A warning with consequences for continued behaviour. No 89 | interaction with the people involved, including unsolicited interaction with 90 | those enforcing the Code of Conduct, for a specified period of time. This 91 | includes avoiding interactions in community spaces as well as external channels 92 | like social media. Violating these terms may lead to a temporary or 93 | permanent ban. 94 | 95 | ### 3. Temporary Ban 96 | 97 | **Community Impact**: A serious violation of community standards, including 98 | sustained inappropriate behaviour. 99 | 100 | **Consequence**: A temporary ban from any sort of interaction or public 101 | communication with the community for a specified period of time. No public or 102 | private interaction with the people involved, including unsolicited interaction 103 | with those enforcing the Code of Conduct, is allowed during this period. 104 | Violating these terms may lead to a permanent ban. 105 | 106 | ### 4. Permanent Ban 107 | 108 | **Community Impact**: Demonstrating a pattern of violation of community 109 | standards, including sustained inappropriate behaviour, harassment of an 110 | individual, or aggression toward or disparagement of classes of individuals. 111 | 112 | **Consequence**: A permanent ban from any sort of public interaction within 113 | the community. 114 | 115 | ## Attribution 116 | 117 | This Code of Conduct is adapted from the [Contributor Covenant][homepage], 118 | version 2.0, available at 119 | https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. 120 | 121 | Community Impact Guidelines were inspired by [Mozilla's code of conduct 122 | enforcement ladder](https://github.com/mozilla/diversity). 123 | 124 | [homepage]: https://www.contributor-covenant.org 125 | 126 | For answers to common questions about this code of conduct, see the FAQ at 127 | https://www.contributor-covenant.org/faq. Translations are available at 128 | https://www.contributor-covenant.org/translations. 129 | -------------------------------------------------------------------------------- /CONTRIBUTING.md: -------------------------------------------------------------------------------- 1 | # Contributing 2 | 3 | We welcome contributions to Quickemu. 4 | 5 | - Help other Quickemu users by answering questions in the [Quickemu Discussions](https://github.com/quickemu-project/quickemu/discussions) 🛟 6 | - Improve the documentation in [this README](https://github.com/quickemu-project/quickemu/edit/master/README.md) and the [Quickemu Wiki](https://github.com/quickemu-project/quickemu/wiki) 📖 7 | - File bug reports and feature requests in the [Quickemu Issues](https://github.com/quickemu-project/quickemu/issues) 📁 8 | - Submit [Quickemu Pull requests](https://github.com/quickemu-project/quickemu/pulls) to fix bugs 🐞 or add new features ✨ 9 | - Follow our [guide to adding a new OS to quickget](https://github.com/quickemu-project/quickemu/wiki/06-Advanced-quickget-features#adding-a-new-os-to-quickget) 10 | - Commit messages must [conform to the Conventional Commits specification](https://www.conventionalcommits.org/). 11 | - [Sponsor the project](https://github.com/sponsors/flexiondotorg) 💖 12 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2020 Wimpy's World 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 |
2 | Quickemu 3 | 4 | # Quickemu 5 | 6 | **Quickly create and run optimised Windows, macOS and Linux virtual machines:** 7 | 8 | **Made with 💝 for Tux (Linux) & Apple (macOS)** 9 |
10 | 11 |

12 |  Discord  13 |  Mastodon  14 |  Twitter  15 |  LinkedIn  16 |

17 | 18 | 19 | # Introduction 20 | 21 | **Quickemu** is a wrapper for the excellent [QEMU](https://www.qemu.org/) that 22 | automatically *"does the right thing"* when creating virtual machines. No 23 | requirement for exhaustive configuration options. You decide what operating 24 | system you want to run and Quickemu takes care of the rest 🤖 25 | 26 | - `quickget` **automatically downloads the upstream OS** and creates the configuration 📀 27 | - `quickemu` enumerates your hardware and launches the virtual machine with the **optimum configuration best suited to your computer** ⚡️ 28 | 29 | The original objective of the project was to [enable quick testing of Linux 30 | distributions](https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines) 31 | where the virtual machines and their configuration can be stored anywhere (such 32 | as external USB storage or your home directory) and no elevated permissions are 33 | required to run the virtual machines. 34 | 35 | **Today, Quickemu includes comprehensive support for [macOS](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines), 36 | [Windows](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines)**, most of the BSDs, novel non-Linux operating systems such as FreeDOS, Haiku, KolibriOS, OpenIndiana, ReactOS, and more. 37 | 38 | # Features 39 | 40 | - Host support for **Linux and macOS** 41 | - **macOS** Sonoma, Ventura, Monterey, Big Sur, Catalina & Mojave 42 | - **Windows** 10 and 11 including TPM 2.0 43 | - **Windows Server** 2022 2019 2016 44 | - [Ubuntu](https://ubuntu.com/desktop) and all the **[official Ubuntu 45 | flavours](https://ubuntu.com/download/flavours)** 46 | - **Nearly 1000 operating system editions are supported!** 47 | - Full SPICE support including host/guest clipboard sharing 48 | - VirtIO-webdavd file sharing for Linux and Windows guests 49 | - VirtIO-9p file sharing for Linux and macOS guests 50 | - [QEMU Guest Agent 51 | support](https://wiki.qemu.org/Features/GuestAgent); provides access 52 | to a system-level agent via standard QMP commands 53 | - Samba file sharing for Linux, macOS and Windows guests (*if `smbd` 54 | is installed on the host*) 55 | - VirGL acceleration 56 | - USB device pass-through 57 | - Smartcard pass-through 58 | - Automatic SSH port forwarding to guests 59 | - Network port forwarding 60 | - Full duplex audio 61 | - Braille support 62 | - EFI (with or without SecureBoot) and Legacy BIOS boot 63 | 64 | ## As featured on [Linux Matters](https://linuxmatters.sh) podcast! 65 | 66 | The presenters of Linux Matters 🐧🎙️ are the creators of each of the principal Quickemu projects. We discussed Quickemu's 2024 reboot in [Episode 30 - Quickemu Rising From the Bashes](https://linuxmatters.sh/30). 67 | 68 |
69 | Linux Matters Podcast 70 |
71 | Linux Matters Podcast 72 |
73 | 74 | # Quick start 75 | 76 | [Once Quickemu is installed](https://github.com/quickemu-project/quickemu/wiki/01-Installation), there are two simple steps to create and run a virtual machine: 77 | 78 | - `quickget` automatically downloads the ISO image for the operating system you want to run and creates a configuration file for the virtual machine. 79 | 80 | ``` shell 81 | quickget nixos unstable minimal 82 | ``` 83 | 84 | - `quickemu` starts the virtual machine using the configuration file created by `quickget`. 85 | 86 | ``` shell 87 | quickemu --vm nixos-unstable-minimal.conf 88 | ``` 89 | 90 | Execute `quickget` (with no arguments) to see a list of all the supported operating systems. 91 | 92 | ## Demo 93 | 94 |
95 | 96 | 97 | 98 |
99 | 100 | # Documentation 101 | 102 | The wiki describes how to get up and running with Quickemu and also covers more advanced configuration and usage. 103 | 104 | - [**Installation**](https://github.com/quickemu-project/quickemu/wiki/01-Installation) 💾 105 | - [**Create Linux virtual machines**](https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines) 🐧 106 | - [**Create macOS virtual machines**](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines) 🍏 107 | - [**Create Windows virtual machines**](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines) 🪟 108 | - [**Advanced quickemu configuration**](https://github.com/quickemu-project/quickemu/wiki/05-Advanced-quickemu-configuration) 🔧 109 | - [**Advanced quickget features**](https://github.com/quickemu-project/quickemu/wiki/06-Advanced-quickget-features) 🤓 110 | - [**Alternative frontends**](https://github.com/quickemu-project/quickemu/wiki/07-Alternative-frontends) 🧑‍💻 111 | - [**References**](https://github.com/quickemu-project/quickemu/wiki/08-References) 📚️ 112 | -------------------------------------------------------------------------------- /SECURITY.md: -------------------------------------------------------------------------------- 1 | # Security Policy 2 | 3 | ## Supported Versions 4 | 5 | Here are the versions of Quickemu currently being supported with security updates. 6 | 7 | | Version | Supported | 8 | | ------- | ------------------ | 9 | | 4.9.x | :white_check_mark: | 10 | | < 4.8 | :x: | 11 | 12 | ## Reporting a Vulnerability 13 | 14 | If you discover a vulnerability in Quickemu then [file an issue](https://github.com/quickemu-project/quickemu/issues/new) and click *Report a vulnerability*. 15 | 16 | - Quickemu is a spare-time hobby project. 17 | - We do not have SLAs for responding to security issues. 18 | - It is a best-efforts basis. 19 | -------------------------------------------------------------------------------- /chunkcheck: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env python3 2 | 3 | from pathlib import Path 4 | import struct 5 | import hashlib 6 | import argparse 7 | v1_prod_pubkey = 0xC3E748CAD9CD384329E10E25A91E43E1A762FF529ADE578C935BDDF9B13F2179D4855E6FC89E9E29CA12517D17DFA1EDCE0BEBF0EA7B461FFE61D94E2BDF72C196F89ACD3536B644064014DAE25A15DB6BB0852ECBD120916318D1CCDEA3C84C92ED743FC176D0BACA920D3FCF3158AFF731F88CE0623182A8ED67E650515F75745909F07D415F55FC15A35654D118C55A462D37A3ACDA08612F3F3F6571761EFCCBCC299AEE99B3A4FD6212CCFFF5EF37A2C334E871191F7E1C31960E010A54E86FA3F62E6D6905E1CD57732410A3EB0C6B4DEFDABE9F59BF1618758C751CD56CEF851D1C0EAA1C558E37AC108DA9089863D20E2E7E4BF475EC66FE6B3EFDCF 8 | # v2_prod_pubkey = 0xCB45C5E53217D4499FB80B2D96AA4F964EB551F1DA4EBFA4F5E23F87BFE82FC113590E536757F329D6EAD1F267771EE342F5A5E61514DD3D3383187E663929D577D94648F262EBA1157E152DB5273D10AE3A6A058CB9CD64D01267DAC82ED3B7BC1631D078C911414129CDAAA0FFB0A8E2A7ADD6F32FB09A7E98D259BFF6ED10808D1BDA58CAF7355DFF1A085A18B11657D2617447BF657140D599364E5AC8E626276AC03BC2417831D9E61B25154AFE9F2D8271E9CE22D2783803083A5A7A575774688721097DC5E4B32D118CF6317A7083BA15BA608430A8C8C6B7DA2D932D81F571603A9363AC0197AB670242D9C9180D97A10900F11FE3D9246CF14F0883 9 | # v2_dev_pubkey = 0xB372CEC9E05E71FB3FAA08C34E3256FB312EA821638A243EF8A5DEA46FCDA33F00F88FC2933FB276D37B914F89BAD5B5D75771E342265B771995AE8F43B4DFF3F21A877FE777A8B419587C8718D36204FA1922A575AD5207D5D6B8C10F84DDCA661B731E7E7601D64D4A894F487FE1AA1DDC2A1697A3553B1DD85D5750DF2AA9D988E83C4C70BBBE4747219F9B92B199FECB16091896EBB441606DEC20F446249D5568BB51FC87BA7F85E6295FBE811B0A314408CD31921C360608A0FF7F87BD733560FE1C96E472834CAB6BE016C35727754273125089BE043FD3B26F0B2DE141E05990CE922F1702DA0A2F4E9F8760D0FA712DDB9928E0CDAC14501ED5E2C3 10 | 11 | ChunkListHeader = struct.Struct('<4sIBBBxQQQ') 12 | assert ChunkListHeader.size == 0x24 13 | 14 | Chunk = struct.Struct(' 0 29 | assert chunk_offset == 0x24 30 | assert signature_offset == chunk_offset + Chunk.size * chunk_count 31 | for i in range(chunk_count): 32 | data = f.read(Chunk.size) 33 | hash_ctx.update(data) 34 | chunk_size, chunk_sha256 = Chunk.unpack(data) 35 | yield chunk_size, chunk_sha256 36 | digest = hash_ctx.digest() 37 | if signature_method == 1: 38 | data = f.read(256) 39 | assert len(data) == 256 40 | signature = int.from_bytes(data, 'little') 41 | plaintext = 0x1ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff003031300d0609608648016503040201050004200000000000000000000000000000000000000000000000000000000000000000 | int.from_bytes(digest, 'big') 42 | assert pow(signature, 0x10001, v1_prod_pubkey) == plaintext 43 | elif signature_method == 2: 44 | data = f.read(32) 45 | assert data == digest 46 | else: 47 | raise NotImplementedError 48 | assert f.read(1) == b'' 49 | 50 | def check_chunklist(path, chunklist_path): 51 | with open(path, 'rb') as f: 52 | for chunk_size, chunk_sha256 in parse_chunklist(chunklist_path): 53 | chunk = f.read(chunk_size) 54 | assert len(chunk) == chunk_size 55 | assert hashlib.sha256(chunk).digest() == chunk_sha256 56 | assert f.read(1) == b'' 57 | 58 | def main(): 59 | parser = argparse.ArgumentParser() 60 | parser.add_argument('vmdir', type=Path) 61 | args = parser.parse_args() 62 | vmdir = args.vmdir 63 | check_chunklist(vmdir / 'RecoveryImage.dmg', vmdir / 'RecoveryImage.chunklist') 64 | 65 | if __name__ == "__main__": 66 | main() 67 | -------------------------------------------------------------------------------- /debian/changelog: -------------------------------------------------------------------------------- 1 | quickemu (4.9.6-1) unstable; urgency=medium 2 | 3 | * New upstream release. 4 | 5 | -- Martin Wimpress Fri, 10 Nov 2023 14:49:08 +0000 6 | -------------------------------------------------------------------------------- /debian/control: -------------------------------------------------------------------------------- 1 | Source: quickemu 2 | Section: utils 3 | Priority: optional 4 | Maintainer: Martin Wimpress 5 | Build-Depends: 6 | debhelper-compat (= 12), 7 | Standards-Version: 4.5.1 8 | Homepage: https://github.com/quickemu-project/quickemu 9 | Vcs-Browser: https://github.com/quickemu-project/quickemu 10 | Vcs-Git: https://github.com/quickemu-project/quickemu.git 11 | Rules-Requires-Root: no 12 | 13 | Package: quickemu 14 | Architecture: all 15 | Depends: 16 | coreutils, 17 | curl, 18 | genisoimage, 19 | jq, 20 | mesa-utils, 21 | pciutils, 22 | procps, 23 | python3-minimal, 24 | qemu-system (>= 6.0), 25 | socat, 26 | spice-client-gtk, 27 | swtpm, 28 | usbutils, 29 | util-linux, 30 | uuid-runtime, 31 | x11-xserver-utils, 32 | xdg-user-dirs, 33 | zsync, 34 | ${misc:Depends}, 35 | ${shlibs:Depends}, 36 | Suggests: 37 | virt-viewer, 38 | Description: Quickemu creates and runs optimised virtual machines. 39 | Simple script to "manage" Qemu virtual machines. Each virtual machine 40 | configuration is a few lines long requiring minimal setup. The main objective 41 | of the project is to enable quick testing of desktop Linux distributions where 42 | the virtual machines configuration and disk images can be stored anywhere, 43 | such as external USB storage or your home directory. Windows and macOS guests 44 | are also supported. 45 | . 46 | -------------------------------------------------------------------------------- /debian/copyright: -------------------------------------------------------------------------------- 1 | Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ 2 | Upstream-Name: quickemu 3 | Upstream-Contact: Martin Wimpress 4 | Source: https://github.com/quickemu-project/quickemu 5 | 6 | Files: * 7 | Copyright: 2020-2024 Martin Wimpress 8 | License: MIT 9 | Permission is hereby granted, free of charge, to any person obtaining a copy 10 | of this software and associated documentation files (the "Software"), to deal 11 | in the Software without restriction, including without limitation the rights 12 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 13 | copies of the Software, and to permit persons to whom the Software is 14 | furnished to do so, subject to the following conditions: 15 | . 16 | The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. 17 | . 18 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 19 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 20 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 21 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 22 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 23 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 24 | SOFTWARE. 25 | 26 | # If you want to use GPL v2 or later for the /debian/* files use 27 | # the following clauses, or change it to suit. Delete these two lines 28 | Files: debian/* 29 | Copyright: 2021 - 2024 Martin Wimpress 30 | License: GPL-2+ 31 | This package is free software; you can redistribute it and/or modify 32 | it under the terms of the GNU General Public License as published by 33 | the Free Software Foundation; either version 2 of the License, or 34 | (at your option) any later version. 35 | . 36 | This package is distributed in the hope that it will be useful, 37 | but WITHOUT ANY WARRANTY; without even the implied warranty of 38 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 39 | GNU General Public License for more details. 40 | . 41 | You should have received a copy of the GNU General Public License 42 | along with this program. If not, see 43 | . 44 | On Debian systems, the complete text of the GNU General 45 | Public License version 2 can be found in "/usr/share/common-licenses/GPL-2". 46 | -------------------------------------------------------------------------------- /debian/install: -------------------------------------------------------------------------------- 1 | chunkcheck usr/bin 2 | quickemu usr/bin 3 | quickget usr/bin 4 | quickreport usr/bin 5 | -------------------------------------------------------------------------------- /debian/rules: -------------------------------------------------------------------------------- 1 | #!/usr/bin/make -f 2 | 3 | %: 4 | dh $@ 5 | 6 | override_dh_builddeb: 7 | dh_builddeb -- -Zgzip 8 | -------------------------------------------------------------------------------- /debian/source/format: -------------------------------------------------------------------------------- 1 | 3.0 (native) 2 | -------------------------------------------------------------------------------- /devshell.nix: -------------------------------------------------------------------------------- 1 | { lib, 2 | mkShell, 3 | pkgs, 4 | stdenv, 5 | }: 6 | mkShell { 7 | packages = with pkgs; ([ 8 | cdrtools 9 | curl 10 | gawk 11 | gnugrep 12 | gnused 13 | jq 14 | pciutils 15 | procps 16 | python3 17 | qemu_full 18 | samba 19 | socat 20 | spice-gtk 21 | swtpm 22 | unzip 23 | util-linux 24 | xorg.xrandr 25 | zsync 26 | OVMF 27 | OVMFFull 28 | ] ++ lib.optionals stdenv.isLinux [ 29 | glxinfo 30 | usbutils 31 | xdg-user-dirs 32 | ]); 33 | 34 | inputsFrom = with pkgs; [ 35 | git 36 | ]; 37 | 38 | shellHook = '' 39 | echo "**********************************************************************" 40 | echo "* 'direnv reload' to update '.direnv/bin/quickemu' for testing *" 41 | echo "**********************************************************************" 42 | sed \ 43 | -e '/OVMF_CODE_4M.secboot.fd/s|ovmfs=(|ovmfs=("${pkgs.OVMFFull.firmware}","${pkgs.OVMFFull.variables}" |' \ 44 | -e '/OVMF_CODE_4M.fd/s|ovmfs=(|ovmfs=("${pkgs.OVMF.firmware}","${pkgs.OVMF.variables}" |' \ 45 | -e '/cp "''${VARS_IN}" "''${VARS_OUT}"/a chmod +w "''${VARS_OUT}"' \ 46 | -e 's,\$(command -v smbd),${pkgs.samba}/bin/smbd,' \ 47 | quickemu > $PWD/.direnv/bin/quickemu 48 | chmod +x $PWD/.direnv/bin/quickemu 49 | ''; 50 | } 51 | -------------------------------------------------------------------------------- /docs/Makefile: -------------------------------------------------------------------------------- 1 | include pandoc-man.mk 2 | 3 | ifeq ($(PREFIX),) 4 | PREFIX := /usr/local 5 | endif 6 | 7 | datarootdir := $(PREFIX)/share 8 | datadir := $(datarootdir) 9 | mandir := $(datarootdir)/man 10 | bindir := $(PREFIX)/bin 11 | 12 | all: quickget.1 quickemu.1 quickemu_conf.5 13 | 14 | clean: 15 | rm *.1 *.5 16 | 17 | install_docs: all 18 | install -d $(DESTDIR)$(mandir)/man1 19 | install -d $(DESTDIR)$(mandir)/man5 20 | install -m 644 quickget.1 $(DESTDIR)$(mandir)/man1 21 | install -m 644 quickemu.1 $(DESTDIR)$(mandir)/man1 22 | install -m 644 quickemu_conf.5 $(DESTDIR)$(mandir)/man5 23 | rm -f $(DESTDIR)$(mandir)/man1/quickemu_conf.1 24 | 25 | # install -m 644 quickgui.1 $(DESTDIR)$(mandir)/man1 26 | 27 | install_bins: 28 | install -d $(DESTDIR)$(bindir) 29 | install -m 755 ../quickget $(DESTDIR)$(bindir) 30 | install -m 755 ../quickemu $(DESTDIR)$(bindir) 31 | install -m 755 ../quickreport $(DESTDIR)$(bindir) 32 | install -m 755 ../chunkcheck $(DESTDIR)$(bindir) 33 | 34 | install: install_bins install_docs 35 | 36 | uninstall:: 37 | rm -f $(DESTDIR)$(mandir)/man1/quickget.1 38 | rm -f $(DESTDIR)$(mandir)/man1/quickemu.1 39 | rm -f $(DESTDIR)$(mandir)/man5/quickemu_conf.5 40 | rm -f $(DESTDIR)$(bindir)/quickget 41 | rm -f $(DESTDIR)$(bindir)/quickemu 42 | rm -f $(DESTDIR)$(bindir)/quickreport 43 | rm -f $(DESTDIR)$(bindir)/macrecovery 44 | rm -f $(DESTDIR)$(bindir)/chunkcheck 45 | 46 | 47 | .PHONY: all 48 | -------------------------------------------------------------------------------- /docs/pandoc-man.mk: -------------------------------------------------------------------------------- 1 | PANDOC ?= pandoc 2 | PANDOC_OPTIONS = -f gfm+definition_lists 3 | 4 | .SUFFIXES: .1.md .1 .5.md .5 5 | 6 | .1.md.1 .5.md.5: 7 | $(PANDOC) --standalone $(PANDOC_OPTIONS) --to man -o $@ $< 8 | -------------------------------------------------------------------------------- /docs/quickemu.1: -------------------------------------------------------------------------------- 1 | .\" Automatically generated by Pandoc 3.6.1 2 | .\" 3 | .TH "QUICKEMU" "1" "December 30, 2024" "quickemu" "Quickemu User Manual" 4 | .SH NAME 5 | quickemu \- A quick VM builder and manager 6 | .SH SYNOPSIS 7 | \f[B]quickemu\f[R] [\f[I]OPTION\f[R]]... 8 | .SH DESCRIPTION 9 | \f[B]quickemu\f[R] will create and run highly optimised desktop virtual 10 | machines for Linux, macOS and Windows 11 | .SH OPTIONS 12 | .TP 13 | \f[B]\-\-vm\f[R] 14 | vm configuration file 15 | .PP 16 | You can also pass optional parameters 17 | .TP 18 | \f[B]\-\-access\f[R] 19 | Enable remote spice access support. 20 | \[aq]local\[aq] (default), \[aq]remote\[aq], \[aq]clientipaddress\[aq] 21 | .TP 22 | \f[B]\-\-braille\f[R] 23 | Enable braille support. 24 | Requires SDL. 25 | .TP 26 | \f[B]\-\-delete\-disk\f[R] 27 | Delete the disk image and EFI variables 28 | .TP 29 | \f[B]\-\-delete\-vm\f[R] 30 | Delete the entire VM and its configuration 31 | .TP 32 | \f[B]\-\-display\f[R] 33 | Select display backend. 34 | \[aq]sdl\[aq] (default), \[aq]gtk\[aq], \[aq]none\[aq], \[aq]spice\[aq] 35 | or \[aq]spice\-app\[aq] 36 | .TP 37 | \f[B]\-\-fullscreen\f[R] 38 | Starts VM in full screen mode (Ctl+Alt+f to exit) 39 | .TP 40 | \f[B]\-\-ignore\-msrs\-always\f[R] 41 | Configure KVM to always ignore unhandled machine\-specific registers 42 | .TP 43 | \f[B]\-\-kill\f[R] 44 | Kill the VM process if it is running 45 | .TP 46 | \f[B]\-\-offline\f[R] 47 | Override all network settings and start the VM offline 48 | .TP 49 | \f[B]\-\-shortcut\f[R] 50 | Create a desktop shortcut 51 | .TP 52 | \f[B]\-\-snapshot apply \f[R] 53 | Apply/restore a snapshot. 54 | .TP 55 | \f[B]\-\-snapshot create \f[R] 56 | Create a snapshot. 57 | .TP 58 | \f[B]\-\-snapshot delete \f[R] 59 | Delete a snapshot. 60 | .TP 61 | \f[B]\-\-snapshot info\f[R] 62 | Show disk/snapshot info. 63 | .TP 64 | \f[B]\-\-status\-quo\f[R] 65 | Do not commit any changes to disk/snapshot. 66 | .TP 67 | \f[B]\-\-viewer \f[R] 68 | Choose an alternative viewer. 69 | \[at]Options: \[aq]spicy\[aq] (default), \[aq]remote\-viewer\[aq], 70 | \[aq]none\[aq] 71 | .TP 72 | \f[B]\-\-width \f[R] 73 | Set VM screen width; requires \[aq]\-\-height\[aq] 74 | .TP 75 | \f[B]\-\-height \f[R] 76 | Set VM screen height; requires \[aq]\-\-width\[aq] 77 | .TP 78 | \f[B]\-\-ssh\-port \f[R] 79 | Set SSH port manually 80 | .TP 81 | \f[B]\-\-spice\-port \f[R] 82 | Set SPICE port manually 83 | .TP 84 | \f[B]\-\-public\-dir \f[R] 85 | Expose share directory. 86 | \[at]Options: \[aq]\[aq] (default: xdg\-user\-dir PUBLICSHARE), 87 | \[aq]\[aq], \[aq]none\[aq] 88 | .TP 89 | \f[B]\-\-monitor \f[R] 90 | Set monitor connection type. 91 | \[at]Options: \[aq]socket\[aq] (default), \[aq]telnet\[aq], 92 | \[aq]none\[aq] 93 | .TP 94 | \f[B]\-\-monitor\-telnet\-host \f[R] 95 | Set telnet host for monitor. 96 | (default: \[aq]localhost\[aq]) 97 | .TP 98 | \f[B]\-\-monitor\-telnet\-port \f[R] 99 | Set telnet port for monitor. 100 | (default: \[aq]4440\[aq]) 101 | .TP 102 | \f[B]\-\-monitor\-cmd \f[R] 103 | Send command to monitor if available. 104 | (Example: system_powerdown) 105 | .TP 106 | \f[B]\-\-serial \f[R] 107 | Set serial connection type. 108 | \[at]Options: \[aq]socket\[aq] (default), \[aq]telnet\[aq], 109 | \[aq]none\[aq] 110 | .TP 111 | \f[B]\-\-serial\-telnet\-host \f[R] 112 | Set telnet host for serial. 113 | (default: \[aq]localhost\[aq]) 114 | .TP 115 | \f[B]\-\-serial\-telnet\-port \f[R] 116 | Set telnet port for serial. 117 | (default: \[aq]6660\[aq]) 118 | .TP 119 | \f[B]\-\-keyboard \f[R] 120 | Set keyboard. 121 | \[at]Options: \[aq]usb\[aq] (default), \[aq]ps2\[aq], \[aq]virtio\[aq] 122 | .TP 123 | \f[B]\-\-keyboard_layout \f[R] 124 | Set keyboard layout: \[aq]en\-us\[aq] (default) 125 | .TP 126 | \f[B]\-\-mouse \f[R] 127 | Set mouse. 128 | \[at]Options: \[aq]tablet\[aq] (default), \[aq]ps2\[aq], \[aq]usb\[aq], 129 | \[aq]virtio\[aq] 130 | .TP 131 | \f[B]\-\-usb\-controller \f[R] 132 | Set usb\-controller. 133 | \[at]Options: \[aq]ehci\[aq] (default), \[aq]xhci\[aq], \[aq]none\[aq] 134 | .TP 135 | \f[B]\-\-sound\-card \f[R] 136 | Set sound card. 137 | \[at]Options: \[aq]intel\-hda\[aq] (default), \[aq]ac97\[aq], 138 | \[aq]es1370\[aq], \[aq]sb16\[aq], \[aq]none\[aq] 139 | .TP 140 | \f[B]\-\-extra_args \f[R] 141 | Pass additional arguments to qemu 142 | .TP 143 | \f[B]\-\-version\f[R] 144 | Print version 145 | .SH EXAMPLES 146 | .TP 147 | \f[B]quickemu \-\-vm ubuntu\-mate\-22.04.conf\f[R] 148 | Launches the VM specified in the file \f[I]ubuntu\-mate\-22.04.conf\f[R] 149 | .SH Introduction 150 | \f[B]Quickemu\f[R] is a wrapper for the excellent \c 151 | .UR https://www.qemu.org/ 152 | QEMU 153 | .UE \c 154 | \ that automatically \f[I]\[dq]does the right thing\[dq]\f[R] when 155 | creating virtual machines. 156 | No requirement for exhaustive configuration options. 157 | You decide what operating system you want to run and Quickemu takes care 158 | of the rest 🤖 159 | .IP \[bu] 2 160 | \f[CR]quickget\f[R] \f[B]automatically downloads the upstream OS\f[R] 161 | and creates the configuration 📀 162 | .IP \[bu] 2 163 | \f[CR]quickemu\f[R] enumerates your hardware and launches the virtual 164 | machine with the \f[B]optimum configuration best suited to your 165 | computer\f[R] ⚡️ 166 | .PP 167 | The original objective of the project was to \c 168 | .UR https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines 169 | enable quick testing of Linux distributions 170 | .UE \c 171 | \ where the virtual machines and their configuration can be stored 172 | anywhere (such as external USB storage or your home directory) and no 173 | elevated permissions are required to run the virtual machines. 174 | .PP 175 | \f[B]Today, Quickemu includes comprehensive support for \c 176 | .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines 177 | macOS 178 | .UE \c 179 | , \c 180 | .UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines 181 | Windows 182 | .UE \c 183 | \f[R], most of the BSDs, novel non\-Linux operating systems such as 184 | FreeDOS, Haiku, KolibriOS, OpenIndiana, ReactOS, and more. 185 | .SH Features 186 | .IP \[bu] 2 187 | Host support for \f[B]Linux and macOS\f[R] 188 | .IP \[bu] 2 189 | \f[B]macOS\f[R] Sonoma, Ventura, Monterey, Big Sur, Catalina & Mojave 190 | .IP \[bu] 2 191 | \f[B]Windows\f[R] 10 and 11 including TPM 2.0 192 | .IP \[bu] 2 193 | \f[B]Windows Server\f[R] 2022 2019 2016 194 | .IP \[bu] 2 195 | \c 196 | .UR https://ubuntu.com/desktop 197 | Ubuntu 198 | .UE \c 199 | \ and all the \f[B]\c 200 | .UR https://ubuntu.com/download/flavours 201 | official Ubuntu flavours 202 | .UE \c 203 | \f[R] 204 | .IP \[bu] 2 205 | \f[B]Nearly 1000 operating system editions are supported!\f[R] 206 | .IP \[bu] 2 207 | Full SPICE support including host/guest clipboard sharing 208 | .IP \[bu] 2 209 | VirtIO\-webdavd file sharing for Linux and Windows guests 210 | .IP \[bu] 2 211 | VirtIO\-9p file sharing for Linux and macOS guests 212 | .IP \[bu] 2 213 | \c 214 | .UR https://wiki.qemu.org/Features/GuestAgent 215 | QEMU Guest Agent support 216 | .UE \c 217 | ; provides access to a system\-level agent via standard QMP commands 218 | .IP \[bu] 2 219 | Samba file sharing for Linux, macOS and Windows guests (\f[I]if 220 | \f[CI]smbd\f[I] is installed on the host\f[R]) 221 | .IP \[bu] 2 222 | VirGL acceleration 223 | .IP \[bu] 2 224 | USB device pass\-through 225 | .IP \[bu] 2 226 | Smartcard pass\-through 227 | .IP \[bu] 2 228 | Automatic SSH port forwarding to guests 229 | .IP \[bu] 2 230 | Network port forwarding 231 | .IP \[bu] 2 232 | Full duplex audio 233 | .IP \[bu] 2 234 | Braille support 235 | .IP \[bu] 2 236 | EFI (with or without SecureBoot) and Legacy BIOS boot 237 | .SS As featured on \c 238 | .UR https://linuxmatters.sh 239 | Linux Matters 240 | .UE \c 241 | \ podcast! 242 | The presenters of Linux Matters 🐧🎙️ are the creators of each of the 243 | principle Quickemu projects. 244 | We discussed Quickemu\[aq]s 2024 reboot in \c 245 | .UR https://linuxmatters.sh/30 246 | Episode 30 \- Quickemu Rising From the Bashes 247 | .UE \c 248 | \&. 249 | .PP 250 | \ Linux Matters Podcast 251 | .PP 252 | When installing from source, you will need to install the following 253 | requirements manually: 254 | .IP \[bu] 2 255 | \c 256 | .UR https://www.qemu.org/ 257 | QEMU 258 | .UE \c 259 | \ (\f[I]6.0.0 or newer\f[R]) \f[B]with GTK, SDL, SPICE & VirtFS 260 | support\f[R] 261 | .IP \[bu] 2 262 | \c 263 | .UR https://www.gnu.org/software/bash/ 264 | bash 265 | .UE \c 266 | \ (\f[I]4.0 or newer\f[R]) 267 | .IP \[bu] 2 268 | \c 269 | .UR https://www.gnu.org/software/coreutils/ 270 | Coreutils 271 | .UE \c 272 | .IP \[bu] 2 273 | \c 274 | .UR https://curl.se/ 275 | curl 276 | .UE \c 277 | .IP \[bu] 2 278 | \c 279 | .UR https://github.com/tianocore/edk2 280 | EDK II 281 | .UE \c 282 | .IP \[bu] 2 283 | \c 284 | .UR https://www.gnu.org/software/gawk/ 285 | gawk 286 | .UE \c 287 | .IP \[bu] 2 288 | \c 289 | .UR https://www.gnu.org/software/grep/ 290 | grep 291 | .UE \c 292 | .IP \[bu] 2 293 | \c 294 | .UR https://gitlab.freedesktop.org/mesa/demos 295 | glxinfo 296 | .UE \c 297 | .IP \[bu] 2 298 | \c 299 | .UR https://stedolan.github.io/jq/ 300 | jq 301 | .UE \c 302 | .IP \[bu] 2 303 | \c 304 | .UR https://wiki.linuxfoundation.org/lsb/start 305 | LSB 306 | .UE \c 307 | .IP \[bu] 2 308 | \c 309 | .UR https://github.com/pciutils/pciutils 310 | pciutils 311 | .UE \c 312 | .IP \[bu] 2 313 | \c 314 | .UR https://gitlab.com/procps-ng/procps 315 | procps 316 | .UE \c 317 | .IP \[bu] 2 318 | \c 319 | .UR https://www.python.org/ 320 | python3 321 | .UE \c 322 | .IP \[bu] 2 323 | \c 324 | .UR http://cdrtools.sourceforge.net/private/cdrecord.html 325 | mkisofs 326 | .UE \c 327 | .IP \[bu] 2 328 | \c 329 | .UR https://github.com/gregkh/usbutils 330 | usbutils 331 | .UE \c 332 | .IP \[bu] 2 333 | \c 334 | .UR https://github.com/karelzak/util-linux 335 | util\-linux 336 | .UE \c 337 | ; including \f[CR]uuidgen\f[R] 338 | .IP \[bu] 2 339 | \c 340 | .UR https://www.gnu.org/software/sed/ 341 | sed 342 | .UE \c 343 | .IP \[bu] 2 344 | \c 345 | .UR http://www.dest-unreach.org/socat/ 346 | socat 347 | .UE \c 348 | .IP \[bu] 2 349 | \c 350 | .UR https://gitlab.freedesktop.org/spice/spice-gtk 351 | spicy 352 | .UE \c 353 | .IP \[bu] 2 354 | \c 355 | .UR https://github.com/stefanberger/swtpm 356 | swtpm 357 | .UE \c 358 | .IP \[bu] 2 359 | \c 360 | .UR https://www.freedesktop.org/wiki/Software/xdg-user-dirs/ 361 | xdg\-user\-dirs 362 | .UE \c 363 | .IP \[bu] 2 364 | \c 365 | .UR https://gitlab.freedesktop.org/xorg/app/xrandr 366 | xrandr 367 | .UE \c 368 | .IP \[bu] 2 369 | \c 370 | .UR http://zsync.moria.org.uk/ 371 | zsync 372 | .UE \c 373 | .IP \[bu] 2 374 | \c 375 | .UR http://www.info-zip.org/UnZip.html 376 | unzip 377 | .UE \c 378 | .PP 379 | For Ubuntu, Arch and NixOS hosts, the \c 380 | .UR https://launchpad.net/~flexiondotorg/+archive/ubuntu/quickemu 381 | ppa 382 | .UE \c 383 | , \c 384 | .UR https://aur.archlinux.org/packages/quickemu 385 | AUR 386 | .UE \c 387 | \ or \c 388 | .UR https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/quickemu 389 | nix 390 | .UE \c 391 | \ packaging will take care of the dependencies. 392 | For other host distributions or operating systems it will be necessary 393 | to install the above requirements or their equivalents. 394 | .PP 395 | These examples may save a little typing: 396 | .SS Install requirements on Debian hosts 397 | This also applies to derivatives: 398 | .IP 399 | .EX 400 | sudo apt\-get install bash coreutils curl genisoimage grep jq mesa\-utils ovmf pciutils procps python3 qemu sed socat spice\-client\-gtk swtpm\-tools unzip usbutils util\-linux xdg\-user\-dirs xrandr zsync 401 | .EE 402 | .SS Install requirements on Fedora hosts 403 | .IP 404 | .EX 405 | sudo dnf install bash coreutils curl edk2\-tools genisoimage grep jq mesa\-demos pciutils procps python3 qemu sed socat spice\-gtk\-tools swtpm unzip usbutils util\-linux uuidgen\-runtime xdg\-user\-dirs xrandr zsync 406 | .EE 407 | .SS Install requirements on Gentoo 408 | Please note that you may have to use \f[CR]sys\-firmware/edk2\-ovmf\f[R] 409 | instead of \f[CR]sys\-firmware/edk2\-ovmf\-bin\f[R] \- depending on how 410 | your system is configured. 411 | .IP 412 | .EX 413 | sudo emerge \-\-ask \-\-noreplace app\-emulation/qemu \[rs] 414 | app\-shells/bash \[rs] 415 | sys\-apps/coreutils \[rs] 416 | net\-misc/curl \[rs] 417 | sys\-firmware/edk2\-ovmf\-bin \[rs] 418 | sys\-apps/gawk \[rs] 419 | sys\-apps/grep \[rs] 420 | x11\-apps/mesa\-progs \[rs] 421 | app\-misc/jq \[rs] 422 | sys\-apps/pciutils \[rs] 423 | sys\-process/procps \[rs] 424 | app\-cdr/cdrtools \[rs] 425 | sys\-apps/usbutils \[rs] 426 | sys\-apps/util\-linux \[rs] 427 | sys\-apps/sed \[rs] 428 | net\-misc/socat \[rs] 429 | app\-emulation/spice \[rs] 430 | app\-crypt/swtpm \[rs] 431 | x11\-misc/xdg\-user\-dirs \[rs] 432 | x11\-apps/xrandr \[rs] 433 | net\-misc/zsync \[rs] 434 | app\-arch/unzip 435 | .EE 436 | .SS Install requirements on macOS hosts 437 | Install the Quickemu requirements using brew: 438 | .IP 439 | .EX 440 | brew install bash cdrtools coreutils jq python3 qemu usbutils samba socat swtpm zsync 441 | .EE 442 | .PP 443 | Now clone the project: 444 | .IP 445 | .EX 446 | git clone https://github.com/quickemu\-project/quickemu 447 | cd quickemu 448 | .EE 449 | .SS \c 450 | .UR https://github.com/quickemu-project/quickemu/wiki/07-Alternative-frontends 451 | Alternative Frontends 452 | .UE \c 453 | .SS Quickgui 454 | While \f[CR]quickemu\f[R] and \f[CR]quickget\f[R] are designed for the 455 | terminal, a graphical user interface is also available: 456 | .IP \[bu] 2 457 | \f[B]\c 458 | .UR https://github.com/quickemu-project/quickgui 459 | Quickgui 460 | .UE \c 461 | \f[R] by \c 462 | .UR https://github.com/marxjohnson 463 | Mark Johnson 464 | .UE \c 465 | \ and \c 466 | .UR https://github.com/ymauray 467 | Yannick Mauray 468 | .UE \c 469 | \&. 470 | .PP 471 | To install Quickgui on Ubuntu: 472 | .IP 473 | .EX 474 | sudo add\-apt\-repository ppa:yannick\-mauray/quickgui 475 | sudo apt update 476 | sudo apt install quickgui 477 | .EE 478 | .PP 479 | Many thanks to \c 480 | .UR https://github.com/Lukewh 481 | Luke Wesley\-Holley 482 | .UE \c 483 | \ and \c 484 | .UR https://github.com/daPhipz 485 | Philipp Kiemle 486 | .UE \c 487 | \ for creating the \f[B]\c 488 | .UR https://github.com/Lukewh/quickemu-icons 489 | Quickemu icons 490 | .UE \c 491 | \f[R] 🎨 492 | .SS Creating Linux guests 🐧 493 | .SS Ubuntu 494 | \f[CR]quickget\f[R] will automatically download an Ubuntu release and 495 | create the virtual machine configuration. 496 | .IP 497 | .EX 498 | quickget ubuntu 22.04 499 | quickemu \-\-vm ubuntu\-22.04.conf 500 | .EE 501 | .IP \[bu] 2 502 | Complete the installation as normal. 503 | .IP \[bu] 2 504 | Post\-install: 505 | .RS 2 506 | .IP \[bu] 2 507 | Install the SPICE agent (\f[CR]spice\-vdagent\f[R]) in the guest to 508 | enable copy/paste and USB redirection 509 | .RS 2 510 | .IP \[bu] 2 511 | \f[CR]sudo apt install spice\-vdagent\f[R] 512 | .RE 513 | .IP \[bu] 2 514 | Install the SPICE WebDAV agent (\f[CR]spice\-webdavd\f[R]) in the guest 515 | to enable file sharing. 516 | .RS 2 517 | .IP \[bu] 2 518 | \f[CR]sudo apt install spice\-webdavd\f[R] 519 | .RE 520 | .RE 521 | .SS Ubuntu daily\-live images 522 | \f[CR]quickget\f[R] can also download/refresh daily\-live images via 523 | \f[CR]zsync\f[R] for Ubuntu developers and testers. 524 | .IP 525 | .EX 526 | quickget ubuntu daily\-live 527 | quickemu \-\-vm ubuntu\-daily\-live.conf 528 | .EE 529 | .PP 530 | You can run \f[CR]quickget ubuntu daily\-live\f[R] to refresh your daily 531 | development image as often as you like, it will even automatically 532 | switch to a new series. 533 | .SS Ubuntu Flavours 534 | All the official Ubuntu flavours are supported, just replace 535 | \f[CR]ubuntu\f[R] with your preferred flavour. 536 | .PP 537 | The project \c 538 | .UR https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines 539 | wiki 540 | .UE \c 541 | \ may have further information. 542 | .IP \[bu] 2 543 | \f[CR]edubuntu\f[R] (Edubuntu) 544 | .IP \[bu] 2 545 | \f[CR]kubuntu\f[R] (Kubuntu) 546 | .IP \[bu] 2 547 | \f[CR]lubuntu\f[R] (Lubuntu) 548 | .IP \[bu] 2 549 | \f[CR]ubuntu\-budgie\f[R] (Ubuntu Budgie) 550 | .IP \[bu] 2 551 | \f[CR]ubuntucinnamon\f[R] (Ubuntu Cinnamon) 552 | .IP \[bu] 2 553 | \f[CR]ubuntukylin\f[R] (Ubuntu Kylin) 554 | .IP \[bu] 2 555 | \f[CR]ubuntu\-mate\f[R] (Ubuntu MATE) 556 | .IP \[bu] 2 557 | \f[CR]ubuntu\-server\f[R] (Ubuntu Server) 558 | .IP \[bu] 2 559 | \f[CR]ubuntustudio\f[R] (Ubuntu Studio) 560 | .IP \[bu] 2 561 | \f[CR]ubuntu\f[R] (Ubuntu) 562 | .IP \[bu] 2 563 | \f[CR]ubuntu\-unity\f[R] (Ubuntu Unity) 564 | .IP \[bu] 2 565 | \f[CR]xubuntu\f[R] (Xubuntu) 566 | .PP 567 | You can also use \f[CR]quickget\f[R] with advanced options : 568 | .IP 569 | .EX 570 | \-\-download [edition] : Download image; no VM configuration 571 | \-\-create\-config [path/url] [flags] : Create VM config for an OS image 572 | \-\-open\-homepage : Open homepage for the OS 573 | \-\-show [os] : Show OS information 574 | \-\-version : Show version 575 | \-\-help : Show this help message 576 | \-\-disable\-unattended : Force quickget not to set up an unattended installation 577 | \-\-url [os] [release] [edition] : Show image URL(s) 578 | \-\-check [os] [release] [edition] : Check image URL(s) 579 | \-\-list : List all supported systems 580 | \-\-list\-csv : List everything in csv format 581 | \-\-list\-json : List everything in json format 582 | .EE 583 | .PP 584 | Here are some typical uses 585 | .IP 586 | .EX 587 | # show an OS ISO download URL for {os} {release} [edition] 588 | quickget \-\-url fedora 38 Silverblue 589 | # test if an OS ISO is available for {os} {release} [edition] 590 | quickget \-\-check nixos unstable plasma5 591 | # open an OS distribution homepage in a browser 592 | quickget \-\-open\-homepage ubuntu\-mate 593 | # Only download image file into current directory, without creating VM 594 | quickget \-\-download elementary 7.1 595 | .EE 596 | .PP 597 | The \f[CR]\-\-url\f[R], \f[CR]\-\-check\f[R], and 598 | \f[CR]\-\-download\f[R] options are fully functional for all operating 599 | systems, including Windows and macOS. 600 | .PP 601 | Further information is available from the project \c 602 | .UR https://github.com/quickemu-project/quickemu/wiki/06-Advanced-quickget-features 603 | wiki 604 | .UE \c 605 | .SS Other Operating Systems 606 | \f[CR]quickget\f[R] also supports: 607 | .IP \[bu] 2 608 | \f[CR]alma\f[R] (AlmaLinux) 609 | .IP \[bu] 2 610 | \f[CR]alpine\f[R] (Alpine Linux) 611 | .IP \[bu] 2 612 | \f[CR]android\f[R] (Android x86) 613 | .IP \[bu] 2 614 | \f[CR]antix\f[R] (Antix) 615 | .IP \[bu] 2 616 | \f[CR]archcraft\f[R] (Archcraft) 617 | .IP \[bu] 2 618 | \f[CR]archlinux\f[R] (Arch Linux) 619 | .IP \[bu] 2 620 | \f[CR]arcolinux\f[R] (Arco Linux) 621 | .IP \[bu] 2 622 | \f[CR]artixlinux\f[R] (Artix Linux) 623 | .IP \[bu] 2 624 | \f[CR]athenaos\f[R] (Athena OS) 625 | .IP \[bu] 2 626 | \f[CR]batocera\f[R] (Batocera) 627 | .IP \[bu] 2 628 | \f[CR]bazzite\f[R] (Bazzite) 629 | .IP \[bu] 2 630 | \f[CR]biglinux\f[R] (BigLinux) 631 | .IP \[bu] 2 632 | \f[CR]blendos\f[R] (BlendOS) 633 | .IP \[bu] 2 634 | \f[CR]bodhi\f[R] (Bodhi) 635 | .IP \[bu] 2 636 | \f[CR]bunsenlabs\f[R] (BunsenLabs) 637 | .IP \[bu] 2 638 | \f[CR]cachyos\f[R] (CachyOS) 639 | .IP \[bu] 2 640 | \f[CR]centos\-stream\f[R] (CentOS Stream) 641 | .IP \[bu] 2 642 | \f[CR]chimeralinux\f[R] (Chimera Linux) 643 | .IP \[bu] 2 644 | \f[CR]crunchbang++\f[R] (Crunchbangplusplus) 645 | .IP \[bu] 2 646 | \f[CR]debian\f[R] (Debian) 647 | .IP \[bu] 2 648 | \f[CR]deepin\f[R] (Deepin) 649 | .IP \[bu] 2 650 | \f[CR]devuan\f[R] (Devuan) 651 | .IP \[bu] 2 652 | \f[CR]dragonflybsd\f[R] (DragonFlyBSD) 653 | .IP \[bu] 2 654 | \f[CR]easyos\f[R] (EasyOS) 655 | .IP \[bu] 2 656 | \f[CR]elementary\f[R] (elementary OS) 657 | .IP \[bu] 2 658 | \f[CR]endeavouros\f[R] (EndeavourOS) 659 | .IP \[bu] 2 660 | \f[CR]endless\f[R] (Endless OS) 661 | .IP \[bu] 2 662 | \f[CR]fedora\f[R] (Fedora) 663 | .IP \[bu] 2 664 | \f[CR]freebsd\f[R] (FreeBSD) 665 | .IP \[bu] 2 666 | \f[CR]freedos\f[R] (FreeDOS) 667 | .IP \[bu] 2 668 | \f[CR]garuda\f[R] (Garuda Linux) 669 | .IP \[bu] 2 670 | \f[CR]gentoo\f[R] (Gentoo) 671 | .IP \[bu] 2 672 | \f[CR]ghostbsd\f[R] (GhostBSD) 673 | .IP \[bu] 2 674 | \f[CR]gnomeos\f[R] (GNOME OS) 675 | .IP \[bu] 2 676 | \f[CR]guix\f[R] (Guix) 677 | .IP \[bu] 2 678 | \f[CR]haiku\f[R] (Haiku) 679 | .IP \[bu] 2 680 | \f[CR]holoiso\f[R] (HoloISO) 681 | .IP \[bu] 2 682 | \f[CR]kali\f[R] (Kali) 683 | .IP \[bu] 2 684 | \f[CR]kdeneon\f[R] (KDE Neon) 685 | .IP \[bu] 2 686 | \f[CR]kolibrios\f[R] (KolibriOS) 687 | .IP \[bu] 2 688 | \f[CR]linuxlite\f[R] (Linux Lite) 689 | .IP \[bu] 2 690 | \f[CR]linuxmint\f[R] (Linux Mint) 691 | .IP \[bu] 2 692 | \f[CR]lmde\f[R] (Linux Mint Debian Edition) 693 | .IP \[bu] 2 694 | \f[CR]maboxlinux\f[R] (Mabox Linux) 695 | .IP \[bu] 2 696 | \f[CR]mageia\f[R] (Mageia) 697 | .IP \[bu] 2 698 | \f[CR]manjaro\f[R] (Manjaro) 699 | .IP \[bu] 2 700 | \f[CR]mxlinux\f[R] (MX Linux) 701 | .IP \[bu] 2 702 | \f[CR]netboot\f[R] (netboot.xyz) 703 | .IP \[bu] 2 704 | \f[CR]netbsd\f[R] (NetBSD) 705 | .IP \[bu] 2 706 | \f[CR]nitrux\f[R] (Nitrux) 707 | .IP \[bu] 2 708 | \f[CR]nixos\f[R] (NixOS) 709 | .IP \[bu] 2 710 | \f[CR]nwg\-shell\f[R] (nwg\-shell) 711 | .IP \[bu] 2 712 | \f[CR]openbsd\f[R] (OpenBSD) 713 | .IP \[bu] 2 714 | \f[CR]openindiana\f[R] (OpenIndiana) 715 | .IP \[bu] 2 716 | \f[CR]opensuse\f[R] (openSUSE) 717 | .IP \[bu] 2 718 | \f[CR]oraclelinux\f[R] (Oracle Linux) 719 | .IP \[bu] 2 720 | \f[CR]parrotsec\f[R] (Parrot Security) 721 | .IP \[bu] 2 722 | \f[CR]peppermint\f[R] (PeppermintOS) 723 | .IP \[bu] 2 724 | \f[CR]popos\f[R] (Pop!_OS) 725 | .IP \[bu] 2 726 | \f[CR]porteus\f[R] (Porteus) 727 | .IP \[bu] 2 728 | \f[CR]primtux\f[R] (PrimTux) 729 | .IP \[bu] 2 730 | \f[CR]proxmox\-ve\f[R] (Proxmox VE) 731 | .IP \[bu] 2 732 | \f[CR]pureos\f[R] (PureOS) 733 | .IP \[bu] 2 734 | \f[CR]reactos\f[R] (ReactOS) 735 | .IP \[bu] 2 736 | \f[CR]rebornos\f[R] (RebornOS) 737 | .IP \[bu] 2 738 | \f[CR]rockylinux\f[R] (Rocky Linux) 739 | .IP \[bu] 2 740 | \f[CR]siduction\f[R] (Siduction) 741 | .IP \[bu] 2 742 | \f[CR]slackware\f[R] (Slackware) 743 | .IP \[bu] 2 744 | \f[CR]slax\f[R] (Slax) 745 | .IP \[bu] 2 746 | \f[CR]slint\f[R] (Slint) 747 | .IP \[bu] 2 748 | \f[CR]slitaz\f[R] (SliTaz) 749 | .IP \[bu] 2 750 | \f[CR]solus\f[R] (Solus) 751 | .IP \[bu] 2 752 | \f[CR]sparkylinux\f[R] (SparkyLinux) 753 | .IP \[bu] 2 754 | \f[CR]spirallinux\f[R] (SpiralLinux) 755 | .IP \[bu] 2 756 | \f[CR]tails\f[R] (Tails) 757 | .IP \[bu] 2 758 | \f[CR]tinycore\f[R] (Tiny Core Linux) 759 | .IP \[bu] 2 760 | \f[CR]trisquel\f[R] (Trisquel\-) 761 | .IP \[bu] 2 762 | \f[CR]truenas\-core\f[R] (TrueNAS Core) 763 | .IP \[bu] 2 764 | \f[CR]truenas\-scale\f[R] (TrueNAS Scale) 765 | .IP \[bu] 2 766 | \f[CR]tuxedo\-os\f[R] (Tuxedo OS) 767 | .IP \[bu] 2 768 | \f[CR]vanillaos\f[R] (Vanilla OS) 769 | .IP \[bu] 2 770 | \f[CR]void\f[R] (Void Linux) 771 | .IP \[bu] 2 772 | \f[CR]vxlinux\f[R] (VX Linux) 773 | .IP \[bu] 2 774 | \f[CR]zorin\f[R] (Zorin OS) 775 | .SS \c 776 | .UR https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines#manually-create-linux-guests 777 | Custom Linux guests 778 | .UE \c 779 | Or you can download a Linux image and manually create a VM 780 | configuration. 781 | .IP \[bu] 2 782 | Download a .iso image of a Linux distribution 783 | .IP \[bu] 2 784 | Create a VM configuration file; for example 785 | \f[CR]debian\-bullseye.conf\f[R] 786 | .IP 787 | .EX 788 | guest_os=\[dq]linux\[dq] 789 | disk_img=\[dq]debian\-bullseye/disk.qcow2\[dq] 790 | iso=\[dq]debian\-bullseye/firmware\-11.0.0\-amd64\-DVD\-1.iso\[dq] 791 | .EE 792 | .IP \[bu] 2 793 | Use \f[CR]quickemu\f[R] to start the virtual machine: 794 | .IP 795 | .EX 796 | quickemu \-\-vm debian\-bullseye.conf 797 | .EE 798 | .IP \[bu] 2 799 | Complete the installation as normal. 800 | .IP \[bu] 2 801 | Post\-install: 802 | .RS 2 803 | .IP \[bu] 2 804 | Install the SPICE agent (\f[CR]spice\-vdagent\f[R]) in the guest to 805 | enable copy/paste and USB redirection. 806 | .IP \[bu] 2 807 | Install the SPICE WebDAV agent (\f[CR]spice\-webdavd\f[R]) in the guest 808 | to enable file sharing. 809 | .RE 810 | .SS Supporting old Linux distros 811 | If you want to run an old Linux , from 2016 or earlier, change the 812 | \f[CR]guest_os\f[R] to \f[CR]linux_old\f[R]. 813 | This will enable the \f[CR]vmware\-svga\f[R] graphics driver which is 814 | better supported on older distros. 815 | .SS \c 816 | .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests 817 | Creating macOS Guests 818 | .UE \c 819 | \ 🍏 820 | \f[B]Installing macOS in a VM can be a bit finicky, if you encounter 821 | problems, \c 822 | .UR https://github.com/quickemu-project/quickemu/discussions 823 | check the Discussions 824 | .UE \c 825 | \ for solutions or ask for help there\f[R] 🛟 826 | .PP 827 | \f[CR]quickget\f[R] automatically downloads a macOS recovery image and 828 | creates a virtual machine configuration. 829 | .IP 830 | .EX 831 | quickget macos big\-sur 832 | quickemu \-\-vm macos\-big\-sur.conf 833 | .EE 834 | .PP 835 | macOS \f[CR]mojave\f[R], \f[CR]catalina\f[R], \f[CR]big\-sur\f[R], 836 | \f[CR]monterey\f[R], \f[CR]ventura\f[R] and \f[CR]sonoma\f[R] are 837 | supported. 838 | .IP \[bu] 2 839 | Use cursor keys and enter key to select the \f[B]macOS Base System\f[R] 840 | .IP \[bu] 2 841 | From \f[B]macOS Utilities\f[R] 842 | .RS 2 843 | .IP \[bu] 2 844 | Click \f[B]Disk Utility\f[R] and \f[B]Continue\f[R] 845 | .RS 2 846 | .IP \[bu] 2 847 | Select \f[CR]QEMU HARDDISK Media\f[R] (\[ti]103.08GB) from the list (on 848 | Big Sur and above use \f[CR]Apple Inc. VirtIO Block Device\f[R]) and 849 | click \f[B]Erase\f[R]. 850 | .IP \[bu] 2 851 | Enter a \f[CR]Name:\f[R] for the disk 852 | .IP \[bu] 2 853 | If you are installing macOS Mojave or later (Catalina, Big Sur, 854 | Monterey, Ventura and Sonoma), choose any of the APFS options as the 855 | filesystem. 856 | MacOS Extended may not work. 857 | .RE 858 | .IP \[bu] 2 859 | Click \f[B]Erase\f[R]. 860 | .IP \[bu] 2 861 | Click \f[B]Done\f[R]. 862 | .IP \[bu] 2 863 | Close Disk Utility 864 | .RE 865 | .IP \[bu] 2 866 | From \f[B]macOS Utilities\f[R] 867 | .RS 2 868 | .IP \[bu] 2 869 | Click \f[B]Reinstall macOS\f[R] and \f[B]Continue\f[R] 870 | .RE 871 | .IP \[bu] 2 872 | Complete the installation as you normally would. 873 | .RS 2 874 | .IP \[bu] 2 875 | On the first reboot use cursor keys and enter key to select \f[B]macOS 876 | Installer\f[R] 877 | .IP \[bu] 2 878 | On the subsequent reboots use cursor keys and enter key to select the 879 | disk you named 880 | .RE 881 | .IP \[bu] 2 882 | Once you have finished installing macOS you will be presented with an 883 | the out\-of\-the\-box first\-start wizard to configure various options 884 | and set up your username and password 885 | .IP \[bu] 2 886 | OPTIONAL: After you have concluded the out\-of\-the\-box wizard, you may 887 | want to enable the TRIM feature that the computer industry created for 888 | SSD disks. 889 | This feature in our macOS installation will allow QuickEmu to compact 890 | (shrink) your macOS disk image whenever you delete files inside the 891 | Virtual Machine. 892 | Without this step your macOS disk image will only ever get larger and 893 | will not shrink even when you delete lots of data inside macOS. 894 | .RS 2 895 | .IP \[bu] 2 896 | To enable TRIM, open the Terminal application and type the following 897 | command followed by pressing enter to tell macos to use the TRIM command 898 | on the hard disk when files are deleted: 899 | .RE 900 | .IP 901 | .EX 902 | sudo trimforce enable 903 | .EE 904 | .PP 905 | You will be prompted to enter your account\[aq]s password to gain the 906 | privilege needed. 907 | Once you\[aq]ve entered your password and pressed enter the command will 908 | request confirmation in the form of two questions that require you to 909 | type y (for a \[dq]yes\[dq] response) followed by enter to confirm. 910 | .PP 911 | If you press enter without first typing y the system will consider that 912 | a negative response as though you said \[dq]no\[dq]: 913 | .IP 914 | .EX 915 | IMPORTANT NOTICE: This tool force\-enables TRIM for all relevant attached devices, even though such devices may not have been validated for data integrity while using TRIM. Use of this tool to enable TRIM may result in unintended data loss or data corruption. It should not be used in a commercial operating environment or with important data. Before using this tool, you should back up all of your data and regularly back up data while TRIM is enabled. This tool is provided on an \[dq]as is\[dq] basis. APPLE MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF NON\-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THIS TOOL OR ITS USE ALONE OR IN COMBINATION WITH YOUR DEVICES, SYSTEMS, OR SERVICES. BY USING THIS TOOL TO ENABLE TRIM, YOU AGREE THAT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, USE OF THE TOOL IS AT YOUR SOLE RISK AND THAT THE ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY AND EFFORT IS WITH YOU. 916 | Are you sure you with to proceed (y/N)? 917 | .EE 918 | .PP 919 | And a second confirmation once you\[aq]ve confirmed the previous one: 920 | .IP 921 | .EX 922 | Your system will immediately reboot when this is complete. 923 | Is this OK (y/N)? 924 | .EE 925 | .PP 926 | As the last message states, your system will automatically reboot as 927 | soon as the command completes. 928 | .PP 929 | The default macOS configuration looks like this: 930 | .IP 931 | .EX 932 | guest_os=\[dq]macos\[dq] 933 | img=\[dq]macos\- big\-sur/RecoveryImage.img\[dq] 934 | disk_img=\[dq]macos\- big\-sur/disk.qcow2\[dq] 935 | macos_release=\[dq] big\-sur\[dq] 936 | .EE 937 | .IP \[bu] 2 938 | \f[CR]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for 939 | macOS. 940 | .IP \[bu] 2 941 | \f[CR]macos_release=\[dq] big\-sur\[dq]\f[R] instructs Quickemu to 942 | optimise for a particular macOS release. 943 | .RS 2 944 | .IP \[bu] 2 945 | For example VirtIO Network and Memory Ballooning are available in Big 946 | Sur and newer, but not previous releases. 947 | .IP \[bu] 2 948 | And VirtIO Block Media (disks) are supported/stable in Catalina and 949 | newer. 950 | .RE 951 | .SH macOS compatibility 952 | There are some considerations when running macOS via Quickemu. 953 | .IP \[bu] 2 954 | Supported macOS releases: 955 | .RS 2 956 | .IP \[bu] 2 957 | Mojave 958 | .IP \[bu] 2 959 | Catalina 960 | .IP \[bu] 2 961 | Big Sur 962 | .IP \[bu] 2 963 | Monterey 964 | .IP \[bu] 2 965 | Ventura 966 | .IP \[bu] 2 967 | Sonoma 968 | .RE 969 | .IP \[bu] 2 970 | \f[CR]quickemu\f[R] will automatically download the required \c 971 | .UR https://github.com/acidanthera/OpenCorePkg 972 | OpenCore 973 | .UE \c 974 | \ bootloader and OVMF firmware from \c 975 | .UR https://github.com/kholia/OSX-KVM 976 | OSX\-KVM 977 | .UE \c 978 | \&. 979 | .IP \[bu] 2 980 | Optimised by default, but no GPU acceleration is available. 981 | .RS 2 982 | .IP \[bu] 2 983 | Host CPU vendor is detected and guest CPU is optimised accordingly. 984 | .IP \[bu] 2 985 | \c 986 | .UR https://www.kraxel.org/blog/2019/06/macos-qemu-guest/ 987 | VirtIO Block Media 988 | .UE \c 989 | \ is used for the system disk where supported. 990 | .IP \[bu] 2 991 | \c 992 | .UR http://philjordan.eu/osx-virt/ 993 | VirtIO \f[CR]usb\-tablet\f[R] 994 | .UE \c 995 | \ is used for the mouse. 996 | .IP \[bu] 2 997 | VirtIO Network (\f[CR]virtio\-net\f[R]) is supported and enabled on 998 | macOS Big Sur and newer, but earlier releases use \f[CR]vmxnet3\f[R]. 999 | .IP \[bu] 2 1000 | VirtIO Memory Ballooning is supported and enabled on macOS Big Sur and 1001 | newer but disabled for other support macOS releases. 1002 | .RE 1003 | .IP \[bu] 2 1004 | USB host and SPICE pass\-through is: 1005 | .RS 2 1006 | .IP \[bu] 2 1007 | UHCI (USB 2.0) on macOS Catalina and earlier. 1008 | .IP \[bu] 2 1009 | XHCI (USB 3.0) on macOS Big Sur and newer. 1010 | .RE 1011 | .IP \[bu] 2 1012 | Display resolution can be changed via \f[CR]quickemu\f[R] using 1013 | \f[CR]\-\-width\f[R] and \f[CR]\-\-height\f[R] command line arguments. 1014 | .IP \[bu] 2 1015 | \f[B]Full Duplex audio requires \c 1016 | .UR https://github.com/chris1111/VoodooHDA-OC 1017 | VoodooHDA OC 1018 | .UE \c 1019 | \ or pass\-through a USB audio\-device to the macOS guest VM\f[R]. 1020 | .RS 2 1021 | .IP \[bu] 2 1022 | NOTE! 1023 | \c 1024 | .UR https://disable-gatekeeper.github.io/ 1025 | Gatekeeper 1026 | .UE \c 1027 | \ and \c 1028 | .UR https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection 1029 | System Integrity Protection (SIP) 1030 | .UE \c 1031 | \ need to be disabled to install VoodooHDA OC 1032 | .RE 1033 | .IP \[bu] 2 1034 | File sharing between guest and host is available via \c 1035 | .UR https://wiki.qemu.org/Documentation/9psetup 1036 | virtio\-9p 1037 | .UE \c 1038 | \ and \c 1039 | .UR https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24 1040 | SPICE webdavd 1041 | .UE \c 1042 | \&. 1043 | .IP \[bu] 2 1044 | Copy/paste via SPICE agent is \f[B]not available on macOS\f[R]. 1045 | .SH macOS App Store 1046 | If you see \f[I]\[dq]Your device or computer could not be 1047 | verified\[dq]\f[R] when you try to login to the App Store, make sure 1048 | that your wired ethernet device is \f[CR]en0\f[R]. 1049 | Use \f[CR]ifconfig\f[R] in a terminal to verify this. 1050 | .PP 1051 | If the wired ethernet device is not \f[CR]en0\f[R], then then go to 1052 | \f[I]System Preferences\f[R] \-> \f[I]Network\f[R], delete all the 1053 | network devices and apply the changes. 1054 | Next, open a terminal and run the following: 1055 | .IP 1056 | .EX 1057 | sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist 1058 | .EE 1059 | .PP 1060 | Now reboot, and the App Store should work. 1061 | .PP 1062 | There may be further advice and information about macOS guests in the 1063 | project \c 1064 | .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests 1065 | wiki 1066 | .UE \c 1067 | \&. 1068 | .SS \c 1069 | .UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines 1070 | Creating Windows guests 1071 | .UE \c 1072 | \ 🪟 1073 | \f[CR]quickget\f[R] can download \c 1074 | .UR https://www.microsoft.com/software-download/windows10 1075 | \f[B]Windows 10\f[R] 1076 | .UE \c 1077 | \ and \c 1078 | .UR https://www.microsoft.com/software-download/windows11 1079 | \f[B]Windows 11\f[R] 1080 | .UE \c 1081 | \ automatically and create an optimised virtual machine configuration. 1082 | This configuration also includes the \c 1083 | .UR https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/ 1084 | VirtIO drivers for Windows 1085 | .UE \c 1086 | \&. 1087 | .PP 1088 | \f[B]Windows 8.1\f[R] is also supported but doesn\[aq]t feature any 1089 | automated installation or driver optimisation. 1090 | .PP 1091 | \f[CR]quickget\f[R] can also download \c 1092 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-10-enterprise 1093 | Windows 10 LTSC 1094 | .UE \c 1095 | \ and Windows Server \c 1096 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-server-2012-r2 1097 | 2012\-r2 1098 | .UE \c 1099 | , \c 1100 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-server-2016 1101 | 2016 1102 | .UE \c 1103 | , \c 1104 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-server-2019 1105 | 2019 1106 | .UE \c 1107 | , and \c 1108 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-server-2022 1109 | 2022 1110 | .UE \c 1111 | \&. 1112 | No automated installation is supported for these releases. 1113 | .IP 1114 | .EX 1115 | quickget windows 11 1116 | quickemu \-\-vm windows\-11.conf 1117 | .EE 1118 | .IP \[bu] 2 1119 | Complete the installation as you normally would. 1120 | .IP \[bu] 2 1121 | All relevant drivers and services should be installed automatically. 1122 | .IP \[bu] 2 1123 | A local administrator user account is automatically created, with these 1124 | credentials: 1125 | .RS 2 1126 | .IP \[bu] 2 1127 | Username: \f[CR]Quickemu\f[R] 1128 | .IP \[bu] 2 1129 | Password: \f[CR]quickemu\f[R] 1130 | .RE 1131 | .PP 1132 | Further information is available from the project \c 1133 | .UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines 1134 | wiki 1135 | .UE \c 1136 | .SS Configuration 1137 | Here are the usage instructions: 1138 | .IP 1139 | .EX 1140 | Usage 1141 | quickemu \-\-vm ubuntu.conf 1142 | 1143 | Arguments 1144 | \-\-access : Enable remote spice access support. \[aq]local\[aq] (default), \[aq]remote\[aq], \[aq]clientipaddress\[aq] 1145 | \-\-braille : Enable braille support. Requires SDL. 1146 | \-\-delete\-disk : Delete the disk image and EFI variables 1147 | \-\-delete\-vm : Delete the entire VM and its configuration 1148 | \-\-display : Select display backend. \[aq]sdl\[aq] (default), \[aq]cocoa\[aq], \[aq]gtk\[aq], \[aq]none\[aq], \[aq]spice\[aq] or \[aq]spice\-app\[aq] 1149 | \-\-fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit) 1150 | \-\-ignore\-msrs\-always : Configure KVM to always ignore unhandled machine\-specific registers 1151 | \-\-kill : Kill the VM process if it is running 1152 | \-\-offline : Override all network settings and start the VM offline 1153 | \-\-shortcut : Create a desktop shortcut 1154 | \-\-snapshot apply : Apply/restore a snapshot. 1155 | \-\-snapshot create : Create a snapshot. 1156 | \-\-snapshot delete : Delete a snapshot. 1157 | \-\-snapshot info : Show disk/snapshot info. 1158 | \-\-status\-quo : Do not commit any changes to disk/snapshot. 1159 | \-\-viewer : Choose an alternative viewer. \[at]Options: \[aq]spicy\[aq] (default), \[aq]remote\-viewer\[aq], \[aq]none\[aq] 1160 | \-\-width : Set VM screen width; requires \[aq]\-\-height\[aq] 1161 | \-\-height : Set VM screen height; requires \[aq]\-\-width\[aq] 1162 | \-\-ssh\-port : Set SSH port manually 1163 | \-\-spice\-port : Set SPICE port manually 1164 | \-\-public\-dir : Expose share directory. \[at]Options: \[aq]\[aq] (default: xdg\-user\-dir PUBLICSHARE), \[aq]\[aq], \[aq]none\[aq] 1165 | \-\-monitor : Set monitor connection type. \[at]Options: \[aq]socket\[aq] (default), \[aq]telnet\[aq], \[aq]none\[aq] 1166 | \-\-monitor\-telnet\-host : Set telnet host for monitor. (default: \[aq]localhost\[aq]) 1167 | \-\-monitor\-telnet\-port : Set telnet port for monitor. (default: \[aq]4440\[aq]) 1168 | \-\-monitor\-cmd : Send command to monitor if available. (Example: system_powerdown) 1169 | \-\-serial : Set serial connection type. \[at]Options: \[aq]socket\[aq] (default), \[aq]telnet\[aq], \[aq]none\[aq] 1170 | \-\-serial\-telnet\-host : Set telnet host for serial. (default: \[aq]localhost\[aq]) 1171 | \-\-serial\-telnet\-port : Set telnet port for serial. (default: \[aq]6660\[aq]) 1172 | \-\-keyboard : Set keyboard. \[at]Options: \[aq]usb\[aq] (default), \[aq]ps2\[aq], \[aq]virtio\[aq] 1173 | \-\-keyboard_layout : Set keyboard layout: \[aq]en\-us\[aq] (default) 1174 | \-\-mouse : Set mouse. \[at]Options: \[aq]tablet\[aq] (default), \[aq]ps2\[aq], \[aq]usb\[aq], \[aq]virtio\[aq] 1175 | \-\-usb\-controller : Set usb\-controller. \[at]Options: \[aq]ehci\[aq] (default), \[aq]xhci\[aq], \[aq]none\[aq] 1176 | \-\-sound\-card : Set sound card. \[at]Options: \[aq]intel\-hda\[aq] (default), \[aq]ac97\[aq], \[aq]es1370\[aq], \[aq]sb16\[aq], \[aq]usb\-audio\[aq], \[aq]none\[aq] 1177 | \-\-sound\-duplex : Set sound card duplex. \[at]Options: \[aq]hda\-micro\[aq] (default: speaker/mic), \[aq]hda\-duplex\[aq] (line\-in/line\-out), \[aq]hda\-output\[aq] (output\-only) 1178 | \-\-extra_args : Pass additional arguments to qemu 1179 | \-\-version : Print version 1180 | .EE 1181 | .SS Desktop shortcuts 1182 | Desktop shortcuts can be created for a VM, the shortcuts are saved in 1183 | \f[CR]\[ti]/.local/share/applications\f[R]. 1184 | Here is an example of how to create a shortcut. 1185 | .IP 1186 | .EX 1187 | quickemu \-\-vm ubuntu\-22.04\-desktop.conf \-\-shortcut 1188 | .EE 1189 | .SS References 1190 | Useful reference that assisted the development of Quickemu. 1191 | .IP \[bu] 2 1192 | General 1193 | .RS 2 1194 | .IP \[bu] 2 1195 | \c 1196 | .UR https://qemu.readthedocs.io/en/latest/ 1197 | QEMU\[aq]s documentation! 1198 | .UE \c 1199 | .IP \[bu] 2 1200 | \c 1201 | .UR https://pve.proxmox.com/wiki/Qemu/KVM_Virtual_Machines 1202 | .UE \c 1203 | .IP \[bu] 2 1204 | \c 1205 | .UR https://www.kraxel.org/blog/2020/01/qemu-sound-audiodev/ 1206 | .UE \c 1207 | .RE 1208 | .IP \[bu] 2 1209 | macOS 1210 | .RS 2 1211 | .IP \[bu] 2 1212 | \c 1213 | .UR https://www.nicksherlock.com/2020/06/installing-macos-big-sur-on-proxmox/ 1214 | .UE \c 1215 | .IP \[bu] 2 1216 | \c 1217 | .UR https://passthroughpo.st/mac-os-adds-early-support-for-virtio-qemu/ 1218 | .UE \c 1219 | .IP \[bu] 2 1220 | \c 1221 | .UR https://github.com/kholia/OSX-KVM 1222 | .UE \c 1223 | .IP \[bu] 2 1224 | \c 1225 | .UR https://github.com/thenickdude/KVM-Opencore 1226 | .UE \c 1227 | .IP \[bu] 2 1228 | \c 1229 | .UR https://gist.github.com/MCJack123/943eaca762730ca4b7ae460b731b68e7 1230 | .UE \c 1231 | .IP \[bu] 2 1232 | \c 1233 | .UR https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/macrecovery 1234 | .UE \c 1235 | .IP \[bu] 2 1236 | \c 1237 | .UR https://www.kraxel.org/blog/2017/09/running-macos-as-guest-in-kvm/ 1238 | .UE \c 1239 | .IP \[bu] 2 1240 | \c 1241 | .UR https://www.nicksherlock.com/2017/10/passthrough-of-advanced-cpu-features-for-macos-high-sierra-guests/ 1242 | .UE \c 1243 | .IP \[bu] 2 1244 | \c 1245 | .UR http://philjordan.eu/osx-virt/ 1246 | .UE \c 1247 | .IP \[bu] 2 1248 | \c 1249 | .UR https://github.com/Dids/clover-builder 1250 | .UE \c 1251 | .IP \[bu] 2 1252 | \c 1253 | .UR https://mackie100projects.altervista.org 1254 | OpenCore Configurator 1255 | .UE \c 1256 | .RE 1257 | .IP \[bu] 2 1258 | Windows 1259 | .RS 2 1260 | .IP \[bu] 2 1261 | \c 1262 | .UR https://www.heiko-sieger.info/running-windows-10-on-linux-using-kvm-with-vga-passthrough/ 1263 | .UE \c 1264 | .IP \[bu] 2 1265 | \c 1266 | .UR https://leduccc.medium.com/improving-the-performance-of-a-windows-10-guest-on-qemu-a5b3f54d9cf5 1267 | .UE \c 1268 | .IP \[bu] 2 1269 | \c 1270 | .UR https://frontpagelinux.com/tutorials/how-to-use-linux-kvm-to-optimize-your-windows-10-virtual-machine/ 1271 | .UE \c 1272 | .IP \[bu] 2 1273 | \c 1274 | .UR https://turlucode.com/qemu-command-line-args/ 1275 | .UE \c 1276 | .IP \[bu] 2 1277 | \c 1278 | .UR https://github.com/pbatard/Fido 1279 | .UE \c 1280 | .IP \[bu] 2 1281 | \c 1282 | .UR https://www.catapultsystems.com/blogs/create-zero-touch-windows-10-iso/ 1283 | .UE \c 1284 | .RE 1285 | .IP \[bu] 2 1286 | TPM 1287 | .RS 2 1288 | .IP \[bu] 2 1289 | \c 1290 | .UR https://qemu-project.gitlab.io/qemu/specs/tpm.html 1291 | .UE \c 1292 | .IP \[bu] 2 1293 | \c 1294 | .UR https://www.tecklyfe.com/how-to-create-a-windows-11-virtual-machine-in-qemu/ 1295 | .UE \c 1296 | .RE 1297 | .IP \[bu] 2 1298 | 9p & virtiofs 1299 | .RS 2 1300 | .IP \[bu] 2 1301 | \c 1302 | .UR https://wiki.qemu.org/Documentation/9p 1303 | .UE \c 1304 | .IP \[bu] 2 1305 | \c 1306 | .UR https://wiki.qemu.org/Documentation/9psetup 1307 | .UE \c 1308 | .IP \[bu] 2 1309 | \c 1310 | .UR https://www.kraxel.org/blog/2019/06/macos-qemu-guest/ 1311 | .UE \c 1312 | .IP \[bu] 2 1313 | \c 1314 | .UR https://superuser.com/questions/628169/how-to-share-a-directory-with-the-host-without-networking-in-qemu 1315 | .UE \c 1316 | .IP \[bu] 2 1317 | \c 1318 | .UR https://virtio-fs.gitlab.io/ 1319 | .UE \c 1320 | .RE 1321 | .SH AUTHORS 1322 | Written by Martin Wimpress. 1323 | .SH BUGS 1324 | Submit bug reports online at: \c 1325 | .UR https://github.com/quickemu-project/quickemu/issues 1326 | .UE \c 1327 | .SH SEE ALSO 1328 | Full sources at: \c 1329 | .UR https://github.com/quickemu-project/quickemu 1330 | .UE \c 1331 | .PP 1332 | quickemu_conf(5), quickget(1), quickgui(1) 1333 | .SH AUTHORS 1334 | Martin Wimpress. 1335 | -------------------------------------------------------------------------------- /docs/quickemu.1.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: Martin Wimpress 3 | date: December 30, 2024 4 | footer: quickemu 5 | header: Quickemu User Manual 6 | section: 1 7 | title: QUICKEMU 8 | --- 9 | 10 | # NAME 11 | 12 | quickemu - A quick VM builder and manager 13 | 14 | # SYNOPSIS 15 | 16 | **quickemu** \[*OPTION*\]... 17 | 18 | # DESCRIPTION 19 | 20 | **quickemu** will create and run highly optimised desktop virtual 21 | machines for Linux, macOS and Windows 22 | 23 | # OPTIONS 24 | 25 | **--vm** 26 | : vm configuration file 27 | 28 | You can also pass optional parameters 29 | 30 | **--access** 31 | : Enable remote spice access support. 'local' (default), 'remote', 32 | 'clientipaddress' 33 | 34 | **--braille** 35 | : Enable braille support. Requires SDL. 36 | 37 | **--delete-disk** 38 | : Delete the disk image and EFI variables 39 | 40 | **--delete-vm** 41 | : Delete the entire VM and its configuration 42 | 43 | **--display** 44 | : Select display backend. 'sdl' (default), 'gtk', 'none', 'spice' or 45 | 'spice-app' 46 | 47 | **--fullscreen** 48 | : Starts VM in full screen mode (Ctl+Alt+f to exit) 49 | 50 | **--ignore-msrs-always** 51 | : Configure KVM to always ignore unhandled machine-specific registers 52 | 53 | **--kill** 54 | : Kill the VM process if it is running 55 | 56 | **--offline** 57 | : Override all network settings and start the VM offline 58 | 59 | **--shortcut** 60 | : Create a desktop shortcut 61 | 62 | **--snapshot apply \** 63 | : Apply/restore a snapshot. 64 | 65 | **--snapshot create \** 66 | : Create a snapshot. 67 | 68 | **--snapshot delete \** 69 | : Delete a snapshot. 70 | 71 | **--snapshot info** 72 | : Show disk/snapshot info. 73 | 74 | **--status-quo** 75 | : Do not commit any changes to disk/snapshot. 76 | 77 | **--viewer \** 78 | : Choose an alternative viewer. @Options: 'spicy' (default), 79 | 'remote-viewer', 'none' 80 | 81 | **--width \** 82 | : Set VM screen width; requires '--height' 83 | 84 | **--height \** 85 | : Set VM screen height; requires '--width' 86 | 87 | **--ssh-port \** 88 | : Set SSH port manually 89 | 90 | **--spice-port \** 91 | : Set SPICE port manually 92 | 93 | **--public-dir \** 94 | : Expose share directory. @Options: '' (default: xdg-user-dir 95 | PUBLICSHARE), '', 'none' 96 | 97 | **--monitor \** 98 | : Set monitor connection type. @Options: 'socket' (default), 'telnet', 99 | 'none' 100 | 101 | **--monitor-telnet-host \** 102 | : Set telnet host for monitor. (default: 'localhost') 103 | 104 | **--monitor-telnet-port \** 105 | : Set telnet port for monitor. (default: '4440') 106 | 107 | **--monitor-cmd \** 108 | : Send command to monitor if available. (Example: system_powerdown) 109 | 110 | **--serial \** 111 | : Set serial connection type. @Options: 'socket' (default), 'telnet', 112 | 'none' 113 | 114 | **--serial-telnet-host \** 115 | : Set telnet host for serial. (default: 'localhost') 116 | 117 | **--serial-telnet-port \** 118 | : Set telnet port for serial. (default: '6660') 119 | 120 | **--keyboard \** 121 | : Set keyboard. @Options: 'usb' (default), 'ps2', 'virtio' 122 | 123 | **--keyboard_layout \** 124 | : Set keyboard layout: 'en-us' (default) 125 | 126 | **--mouse \** 127 | : Set mouse. @Options: 'tablet' (default), 'ps2', 'usb', 'virtio' 128 | 129 | **--usb-controller \** 130 | : Set usb-controller. @Options: 'ehci' (default), 'xhci', 'none' 131 | 132 | **--sound-card \** 133 | : Set sound card. @Options: 'intel-hda' (default), 'ac97', 'es1370', 134 | 'sb16', 'none' 135 | 136 | **--extra_args \** 137 | : Pass additional arguments to qemu 138 | 139 | **--version** 140 | : Print version 141 | 142 | # EXAMPLES 143 | 144 | **quickemu --vm ubuntu-mate-22.04.conf** 145 | : Launches the VM specified in the file *ubuntu-mate-22.04.conf* 146 | 147 | # Introduction 148 | 149 | **Quickemu** is a wrapper for the excellent 150 | [QEMU](https://www.qemu.org/) that automatically *"does the right 151 | thing"* when creating virtual machines. No requirement for exhaustive 152 | configuration options. You decide what operating system you want to run 153 | and Quickemu takes care of the rest 🤖 154 | 155 | - `quickget` **automatically downloads the upstream OS** and creates the 156 | configuration 📀 157 | - `quickemu` enumerates your hardware and launches the virtual machine 158 | with the **optimum configuration best suited to your computer** ⚡️ 159 | 160 | The original objective of the project was to [enable quick testing of 161 | Linux 162 | distributions](https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines) 163 | where the virtual machines and their configuration can be stored 164 | anywhere (such as external USB storage or your home directory) and no 165 | elevated permissions are required to run the virtual machines. 166 | 167 | **Today, Quickemu includes comprehensive support for 168 | [macOS](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines), 169 | [Windows](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines)**, 170 | most of the BSDs, novel non-Linux operating systems such as FreeDOS, 171 | Haiku, KolibriOS, OpenIndiana, ReactOS, and more. 172 | 173 | # Features 174 | 175 | - Host support for **Linux and macOS** 176 | - **macOS** Sonoma, Ventura, Monterey, Big Sur, Catalina & Mojave 177 | - **Windows** 10 and 11 including TPM 2.0 178 | - **Windows Server** 2022 2019 2016 179 | - [Ubuntu](https://ubuntu.com/desktop) and all the **[official Ubuntu 180 | flavours](https://ubuntu.com/download/flavours)** 181 | - **Nearly 1000 operating system editions are supported!** 182 | - Full SPICE support including host/guest clipboard sharing 183 | - VirtIO-webdavd file sharing for Linux and Windows guests 184 | - VirtIO-9p file sharing for Linux and macOS guests 185 | - [QEMU Guest Agent support](https://wiki.qemu.org/Features/GuestAgent); 186 | provides access to a system-level agent via standard QMP commands 187 | - Samba file sharing for Linux, macOS and Windows guests (*if `smbd` is 188 | installed on the host*) 189 | - VirGL acceleration 190 | - USB device pass-through 191 | - Smartcard pass-through 192 | - Automatic SSH port forwarding to guests 193 | - Network port forwarding 194 | - Full duplex audio 195 | - Braille support 196 | - EFI (with or without SecureBoot) and Legacy BIOS boot 197 | 198 | ## As featured on [Linux Matters](https://linuxmatters.sh) podcast! 199 | 200 | The presenters of Linux Matters 🐧🎙️ are the creators of each of the 201 | principle Quickemu projects. We discussed Quickemu's 2024 reboot in 202 | [Episode 30 - Quickemu Rising From the 203 | Bashes](https://linuxmatters.sh/30). 204 | 205 | 206 |
207 | 208 | Linux Matters Podcast 209 |
Linux Matters Podcast 210 | 211 |
212 | 213 | When installing from source, you will need to install the following 214 | requirements manually: 215 | 216 | - [QEMU](https://www.qemu.org/) (*6.0.0 or newer*) **with GTK, SDL, 217 | SPICE & VirtFS support** 218 | - [bash](https://www.gnu.org/software/bash/) (*4.0 or newer*) 219 | - [Coreutils](https://www.gnu.org/software/coreutils/) 220 | - [curl](https://curl.se/) 221 | - [EDK II](https://github.com/tianocore/edk2) 222 | - [gawk](https://www.gnu.org/software/gawk/) 223 | - [grep](https://www.gnu.org/software/grep/) 224 | - [glxinfo](https://gitlab.freedesktop.org/mesa/demos) 225 | - [jq](https://stedolan.github.io/jq/) 226 | - [LSB](https://wiki.linuxfoundation.org/lsb/start) 227 | - [pciutils](https://github.com/pciutils/pciutils) 228 | - [procps](https://gitlab.com/procps-ng/procps) 229 | - [python3](https://www.python.org/) 230 | - [mkisofs](http://cdrtools.sourceforge.net/private/cdrecord.html) 231 | - [usbutils](https://github.com/gregkh/usbutils) 232 | - [util-linux](https://github.com/karelzak/util-linux); including 233 | `uuidgen` 234 | - [sed](https://www.gnu.org/software/sed/) 235 | - [socat](http://www.dest-unreach.org/socat/) 236 | - [spicy](https://gitlab.freedesktop.org/spice/spice-gtk) 237 | - [swtpm](https://github.com/stefanberger/swtpm) 238 | - [xdg-user-dirs](https://www.freedesktop.org/wiki/Software/xdg-user-dirs/) 239 | - [xrandr](https://gitlab.freedesktop.org/xorg/app/xrandr) 240 | - [zsync](http://zsync.moria.org.uk/) 241 | - [unzip](http://www.info-zip.org/UnZip.html) 242 | 243 | For Ubuntu, Arch and NixOS hosts, the 244 | [ppa](https://launchpad.net/~flexiondotorg/+archive/ubuntu/quickemu), 245 | [AUR](https://aur.archlinux.org/packages/quickemu) or 246 | [nix](https://github.com/NixOS/nixpkgs/tree/master/pkgs/development/quickemu) 247 | packaging will take care of the dependencies. For other host 248 | distributions or operating systems it will be necessary to install the 249 | above requirements or their equivalents. 250 | 251 | These examples may save a little typing: 252 | 253 | #### Install requirements on Debian hosts 254 | 255 | This also applies to derivatives: 256 | 257 | ``` shell 258 | sudo apt-get install bash coreutils curl genisoimage grep jq mesa-utils ovmf pciutils procps python3 qemu sed socat spice-client-gtk swtpm-tools unzip usbutils util-linux xdg-user-dirs xrandr zsync 259 | ``` 260 | 261 | #### Install requirements on Fedora hosts 262 | 263 | ``` shell 264 | sudo dnf install bash coreutils curl edk2-tools genisoimage grep jq mesa-demos pciutils procps python3 qemu sed socat spice-gtk-tools swtpm unzip usbutils util-linux uuidgen-runtime xdg-user-dirs xrandr zsync 265 | ``` 266 | 267 | ### Install requirements on Gentoo 268 | 269 | Please note that you may have to use `sys-firmware/edk2-ovmf` instead of 270 | `sys-firmware/edk2-ovmf-bin` - depending on how your system is 271 | configured. 272 | 273 | ``` shell 274 | sudo emerge --ask --noreplace app-emulation/qemu \ 275 | app-shells/bash \ 276 | sys-apps/coreutils \ 277 | net-misc/curl \ 278 | sys-firmware/edk2-ovmf-bin \ 279 | sys-apps/gawk \ 280 | sys-apps/grep \ 281 | x11-apps/mesa-progs \ 282 | app-misc/jq \ 283 | sys-apps/pciutils \ 284 | sys-process/procps \ 285 | app-cdr/cdrtools \ 286 | sys-apps/usbutils \ 287 | sys-apps/util-linux \ 288 | sys-apps/sed \ 289 | net-misc/socat \ 290 | app-emulation/spice \ 291 | app-crypt/swtpm \ 292 | x11-misc/xdg-user-dirs \ 293 | x11-apps/xrandr \ 294 | net-misc/zsync \ 295 | app-arch/unzip 296 | ``` 297 | 298 | #### Install requirements on macOS hosts 299 | 300 | Install the Quickemu requirements using brew: 301 | 302 | ``` shell 303 | brew install bash cdrtools coreutils jq python3 qemu usbutils samba socat swtpm zsync 304 | ``` 305 | 306 | Now clone the project: 307 | 308 | ``` shell 309 | git clone https://github.com/quickemu-project/quickemu 310 | cd quickemu 311 | ``` 312 | 313 | ## [Alternative Frontends](https://github.com/quickemu-project/quickemu/wiki/07-Alternative-frontends) 314 | 315 | ### Quickgui 316 | 317 | While `quickemu` and `quickget` are designed for the terminal, a 318 | graphical user interface is also available: 319 | 320 | - **[Quickgui](https://github.com/quickemu-project/quickgui)** by [Mark 321 | Johnson](https://github.com/marxjohnson) and [Yannick 322 | Mauray](https://github.com/ymauray). 323 | 324 | To install Quickgui on Ubuntu: 325 | 326 | ``` shell 327 | sudo add-apt-repository ppa:yannick-mauray/quickgui 328 | sudo apt update 329 | sudo apt install quickgui 330 | ``` 331 | 332 | Many thanks to [Luke Wesley-Holley](https://github.com/Lukewh) and 333 | [Philipp Kiemle](https://github.com/daPhipz) for creating the 334 | **[Quickemu icons](https://github.com/Lukewh/quickemu-icons)** 🎨 335 | 336 | ## Creating Linux guests 🐧 337 | 338 | ### Ubuntu 339 | 340 | `quickget` will automatically download an Ubuntu release and create the 341 | virtual machine configuration. 342 | 343 | ``` shell 344 | quickget ubuntu 22.04 345 | quickemu --vm ubuntu-22.04.conf 346 | ``` 347 | 348 | - Complete the installation as normal. 349 | - Post-install: 350 | - Install the SPICE agent (`spice-vdagent`) in the guest to enable 351 | copy/paste and USB redirection 352 | - `sudo apt install spice-vdagent` 353 | - Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to 354 | enable file sharing. 355 | - `sudo apt install spice-webdavd` 356 | 357 | ### Ubuntu daily-live images 358 | 359 | `quickget` can also download/refresh daily-live images via `zsync` for 360 | Ubuntu developers and testers. 361 | 362 | ``` shell 363 | quickget ubuntu daily-live 364 | quickemu --vm ubuntu-daily-live.conf 365 | ``` 366 | 367 | You can run `quickget ubuntu daily-live` to refresh your daily 368 | development image as often as you like, it will even automatically 369 | switch to a new series. 370 | 371 | ### Ubuntu Flavours 372 | 373 | All the official Ubuntu flavours are supported, just replace `ubuntu` 374 | with your preferred flavour. 375 | 376 | The project 377 | [wiki](https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines) 378 | may have further information. 379 | 380 | - `edubuntu` (Edubuntu) 381 | - `kubuntu` (Kubuntu) 382 | - `lubuntu` (Lubuntu) 383 | - `ubuntu-budgie` (Ubuntu Budgie) 384 | - `ubuntucinnamon` (Ubuntu Cinnamon) 385 | - `ubuntukylin` (Ubuntu Kylin) 386 | - `ubuntu-mate` (Ubuntu MATE) 387 | - `ubuntu-server` (Ubuntu Server) 388 | - `ubuntustudio` (Ubuntu Studio) 389 | - `ubuntu` (Ubuntu) 390 | - `ubuntu-unity` (Ubuntu Unity) 391 | - `xubuntu` (Xubuntu) 392 | 393 | You can also use `quickget` with advanced options : 394 | 395 | ``` text 396 | --download [edition] : Download image; no VM configuration 397 | --create-config [path/url] [flags] : Create VM config for an OS image 398 | --open-homepage : Open homepage for the OS 399 | --show [os] : Show OS information 400 | --version : Show version 401 | --help : Show this help message 402 | --disable-unattended : Force quickget not to set up an unattended installation 403 | --url [os] [release] [edition] : Show image URL(s) 404 | --check [os] [release] [edition] : Check image URL(s) 405 | --list : List all supported systems 406 | --list-csv : List everything in csv format 407 | --list-json : List everything in json format 408 | ``` 409 | 410 | Here are some typical uses 411 | 412 | ``` shell 413 | # show an OS ISO download URL for {os} {release} [edition] 414 | quickget --url fedora 38 Silverblue 415 | # test if an OS ISO is available for {os} {release} [edition] 416 | quickget --check nixos unstable plasma5 417 | # open an OS distribution homepage in a browser 418 | quickget --open-homepage ubuntu-mate 419 | # Only download image file into current directory, without creating VM 420 | quickget --download elementary 7.1 421 | ``` 422 | 423 | The `--url`, `--check`, and `--download` options are fully functional 424 | for all operating systems, including Windows and macOS. 425 | 426 | Further information is available from the project 427 | [wiki](https://github.com/quickemu-project/quickemu/wiki/06-Advanced-quickget-features) 428 | 429 | ### Other Operating Systems 430 | 431 | `quickget` also supports: 432 | 433 | - `alma` (AlmaLinux) 434 | - `alpine` (Alpine Linux) 435 | - `android` (Android x86) 436 | - `antix` (Antix) 437 | - `archcraft` (Archcraft) 438 | - `archlinux` (Arch Linux) 439 | - `arcolinux` (Arco Linux) 440 | - `artixlinux` (Artix Linux) 441 | - `athenaos` (Athena OS) 442 | - `batocera` (Batocera) 443 | - `bazzite` (Bazzite) 444 | - `biglinux` (BigLinux) 445 | - `blendos` (BlendOS) 446 | - `bodhi` (Bodhi) 447 | - `bunsenlabs` (BunsenLabs) 448 | - `cachyos` (CachyOS) 449 | - `centos-stream` (CentOS Stream) 450 | - `chimeralinux` (Chimera Linux) 451 | - `crunchbang++` (Crunchbangplusplus) 452 | - `debian` (Debian) 453 | - `deepin` (Deepin) 454 | - `devuan` (Devuan) 455 | - `dragonflybsd` (DragonFlyBSD) 456 | - `easyos` (EasyOS) 457 | - `elementary` (elementary OS) 458 | - `endeavouros` (EndeavourOS) 459 | - `endless` (Endless OS) 460 | - `fedora` (Fedora) 461 | - `freebsd` (FreeBSD) 462 | - `freedos` (FreeDOS) 463 | - `garuda` (Garuda Linux) 464 | - `gentoo` (Gentoo) 465 | - `ghostbsd` (GhostBSD) 466 | - `gnomeos` (GNOME OS) 467 | - `guix` (Guix) 468 | - `haiku` (Haiku) 469 | - `holoiso` (HoloISO) 470 | - `kali` (Kali) 471 | - `kdeneon` (KDE Neon) 472 | - `kolibrios` (KolibriOS) 473 | - `linuxlite` (Linux Lite) 474 | - `linuxmint` (Linux Mint) 475 | - `lmde` (Linux Mint Debian Edition) 476 | - `maboxlinux` (Mabox Linux) 477 | - `mageia` (Mageia) 478 | - `manjaro` (Manjaro) 479 | - `mxlinux` (MX Linux) 480 | - `netboot` (netboot.xyz) 481 | - `netbsd` (NetBSD) 482 | - `nitrux` (Nitrux) 483 | - `nixos` (NixOS) 484 | - `nwg-shell` (nwg-shell) 485 | - `openbsd` (OpenBSD) 486 | - `openindiana` (OpenIndiana) 487 | - `opensuse` (openSUSE) 488 | - `oraclelinux` (Oracle Linux) 489 | - `parrotsec` (Parrot Security) 490 | - `peppermint` (PeppermintOS) 491 | - `popos` (Pop!\_OS) 492 | - `porteus` (Porteus) 493 | - `primtux` (PrimTux) 494 | - `proxmox-ve` (Proxmox VE) 495 | - `pureos` (PureOS) 496 | - `reactos` (ReactOS) 497 | - `rebornos` (RebornOS) 498 | - `rockylinux` (Rocky Linux) 499 | - `siduction` (Siduction) 500 | - `slackware` (Slackware) 501 | - `slax` (Slax) 502 | - `slint` (Slint) 503 | - `slitaz` (SliTaz) 504 | - `solus` (Solus) 505 | - `sparkylinux` (SparkyLinux) 506 | - `spirallinux` (SpiralLinux) 507 | - `tails` (Tails) 508 | - `tinycore` (Tiny Core Linux) 509 | - `trisquel` (Trisquel-) 510 | - `truenas-core` (TrueNAS Core) 511 | - `truenas-scale` (TrueNAS Scale) 512 | - `tuxedo-os` (Tuxedo OS) 513 | - `vanillaos` (Vanilla OS) 514 | - `void` (Void Linux) 515 | - `vxlinux` (VX Linux) 516 | - `zorin` (Zorin OS) 517 | 518 | ### [Custom Linux guests](https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines#manually-create-linux-guests) 519 | 520 | Or you can download a Linux image and manually create a VM 521 | configuration. 522 | 523 | - Download a .iso image of a Linux distribution 524 | - Create a VM configuration file; for example `debian-bullseye.conf` 525 | 526 | ``` shell 527 | guest_os="linux" 528 | disk_img="debian-bullseye/disk.qcow2" 529 | iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" 530 | ``` 531 | 532 | - Use `quickemu` to start the virtual machine: 533 | 534 | ``` shell 535 | quickemu --vm debian-bullseye.conf 536 | ``` 537 | 538 | - Complete the installation as normal. 539 | - Post-install: 540 | - Install the SPICE agent (`spice-vdagent`) in the guest to enable 541 | copy/paste and USB redirection. 542 | - Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to 543 | enable file sharing. 544 | 545 | ## Supporting old Linux distros 546 | 547 | If you want to run an old Linux , from 2016 or earlier, change the 548 | `guest_os` to `linux_old`. This will enable the `vmware-svga` graphics 549 | driver which is better supported on older distros. 550 | 551 | ## [Creating macOS Guests](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests) 🍏 552 | 553 | **Installing macOS in a VM can be a bit finicky, if you encounter 554 | problems, [check the 555 | Discussions](https://github.com/quickemu-project/quickemu/discussions) 556 | for solutions or ask for help there** 🛟 557 | 558 | `quickget` automatically downloads a macOS recovery image and creates a 559 | virtual machine configuration. 560 | 561 | ``` shell 562 | quickget macos big-sur 563 | quickemu --vm macos-big-sur.conf 564 | ``` 565 | 566 | macOS `mojave`, `catalina`, `big-sur`, `monterey`, `ventura` and 567 | `sonoma` are supported. 568 | 569 | - Use cursor keys and enter key to select the **macOS Base System** 570 | - From **macOS Utilities** 571 | - Click **Disk Utility** and **Continue** 572 | - Select `QEMU HARDDISK Media` (~103.08GB) from the list (on Big Sur 573 | and above use `Apple Inc. VirtIO Block Device`) and click 574 | **Erase**. 575 | - Enter a `Name:` for the disk 576 | - If you are installing macOS Mojave or later (Catalina, Big Sur, 577 | Monterey, Ventura and Sonoma), choose any of the APFS options as 578 | the filesystem. MacOS Extended may not work. 579 | - Click **Erase**. 580 | - Click **Done**. 581 | - Close Disk Utility 582 | - From **macOS Utilities** 583 | - Click **Reinstall macOS** and **Continue** 584 | - Complete the installation as you normally would. 585 | - On the first reboot use cursor keys and enter key to select **macOS 586 | Installer** 587 | - On the subsequent reboots use cursor keys and enter key to select 588 | the disk you named 589 | - Once you have finished installing macOS you will be presented with an 590 | the out-of-the-box first-start wizard to configure various options and 591 | set up your username and password 592 | - OPTIONAL: After you have concluded the out-of-the-box wizard, you may 593 | want to enable the TRIM feature that the computer industry created for 594 | SSD disks. This feature in our macOS installation will allow QuickEmu 595 | to compact (shrink) your macOS disk image whenever you delete files 596 | inside the Virtual Machine. Without this step your macOS disk image 597 | will only ever get larger and will not shrink even when you delete 598 | lots of data inside macOS. 599 | - To enable TRIM, open the Terminal application and type the following 600 | command followed by pressing enter to tell macos to use 601 | the TRIM command on the hard disk when files are deleted: 602 | 603 | ``` shell 604 | sudo trimforce enable 605 | ``` 606 | 607 | You will be prompted to enter your account's password to gain the 608 | privilege needed. Once you've entered your password and pressed 609 | enter the command will request confirmation in the form of 610 | two questions that require you to type y (for a "yes" 611 | response) followed by enter to confirm. 612 | 613 | If you press enter without first typing y the 614 | system will consider that a negative response as though you said "no": 615 | 616 | ``` plain 617 | IMPORTANT NOTICE: This tool force-enables TRIM for all relevant attached devices, even though such devices may not have been validated for data integrity while using TRIM. Use of this tool to enable TRIM may result in unintended data loss or data corruption. It should not be used in a commercial operating environment or with important data. Before using this tool, you should back up all of your data and regularly back up data while TRIM is enabled. This tool is provided on an "as is" basis. APPLE MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THIS TOOL OR ITS USE ALONE OR IN COMBINATION WITH YOUR DEVICES, SYSTEMS, OR SERVICES. BY USING THIS TOOL TO ENABLE TRIM, YOU AGREE THAT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, USE OF THE TOOL IS AT YOUR SOLE RISK AND THAT THE ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY AND EFFORT IS WITH YOU. 618 | Are you sure you with to proceed (y/N)? 619 | ``` 620 | 621 | And a second confirmation once you've confirmed the previous one: 622 | 623 | ``` plain 624 | Your system will immediately reboot when this is complete. 625 | Is this OK (y/N)? 626 | ``` 627 | 628 | As the last message states, your system will automatically reboot as 629 | soon as the command completes. 630 | 631 | The default macOS configuration looks like this: 632 | 633 | ``` shell 634 | guest_os="macos" 635 | img="macos- big-sur/RecoveryImage.img" 636 | disk_img="macos- big-sur/disk.qcow2" 637 | macos_release=" big-sur" 638 | ``` 639 | 640 | - `guest_os="macos"` instructs Quickemu to optimise for macOS. 641 | - `macos_release=" big-sur"` instructs Quickemu to optimise for a 642 | particular macOS release. 643 | - For example VirtIO Network and Memory Ballooning are available in 644 | Big Sur and newer, but not previous releases. 645 | - And VirtIO Block Media (disks) are supported/stable in Catalina and 646 | newer. 647 | 648 | # macOS compatibility 649 | 650 | There are some considerations when running macOS via Quickemu. 651 | 652 | - Supported macOS releases: 653 | - Mojave 654 | - Catalina 655 | - Big Sur 656 | - Monterey 657 | - Ventura 658 | - Sonoma 659 | - `quickemu` will automatically download the required 660 | [OpenCore](https://github.com/acidanthera/OpenCorePkg) bootloader and 661 | OVMF firmware from [OSX-KVM](https://github.com/kholia/OSX-KVM). 662 | - Optimised by default, but no GPU acceleration is available. 663 | - Host CPU vendor is detected and guest CPU is optimised accordingly. 664 | - [VirtIO Block 665 | Media](https://www.kraxel.org/blog/2019/06/macos-qemu-guest/) is 666 | used for the system disk where supported. 667 | - [VirtIO `usb-tablet`](http://philjordan.eu/osx-virt/) is used for 668 | the mouse. 669 | - VirtIO Network (`virtio-net`) is supported and enabled on macOS Big 670 | Sur and newer, but earlier releases use `vmxnet3`. 671 | - VirtIO Memory Ballooning is supported and enabled on macOS Big Sur 672 | and newer but disabled for other support macOS releases. 673 | - USB host and SPICE pass-through is: 674 | - UHCI (USB 2.0) on macOS Catalina and earlier. 675 | - XHCI (USB 3.0) on macOS Big Sur and newer. 676 | - Display resolution can be changed via `quickemu` using `--width` and 677 | `--height` command line arguments. 678 | - **Full Duplex audio requires [VoodooHDA 679 | OC](https://github.com/chris1111/VoodooHDA-OC) or pass-through a USB 680 | audio-device to the macOS guest VM**. 681 | - NOTE! [Gatekeeper](https://disable-gatekeeper.github.io/) and 682 | [System Integrity Protection 683 | (SIP)](https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection) 684 | need to be disabled to install VoodooHDA OC 685 | - File sharing between guest and host is available via 686 | [virtio-9p](https://wiki.qemu.org/Documentation/9psetup) and [SPICE 687 | webdavd](https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24). 688 | - Copy/paste via SPICE agent is **not available on macOS**. 689 | 690 | # macOS App Store 691 | 692 | If you see *"Your device or computer could not be verified"* when you 693 | try to login to the App Store, make sure that your wired ethernet device 694 | is `en0`. Use `ifconfig` in a terminal to verify this. 695 | 696 | If the wired ethernet device is not `en0`, then then go to *System 697 | Preferences* -\> *Network*, delete all the network devices and apply the 698 | changes. Next, open a terminal and run the following: 699 | 700 | ``` shell 701 | sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist 702 | ``` 703 | 704 | Now reboot, and the App Store should work. 705 | 706 | There may be further advice and information about macOS guests in the 707 | project 708 | [wiki](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests). 709 | 710 | ## [Creating Windows guests](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines) 🪟 711 | 712 | `quickget` can download [**Windows 713 | 10**](https://www.microsoft.com/software-download/windows10) and 714 | [**Windows 11**](https://www.microsoft.com/software-download/windows11) 715 | automatically and create an optimised virtual machine configuration. 716 | This configuration also includes the [VirtIO drivers for 717 | Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/). 718 | 719 | **Windows 8.1** is also supported but doesn't feature any automated 720 | installation or driver optimisation. 721 | 722 | `quickget` can also download [Windows 10 723 | LTSC](https://www.microsoft.com/en-us/evalcenter/download-windows-10-enterprise) 724 | and Windows Server 725 | [2012-r2](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2012-r2), 726 | [2016](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2016), 727 | [2019](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2019), 728 | and 729 | [2022](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2022). 730 | No automated installation is supported for these releases. 731 | 732 | ``` shell 733 | quickget windows 11 734 | quickemu --vm windows-11.conf 735 | ``` 736 | 737 | - Complete the installation as you normally would. 738 | - All relevant drivers and services should be installed automatically. 739 | - A local administrator user account is automatically created, with 740 | these credentials: 741 | - Username: `Quickemu` 742 | - Password: `quickemu` 743 | 744 | Further information is available from the project 745 | [wiki](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines) 746 | 747 | ## Configuration 748 | 749 | Here are the usage instructions: 750 | 751 | ``` text 752 | Usage 753 | quickemu --vm ubuntu.conf 754 | 755 | Arguments 756 | --access : Enable remote spice access support. 'local' (default), 'remote', 'clientipaddress' 757 | --braille : Enable braille support. Requires SDL. 758 | --delete-disk : Delete the disk image and EFI variables 759 | --delete-vm : Delete the entire VM and its configuration 760 | --display : Select display backend. 'sdl' (default), 'cocoa', 'gtk', 'none', 'spice' or 'spice-app' 761 | --fullscreen : Starts VM in full screen mode (Ctl+Alt+f to exit) 762 | --ignore-msrs-always : Configure KVM to always ignore unhandled machine-specific registers 763 | --kill : Kill the VM process if it is running 764 | --offline : Override all network settings and start the VM offline 765 | --shortcut : Create a desktop shortcut 766 | --snapshot apply : Apply/restore a snapshot. 767 | --snapshot create : Create a snapshot. 768 | --snapshot delete : Delete a snapshot. 769 | --snapshot info : Show disk/snapshot info. 770 | --status-quo : Do not commit any changes to disk/snapshot. 771 | --viewer : Choose an alternative viewer. @Options: 'spicy' (default), 'remote-viewer', 'none' 772 | --width : Set VM screen width; requires '--height' 773 | --height : Set VM screen height; requires '--width' 774 | --ssh-port : Set SSH port manually 775 | --spice-port : Set SPICE port manually 776 | --public-dir : Expose share directory. @Options: '' (default: xdg-user-dir PUBLICSHARE), '', 'none' 777 | --monitor : Set monitor connection type. @Options: 'socket' (default), 'telnet', 'none' 778 | --monitor-telnet-host : Set telnet host for monitor. (default: 'localhost') 779 | --monitor-telnet-port : Set telnet port for monitor. (default: '4440') 780 | --monitor-cmd : Send command to monitor if available. (Example: system_powerdown) 781 | --serial : Set serial connection type. @Options: 'socket' (default), 'telnet', 'none' 782 | --serial-telnet-host : Set telnet host for serial. (default: 'localhost') 783 | --serial-telnet-port : Set telnet port for serial. (default: '6660') 784 | --keyboard : Set keyboard. @Options: 'usb' (default), 'ps2', 'virtio' 785 | --keyboard_layout : Set keyboard layout: 'en-us' (default) 786 | --mouse : Set mouse. @Options: 'tablet' (default), 'ps2', 'usb', 'virtio' 787 | --usb-controller : Set usb-controller. @Options: 'ehci' (default), 'xhci', 'none' 788 | --sound-card : Set sound card. @Options: 'intel-hda' (default), 'ac97', 'es1370', 'sb16', 'usb-audio', 'none' 789 | --sound-duplex : Set sound card duplex. @Options: 'hda-micro' (default: speaker/mic), 'hda-duplex' (line-in/line-out), 'hda-output' (output-only) 790 | --extra_args : Pass additional arguments to qemu 791 | --version : Print version 792 | ``` 793 | 794 | ## Desktop shortcuts 795 | 796 | Desktop shortcuts can be created for a VM, the shortcuts are saved in 797 | `~/.local/share/applications`. Here is an example of how to create a 798 | shortcut. 799 | 800 | ``` shell 801 | quickemu --vm ubuntu-22.04-desktop.conf --shortcut 802 | ``` 803 | 804 | ## References 805 | 806 | Useful reference that assisted the development of Quickemu. 807 | 808 | - General 809 | - [QEMU's documentation!](https://qemu.readthedocs.io/en/latest/) 810 | - 811 | - 812 | - macOS 813 | - 814 | - 815 | - 816 | - 817 | - 818 | - 819 | - 820 | - 821 | - 822 | - 823 | - [OpenCore Configurator](https://mackie100projects.altervista.org) 824 | - Windows 825 | - 826 | - 827 | - 828 | - 829 | - 830 | - 831 | - TPM 832 | - 833 | - 834 | - 9p & virtiofs 835 | - 836 | - 837 | - 838 | - 839 | - 840 | 841 | # AUTHORS 842 | 843 | Written by Martin Wimpress. 844 | 845 | # BUGS 846 | 847 | Submit bug reports online at: 848 | 849 | 850 | # SEE ALSO 851 | 852 | Full sources at: 853 | 854 | quickemu_conf(5), quickget(1), quickgui(1) 855 | -------------------------------------------------------------------------------- /docs/quickemu_conf.5: -------------------------------------------------------------------------------- 1 | .\" Automatically generated by Pandoc 3.6.1 2 | .\" 3 | .TH "QUICKEMU_CONF" "5" "December 30, 2024" "quickemu_conf" "Quickemu Configuration Manual" 4 | .SH NAME 5 | quickemu_conf \- Options and parameters in the quickemu .conf 6 | .SH DESCRIPTION 7 | \f[B]quickemu\f[R] will create and run highly optimised desktop virtual 8 | machines for Linux, macOS and Windows. 9 | It uses sensible defaults, but many configuration options can be 10 | overridden in the required configuration file, which will as a minimum 11 | specify the path to the installation ISO and QEMU disk for the installed 12 | VM 13 | .SH OPTIONS 14 | These are the options and defaults for the .conf file 15 | .IP 16 | .EX 17 | # Lowercase variables are used in the VM config file only 18 | boot=\[dq]efi\[dq] 19 | cpu_cores=\[dq]\[dq] 20 | disk_img=\[dq]\[dq] 21 | disk_size=\[dq]\[dq] 22 | display=\[dq]\[dq] 23 | extra_args=\[dq]\[dq] 24 | fixed_iso=\[dq]\[dq] 25 | floppy=\[dq]\[dq] 26 | guest_os=\[dq]linux\[dq] 27 | img=\[dq]\[dq] 28 | iso=\[dq]\[dq] 29 | macaddr=\[dq]\[dq] 30 | macos_release=\[dq]\[dq] 31 | network=\[dq]\[dq] 32 | port_forwards=() 33 | preallocation=\[dq]off\[dq] 34 | ram=\[dq]\[dq] 35 | secureboot=\[dq]off\[dq] 36 | tpm=\[dq]off\[dq] 37 | usb_devices=() 38 | viewer=\[dq]spicy\[dq] 39 | ssh_port=\[dq]\[dq] 40 | spice_port=\[dq]\[dq] 41 | public_dir=\[dq]\[dq] 42 | monitor=\[dq]socket\[dq] 43 | monitor_telnet_port=\[dq]4440\[dq] 44 | monitor_telnet_host=\[dq]localhost\[dq] 45 | monitor_cmd=\[dq]\[dq] 46 | serial=\[dq]socket\[dq] 47 | serial_telnet_port=\[dq]6660\[dq] 48 | serial_telnet_host=\[dq]localhost\[dq] 49 | # options: ehci(USB2.0), xhci(USB3.0) 50 | usb_controller=\[dq]ehci\[dq] 51 | # options: ps2, usb, virtio 52 | keyboard=\[dq]usb\[dq] 53 | keyboard_layout=\[dq]en\-us\[dq] 54 | # options: ps2, usb, tablet, virtio 55 | mouse=\[dq]tablet\[dq] 56 | .EE 57 | .SH EXAMPLES 58 | .IP 59 | .EX 60 | guest_os=\[dq]linux\[dq] 61 | disk_img=\[dq]debian\-bullseye/disk.qcow2\[dq] 62 | iso=\[dq]debian\-bullseye/firmware\-11.0.0\-amd64\-DVD\-1.iso\[dq] 63 | .EE 64 | .PP 65 | The default macOS configuration looks like this: 66 | .IP 67 | .EX 68 | guest_os=\[dq]macos\[dq] 69 | img=\[dq]macos\-catalina/RecoveryImage.img\[dq] 70 | disk_img=\[dq]macos\-catalina/disk.qcow2\[dq] 71 | macos_release=\[dq]catalina\[dq] 72 | .EE 73 | .IP \[bu] 2 74 | \f[CR]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for 75 | macOS. 76 | .IP \[bu] 2 77 | \f[CR]macos_release=\[dq]catalina\[dq]\f[R] instructs Quickemu to 78 | optimise for a particular macOS release. 79 | .RS 2 80 | .IP \[bu] 2 81 | For example VirtIO Network and Memory Ballooning are available in Big 82 | Sur and newer, but not previous releases. 83 | .IP \[bu] 2 84 | And VirtIO Block Media (disks) are supported/stable in Catalina and 85 | newer. 86 | .RE 87 | .PP 88 | The default Windows 11 configuration looks like this: 89 | .IP 90 | .EX 91 | guest_os=\[dq]windows\[dq] 92 | disk_img=\[dq]windows\-11/disk.qcow2\[dq] 93 | iso=\[dq]windows\-11/Win11_EnglishInternational_x64.iso\[dq] 94 | fixed_iso=\[dq]windows\-11/virtio\-win.iso\[dq] 95 | tpm=\[dq]on\[dq] 96 | secureboot=\[dq]on\[dq] 97 | .EE 98 | .IP \[bu] 2 99 | \f[CR]guest_os=\[dq]windows\[dq]\f[R] instructs \f[CR]quickemu\f[R] to 100 | optimise for Windows. 101 | .IP \[bu] 2 102 | \f[CR]fixed_iso=\f[R] specifies the ISO image that provides VirtIO 103 | drivers. 104 | .IP \[bu] 2 105 | \f[CR]tpm=\[dq]on\[dq]\f[R] instructs \f[CR]quickemu\f[R] to create a 106 | software emulated TPM device using \f[CR]swtpm\f[R]. 107 | .SS BIOS and EFI 108 | Since Quickemu 2.1.0 \f[CR]efi\f[R] is the default boot option. 109 | If you want to override this behaviour then add the following line to 110 | you VM configuration to enable legacy BIOS. 111 | .IP \[bu] 2 112 | \f[CR]boot=\[dq]legacy\[dq]\f[R] \- Enable Legacy BIOS boot 113 | .SS Tuning CPU cores, RAM & disks 114 | By default, Quickemu will calculate the number of CPUs cores and RAM to 115 | allocate to a VM based on the specifications of your host computer. 116 | You can override this default behaviour and tune the VM configuration to 117 | your liking. 118 | .PP 119 | Add additional lines to your virtual machine configuration: 120 | .IP \[bu] 2 121 | \f[CR]cpu_cores=\[dq]4\[dq]\f[R] \- Specify the number of CPU cores 122 | allocated to the VM 123 | .IP \[bu] 2 124 | \f[CR]ram=\[dq]4G\[dq]\f[R] \- Specify the amount of RAM to allocate to 125 | the VM 126 | .IP \[bu] 2 127 | \f[CR]disk_size=\[dq]16G\[dq]\f[R] \- Specify the size of the virtual 128 | disk allocated to the VM 129 | .SS Disk preallocation 130 | Preallocation mode (allowed values: \f[CR]off\f[R] (default), 131 | \f[CR]metadata\f[R], \f[CR]falloc\f[R], \f[CR]full\f[R]). 132 | An image with preallocated metadata is initially larger but can improve 133 | performance when the image needs to grow. 134 | .PP 135 | Specify what disk preallocation should be used, if any, when creating 136 | the system disk image by adding a line like this to your VM 137 | configuration. 138 | .IP \[bu] 2 139 | \f[CR]preallocation=\[dq]metadata\[dq]\f[R] 140 | .SS CD\-ROM disks 141 | If you want to expose an ISO image from the host to guest add the 142 | following line to the VM configuration: 143 | .IP \[bu] 2 144 | \f[CR]fixed_iso=\[dq]/path/to/image.iso\[dq]\f[R] 145 | .SS Floppy disks 146 | If you\[aq]re like \c 147 | .UR https://popey.com 148 | Alan Pope 149 | .UE \c 150 | \ you\[aq]ll probably want to mount a floppy disk image in the guest. 151 | To do so add the following line to the VM configuration: 152 | .IP \[bu] 2 153 | \f[CR]floppy=\[dq]/path/to/floppy.img\[dq]\f[R] 154 | .SS File Sharing 155 | All File Sharing options will only expose \f[CR]\[ti]/Public\f[R] (or 156 | localised variations) for the current user to the guest VMs. 157 | .SS Samba 🐧 🍏 🪟 158 | If \f[CR]smbd\f[R] is available on the host, Quickemu will automatically 159 | enable the built\-in QEMU support for exposing a Samba share from the 160 | host to the guest. 161 | .PP 162 | You can install the minimal Samba components on Ubuntu using: 163 | .IP 164 | .EX 165 | sudo apt install \-\-no\-install\-recommends samba 166 | .EE 167 | .PP 168 | If everything is set up correctly, the \f[CR]smbd\f[R] address will be 169 | printed when the virtual machine is started. 170 | For example: 171 | .IP 172 | .EX 173 | \- smbd: On guest: smb://10.0.2.4/qemu 174 | .EE 175 | .PP 176 | If using a Windows guest, right\-click on \[dq]This PC\[dq], click 177 | \[dq]Add a network location\[dq], and paste this address, removing 178 | \f[CR]smb:\f[R] and replacing forward slashes with backslashes (in this 179 | example \f[CR]\[rs]\[rs]10.0.2.4\[rs]qemu\f[R]). 180 | .SS SPICE WebDAV 🐧 🪟 181 | .IP \[bu] 2 182 | TBD 183 | .SS VirtIO\-9P 🐧 🍏 184 | .IP \[bu] 2 185 | TBD 186 | .SS Networking 187 | .SS Port forwarding 188 | Add an additional line to your virtual machine configuration. 189 | For example: 190 | .IP \[bu] 2 191 | \f[CR]port_forwards=(\[dq]8123:8123\[dq] \[dq]8888:80\[dq])\f[R] 192 | .PP 193 | In the example above: 194 | .IP \[bu] 2 195 | Port 8123 on the host is forwarded to port 8123 on the guest. 196 | .IP \[bu] 2 197 | Port 8888 on the host is forwarded to port 80 on the guest. 198 | .SS Disable networking 199 | To completely disable all network interfaces in a guest VM add this 200 | additional line to your virtual machine configuration: 201 | .IP \[bu] 2 202 | \f[CR]network=\[dq]none\[dq]\f[R] 203 | .SS Restricted networking 204 | You can isolate the guest from the host (and broader network) using the 205 | restrict option, which will restrict networking to just the guest and 206 | any virtual devices. 207 | .PP 208 | This can be used to prevent software running inside the guest from 209 | phoning home while still providing a network inside the guest. 210 | Add this additional line to your virtual machine configuration: 211 | .IP \[bu] 2 212 | \f[CR]network=\[dq]restrict\[dq]\f[R] 213 | .SS Bridged networking 214 | Connect your virtual machine to a preconfigured network bridge. 215 | Add an additional line to your virtual machine configuration: 216 | .IP \[bu] 2 217 | \f[CR]network=\[dq]br0\[dq]\f[R] 218 | .PP 219 | If you want to have a persistent MAC address for your bridged network 220 | interface in the guest VM you can add \f[CR]macaddr\f[R] to the virtual 221 | machine configuration. 222 | QEMU requires that the MAC address is in the range: 223 | \f[B]52:54:00:AB:00:00 \- 52:54:00:AB:FF:FF\f[R] 224 | .PP 225 | So you can generate your own MAC addresses with: 226 | .IP \[bu] 2 227 | \f[CR]macaddr=\[dq]52:54:00:AB:51:AE\[dq]\f[R] 228 | .SS USB redirection 229 | Quickemu supports USB redirection via SPICE pass\-through and host 230 | pass\-through. 231 | Quickemu supports USB redirection via SPICE pass\-through and host 232 | pass\-through. 233 | .PP 234 | \f[B]NOTE!\f[R] When a USB device is redirected from the host, it will 235 | not be usable by host operating system until the guest redirection is 236 | stopped. 237 | Therefore, do not redirect the input devices, such as the keyboard and 238 | mouse, as it will be difficult (or impossible) to revert the situation. 239 | .SS SPICE redirection (recommended) 240 | Using SPICE for USB pass\-through is easiest as it doesn\[aq]t require 241 | any elevated permission: 242 | .PP 243 | Both \f[CR]spicy\f[R] from \c 244 | .UR https://www.spice-space.org/spice-gtk.html 245 | spice\-gtk 246 | .UE \c 247 | \ (\f[I]Input \-> Select USB Devices for redirection\f[R]) and 248 | \f[CR]remote\-viewer\f[R] from \c 249 | .UR https://gitlab.com/virt-viewer/virt-viewer 250 | virt\-viewer 251 | .UE \c 252 | \ (\f[I]File \-> USB device selection\f[R]) support this feature. 253 | .IP \[bu] 2 254 | Start Quickemu with \f[CR]\-\-display spice\f[R] and then 255 | .IP \[bu] 2 256 | Select \f[CR]Input\f[R] \-> \f[CR]Select USB Device for redirection\f[R] 257 | from the menu to choose which device(s) you want to attach to the guest. 258 | .IP \[bu] 2 259 | **\f[CR]spicy\f[R] (default) 260 | .RS 2 261 | .IP \[bu] 2 262 | **Select \f[CR]Input\f[R] \-> 263 | \f[CR]Select USB Device for redirection\f[R] from the menu to choose 264 | which device(s) you want to attach to the guest. 265 | .RE 266 | .IP \[bu] 2 267 | **\f[CR]remote\-viewer\f[R] 268 | .RS 2 269 | .IP \[bu] 2 270 | **Select \f[CR]File\f[R] \-> \f[CR]USB device selection\f[R] from the 271 | menu to choose which device(s) you want to attach to the guest. 272 | .RE 273 | .PP 274 | To ensure that this functionality works as expected, make sure that you 275 | have installed the necessary SPICE Guest Tools on the virtual machine. 276 | .SS Enabling SPICE redirection on NixOS 277 | On NixOS, if you encounter this error: 278 | .IP 279 | .EX 280 | Error setting facl: Operation not permitted 281 | .EE 282 | .PP 283 | Try setting \c 284 | .UR https://search.nixos.org/options?channel=23.11&show=virtualisation.spiceUSBRedirection.enable&from=0&size=50&sort=relevance&type=packages&query=spiceusbredirec 285 | the following option 286 | .UE \c 287 | : 288 | .IP 289 | .EX 290 | virtualisation.spiceUSBRedirection.enable = true; 291 | .EE 292 | .SS Host redirection (\f[B]NOT Recommended\f[R]) 293 | \f[B]USB host redirection is not recommended\f[R], it is provided purely 294 | for backwards compatibility to older versions of Quickemu. 295 | Using SPICE is preferred, see above. 296 | .PP 297 | Add an additional line to your virtual machine configuration. 298 | For example: 299 | .IP \[bu] 2 300 | \f[CR]usb_devices=(\[dq]046d:082d\[dq] \[dq]046d:085e\[dq])\f[R] 301 | .PP 302 | In the example above: 303 | .IP \[bu] 2 304 | The USB device with vendor_id 046d and product_id 082d will be exposed 305 | to the guest. 306 | .IP \[bu] 2 307 | The USB device with vendor_id 046d and product_id 085e will be exposed 308 | to the guest. 309 | .PP 310 | If the USB devices are not writable, \f[CR]quickemu\f[R] will display 311 | the appropriate commands to modify the USB device(s) access permissions, 312 | like this: 313 | .IP 314 | .EX 315 | \- USB: Host pass\-through requested: 316 | \- Sennheiser Communications EPOS GTW 270 on bus 001 device 005 needs permission changes: 317 | sudo chown \-v root:user /dev/bus/usb/001/005 318 | ERROR! USB permission changes are required 👆 319 | .EE 320 | .SS TPM 321 | Since Quickemu 2.2.0 a software emulated TPM device can be added to 322 | guest virtual machines. 323 | Just add \f[CR]tpm=\[dq]on\[dq]\f[R] to your VM configuration. 324 | \f[CR]quickget\f[R] will automatically add this line to Windows 11 325 | virtual machines. 326 | .SH AUTHORS 327 | Written by Martin Wimpress. 328 | .SH BUGS 329 | Submit bug reports online at: \c 330 | .UR https://github.com/quickemu-project/quickemu/issues 331 | .UE \c 332 | .SH SEE ALSO 333 | Full sources at: \c 334 | .UR https://github.com/quickemu-project/quickemu 335 | .UE \c 336 | .PP 337 | quickget(1), quickemu(1), quickgui(1) 338 | .SH AUTHORS 339 | Martin Wimpress. 340 | -------------------------------------------------------------------------------- /docs/quickemu_conf.5.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: Martin Wimpress 3 | date: December 30, 2024 4 | footer: quickemu_conf 5 | header: Quickemu Configuration Manual 6 | section: 5 7 | title: QUICKEMU_CONF 8 | --- 9 | 10 | # NAME 11 | 12 | quickemu_conf - Options and parameters in the quickemu \.conf 13 | 14 | # DESCRIPTION 15 | 16 | **quickemu** will create and run highly optimised desktop virtual 17 | machines for Linux, macOS and Windows. It uses sensible defaults, but 18 | many configuration options can be overridden in the required 19 | configuration file, which will as a minimum specify the path to the 20 | installation ISO and QEMU disk for the installed VM 21 | 22 | # OPTIONS 23 | 24 | These are the options and defaults for the \.conf file 25 | 26 | ``` shell 27 | # Lowercase variables are used in the VM config file only 28 | boot="efi" 29 | cpu_cores="" 30 | disk_img="" 31 | disk_size="" 32 | display="" 33 | extra_args="" 34 | fixed_iso="" 35 | floppy="" 36 | guest_os="linux" 37 | img="" 38 | iso="" 39 | macaddr="" 40 | macos_release="" 41 | network="" 42 | port_forwards=() 43 | preallocation="off" 44 | ram="" 45 | secureboot="off" 46 | tpm="off" 47 | usb_devices=() 48 | viewer="spicy" 49 | ssh_port="" 50 | spice_port="" 51 | public_dir="" 52 | monitor="socket" 53 | monitor_telnet_port="4440" 54 | monitor_telnet_host="localhost" 55 | monitor_cmd="" 56 | serial="socket" 57 | serial_telnet_port="6660" 58 | serial_telnet_host="localhost" 59 | # options: ehci(USB2.0), xhci(USB3.0) 60 | usb_controller="ehci" 61 | # options: ps2, usb, virtio 62 | keyboard="usb" 63 | keyboard_layout="en-us" 64 | # options: ps2, usb, tablet, virtio 65 | mouse="tablet" 66 | ``` 67 | 68 | # EXAMPLES 69 | 70 | ``` shell 71 | guest_os="linux" 72 | disk_img="debian-bullseye/disk.qcow2" 73 | iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" 74 | ``` 75 | 76 | The default macOS configuration looks like this: 77 | 78 | ``` shell 79 | guest_os="macos" 80 | img="macos-catalina/RecoveryImage.img" 81 | disk_img="macos-catalina/disk.qcow2" 82 | macos_release="catalina" 83 | ``` 84 | 85 | - `guest_os="macos"` instructs Quickemu to optimise for macOS. 86 | - `macos_release="catalina"` instructs Quickemu to optimise for a 87 | particular macOS release. 88 | - For example VirtIO Network and Memory Ballooning are available in 89 | Big Sur and newer, but not previous releases. 90 | - And VirtIO Block Media (disks) are supported/stable in Catalina and 91 | newer. 92 | 93 | The default Windows 11 configuration looks like this: 94 | 95 | ``` shell 96 | guest_os="windows" 97 | disk_img="windows-11/disk.qcow2" 98 | iso="windows-11/Win11_EnglishInternational_x64.iso" 99 | fixed_iso="windows-11/virtio-win.iso" 100 | tpm="on" 101 | secureboot="on" 102 | ``` 103 | 104 | - `guest_os="windows"` instructs `quickemu` to optimise for Windows. 105 | - `fixed_iso=` specifies the ISO image that provides VirtIO drivers. 106 | - `tpm="on"` instructs `quickemu` to create a software emulated TPM 107 | device using `swtpm`. 108 | 109 | ### BIOS and EFI 110 | 111 | Since Quickemu 2.1.0 `efi` is the default boot option. If you want to 112 | override this behaviour then add the following line to you VM 113 | configuration to enable legacy BIOS. 114 | 115 | - `boot="legacy"` - Enable Legacy BIOS boot 116 | 117 | ### Tuning CPU cores, RAM & disks 118 | 119 | By default, Quickemu will calculate the number of CPUs cores and RAM to 120 | allocate to a VM based on the specifications of your host computer. You 121 | can override this default behaviour and tune the VM configuration to 122 | your liking. 123 | 124 | Add additional lines to your virtual machine configuration: 125 | 126 | - `cpu_cores="4"` - Specify the number of CPU cores allocated to the VM 127 | - `ram="4G"` - Specify the amount of RAM to allocate to the VM 128 | - `disk_size="16G"` - Specify the size of the virtual disk allocated to 129 | the VM 130 | 131 | ### Disk preallocation 132 | 133 | Preallocation mode (allowed values: `off` (default), `metadata`, 134 | `falloc`, `full`). An image with preallocated metadata is initially 135 | larger but can improve performance when the image needs to grow. 136 | 137 | Specify what disk preallocation should be used, if any, when creating 138 | the system disk image by adding a line like this to your VM 139 | configuration. 140 | 141 | - `preallocation="metadata"` 142 | 143 | ### CD-ROM disks 144 | 145 | If you want to expose an ISO image from the host to guest add the 146 | following line to the VM configuration: 147 | 148 | - `fixed_iso="/path/to/image.iso"` 149 | 150 | ### Floppy disks 151 | 152 | If you're like [Alan Pope](https://popey.com) you'll probably want to 153 | mount a floppy disk image in the guest. To do so add the following line 154 | to the VM configuration: 155 | 156 | - `floppy="/path/to/floppy.img"` 157 | 158 | ### File Sharing 159 | 160 | All File Sharing options will only expose `~/Public` (or localised 161 | variations) for the current user to the guest VMs. 162 | 163 | #### Samba 🐧 🍏 🪟 164 | 165 | If `smbd` is available on the host, Quickemu will automatically enable 166 | the built-in QEMU support for exposing a Samba share from the host to 167 | the guest. 168 | 169 | You can install the minimal Samba components on Ubuntu using: 170 | 171 | ``` shell 172 | sudo apt install --no-install-recommends samba 173 | ``` 174 | 175 | If everything is set up correctly, the `smbd` address will be printed 176 | when the virtual machine is started. For example: 177 | 178 | - smbd: On guest: smb://10.0.2.4/qemu 179 | 180 | If using a Windows guest, right-click on "This PC", click "Add a network 181 | location", and paste this address, removing `smb:` and replacing forward 182 | slashes with backslashes (in this example `\\10.0.2.4\qemu`). 183 | 184 | #### SPICE WebDAV 🐧 🪟 185 | 186 | - TBD 187 | 188 | #### VirtIO-9P 🐧 🍏 189 | 190 | - TBD 191 | 192 | ### Networking 193 | 194 | #### Port forwarding 195 | 196 | Add an additional line to your virtual machine configuration. For 197 | example: 198 | 199 | - `port_forwards=("8123:8123" "8888:80")` 200 | 201 | In the example above: 202 | 203 | - Port 8123 on the host is forwarded to port 8123 on the guest. 204 | - Port 8888 on the host is forwarded to port 80 on the guest. 205 | 206 | #### Disable networking 207 | 208 | To completely disable all network interfaces in a guest VM add this 209 | additional line to your virtual machine configuration: 210 | 211 | - `network="none"` 212 | 213 | #### Restricted networking 214 | 215 | You can isolate the guest from the host (and broader network) using the 216 | restrict option, which will restrict networking to just the guest and 217 | any virtual devices. 218 | 219 | This can be used to prevent software running inside the guest from 220 | phoning home while still providing a network inside the guest. Add this 221 | additional line to your virtual machine configuration: 222 | 223 | - `network="restrict"` 224 | 225 | #### Bridged networking 226 | 227 | Connect your virtual machine to a preconfigured network bridge. Add an 228 | additional line to your virtual machine configuration: 229 | 230 | - `network="br0"` 231 | 232 | If you want to have a persistent MAC address for your bridged network 233 | interface in the guest VM you can add `macaddr` to the virtual machine 234 | configuration. QEMU requires that the MAC address is in the range: 235 | **52:54:00:AB:00:00 - 52:54:00:AB:FF:FF** 236 | 237 | So you can generate your own MAC addresses with: 238 | 239 | - `macaddr="52:54:00:AB:51:AE"` 240 | 241 | ### USB redirection 242 | 243 | Quickemu supports USB redirection via SPICE pass-through and host 244 | pass-through. Quickemu supports USB redirection via SPICE pass-through 245 | and host pass-through. 246 | 247 | **NOTE!** When a USB device is redirected from the host, it will not be 248 | usable by host operating system until the guest redirection is stopped. 249 | Therefore, do not redirect the input devices, such as the keyboard and 250 | mouse, as it will be difficult (or impossible) to revert the situation. 251 | 252 | #### SPICE redirection (recommended) 253 | 254 | Using SPICE for USB pass-through is easiest as it doesn't require any 255 | elevated permission: 256 | 257 | Both `spicy` from 258 | [spice-gtk](https://www.spice-space.org/spice-gtk.html) (*Input -\> 259 | Select USB Devices for redirection*) and `remote-viewer` from 260 | [virt-viewer](https://gitlab.com/virt-viewer/virt-viewer) (*File -\> USB 261 | device selection*) support this feature. 262 | 263 | - Start Quickemu with `--display spice` and then 264 | - Select `Input` -\> `Select USB Device for redirection` from the menu 265 | to choose which device(s) you want to attach to the guest. 266 | - \*\*`spicy` (default) 267 | - \*\*Select `Input` -\> `Select USB Device for redirection` from the 268 | menu to choose which device(s) you want to attach to the guest. 269 | - \*\*`remote-viewer` 270 | - \*\*Select `File` -\> `USB device selection` from the menu to choose 271 | which device(s) you want to attach to the guest. 272 | 273 | To ensure that this functionality works as expected, make sure that you 274 | have installed the necessary SPICE Guest Tools on the virtual machine. 275 | 276 | ##### Enabling SPICE redirection on NixOS 277 | 278 | On NixOS, if you encounter this error: 279 | 280 | Error setting facl: Operation not permitted 281 | 282 | Try setting [the following 283 | option](https://search.nixos.org/options?channel=23.11&show=virtualisation.spiceUSBRedirection.enable&from=0&size=50&sort=relevance&type=packages&query=spiceusbredirec): 284 | 285 | ``` nix 286 | virtualisation.spiceUSBRedirection.enable = true; 287 | ``` 288 | 289 | #### Host redirection (**NOT Recommended**) 290 | 291 | **USB host redirection is not recommended**, it is provided purely for 292 | backwards compatibility to older versions of Quickemu. Using SPICE is 293 | preferred, see above. 294 | 295 | Add an additional line to your virtual machine configuration. For 296 | example: 297 | 298 | - `usb_devices=("046d:082d" "046d:085e")` 299 | 300 | In the example above: 301 | 302 | - The USB device with vendor_id 046d and product_id 082d will be exposed 303 | to the guest. 304 | - The USB device with vendor_id 046d and product_id 085e will be exposed 305 | to the guest. 306 | 307 | If the USB devices are not writable, `quickemu` will display the 308 | appropriate commands to modify the USB device(s) access permissions, 309 | like this: 310 | 311 | - USB: Host pass-through requested: 312 | - Sennheiser Communications EPOS GTW 270 on bus 001 device 005 needs permission changes: 313 | sudo chown -v root:user /dev/bus/usb/001/005 314 | ERROR! USB permission changes are required 👆 315 | 316 | ### TPM 317 | 318 | Since Quickemu 2.2.0 a software emulated TPM device can be added to 319 | guest virtual machines. Just add `tpm="on"` to your VM configuration. 320 | `quickget` will automatically add this line to Windows 11 virtual 321 | machines. 322 | 323 | # AUTHORS 324 | 325 | Written by Martin Wimpress. 326 | 327 | # BUGS 328 | 329 | Submit bug reports online at: 330 | 331 | 332 | # SEE ALSO 333 | 334 | Full sources at: 335 | 336 | quickget(1), quickemu(1), quickgui(1) 337 | -------------------------------------------------------------------------------- /docs/quickget.1: -------------------------------------------------------------------------------- 1 | .\" Automatically generated by Pandoc 3.6.1 2 | .\" 3 | .TH "QUICKGET" "1" "December 30, 2024" "quickget" "Quickget User Manual" 4 | .SH NAME 5 | quickget \- download and prepare materials for building a quickemu VM 6 | .SH SYNOPSIS 7 | \f[B]quickget\f[R] [\f[I]os\f[R]] [\f[I]release\f[R]] 8 | [\f[I]edition\f[R]] | [\f[I]OPTION\f[R]]* 9 | .SH DESCRIPTION 10 | \f[B]quickget\f[R] will download the requisite materials and prepare a 11 | configuration for \f[CR]quickemu\f[R] to use to build and run 12 | .SH OPTIONS 13 | .TP 14 | \f[B][OS] [Release] [Edition]\f[R] 15 | specify the OS and release (and optional edition) if insufficient input 16 | is provided a list of missing options will be reported and the script 17 | will exit. 18 | Editions may not apply and will be defaulted if not provided. 19 | .TP 20 | \f[B]\-\-download\f[R] [edition] 21 | Download image; no VM configuration 22 | .TP 23 | \f[B]\-\-create\-config\f[R] [path/url] 24 | Create VM config for a OS image 25 | .TP 26 | \f[B]\-\-open\-homepage\f[R] 27 | Open homepage for the OS 28 | .TP 29 | \f[B]\-\-show\f[R] [os] 30 | Show OS information 31 | .TP 32 | \f[B]\-\-url\f[R] [os] [release] [edition] 33 | Show image URL(s) 34 | .TP 35 | \f[B]\-\-check\f[R] [os] [release] [edition] 36 | Check image URL(s) 37 | .TP 38 | \f[B]\-\-list\f[R] 39 | List all supported systems 40 | .TP 41 | \f[B]\-\-list\-csv\f[R] 42 | List everything in csv format 43 | .TP 44 | \f[B]\-\-list\-json\f[R] 45 | List everything in json format 46 | .TP 47 | \f[B]\-\-version\f[R] 48 | Show version 49 | .TP 50 | \f[B]\-\-help\f[R] 51 | Show this help message 52 | .SH NOTES 53 | .SS Creating Linux guests 🐧 54 | .SS Ubuntu 55 | \f[CR]quickget\f[R] will automatically download an Ubuntu release and 56 | create the virtual machine configuration. 57 | .IP 58 | .EX 59 | quickget ubuntu 22.04 60 | quickemu \-\-vm ubuntu\-22.04.conf 61 | .EE 62 | .IP \[bu] 2 63 | Complete the installation as normal. 64 | .IP \[bu] 2 65 | Post\-install: 66 | .RS 2 67 | .IP \[bu] 2 68 | Install the SPICE agent (\f[CR]spice\-vdagent\f[R]) in the guest to 69 | enable copy/paste and USB redirection 70 | .RS 2 71 | .IP \[bu] 2 72 | \f[CR]sudo apt install spice\-vdagent\f[R] 73 | .RE 74 | .IP \[bu] 2 75 | Install the SPICE WebDAV agent (\f[CR]spice\-webdavd\f[R]) in the guest 76 | to enable file sharing. 77 | .RS 2 78 | .IP \[bu] 2 79 | \f[CR]sudo apt install spice\-webdavd\f[R] 80 | .RE 81 | .RE 82 | .SS Ubuntu daily\-live images 83 | \f[CR]quickget\f[R] can also download/refresh daily\-live images via 84 | \f[CR]zsync\f[R] for Ubuntu developers and testers. 85 | .IP 86 | .EX 87 | quickget ubuntu daily\-live 88 | quickemu \-\-vm ubuntu\-daily\-live.conf 89 | .EE 90 | .PP 91 | You can run \f[CR]quickget ubuntu daily\-live\f[R] to refresh your daily 92 | development image as often as you like, it will even automatically 93 | switch to a new series. 94 | .SS Ubuntu Flavours 95 | All the official Ubuntu flavours are supported, just replace 96 | \f[CR]ubuntu\f[R] with your preferred flavour. 97 | .PP 98 | The project \c 99 | .UR https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines 100 | wiki 101 | .UE \c 102 | \ may have further information. 103 | .IP \[bu] 2 104 | \f[CR]edubuntu\f[R] (Edubuntu) 105 | .IP \[bu] 2 106 | \f[CR]kubuntu\f[R] (Kubuntu) 107 | .IP \[bu] 2 108 | \f[CR]lubuntu\f[R] (Lubuntu) 109 | .IP \[bu] 2 110 | \f[CR]ubuntu\-budgie\f[R] (Ubuntu Budgie) 111 | .IP \[bu] 2 112 | \f[CR]ubuntucinnamon\f[R] (Ubuntu Cinnamon) 113 | .IP \[bu] 2 114 | \f[CR]ubuntukylin\f[R] (Ubuntu Kylin) 115 | .IP \[bu] 2 116 | \f[CR]ubuntu\-mate\f[R] (Ubuntu MATE) 117 | .IP \[bu] 2 118 | \f[CR]ubuntu\-server\f[R] (Ubuntu Server) 119 | .IP \[bu] 2 120 | \f[CR]ubuntustudio\f[R] (Ubuntu Studio) 121 | .IP \[bu] 2 122 | \f[CR]ubuntu\f[R] (Ubuntu) 123 | .IP \[bu] 2 124 | \f[CR]ubuntu\-unity\f[R] (Ubuntu Unity) 125 | .IP \[bu] 2 126 | \f[CR]xubuntu\f[R] (Xubuntu) 127 | .PP 128 | You can also use \f[CR]quickget\f[R] with advanced options : 129 | .IP 130 | .EX 131 | \-\-download [edition] : Download image; no VM configuration 132 | \-\-create\-config [path/url] [flags] : Create VM config for an OS image 133 | \-\-open\-homepage : Open homepage for the OS 134 | \-\-show [os] : Show OS information 135 | \-\-version : Show version 136 | \-\-help : Show this help message 137 | \-\-disable\-unattended : Force quickget not to set up an unattended installation 138 | \-\-url [os] [release] [edition] : Show image URL(s) 139 | \-\-check [os] [release] [edition] : Check image URL(s) 140 | \-\-list : List all supported systems 141 | \-\-list\-csv : List everything in csv format 142 | \-\-list\-json : List everything in json format 143 | .EE 144 | .PP 145 | Here are some typical uses 146 | .IP 147 | .EX 148 | # show an OS ISO download URL for {os} {release} [edition] 149 | quickget \-\-url fedora 38 Silverblue 150 | # test if an OS ISO is available for {os} {release} [edition] 151 | quickget \-\-check nixos unstable plasma5 152 | # open an OS distribution homepage in a browser 153 | quickget \-\-open\-homepage ubuntu\-mate 154 | # Only download image file into current directory, without creating VM 155 | quickget \-\-download elementary 7.1 156 | .EE 157 | .PP 158 | The \f[CR]\-\-url\f[R], \f[CR]\-\-check\f[R], and 159 | \f[CR]\-\-download\f[R] options are fully functional for all operating 160 | systems, including Windows and macOS. 161 | .PP 162 | Further information is available from the project \c 163 | .UR https://github.com/quickemu-project/quickemu/wiki/06-Advanced-quickget-features 164 | wiki 165 | .UE \c 166 | .SS Other Operating Systems 167 | \f[CR]quickget\f[R] also supports: 168 | .IP \[bu] 2 169 | \f[CR]alma\f[R] (AlmaLinux) 170 | .IP \[bu] 2 171 | \f[CR]alpine\f[R] (Alpine Linux) 172 | .IP \[bu] 2 173 | \f[CR]android\f[R] (Android x86) 174 | .IP \[bu] 2 175 | \f[CR]antix\f[R] (Antix) 176 | .IP \[bu] 2 177 | \f[CR]archcraft\f[R] (Archcraft) 178 | .IP \[bu] 2 179 | \f[CR]archlinux\f[R] (Arch Linux) 180 | .IP \[bu] 2 181 | \f[CR]arcolinux\f[R] (Arco Linux) 182 | .IP \[bu] 2 183 | \f[CR]artixlinux\f[R] (Artix Linux) 184 | .IP \[bu] 2 185 | \f[CR]athenaos\f[R] (Athena OS) 186 | .IP \[bu] 2 187 | \f[CR]batocera\f[R] (Batocera) 188 | .IP \[bu] 2 189 | \f[CR]bazzite\f[R] (Bazzite) 190 | .IP \[bu] 2 191 | \f[CR]biglinux\f[R] (BigLinux) 192 | .IP \[bu] 2 193 | \f[CR]blendos\f[R] (BlendOS) 194 | .IP \[bu] 2 195 | \f[CR]bodhi\f[R] (Bodhi) 196 | .IP \[bu] 2 197 | \f[CR]bunsenlabs\f[R] (BunsenLabs) 198 | .IP \[bu] 2 199 | \f[CR]cachyos\f[R] (CachyOS) 200 | .IP \[bu] 2 201 | \f[CR]centos\-stream\f[R] (CentOS Stream) 202 | .IP \[bu] 2 203 | \f[CR]chimeralinux\f[R] (Chimera Linux) 204 | .IP \[bu] 2 205 | \f[CR]crunchbang++\f[R] (Crunchbangplusplus) 206 | .IP \[bu] 2 207 | \f[CR]debian\f[R] (Debian) 208 | .IP \[bu] 2 209 | \f[CR]deepin\f[R] (Deepin) 210 | .IP \[bu] 2 211 | \f[CR]devuan\f[R] (Devuan) 212 | .IP \[bu] 2 213 | \f[CR]dragonflybsd\f[R] (DragonFlyBSD) 214 | .IP \[bu] 2 215 | \f[CR]easyos\f[R] (EasyOS) 216 | .IP \[bu] 2 217 | \f[CR]elementary\f[R] (elementary OS) 218 | .IP \[bu] 2 219 | \f[CR]endeavouros\f[R] (EndeavourOS) 220 | .IP \[bu] 2 221 | \f[CR]endless\f[R] (Endless OS) 222 | .IP \[bu] 2 223 | \f[CR]fedora\f[R] (Fedora) 224 | .IP \[bu] 2 225 | \f[CR]freebsd\f[R] (FreeBSD) 226 | .IP \[bu] 2 227 | \f[CR]freedos\f[R] (FreeDOS) 228 | .IP \[bu] 2 229 | \f[CR]garuda\f[R] (Garuda Linux) 230 | .IP \[bu] 2 231 | \f[CR]gentoo\f[R] (Gentoo) 232 | .IP \[bu] 2 233 | \f[CR]ghostbsd\f[R] (GhostBSD) 234 | .IP \[bu] 2 235 | \f[CR]gnomeos\f[R] (GNOME OS) 236 | .IP \[bu] 2 237 | \f[CR]guix\f[R] (Guix) 238 | .IP \[bu] 2 239 | \f[CR]haiku\f[R] (Haiku) 240 | .IP \[bu] 2 241 | \f[CR]holoiso\f[R] (HoloISO) 242 | .IP \[bu] 2 243 | \f[CR]kali\f[R] (Kali) 244 | .IP \[bu] 2 245 | \f[CR]kdeneon\f[R] (KDE Neon) 246 | .IP \[bu] 2 247 | \f[CR]kolibrios\f[R] (KolibriOS) 248 | .IP \[bu] 2 249 | \f[CR]linuxlite\f[R] (Linux Lite) 250 | .IP \[bu] 2 251 | \f[CR]linuxmint\f[R] (Linux Mint) 252 | .IP \[bu] 2 253 | \f[CR]lmde\f[R] (Linux Mint Debian Edition) 254 | .IP \[bu] 2 255 | \f[CR]maboxlinux\f[R] (Mabox Linux) 256 | .IP \[bu] 2 257 | \f[CR]mageia\f[R] (Mageia) 258 | .IP \[bu] 2 259 | \f[CR]manjaro\f[R] (Manjaro) 260 | .IP \[bu] 2 261 | \f[CR]mxlinux\f[R] (MX Linux) 262 | .IP \[bu] 2 263 | \f[CR]netboot\f[R] (netboot.xyz) 264 | .IP \[bu] 2 265 | \f[CR]netbsd\f[R] (NetBSD) 266 | .IP \[bu] 2 267 | \f[CR]nitrux\f[R] (Nitrux) 268 | .IP \[bu] 2 269 | \f[CR]nixos\f[R] (NixOS) 270 | .IP \[bu] 2 271 | \f[CR]nwg\-shell\f[R] (nwg\-shell) 272 | .IP \[bu] 2 273 | \f[CR]openbsd\f[R] (OpenBSD) 274 | .IP \[bu] 2 275 | \f[CR]openindiana\f[R] (OpenIndiana) 276 | .IP \[bu] 2 277 | \f[CR]opensuse\f[R] (openSUSE) 278 | .IP \[bu] 2 279 | \f[CR]oraclelinux\f[R] (Oracle Linux) 280 | .IP \[bu] 2 281 | \f[CR]parrotsec\f[R] (Parrot Security) 282 | .IP \[bu] 2 283 | \f[CR]peppermint\f[R] (PeppermintOS) 284 | .IP \[bu] 2 285 | \f[CR]popos\f[R] (Pop!_OS) 286 | .IP \[bu] 2 287 | \f[CR]porteus\f[R] (Porteus) 288 | .IP \[bu] 2 289 | \f[CR]primtux\f[R] (PrimTux) 290 | .IP \[bu] 2 291 | \f[CR]proxmox\-ve\f[R] (Proxmox VE) 292 | .IP \[bu] 2 293 | \f[CR]pureos\f[R] (PureOS) 294 | .IP \[bu] 2 295 | \f[CR]reactos\f[R] (ReactOS) 296 | .IP \[bu] 2 297 | \f[CR]rebornos\f[R] (RebornOS) 298 | .IP \[bu] 2 299 | \f[CR]rockylinux\f[R] (Rocky Linux) 300 | .IP \[bu] 2 301 | \f[CR]siduction\f[R] (Siduction) 302 | .IP \[bu] 2 303 | \f[CR]slackware\f[R] (Slackware) 304 | .IP \[bu] 2 305 | \f[CR]slax\f[R] (Slax) 306 | .IP \[bu] 2 307 | \f[CR]slint\f[R] (Slint) 308 | .IP \[bu] 2 309 | \f[CR]slitaz\f[R] (SliTaz) 310 | .IP \[bu] 2 311 | \f[CR]solus\f[R] (Solus) 312 | .IP \[bu] 2 313 | \f[CR]sparkylinux\f[R] (SparkyLinux) 314 | .IP \[bu] 2 315 | \f[CR]spirallinux\f[R] (SpiralLinux) 316 | .IP \[bu] 2 317 | \f[CR]tails\f[R] (Tails) 318 | .IP \[bu] 2 319 | \f[CR]tinycore\f[R] (Tiny Core Linux) 320 | .IP \[bu] 2 321 | \f[CR]trisquel\f[R] (Trisquel\-) 322 | .IP \[bu] 2 323 | \f[CR]truenas\-core\f[R] (TrueNAS Core) 324 | .IP \[bu] 2 325 | \f[CR]truenas\-scale\f[R] (TrueNAS Scale) 326 | .IP \[bu] 2 327 | \f[CR]tuxedo\-os\f[R] (Tuxedo OS) 328 | .IP \[bu] 2 329 | \f[CR]vanillaos\f[R] (Vanilla OS) 330 | .IP \[bu] 2 331 | \f[CR]void\f[R] (Void Linux) 332 | .IP \[bu] 2 333 | \f[CR]vxlinux\f[R] (VX Linux) 334 | .IP \[bu] 2 335 | \f[CR]zorin\f[R] (Zorin OS) 336 | .SS \c 337 | .UR https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines#manually-create-linux-guests 338 | Custom Linux guests 339 | .UE \c 340 | Or you can download a Linux image and manually create a VM 341 | configuration. 342 | .IP \[bu] 2 343 | Download a .iso image of a Linux distribution 344 | .IP \[bu] 2 345 | Create a VM configuration file; for example 346 | \f[CR]debian\-bullseye.conf\f[R] 347 | .IP 348 | .EX 349 | guest_os=\[dq]linux\[dq] 350 | disk_img=\[dq]debian\-bullseye/disk.qcow2\[dq] 351 | iso=\[dq]debian\-bullseye/firmware\-11.0.0\-amd64\-DVD\-1.iso\[dq] 352 | .EE 353 | .IP \[bu] 2 354 | Use \f[CR]quickemu\f[R] to start the virtual machine: 355 | .IP 356 | .EX 357 | quickemu \-\-vm debian\-bullseye.conf 358 | .EE 359 | .IP \[bu] 2 360 | Complete the installation as normal. 361 | .IP \[bu] 2 362 | Post\-install: 363 | .RS 2 364 | .IP \[bu] 2 365 | Install the SPICE agent (\f[CR]spice\-vdagent\f[R]) in the guest to 366 | enable copy/paste and USB redirection. 367 | .IP \[bu] 2 368 | Install the SPICE WebDAV agent (\f[CR]spice\-webdavd\f[R]) in the guest 369 | to enable file sharing. 370 | .RE 371 | .SS Supporting old Linux distros 372 | If you want to run an old Linux , from 2016 or earlier, change the 373 | \f[CR]guest_os\f[R] to \f[CR]linux_old\f[R]. 374 | This will enable the \f[CR]vmware\-svga\f[R] graphics driver which is 375 | better supported on older distros. 376 | .SS \c 377 | .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests 378 | Creating macOS Guests 379 | .UE \c 380 | \ 🍏 381 | \f[B]Installing macOS in a VM can be a bit finicky, if you encounter 382 | problems, \c 383 | .UR https://github.com/quickemu-project/quickemu/discussions 384 | check the Discussions 385 | .UE \c 386 | \ for solutions or ask for help there\f[R] 🛟 387 | .PP 388 | \f[CR]quickget\f[R] automatically downloads a macOS recovery image and 389 | creates a virtual machine configuration. 390 | .IP 391 | .EX 392 | quickget macos big\-sur 393 | quickemu \-\-vm macos\-big\-sur.conf 394 | .EE 395 | .PP 396 | macOS \f[CR]mojave\f[R], \f[CR]catalina\f[R], \f[CR]big\-sur\f[R], 397 | \f[CR]monterey\f[R], \f[CR]ventura\f[R] and \f[CR]sonoma\f[R] are 398 | supported. 399 | .IP \[bu] 2 400 | Use cursor keys and enter key to select the \f[B]macOS Base System\f[R] 401 | .IP \[bu] 2 402 | From \f[B]macOS Utilities\f[R] 403 | .RS 2 404 | .IP \[bu] 2 405 | Click \f[B]Disk Utility\f[R] and \f[B]Continue\f[R] 406 | .RS 2 407 | .IP \[bu] 2 408 | Select \f[CR]QEMU HARDDISK Media\f[R] (\[ti]103.08GB) from the list (on 409 | Big Sur and above use \f[CR]Apple Inc. VirtIO Block Device\f[R]) and 410 | click \f[B]Erase\f[R]. 411 | .IP \[bu] 2 412 | Enter a \f[CR]Name:\f[R] for the disk 413 | .IP \[bu] 2 414 | If you are installing macOS Mojave or later (Catalina, Big Sur, 415 | Monterey, Ventura and Sonoma), choose any of the APFS options as the 416 | filesystem. 417 | MacOS Extended may not work. 418 | .RE 419 | .IP \[bu] 2 420 | Click \f[B]Erase\f[R]. 421 | .IP \[bu] 2 422 | Click \f[B]Done\f[R]. 423 | .IP \[bu] 2 424 | Close Disk Utility 425 | .RE 426 | .IP \[bu] 2 427 | From \f[B]macOS Utilities\f[R] 428 | .RS 2 429 | .IP \[bu] 2 430 | Click \f[B]Reinstall macOS\f[R] and \f[B]Continue\f[R] 431 | .RE 432 | .IP \[bu] 2 433 | Complete the installation as you normally would. 434 | .RS 2 435 | .IP \[bu] 2 436 | On the first reboot use cursor keys and enter key to select \f[B]macOS 437 | Installer\f[R] 438 | .IP \[bu] 2 439 | On the subsequent reboots use cursor keys and enter key to select the 440 | disk you named 441 | .RE 442 | .IP \[bu] 2 443 | Once you have finished installing macOS you will be presented with an 444 | the out\-of\-the\-box first\-start wizard to configure various options 445 | and set up your username and password 446 | .IP \[bu] 2 447 | OPTIONAL: After you have concluded the out\-of\-the\-box wizard, you may 448 | want to enable the TRIM feature that the computer industry created for 449 | SSD disks. 450 | This feature in our macOS installation will allow QuickEmu to compact 451 | (shrink) your macOS disk image whenever you delete files inside the 452 | Virtual Machine. 453 | Without this step your macOS disk image will only ever get larger and 454 | will not shrink even when you delete lots of data inside macOS. 455 | .RS 2 456 | .IP \[bu] 2 457 | To enable TRIM, open the Terminal application and type the following 458 | command followed by pressing enter to tell macos to use the TRIM command 459 | on the hard disk when files are deleted: 460 | .RE 461 | .IP 462 | .EX 463 | sudo trimforce enable 464 | .EE 465 | .PP 466 | You will be prompted to enter your account\[aq]s password to gain the 467 | privilege needed. 468 | Once you\[aq]ve entered your password and pressed enter the command will 469 | request confirmation in the form of two questions that require you to 470 | type y (for a \[dq]yes\[dq] response) followed by enter to confirm. 471 | .PP 472 | If you press enter without first typing y the system will consider that 473 | a negative response as though you said \[dq]no\[dq]: 474 | .IP 475 | .EX 476 | IMPORTANT NOTICE: This tool force\-enables TRIM for all relevant attached devices, even though such devices may not have been validated for data integrity while using TRIM. Use of this tool to enable TRIM may result in unintended data loss or data corruption. It should not be used in a commercial operating environment or with important data. Before using this tool, you should back up all of your data and regularly back up data while TRIM is enabled. This tool is provided on an \[dq]as is\[dq] basis. APPLE MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF NON\-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THIS TOOL OR ITS USE ALONE OR IN COMBINATION WITH YOUR DEVICES, SYSTEMS, OR SERVICES. BY USING THIS TOOL TO ENABLE TRIM, YOU AGREE THAT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, USE OF THE TOOL IS AT YOUR SOLE RISK AND THAT THE ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY AND EFFORT IS WITH YOU. 477 | Are you sure you with to proceed (y/N)? 478 | .EE 479 | .PP 480 | And a second confirmation once you\[aq]ve confirmed the previous one: 481 | .IP 482 | .EX 483 | Your system will immediately reboot when this is complete. 484 | Is this OK (y/N)? 485 | .EE 486 | .PP 487 | As the last message states, your system will automatically reboot as 488 | soon as the command completes. 489 | .PP 490 | The default macOS configuration looks like this: 491 | .IP 492 | .EX 493 | guest_os=\[dq]macos\[dq] 494 | img=\[dq]macos\- big\-sur/RecoveryImage.img\[dq] 495 | disk_img=\[dq]macos\- big\-sur/disk.qcow2\[dq] 496 | macos_release=\[dq] big\-sur\[dq] 497 | .EE 498 | .IP \[bu] 2 499 | \f[CR]guest_os=\[dq]macos\[dq]\f[R] instructs Quickemu to optimise for 500 | macOS. 501 | .IP \[bu] 2 502 | \f[CR]macos_release=\[dq] big\-sur\[dq]\f[R] instructs Quickemu to 503 | optimise for a particular macOS release. 504 | .RS 2 505 | .IP \[bu] 2 506 | For example VirtIO Network and Memory Ballooning are available in Big 507 | Sur and newer, but not previous releases. 508 | .IP \[bu] 2 509 | And VirtIO Block Media (disks) are supported/stable in Catalina and 510 | newer. 511 | .RE 512 | .SH macOS compatibility 513 | There are some considerations when running macOS via Quickemu. 514 | .IP \[bu] 2 515 | Supported macOS releases: 516 | .RS 2 517 | .IP \[bu] 2 518 | Mojave 519 | .IP \[bu] 2 520 | Catalina 521 | .IP \[bu] 2 522 | Big Sur 523 | .IP \[bu] 2 524 | Monterey 525 | .IP \[bu] 2 526 | Ventura 527 | .IP \[bu] 2 528 | Sonoma 529 | .RE 530 | .IP \[bu] 2 531 | \f[CR]quickemu\f[R] will automatically download the required \c 532 | .UR https://github.com/acidanthera/OpenCorePkg 533 | OpenCore 534 | .UE \c 535 | \ bootloader and OVMF firmware from \c 536 | .UR https://github.com/kholia/OSX-KVM 537 | OSX\-KVM 538 | .UE \c 539 | \&. 540 | .IP \[bu] 2 541 | Optimised by default, but no GPU acceleration is available. 542 | .RS 2 543 | .IP \[bu] 2 544 | Host CPU vendor is detected and guest CPU is optimised accordingly. 545 | .IP \[bu] 2 546 | \c 547 | .UR https://www.kraxel.org/blog/2019/06/macos-qemu-guest/ 548 | VirtIO Block Media 549 | .UE \c 550 | \ is used for the system disk where supported. 551 | .IP \[bu] 2 552 | \c 553 | .UR http://philjordan.eu/osx-virt/ 554 | VirtIO \f[CR]usb\-tablet\f[R] 555 | .UE \c 556 | \ is used for the mouse. 557 | .IP \[bu] 2 558 | VirtIO Network (\f[CR]virtio\-net\f[R]) is supported and enabled on 559 | macOS Big Sur and newer, but earlier releases use \f[CR]vmxnet3\f[R]. 560 | .IP \[bu] 2 561 | VirtIO Memory Ballooning is supported and enabled on macOS Big Sur and 562 | newer but disabled for other support macOS releases. 563 | .RE 564 | .IP \[bu] 2 565 | USB host and SPICE pass\-through is: 566 | .RS 2 567 | .IP \[bu] 2 568 | UHCI (USB 2.0) on macOS Catalina and earlier. 569 | .IP \[bu] 2 570 | XHCI (USB 3.0) on macOS Big Sur and newer. 571 | .RE 572 | .IP \[bu] 2 573 | Display resolution can be changed via \f[CR]quickemu\f[R] using 574 | \f[CR]\-\-width\f[R] and \f[CR]\-\-height\f[R] command line arguments. 575 | .IP \[bu] 2 576 | \f[B]Full Duplex audio requires \c 577 | .UR https://github.com/chris1111/VoodooHDA-OC 578 | VoodooHDA OC 579 | .UE \c 580 | \ or pass\-through a USB audio\-device to the macOS guest VM\f[R]. 581 | .RS 2 582 | .IP \[bu] 2 583 | NOTE! 584 | \c 585 | .UR https://disable-gatekeeper.github.io/ 586 | Gatekeeper 587 | .UE \c 588 | \ and \c 589 | .UR https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection 590 | System Integrity Protection (SIP) 591 | .UE \c 592 | \ need to be disabled to install VoodooHDA OC 593 | .RE 594 | .IP \[bu] 2 595 | File sharing between guest and host is available via \c 596 | .UR https://wiki.qemu.org/Documentation/9psetup 597 | virtio\-9p 598 | .UE \c 599 | \ and \c 600 | .UR https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24 601 | SPICE webdavd 602 | .UE \c 603 | \&. 604 | .IP \[bu] 2 605 | Copy/paste via SPICE agent is \f[B]not available on macOS\f[R]. 606 | .SH macOS App Store 607 | If you see \f[I]\[dq]Your device or computer could not be 608 | verified\[dq]\f[R] when you try to login to the App Store, make sure 609 | that your wired ethernet device is \f[CR]en0\f[R]. 610 | Use \f[CR]ifconfig\f[R] in a terminal to verify this. 611 | .PP 612 | If the wired ethernet device is not \f[CR]en0\f[R], then then go to 613 | \f[I]System Preferences\f[R] \-> \f[I]Network\f[R], delete all the 614 | network devices and apply the changes. 615 | Next, open a terminal and run the following: 616 | .IP 617 | .EX 618 | sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist 619 | .EE 620 | .PP 621 | Now reboot, and the App Store should work. 622 | .PP 623 | There may be further advice and information about macOS guests in the 624 | project \c 625 | .UR https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests 626 | wiki 627 | .UE \c 628 | \&. 629 | .SS \c 630 | .UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines 631 | Creating Windows guests 632 | .UE \c 633 | \ 🪟 634 | \f[CR]quickget\f[R] can download \c 635 | .UR https://www.microsoft.com/software-download/windows10 636 | \f[B]Windows 10\f[R] 637 | .UE \c 638 | \ and \c 639 | .UR https://www.microsoft.com/software-download/windows11 640 | \f[B]Windows 11\f[R] 641 | .UE \c 642 | \ automatically and create an optimised virtual machine configuration. 643 | This configuration also includes the \c 644 | .UR https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/ 645 | VirtIO drivers for Windows 646 | .UE \c 647 | \&. 648 | .PP 649 | \f[B]Windows 8.1\f[R] is also supported but doesn\[aq]t feature any 650 | automated installation or driver optimisation. 651 | .PP 652 | \f[CR]quickget\f[R] can also download \c 653 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-10-enterprise 654 | Windows 10 LTSC 655 | .UE \c 656 | \ and Windows Server \c 657 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-server-2012-r2 658 | 2012\-r2 659 | .UE \c 660 | , \c 661 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-server-2016 662 | 2016 663 | .UE \c 664 | , \c 665 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-server-2019 666 | 2019 667 | .UE \c 668 | , and \c 669 | .UR https://www.microsoft.com/en-us/evalcenter/download-windows-server-2022 670 | 2022 671 | .UE \c 672 | \&. 673 | No automated installation is supported for these releases. 674 | .IP 675 | .EX 676 | quickget windows 11 677 | quickemu \-\-vm windows\-11.conf 678 | .EE 679 | .IP \[bu] 2 680 | Complete the installation as you normally would. 681 | .IP \[bu] 2 682 | All relevant drivers and services should be installed automatically. 683 | .IP \[bu] 2 684 | A local administrator user account is automatically created, with these 685 | credentials: 686 | .RS 2 687 | .IP \[bu] 2 688 | Username: \f[CR]Quickemu\f[R] 689 | .IP \[bu] 2 690 | Password: \f[CR]quickemu\f[R] 691 | .RE 692 | .PP 693 | Further information is available from the project \c 694 | .UR https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines 695 | wiki 696 | .UE \c 697 | .SH AUTHORS 698 | Written by Martin Wimpress. 699 | .SH BUGS 700 | Submit bug reports online at: \c 701 | .UR https://github.com/quickemu-project/quickemu/issues 702 | .UE \c 703 | .SH SEE ALSO 704 | Full sources at: \c 705 | .UR https://github.com/quickemu-project/quickemu 706 | .UE \c 707 | .PP 708 | quickemu(1), quickemu_conf(5), quickgui(1) 709 | .SH AUTHORS 710 | Martin Wimpress. 711 | -------------------------------------------------------------------------------- /docs/quickget.1.md: -------------------------------------------------------------------------------- 1 | --- 2 | author: Martin Wimpress 3 | date: December 30, 2024 4 | footer: quickget 5 | header: Quickget User Manual 6 | section: 1 7 | title: QUICKGET 8 | --- 9 | 10 | # NAME 11 | 12 | quickget - download and prepare materials for building a quickemu VM 13 | 14 | # SYNOPSIS 15 | 16 | **quickget** \[*os*\] \[*release*\] \[*edition*\] \| \[*OPTION*\]\* 17 | 18 | # DESCRIPTION 19 | 20 | **quickget** will download the requisite materials and prepare a 21 | configuration for `quickemu` to use to build and run 22 | 23 | # OPTIONS 24 | 25 | **\[OS\] \[Release\] \[Edition\]** 26 | : specify the OS and release (and optional edition) if insufficient 27 | input is provided a list of missing options will be reported and the 28 | script will exit. Editions may not apply and will be defaulted if 29 | not provided. 30 | 31 | **--download** \[edition\] 32 | : Download image; no VM configuration 33 | 34 | **--create-config** \[path/url\] 35 | : Create VM config for a OS image 36 | 37 | **--open-homepage** 38 | : Open homepage for the OS 39 | 40 | **--show** \[os\] 41 | : Show OS information 42 | 43 | **--url** \[os\] \[release\] \[edition\] 44 | : Show image URL(s) 45 | 46 | **--check** \[os\] \[release\] \[edition\] 47 | : Check image URL(s) 48 | 49 | **--list** 50 | : List all supported systems 51 | 52 | **--list-csv** 53 | : List everything in csv format 54 | 55 | **--list-json** 56 | : List everything in json format 57 | 58 | **--version** 59 | : Show version 60 | 61 | **--help** 62 | : Show this help message 63 | 64 | # NOTES 65 | 66 | ## Creating Linux guests 🐧 67 | 68 | ### Ubuntu 69 | 70 | `quickget` will automatically download an Ubuntu release and create the 71 | virtual machine configuration. 72 | 73 | ``` shell 74 | quickget ubuntu 22.04 75 | quickemu --vm ubuntu-22.04.conf 76 | ``` 77 | 78 | - Complete the installation as normal. 79 | - Post-install: 80 | - Install the SPICE agent (`spice-vdagent`) in the guest to enable 81 | copy/paste and USB redirection 82 | - `sudo apt install spice-vdagent` 83 | - Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to 84 | enable file sharing. 85 | - `sudo apt install spice-webdavd` 86 | 87 | ### Ubuntu daily-live images 88 | 89 | `quickget` can also download/refresh daily-live images via `zsync` for 90 | Ubuntu developers and testers. 91 | 92 | ``` shell 93 | quickget ubuntu daily-live 94 | quickemu --vm ubuntu-daily-live.conf 95 | ``` 96 | 97 | You can run `quickget ubuntu daily-live` to refresh your daily 98 | development image as often as you like, it will even automatically 99 | switch to a new series. 100 | 101 | ### Ubuntu Flavours 102 | 103 | All the official Ubuntu flavours are supported, just replace `ubuntu` 104 | with your preferred flavour. 105 | 106 | The project 107 | [wiki](https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines) 108 | may have further information. 109 | 110 | - `edubuntu` (Edubuntu) 111 | - `kubuntu` (Kubuntu) 112 | - `lubuntu` (Lubuntu) 113 | - `ubuntu-budgie` (Ubuntu Budgie) 114 | - `ubuntucinnamon` (Ubuntu Cinnamon) 115 | - `ubuntukylin` (Ubuntu Kylin) 116 | - `ubuntu-mate` (Ubuntu MATE) 117 | - `ubuntu-server` (Ubuntu Server) 118 | - `ubuntustudio` (Ubuntu Studio) 119 | - `ubuntu` (Ubuntu) 120 | - `ubuntu-unity` (Ubuntu Unity) 121 | - `xubuntu` (Xubuntu) 122 | 123 | You can also use `quickget` with advanced options : 124 | 125 | ``` text 126 | --download [edition] : Download image; no VM configuration 127 | --create-config [path/url] [flags] : Create VM config for an OS image 128 | --open-homepage : Open homepage for the OS 129 | --show [os] : Show OS information 130 | --version : Show version 131 | --help : Show this help message 132 | --disable-unattended : Force quickget not to set up an unattended installation 133 | --url [os] [release] [edition] : Show image URL(s) 134 | --check [os] [release] [edition] : Check image URL(s) 135 | --list : List all supported systems 136 | --list-csv : List everything in csv format 137 | --list-json : List everything in json format 138 | ``` 139 | 140 | Here are some typical uses 141 | 142 | ``` shell 143 | # show an OS ISO download URL for {os} {release} [edition] 144 | quickget --url fedora 38 Silverblue 145 | # test if an OS ISO is available for {os} {release} [edition] 146 | quickget --check nixos unstable plasma5 147 | # open an OS distribution homepage in a browser 148 | quickget --open-homepage ubuntu-mate 149 | # Only download image file into current directory, without creating VM 150 | quickget --download elementary 7.1 151 | ``` 152 | 153 | The `--url`, `--check`, and `--download` options are fully functional 154 | for all operating systems, including Windows and macOS. 155 | 156 | Further information is available from the project 157 | [wiki](https://github.com/quickemu-project/quickemu/wiki/06-Advanced-quickget-features) 158 | 159 | ### Other Operating Systems 160 | 161 | `quickget` also supports: 162 | 163 | - `alma` (AlmaLinux) 164 | - `alpine` (Alpine Linux) 165 | - `android` (Android x86) 166 | - `antix` (Antix) 167 | - `archcraft` (Archcraft) 168 | - `archlinux` (Arch Linux) 169 | - `arcolinux` (Arco Linux) 170 | - `artixlinux` (Artix Linux) 171 | - `athenaos` (Athena OS) 172 | - `batocera` (Batocera) 173 | - `bazzite` (Bazzite) 174 | - `biglinux` (BigLinux) 175 | - `blendos` (BlendOS) 176 | - `bodhi` (Bodhi) 177 | - `bunsenlabs` (BunsenLabs) 178 | - `cachyos` (CachyOS) 179 | - `centos-stream` (CentOS Stream) 180 | - `chimeralinux` (Chimera Linux) 181 | - `crunchbang++` (Crunchbangplusplus) 182 | - `debian` (Debian) 183 | - `deepin` (Deepin) 184 | - `devuan` (Devuan) 185 | - `dragonflybsd` (DragonFlyBSD) 186 | - `easyos` (EasyOS) 187 | - `elementary` (elementary OS) 188 | - `endeavouros` (EndeavourOS) 189 | - `endless` (Endless OS) 190 | - `fedora` (Fedora) 191 | - `freebsd` (FreeBSD) 192 | - `freedos` (FreeDOS) 193 | - `garuda` (Garuda Linux) 194 | - `gentoo` (Gentoo) 195 | - `ghostbsd` (GhostBSD) 196 | - `gnomeos` (GNOME OS) 197 | - `guix` (Guix) 198 | - `haiku` (Haiku) 199 | - `holoiso` (HoloISO) 200 | - `kali` (Kali) 201 | - `kdeneon` (KDE Neon) 202 | - `kolibrios` (KolibriOS) 203 | - `linuxlite` (Linux Lite) 204 | - `linuxmint` (Linux Mint) 205 | - `lmde` (Linux Mint Debian Edition) 206 | - `maboxlinux` (Mabox Linux) 207 | - `mageia` (Mageia) 208 | - `manjaro` (Manjaro) 209 | - `mxlinux` (MX Linux) 210 | - `netboot` (netboot.xyz) 211 | - `netbsd` (NetBSD) 212 | - `nitrux` (Nitrux) 213 | - `nixos` (NixOS) 214 | - `nwg-shell` (nwg-shell) 215 | - `openbsd` (OpenBSD) 216 | - `openindiana` (OpenIndiana) 217 | - `opensuse` (openSUSE) 218 | - `oraclelinux` (Oracle Linux) 219 | - `parrotsec` (Parrot Security) 220 | - `peppermint` (PeppermintOS) 221 | - `popos` (Pop!\_OS) 222 | - `porteus` (Porteus) 223 | - `primtux` (PrimTux) 224 | - `proxmox-ve` (Proxmox VE) 225 | - `pureos` (PureOS) 226 | - `reactos` (ReactOS) 227 | - `rebornos` (RebornOS) 228 | - `rockylinux` (Rocky Linux) 229 | - `siduction` (Siduction) 230 | - `slackware` (Slackware) 231 | - `slax` (Slax) 232 | - `slint` (Slint) 233 | - `slitaz` (SliTaz) 234 | - `solus` (Solus) 235 | - `sparkylinux` (SparkyLinux) 236 | - `spirallinux` (SpiralLinux) 237 | - `tails` (Tails) 238 | - `tinycore` (Tiny Core Linux) 239 | - `trisquel` (Trisquel-) 240 | - `truenas-core` (TrueNAS Core) 241 | - `truenas-scale` (TrueNAS Scale) 242 | - `tuxedo-os` (Tuxedo OS) 243 | - `vanillaos` (Vanilla OS) 244 | - `void` (Void Linux) 245 | - `vxlinux` (VX Linux) 246 | - `zorin` (Zorin OS) 247 | 248 | ### [Custom Linux guests](https://github.com/quickemu-project/quickemu/wiki/02-Create-Linux-virtual-machines#manually-create-linux-guests) 249 | 250 | Or you can download a Linux image and manually create a VM 251 | configuration. 252 | 253 | - Download a .iso image of a Linux distribution 254 | - Create a VM configuration file; for example `debian-bullseye.conf` 255 | 256 | ``` shell 257 | guest_os="linux" 258 | disk_img="debian-bullseye/disk.qcow2" 259 | iso="debian-bullseye/firmware-11.0.0-amd64-DVD-1.iso" 260 | ``` 261 | 262 | - Use `quickemu` to start the virtual machine: 263 | 264 | ``` shell 265 | quickemu --vm debian-bullseye.conf 266 | ``` 267 | 268 | - Complete the installation as normal. 269 | - Post-install: 270 | - Install the SPICE agent (`spice-vdagent`) in the guest to enable 271 | copy/paste and USB redirection. 272 | - Install the SPICE WebDAV agent (`spice-webdavd`) in the guest to 273 | enable file sharing. 274 | 275 | ## Supporting old Linux distros 276 | 277 | If you want to run an old Linux , from 2016 or earlier, change the 278 | `guest_os` to `linux_old`. This will enable the `vmware-svga` graphics 279 | driver which is better supported on older distros. 280 | 281 | ## [Creating macOS Guests](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests) 🍏 282 | 283 | **Installing macOS in a VM can be a bit finicky, if you encounter 284 | problems, [check the 285 | Discussions](https://github.com/quickemu-project/quickemu/discussions) 286 | for solutions or ask for help there** 🛟 287 | 288 | `quickget` automatically downloads a macOS recovery image and creates a 289 | virtual machine configuration. 290 | 291 | ``` shell 292 | quickget macos big-sur 293 | quickemu --vm macos-big-sur.conf 294 | ``` 295 | 296 | macOS `mojave`, `catalina`, `big-sur`, `monterey`, `ventura` and 297 | `sonoma` are supported. 298 | 299 | - Use cursor keys and enter key to select the **macOS Base System** 300 | - From **macOS Utilities** 301 | - Click **Disk Utility** and **Continue** 302 | - Select `QEMU HARDDISK Media` (~103.08GB) from the list (on Big Sur 303 | and above use `Apple Inc. VirtIO Block Device`) and click 304 | **Erase**. 305 | - Enter a `Name:` for the disk 306 | - If you are installing macOS Mojave or later (Catalina, Big Sur, 307 | Monterey, Ventura and Sonoma), choose any of the APFS options as 308 | the filesystem. MacOS Extended may not work. 309 | - Click **Erase**. 310 | - Click **Done**. 311 | - Close Disk Utility 312 | - From **macOS Utilities** 313 | - Click **Reinstall macOS** and **Continue** 314 | - Complete the installation as you normally would. 315 | - On the first reboot use cursor keys and enter key to select **macOS 316 | Installer** 317 | - On the subsequent reboots use cursor keys and enter key to select 318 | the disk you named 319 | - Once you have finished installing macOS you will be presented with an 320 | the out-of-the-box first-start wizard to configure various options and 321 | set up your username and password 322 | - OPTIONAL: After you have concluded the out-of-the-box wizard, you may 323 | want to enable the TRIM feature that the computer industry created for 324 | SSD disks. This feature in our macOS installation will allow QuickEmu 325 | to compact (shrink) your macOS disk image whenever you delete files 326 | inside the Virtual Machine. Without this step your macOS disk image 327 | will only ever get larger and will not shrink even when you delete 328 | lots of data inside macOS. 329 | - To enable TRIM, open the Terminal application and type the following 330 | command followed by pressing enter to tell macos to use 331 | the TRIM command on the hard disk when files are deleted: 332 | 333 | ``` shell 334 | sudo trimforce enable 335 | ``` 336 | 337 | You will be prompted to enter your account's password to gain the 338 | privilege needed. Once you've entered your password and pressed 339 | enter the command will request confirmation in the form of 340 | two questions that require you to type y (for a "yes" 341 | response) followed by enter to confirm. 342 | 343 | If you press enter without first typing y the 344 | system will consider that a negative response as though you said "no": 345 | 346 | ``` plain 347 | IMPORTANT NOTICE: This tool force-enables TRIM for all relevant attached devices, even though such devices may not have been validated for data integrity while using TRIM. Use of this tool to enable TRIM may result in unintended data loss or data corruption. It should not be used in a commercial operating environment or with important data. Before using this tool, you should back up all of your data and regularly back up data while TRIM is enabled. This tool is provided on an "as is" basis. APPLE MAKES NO WARRANTIES, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION THE IMPLIED WARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE, REGARDING THIS TOOL OR ITS USE ALONE OR IN COMBINATION WITH YOUR DEVICES, SYSTEMS, OR SERVICES. BY USING THIS TOOL TO ENABLE TRIM, YOU AGREE THAT, TO THE EXTENT PERMITTED BY APPLICABLE LAW, USE OF THE TOOL IS AT YOUR SOLE RISK AND THAT THE ENTIRE RISK AS TO SATISFACTORY QUALITY, PERFORMANCE, ACCURACY AND EFFORT IS WITH YOU. 348 | Are you sure you with to proceed (y/N)? 349 | ``` 350 | 351 | And a second confirmation once you've confirmed the previous one: 352 | 353 | ``` plain 354 | Your system will immediately reboot when this is complete. 355 | Is this OK (y/N)? 356 | ``` 357 | 358 | As the last message states, your system will automatically reboot as 359 | soon as the command completes. 360 | 361 | The default macOS configuration looks like this: 362 | 363 | ``` shell 364 | guest_os="macos" 365 | img="macos- big-sur/RecoveryImage.img" 366 | disk_img="macos- big-sur/disk.qcow2" 367 | macos_release=" big-sur" 368 | ``` 369 | 370 | - `guest_os="macos"` instructs Quickemu to optimise for macOS. 371 | - `macos_release=" big-sur"` instructs Quickemu to optimise for a 372 | particular macOS release. 373 | - For example VirtIO Network and Memory Ballooning are available in 374 | Big Sur and newer, but not previous releases. 375 | - And VirtIO Block Media (disks) are supported/stable in Catalina and 376 | newer. 377 | 378 | # macOS compatibility 379 | 380 | There are some considerations when running macOS via Quickemu. 381 | 382 | - Supported macOS releases: 383 | - Mojave 384 | - Catalina 385 | - Big Sur 386 | - Monterey 387 | - Ventura 388 | - Sonoma 389 | - `quickemu` will automatically download the required 390 | [OpenCore](https://github.com/acidanthera/OpenCorePkg) bootloader and 391 | OVMF firmware from [OSX-KVM](https://github.com/kholia/OSX-KVM). 392 | - Optimised by default, but no GPU acceleration is available. 393 | - Host CPU vendor is detected and guest CPU is optimised accordingly. 394 | - [VirtIO Block 395 | Media](https://www.kraxel.org/blog/2019/06/macos-qemu-guest/) is 396 | used for the system disk where supported. 397 | - [VirtIO `usb-tablet`](http://philjordan.eu/osx-virt/) is used for 398 | the mouse. 399 | - VirtIO Network (`virtio-net`) is supported and enabled on macOS Big 400 | Sur and newer, but earlier releases use `vmxnet3`. 401 | - VirtIO Memory Ballooning is supported and enabled on macOS Big Sur 402 | and newer but disabled for other support macOS releases. 403 | - USB host and SPICE pass-through is: 404 | - UHCI (USB 2.0) on macOS Catalina and earlier. 405 | - XHCI (USB 3.0) on macOS Big Sur and newer. 406 | - Display resolution can be changed via `quickemu` using `--width` and 407 | `--height` command line arguments. 408 | - **Full Duplex audio requires [VoodooHDA 409 | OC](https://github.com/chris1111/VoodooHDA-OC) or pass-through a USB 410 | audio-device to the macOS guest VM**. 411 | - NOTE! [Gatekeeper](https://disable-gatekeeper.github.io/) and 412 | [System Integrity Protection 413 | (SIP)](https://developer.apple.com/documentation/security/disabling_and_enabling_system_integrity_protection) 414 | need to be disabled to install VoodooHDA OC 415 | - File sharing between guest and host is available via 416 | [virtio-9p](https://wiki.qemu.org/Documentation/9psetup) and [SPICE 417 | webdavd](https://gitlab.gnome.org/GNOME/phodav/-/merge_requests/24). 418 | - Copy/paste via SPICE agent is **not available on macOS**. 419 | 420 | # macOS App Store 421 | 422 | If you see *"Your device or computer could not be verified"* when you 423 | try to login to the App Store, make sure that your wired ethernet device 424 | is `en0`. Use `ifconfig` in a terminal to verify this. 425 | 426 | If the wired ethernet device is not `en0`, then then go to *System 427 | Preferences* -\> *Network*, delete all the network devices and apply the 428 | changes. Next, open a terminal and run the following: 429 | 430 | ``` shell 431 | sudo rm /Library/Preferences/SystemConfiguration/NetworkInterfaces.plist 432 | ``` 433 | 434 | Now reboot, and the App Store should work. 435 | 436 | There may be further advice and information about macOS guests in the 437 | project 438 | [wiki](https://github.com/quickemu-project/quickemu/wiki/03-Create-macOS-virtual-machines#automatically-create-macos-guests). 439 | 440 | ## [Creating Windows guests](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines) 🪟 441 | 442 | `quickget` can download [**Windows 443 | 10**](https://www.microsoft.com/software-download/windows10) and 444 | [**Windows 11**](https://www.microsoft.com/software-download/windows11) 445 | automatically and create an optimised virtual machine configuration. 446 | This configuration also includes the [VirtIO drivers for 447 | Windows](https://fedorapeople.org/groups/virt/virtio-win/direct-downloads/). 448 | 449 | **Windows 8.1** is also supported but doesn't feature any automated 450 | installation or driver optimisation. 451 | 452 | `quickget` can also download [Windows 10 453 | LTSC](https://www.microsoft.com/en-us/evalcenter/download-windows-10-enterprise) 454 | and Windows Server 455 | [2012-r2](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2012-r2), 456 | [2016](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2016), 457 | [2019](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2019), 458 | and 459 | [2022](https://www.microsoft.com/en-us/evalcenter/download-windows-server-2022). 460 | No automated installation is supported for these releases. 461 | 462 | ``` shell 463 | quickget windows 11 464 | quickemu --vm windows-11.conf 465 | ``` 466 | 467 | - Complete the installation as you normally would. 468 | - All relevant drivers and services should be installed automatically. 469 | - A local administrator user account is automatically created, with 470 | these credentials: 471 | - Username: `Quickemu` 472 | - Password: `quickemu` 473 | 474 | Further information is available from the project 475 | [wiki](https://github.com/quickemu-project/quickemu/wiki/04-Create-Windows-virtual-machines) 476 | 477 | # AUTHORS 478 | 479 | Written by Martin Wimpress. 480 | 481 | # BUGS 482 | 483 | Submit bug reports online at: 484 | 485 | 486 | # SEE ALSO 487 | 488 | Full sources at: 489 | 490 | quickemu(1), quickemu_conf(5), quickgui(1) 491 | -------------------------------------------------------------------------------- /flake.lock: -------------------------------------------------------------------------------- 1 | { 2 | "nodes": { 3 | "flake-schemas": { 4 | "locked": { 5 | "lastModified": 1721999734, 6 | "narHash": "sha256-G5CxYeJVm4lcEtaO87LKzOsVnWeTcHGKbKxNamNWgOw=", 7 | "rev": "0a5c42297d870156d9c57d8f99e476b738dcd982", 8 | "revCount": 75, 9 | "type": "tarball", 10 | "url": "https://api.flakehub.com/f/pinned/DeterminateSystems/flake-schemas/0.1.5/0190ef2f-61e0-794b-ba14-e82f225e55e6/source.tar.gz" 11 | }, 12 | "original": { 13 | "type": "tarball", 14 | "url": "https://flakehub.com/f/DeterminateSystems/flake-schemas/%2A.tar.gz" 15 | } 16 | }, 17 | "nixpkgs": { 18 | "locked": { 19 | "lastModified": 1748162331, 20 | "narHash": "sha256-rqc2RKYTxP3tbjA+PB3VMRQNnjesrT0pEofXQTrMsS8=", 21 | "rev": "7c43f080a7f28b2774f3b3f43234ca11661bf334", 22 | "revCount": 802491, 23 | "type": "tarball", 24 | "url": "https://api.flakehub.com/f/pinned/NixOS/nixpkgs/0.2505.802491%2Brev-7c43f080a7f28b2774f3b3f43234ca11661bf334/01970886-40c4-7b8c-a32f-bb580ba9bcb1/source.tar.gz" 25 | }, 26 | "original": { 27 | "type": "tarball", 28 | "url": "https://flakehub.com/f/NixOS/nixpkgs/%2A.tar.gz" 29 | } 30 | }, 31 | "root": { 32 | "inputs": { 33 | "flake-schemas": "flake-schemas", 34 | "nixpkgs": "nixpkgs" 35 | } 36 | } 37 | }, 38 | "root": "root", 39 | "version": 7 40 | } 41 | -------------------------------------------------------------------------------- /flake.nix: -------------------------------------------------------------------------------- 1 | { 2 | description = "Quickemu flake"; 3 | inputs = { 4 | flake-schemas.url = "https://flakehub.com/f/DeterminateSystems/flake-schemas/*.tar.gz"; 5 | nixpkgs.url = "https://flakehub.com/f/NixOS/nixpkgs/*.tar.gz"; 6 | }; 7 | 8 | outputs = { 9 | self, 10 | flake-schemas, 11 | nixpkgs, 12 | }: let 13 | # Define supported systems and a helper function for generating system-specific outputs 14 | supportedSystems = [ "x86_64-linux" "x86_64-darwin" "aarch64-darwin" "aarch64-linux" ]; 15 | 16 | forEachSupportedSystem = f: nixpkgs.lib.genAttrs supportedSystems (system: f { 17 | system = system; 18 | pkgs = import nixpkgs { inherit system; }; 19 | }); 20 | in { 21 | # Define schemas for the flake's outputs 22 | schemas = flake-schemas.schemas; 23 | 24 | # Define overlays for each supported system 25 | overlays = { 26 | default = final: prev: { 27 | quickemu = final.callPackage ./package.nix { }; 28 | }; 29 | }; 30 | 31 | # Define packages for each supported system 32 | packages = forEachSupportedSystem ({pkgs, system, ...}: rec { 33 | quickemu = pkgs.callPackage ./package.nix { }; 34 | default = quickemu; 35 | }); 36 | 37 | # Define devShells for each supported system 38 | devShells = forEachSupportedSystem ({pkgs, system, ...}: { 39 | default = pkgs.callPackage ./devshell.nix { }; 40 | }); 41 | }; 42 | } 43 | -------------------------------------------------------------------------------- /package.nix: -------------------------------------------------------------------------------- 1 | { lib 2 | , fetchFromGitHub 3 | , installShellFiles 4 | , makeWrapper 5 | , stdenv 6 | , testers 7 | , cdrtools 8 | , curl 9 | , gawk 10 | , glxinfo 11 | , gnugrep 12 | , gnused 13 | , jq 14 | , pciutils 15 | , procps 16 | , python3 17 | , qemu_full 18 | , samba 19 | , socat 20 | , spice-gtk 21 | , swtpm 22 | , unzip 23 | , usbutils 24 | , util-linux 25 | , xdg-user-dirs 26 | , xrandr 27 | , zsync 28 | , OVMF 29 | , OVMFFull 30 | , quickemu 31 | }: 32 | let 33 | runtimePaths = [ 34 | cdrtools 35 | curl 36 | gawk 37 | gnugrep 38 | gnused 39 | jq 40 | pciutils 41 | procps 42 | python3 43 | qemu_full 44 | samba 45 | socat 46 | swtpm 47 | unzip 48 | util-linux 49 | xrandr 50 | zsync 51 | OVMF 52 | OVMFFull 53 | ] ++ lib.optionals stdenv.isLinux [ 54 | glxinfo 55 | usbutils 56 | xdg-user-dirs 57 | ]; 58 | versionMatches = 59 | builtins.match '' 60 | .* 61 | readonly[[:blank:]]VERSION="([[:digit:]]+\.[[:digit:]]+\.[[:digit:]]+)" 62 | .* 63 | '' (builtins.readFile ./quickemu); 64 | in 65 | stdenv.mkDerivation rec { 66 | pname = "quickemu"; 67 | version = builtins.concatStringsSep "" versionMatches; 68 | src = lib.cleanSource ./.; 69 | 70 | postPatch = '' 71 | sed -i \ 72 | -e '/OVMF_CODE_4M.secboot.fd/s|ovmfs=(|ovmfs=("${OVMFFull.firmware}","${OVMFFull.variables}" |' \ 73 | -e '/OVMF_CODE_4M.fd/s|ovmfs=(|ovmfs=("${OVMF.firmware}","${OVMF.variables}" |' \ 74 | -e '/cp "''${VARS_IN}" "''${VARS_OUT}"/a chmod +w "''${VARS_OUT}"' \ 75 | -e 's,\$(command -v smbd),${samba}/bin/smbd,' \ 76 | quickemu 77 | ''; 78 | 79 | nativeBuildInputs = [ makeWrapper installShellFiles ]; 80 | 81 | installPhase = '' 82 | runHook preInstall 83 | 84 | installManPage docs/quickget.1 docs/quickemu.1 docs/quickemu_conf.5 85 | install -Dm755 -t "$out/bin" chunkcheck quickemu quickget quickreport 86 | 87 | # spice-gtk needs to be put in suffix so that when virtualisation.spiceUSBRedirection 88 | # is enabled, the wrapped spice-client-glib-usb-acl-helper is used 89 | for f in chunkcheck quickget quickemu quickreport; do 90 | wrapProgram $out/bin/$f \ 91 | --prefix PATH : "${lib.makeBinPath runtimePaths}" \ 92 | --suffix PATH : "${lib.makeBinPath [ spice-gtk ]}" 93 | done 94 | 95 | runHook postInstall 96 | ''; 97 | 98 | passthru.tests = testers.testVersion { package = quickemu; }; 99 | 100 | meta = { 101 | description = "Quickly create and run optimised Windows, macOS and Linux virtual machines"; 102 | homepage = "https://github.com/quickemu-project/quickemu"; 103 | mainProgram = "quickemu"; 104 | license = lib.licenses.mit; 105 | maintainers = with lib.maintainers; [ fedx-sudo flexiondotorg ]; 106 | }; 107 | } 108 | -------------------------------------------------------------------------------- /quickreport: -------------------------------------------------------------------------------- 1 | #!/usr/bin/env bash 2 | 3 | quick_report() { 4 | local GPUS 5 | local OS_KERNEL 6 | local PRETTY_NAME 7 | local QUICKEMU 8 | local VERSION 9 | OS_KERNEL=$(uname -s) 10 | 11 | if [ "${OS_KERNEL}" == "Darwin" ]; then 12 | # Get macOS product name and version using swvers 13 | if [ -x "$(command -v sw_vers)" ]; then 14 | PRETTY_NAME="$(sw_vers -productName) $(sw_vers -productVersion)" 15 | else 16 | PRETTY_NAME="macOS" 17 | fi 18 | elif [ -e /etc/os-release ]; then 19 | PRETTY_NAME=$(grep PRETTY_NAME /etc/os-release | cut -d'"' -f2) 20 | else 21 | PRETTY_NAME="Unknown OS" 22 | fi 23 | 24 | CWD="$(dirname "${0}")" 25 | if [ -x "${CWD}/quickemu" ]; then 26 | QUICKEMU="${CWD}/quickemu" 27 | elif [ -x "$(command -v quickemu)" ]; then 28 | QUICKEMU="$(command -v quickemu)" 29 | fi 30 | 31 | if [ -n "${QUICKEMU}" ]; then 32 | VERSION=$(${QUICKEMU} --version) 33 | echo \ 34 | "---------------------------------- 35 | Quickemu ${VERSION} 36 | ----------------------------------" 37 | echo -e "Distro:\t${PRETTY_NAME}" 38 | echo -e "Kernel:\t$(uname -s -r -m)" 39 | 40 | if [ "${OS_KERNEL}" == "Darwin" ]; then 41 | echo -e "Memory:\t$(($(sysctl -n hw.memsize) / (1048576*1024)))G" 42 | else 43 | # Determine the number of gigabytes of RAM in the host by extracting the first numerical value from the output. 44 | echo -e "Memory:\t$(free --giga -h | tr ' ' '\n' | grep -m 1 "[0-9]" | cut -d'G' -f 1)G" 45 | fi 46 | 47 | # Break IFS on new line 48 | IFS=$'\n' 49 | if [ "${OS_KERNEL}" == "Darwin" ]; then 50 | # Get GPU information using system_profiler 51 | GPUS=$(system_profiler SPDisplaysDataType | grep "Chipset Model" | awk -F: '{print $2}' | sed 's/^ *//') 52 | else 53 | GPUS=$(lspci | grep -i vga | cut -d':' -f3) 54 | fi 55 | 56 | if [ "$(echo "${GPUS}" | wc -l)" -eq 1 ]; then 57 | echo "GPU:" 58 | else 59 | echo "GPUs:" 60 | fi 61 | for GPU in ${GPUS}; do 62 | echo " -${GPU}" 63 | done 64 | else 65 | echo \ 66 | "---------------------------------- 67 | Quickemu missing! 68 | ----------------------------------" 69 | exit 1 70 | fi 71 | 72 | if command -v curl &> /dev/null; then 73 | VERSION=$(curl --version) 74 | echo \ 75 | "---------------------------------- 76 | curl $(echo "${VERSION}" | head -n 1 | cut -d' ' -f2) 77 | ----------------------------------" 78 | echo -e "Libraries:$(echo "${VERSION}" | head -n 1 | cut -d')' -f2-)" 79 | echo -e "Protocols:$(echo "${VERSION}" | tail -n +3 | head -n 1 | cut -d':' -f2-)" 80 | echo -e "Features: $(echo "${VERSION}" | tail -n +4 | head -n 1 | cut -d':' -f2-)" 81 | else 82 | echo \ 83 | "---------------------------------- 84 | curl missing 85 | ----------------------------------" 86 | fi 87 | 88 | local HOST_ARCH 89 | HOST_ARCH=$(uname -m) 90 | local QEMU_ARCH="${HOST_ARCH}" 91 | if [ "${HOST_ARCH}" == "arm64" ]; then 92 | QEMU_ARCH="aarch64" 93 | fi 94 | 95 | if command -v "qemu-system-${QEMU_ARCH}" &> /dev/null; then 96 | VERSION=$("qemu-system-${QEMU_ARCH}" --version | head -n 1 | cut -d' ' -f4) 97 | echo \ 98 | "---------------------------------- 99 | QEMU ${VERSION} 100 | ----------------------------------" 101 | "qemu-system-${QEMU_ARCH}" -cpu help 102 | else 103 | echo \ 104 | "---------------------------------- 105 | QEMU missing 106 | ----------------------------------" 107 | fi 108 | 109 | echo \ 110 | "---------------------------------- 111 | CPU 112 | ----------------------------------" 113 | if [ "${OS_KERNEL}" == "Darwin" ]; then 114 | sysctl -n machdep.cpu.brand_string 115 | else 116 | lscpu 117 | fi 118 | } 119 | 120 | clear 121 | quick_report | tee quickreport.txt 122 | --------------------------------------------------------------------------------