macOS-Simple-KVM/README.md

# macOS-Simple-KVM
Documentation to set up a simple macOS VM in QEMU, accelerated by KVM.

By [@FoxletFox](https://twitter.com/foxletfox), and the help of many others. Find this useful? [You can donate here!](https://commerce.coinbase.com/checkout/96dc5777-0abf-437d-a9b5-a78ae2c4c227)

New to macOS KVM? Check [the FAQs.](docs/FAQs.md)

## Getting Started
You'll need a Linux system with `qemu` (3.1 or later), `python3`, `pip` and the KVM extensions installed for this project. A Mac is **not** required. Some examples for different distributions:

```
sudo apt-get install qemu-system qemu-utils python3 python3-pip  # for Ubuntu, Debian, Mint, and PopOS.
sudo pacman -S qemu python python-pip            # for Arch.
sudo xbps-install -Su qemu python3 python3-pip   # for Void Linux.
```

## Step 1
Run `jumpstart.sh` to download installation media for macOS (internet required). The default installation uses Catalina, but you can choose which version to get by adding either `--high-sierra`, `--mojave`, or `--catalina`. For example:
```
./jumpstart.sh --mojave
```
> Note: You can skip this if you already have `BaseSystem.img` downloaded. If you have `BaseSystem.dmg`, you will need to convert it with the `dmg2img` tool.

## Step 2
Create an empty hard disk using `qemu-img`, changing the name and size to preference:
```
qemu-img create -f qcow2 MyDisk.qcow2 64G
```

Then run `basic.sh` to start the machine and install macOS, setting the
`SYSTEM_DISK` environment variable to the path to your freshly created
system disk image:

```
SYSTEM_DISK=MyDisk.qcow2 ./basic.sh
```

If you're running on a headless system (such as on Cloud providers), set
the `HEADLESS` environment variable to 1:

```
SYSTEM_DISK=MyDisk.qcow2 HEADLESS=1 ./basic.sh
```

Remember to partition in Disk Utility first!

## Step 2a (Virtual Machine Manager)
If instead of QEMU, you'd like to import the setup into Virt-Manager for further configuration, just run `make.sh --add`.

## Step 3

You're done!

To fine-tune the system and improve performance, look in the `docs` folder for more information on [adding memory](docs/guide-performance.md), setting up [bridged networking](docs/guide-networking.md), adding [passthrough hardware (for GPUs)](docs/guide-passthrough.md), and enabling sound features.
Initial commit 2019-04-22 09:25:21 +02:00			`# macOS-Simple-KVM`
[DOCS] Update docs. 2019-04-30 23:48:10 +02:00			`Documentation to set up a simple macOS VM in QEMU, accelerated by KVM.`
Initial documentation. 2019-04-23 00:08:10 +02:00
[DOCS] Clarify Cloud support, QEMU version. 2019-06-20 00:35:31 +02:00			`By [@FoxletFox](https://twitter.com/foxletfox), and the help of many others. Find this useful? [You can donate here!](https://commerce.coinbase.com/checkout/96dc5777-0abf-437d-a9b5-a78ae2c4c227)`

			`New to macOS KVM? Check [the FAQs.](docs/FAQs.md)`
[DOCS] Update sections. 2019-05-11 23:25:09 +02:00
[DOCS] Update README. 2019-05-10 20:07:24 +02:00			`## Getting Started`
[DOCS] Clarify Cloud support, QEMU version. 2019-06-20 00:35:31 +02:00			You'll need a Linux system with `qemu` (3.1 or later), `python3`, `pip` and the KVM extensions installed for this project. A Mac is not required. Some examples for different distributions:
[DOCS] Clarify installation. 2019-06-07 01:53:57 +02:00
			```
[DOCS] Clarify Cloud support, QEMU version. 2019-06-20 00:35:31 +02:00			`sudo apt-get install qemu-system qemu-utils python3 python3-pip # for Ubuntu, Debian, Mint, and PopOS.`
			`sudo pacman -S qemu python python-pip # for Arch.`
			`sudo xbps-install -Su qemu python3 python3-pip # for Void Linux.`
[DOCS] Clarify installation. 2019-06-07 01:53:57 +02:00			```
[DOCS] Update README. 2019-04-25 22:57:52 +02:00
Initial documentation. 2019-04-23 00:08:10 +02:00			`## Step 1`
[DOCS] Clarify installation. 2019-06-07 01:53:57 +02:00			Run `jumpstart.sh` to download installation media for macOS (internet required). The default installation uses Catalina, but you can choose which version to get by adding either `--high-sierra`, `--mojave`, or `--catalina`. For example:
			```
			`./jumpstart.sh --mojave`
			```
[DOCS] Fix formatting. 2019-05-11 23:32:56 +02:00			> Note: You can skip this if you already have `BaseSystem.img` downloaded. If you have `BaseSystem.dmg`, you will need to convert it with the `dmg2img` tool.
Initial documentation. 2019-04-23 00:08:10 +02:00
[DOCS] Update docs. 2019-04-30 23:48:10 +02:00			`## Step 2`
[DOCS] Update README. 2019-05-10 20:07:24 +02:00			Create an empty hard disk using `qemu-img`, changing the name and size to preference:
[DOCS] Add instructions to create a disk. 2019-04-24 17:11:50 +02:00			```
			`qemu-img create -f qcow2 MyDisk.qcow2 64G`
			```

basic.sh: Get system disk image path from environment Currently users have to modify the basic.sh script by hand to add the path to the system disk image they created. Rather than having them modify the script, just grab it from the environment. 2019-06-20 01:22:43 +02:00			Then run `basic.sh` to start the machine and install macOS, setting the
			`SYSTEM_DISK` environment variable to the path to your freshly created
			`system disk image:`

[DOCS] Add instructions to create a disk. 2019-04-24 17:11:50 +02:00			```
basic.sh: Get system disk image path from environment Currently users have to modify the basic.sh script by hand to add the path to the system disk image they created. Rather than having them modify the script, just grab it from the environment. 2019-06-20 01:22:43 +02:00			`SYSTEM_DISK=MyDisk.qcow2 ./basic.sh`
[DOCS] Add instructions to create a disk. 2019-04-24 17:11:50 +02:00			```

basic.sh: Add support for HEADLESS mode via environment Currently if a user wants to run in headless mode they have to edit the basic.sh script by hand. Rather than making them edit the script by hand, add support for a HEADLESS environment variable which can be set to 1 to add necessary command line arguments to qemu. 2019-06-20 01:28:56 +02:00			`If you're running on a headless system (such as on Cloud providers), set`
			the `HEADLESS` environment variable to 1:

			```
			`SYSTEM_DISK=MyDisk.qcow2 HEADLESS=1 ./basic.sh`
			```

basic.sh: Get system disk image path from environment Currently users have to modify the basic.sh script by hand to add the path to the system disk image they created. Rather than having them modify the script, just grab it from the environment. 2019-06-20 01:22:43 +02:00			`Remember to partition in Disk Utility first!`
Initial documentation. 2019-04-23 00:08:10 +02:00
[DOCS] Update README. 2019-05-10 20:07:24 +02:00			`## Step 2a (Virtual Machine Manager)`
			If instead of QEMU, you'd like to import the setup into Virt-Manager for further configuration, just run `make.sh --add`.

Initial documentation. 2019-04-23 00:08:10 +02:00			`## Step 3`
[DOCS] Update docs. 2019-04-30 23:48:10 +02:00
			`You're done!`

chore: simple typo fix seting -> setting 2019-06-20 00:58:52 +02:00			To fine-tune the system and improve performance, look in the `docs` folder for more information on [adding memory](docs/guide-performance.md), setting up [bridged networking](docs/guide-networking.md), adding [passthrough hardware (for GPUs)](docs/guide-passthrough.md), and enabling sound features.