@ -6,13 +6,41 @@ Run Mac OS X in Docker with near-native performance! X11 Forwarding! iMessage se
## Author
This project is maintained by [Sick.Codes](https://sick.codes/) [(Twitter)](https://twitter.com/sickcodes)
This project is maintained by [Sick.Codes](https://sick.codes/). [(Twitter)](https://twitter.com/sickcodes)
Additional credits can be found here: https://github.com/sickcodes/Docker-OSX/blob/master/CREDITS.md
Additionally, comprehensive list of all contributors can be found here: https://github.com/sickcodes/Docker-OSX/graphs/contributors
Special thanks to [@kholia](https://twitter.com/kholia) for maintaining the upstream project, which Docker-OSX is built on top of: [OSX-KVM](https://github.com/kholia/OSX-KVM)
Special thanks to [@kholia](https://twitter.com/kholia) for maintaining the upstream project, which Docker-OSX is built on top of: [OSX-KVM](https://github.com/kholia/OSX-KVM).
## Technical details
**Current large image size:** 17.5GB
The images (excluding `:naked`) launch a container with an existing installation with a couple of premade configurations. This special image was developed by [Sick.Codes](https://sick.codes):
- username: `user`, password: `alpine`
- ssh enabled (`localhost:50922`)
- vnc enabled (`localhost:8888`)
- auto-updates disabled
- serial number generators!
- x11 forwarding is enabled
- runs on top of QEMU + KVM
- supports big sur, custom images, xfvb headless mode
- you can clone your container with `docker commit`
### Requirements
- at least 50 GBs (half for the base image, half for your runtime image
- virtualization should be enabled in your bios settings
- a kvm-capable host
### To be done
- documentation for security researchers
- gpu acceleration
- support for virt-manager
Big thanks to the OpenCore team over at: https://github.com/acidanthera/OpenCorePkg. Their well-maintained bootloader provides much of the great functionality that Docker-OSX users enjoy :)
@ -22,13 +50,13 @@ If you like this project, consider contributing upstream!
Images built on top of the contents of this repository are also available on **Docker Hub** for convenience: https://hub.docker.com/r/sickcodes/docker-osx
A comprehensive list of the available Docker images and their intended purpose can be found in the [Instructions](README.md#Instructions)
A comprehensive list of the available Docker images and their intended purpose can be found in the [Instructions](README.md#Instructions).
## Kubernetes
Docker-OSX supports Kubernetes.
Kubernetes Helm Chart & Documentation can be found under the [helm directory](helm/README.md)
Kubernetes Helm Chart & Documentation can be found under the [helm directory](helm/README.md).
Thanks [cephasara](https://github.com/cephasara) for contributing this major contribution.
@ -44,7 +72,7 @@ Feel free to open an [issue](https://github.com/sickcodes/Docker-OSX/issues/new/
Before you open an issue, however, please check the [closed issues](https://github.com/sickcodes/Docker-OSX/issues?q=is%3Aissue+is%3Aclosed) and confirm that you're using the latest version of this repository — your issues may have already been resolved!
@ -62,6 +90,10 @@ In case you're interested, contact [@sickcodes on Twitter](https://twitter.com/s
Docker-OSX is licensed under the [GPL v3+](LICENSE). Contributions are welcomed and immensely appreciated. You are in-fact permitted to use Docker-OSX as a tool to create proprietary software.
### Other cool Docker/QEMU based projects
- [Run iOS in a Docker container with Docker-eyeOS](https://github.com/sickcodes/Docker-eyeOS) - [https://github.com/sickcodes/Docker-eyeOS](https://github.com/sickcodes/Docker-eyeOS)
## Disclaimer
If you are serious about Apple Security, and possibly finding 6-figure bug bounties within the Apple Bug Bounty Program, then you're in the right place! Further notes: [Is Hackintosh, OSX-KVM, or Docker-OSX legal?](https://sick.codes/is-hackintosh-osx-kvm-or-docker-osx-legal/).
@ -171,22 +203,11 @@ Use `docker commit`, copy the ID, and then run `docker start -ai <Replace this w
[Extract the .img file](https://github.com/sickcodes/Docker-OSX#backup-the-disk-wheres-my-disk), and then use that [.img file with :naked](https://github.com/sickcodes/Docker-OSX#quick-start-own-image-naked-container-image)
# Technical details
**Current large image size:** 17.5GB
The images (excluding `:naked`) launch a container with an existing installation with a couple of premade configurations. This special image was developed by [Sick.Codes](https://sick.codes):
- SSH enabled
- username is `user`
- password is `alpine`
- auto-updates are disabled
## Requirements
#### Further examples
You will need around *50 GB* of space to run this image: half for the base image + half for your runtime image.
Apart from the previous examples, there's a myriad of other potential use cases that can work perfectly with Docker-OSX.
If you run out of space, you can delete all your old Docker images/history/cache by simply deleting `/var/lib/docker`, and restarting `dockerd`.
### Run Mac OS X
```bash
docker pull sickcodes/docker-osx:auto
@ -201,7 +222,6 @@ docker run -it \
```
```bash
docker pull sickcodes/docker-osx:auto
# boot directly into a real OS X shell with a visual display [NOT HEADLESS]
@ -211,10 +231,25 @@ docker run -it \
-v /tmp/.X11-unix:/tmp/.X11-unix \
-e "DISPLAY=${DISPLAY:-:0.0}" \
sickcodes/docker-osx:auto
```
### Download the image manually and use it in Docker
This is a particularly good way for downloading the container, in case Docker's CDN (or your connection) happens to be slow.
### Pre-built Image + Arbitrary Command Line Arguments.
### Use a pre-built image + arbitrary command line arguments.
```bash
docker pull sickcodes/docker-osx:auto
@ -231,7 +266,20 @@ docker run -it \
# Boots in a minute or two!
```
### Restart an auto container
### Run Mac OS X headlessly with a custom image
This is particularly helpful for CI/CD pipelines.
```bash
# run your own image headless + SSH
docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v "${PWD}/mac_hdd_ng.img:/image" \
sickcodes/docker-osx:naked
```
### Restart a container that starts automatically
Containers that use `sickcodes/docker-osx:auto` can be stopped while being started.
@ -243,17 +291,18 @@ docker ps -a
docker start -ai -i <ReplacethiswithyourID>
```
### Quick Start Own Image (naked container image)
### Quick Start your own image (naked container image)
This is my favourite container. You can supply an existing disk image as a docker command line argument.
This is my favourite container. You can supply an existing disk image as a Docker command line argument.
Pull images out using `sudo find /var/lib/docker -size +10G | grep mac_hdd_ng.img`
- Pull images out using `sudo find /var/lib/docker -size +10G | grep mac_hdd_ng.img`
Supply your own local image with `-v "${PWD}/mac_hdd_ng.img:/image"` and use `sickcodes/docker-osx:naked`
- Supply your own local image with the command argument`-v "${PWD}/mac_hdd_ng.img:/image"` and use `sickcodes/docker-osx:naked` when instructing Docker to create your container.
- Naked image is for booting any existing .img file, e.g in the current working directory (`$PWD`)
- Naked image is for booting any existing .img file, e.g in the current working directory (`$PWD`)
- By default, this image has a variable called `NOPICKER` which is `"true"`. This skips the disk selection menu. Use `-e NOPICKER=false` or any other string than the word `true` to enter the boot menu.
-Bydefault, this image hasa variable called `NOPICKER` which is `"true"`. This skips the disk selection menu. Use `-e NOPICKER=false` or any other string than the word `true` to enter the boot menu. This lets you use other disks instead of skipping the boot menu, e.g. recovery disk or disk utility.
This lets you use other disks instead of skipping the boot menu, e.g. recovery disk or disk utility.
```bash
docker pull sickcodes/docker-osx:naked
@ -279,55 +328,7 @@ docker run -it \
sickcodes/docker-osx:naked
```
### Fully Headless, using a custom image, for CI/CD
```bash
# run your own image headless + SSH
docker run -it \
--device /dev/kvm \
-p 50922:10022 \
-v "${PWD}/mac_hdd_ng.img:/image" \
sickcodes/docker-osx:naked
```
# Features In Docker-OSX v4
- `sickcodes/docker-osx:big-sur` - original base recovery image for latest OS (safe)
- Serial number generators. [See below or ./custom](https://github.com/sickcodes/Docker-OSX/tree/master/custom)
- Full auto mode: boot straight to OS X shell and even run commands as runtime arguments!
- `sickcodes/docker-osx:latest` - original base recovery image (safe)
- `sickcodes/docker-osx:naked` - supply your own .img file (safe)
- `sickcodes/docker-osx:auto` - Large docker image that boots to OS X shell (must trust @sickcodes)
- Supply your own image using `-v "${PWD}/disk.img:/image"`
- [OSX-KVM](https://github.com/kholia/OSX-KVM) inside a Docker container!
- X11 Forwarding
- SSH on `localhost:50922`
- QEMU + KVM!
- VNC version on `localhost:8888` [vnc version is inside a separate directory, there are security risks involved with using VNC, see insid the Dockerfile](https://github.com/sickcodes/Docker-OSX/blob/master/vnc-version/Dockerfile)
- Create an ARMY of the same exact container using `docker commit`
[Run iOS in a Docker with Docker-eyeOS](https://github.com/sickcodes/Docker-eyeOS) - [https://github.com/sickcodes/Docker-eyeOS](https://github.com/sickcodes/Docker-eyeOS)
# Run Docker-OSX (Original Version)
### Run the original version of Docker-OSX
```bash
@ -340,12 +341,9 @@ docker run -it \
-e "DISPLAY=${DISPLAY:-:0.0}" \
sickcodes/docker-osx:latest
# press ctrl G if your mouse gets stuck
# press CTRL + G if your mouse gets stuck
# scroll down to troubleshooting if you have problems
# need more RAM and SSH on localhost -p 50922?
```
# Run but enable SSH in OS X (Original Version)!
@ -360,11 +358,10 @@ docker run -it \
sickcodes/docker-osx:latest
# turn on SSH after you've installed OS X in the "Sharing" settings.
ssh fullname@localhost -p 50922
ssh user@localhost -p 50922
```
# Autoboot into OS X after you've installed everything
### Autoboot into OS X after you've installed everything
You can use `-e NOPICKER=true`.
@ -466,13 +463,16 @@ docker run \
newImageName
```
# Troubleshooting
## Troubleshooting
Big thank you to our contributors who have worked out almost every conceivable issue so far!
@ -522,7 +522,9 @@ Of course you cannot allocate more RAM that your have. The default is 3 Gigabyte
#### PulseAudio
PulseAudio for sound (note neither [AppleALC](https://github.com/acidanthera/AppleALC) and varying [`alcid`](https://dortania.github.io/OpenCore-Post-Install/universal/audio.html) or [VoodooHDA-OC](https://github.com/chris1111/VoodooHDA-OC) have [codec support](https://osy.gitbook.io/hac-mini-guide/details/hda-fix#hda-codec) though [IORegistryExplorer](https://github.com/vulgo/IORegistryExplorer) does show the controller component working):
### Use PulseAudio for sound
Note: [AppleALC](https://github.com/acidanthera/AppleALC), [`alcid`](https://dortania.github.io/OpenCore-Post-Install/universal/audio.html) and [VoodooHDA-OC](https://github.com/chris1111/VoodooHDA-OC) do not have [codec support](https://osy.gitbook.io/hac-mini-guide/details/hda-fix#hda-codec). However, [IORegistryExplorer](https://github.com/vulgo/IORegistryExplorer) does show the controller component working.
```bash
docker run \
@ -533,7 +535,8 @@ docker run \
sickcodes/docker-osx
```
PulseAudio debugging:
#### PulseAudio debugging
```bash
docker run \
--device /dev/kvm \
@ -554,44 +557,49 @@ sudo tee /sys/module/kvm/parameters/ignore_msrs <<< 1
egrep -c '(svm|vmx)' /proc/cpuinfo
```
### Routine checks
#### Confirm that your CPU supports virtualization
#### Add yourself to the Docker group, KVM group, libvirt group.
If you use `sudo dockerd` or dockerd is controlled by systemd/systemctl, then you must be in the Docker group:
To add yourself to the docker group:
#### Try adding yourself to the docker group
```bash
sudo usermod -aG docker "${USER}"
```
and for the rest:
and also to the kvm and libvirt groups:
```bash
sudo usermod -aG libvirt "${USER}"
sudo usermod -aG kvm "${USER}"
```
Turn on docker daemon
#### Enable docker daemon
```bash
# run ad hoc
# enable it in systemd
sudo systemctl enable --now docker
# or run ad hoc
sudo dockerd
# or daemonize it
sudo nohup dockerd &
# or enable it in systemd
sudo systemctl enable --now docker
```
# How to Forward Additional Ports from the guest.
#### Forward additional ports (nginx)
This is how it visually looks:
It's possible to forward additional ports depending on your needs. In this example, we're going to use Mac OS X to host nginx in a way that looks like this:
@ -621,13 +630,11 @@ You can string multiple statements, for example:
-p 10043:10043 \
```
# How to Enable Network Forwarding
Allow ipv4 forwarding for bridged networking connections:
### Enable IPv4 forwarding for bridged network connections
This is not required for LOCAL installations and may cause containers behind [VPN's to leak host IP](https://sick.codes/cve-2020-15590/).
This is not required for LOCAL installations and may [cause the host to leak your IP, even if you're using a VPN in the container](https://sick.codes/cve-2020-15590/).
If you are connecting to a REMOTE Docker-OSX, e.g. a "Mac Mini" in a datacenter, then this may boost networking:
However, if you're trying to connect to an instance of Docker-OSX remotely (e.g. an instance of Docker-OSX hosted in a datacenter), this may improve your performance:
```bash
# enable for current session
@ -642,36 +649,15 @@ sudo tee -a /etc/sysctl.conf <<EOF
net.ipv4.ip_forward = 1
EOF
# OR edit manually
# or edit manually with the editor of your choice
nano /etc/sysctl.conf || vi /etc/sysctl.conf || vim /etc/sysctl.conf
# now reboot
```
# How to install Docker if you don't have Docker already
### Fedora: No internet connectivity with a bridged network
### Fedora: if you have no internet connectivity from the VM, and you are using bridge networking:
Fedora's default firewall settings may prevent Docker's network interface from reaching the internet. In order to reoslve this, you will need to whitelist the interface in your firewall:
# you can move (mv) it somewhere, using cp can take loads of disk space
sudo mv somedir/mac_hdd_ng.img .
```
# Use an Old Docker-OSX Disk in a Fresh Container (Replication)
[Use the sickcodes/docker-osx:naked image.](https://github.com/sickcodes/Docker-OSX/tree/master#quick-start-own-image)
# Internet Speeds
### FAST internet
`-e NETWORKING=vmxnet3`
### SLOW internet
#### Slow internet connectivity
`-e NETWORKING=e1000-82545em`
# DESTROY: Wipe old images to free disk space
The easiest way to clean out your entire Docker (ALL images, layers, and containers) is to `sudo rm -rf /var/lib/docker`
### I'd like to use SPICE instead of VNC
This is useful for getting disk space back.
Optionally, you can enable the SPICE protocol, which allows you to use `remote-viewer` to access it rather than VNC.
It will delete ALL your old (and new) docker containers.
Note: `-disable-ticketing` will allow unauthenticated access to the VM. See the [spice manual](https://www.spice-space.org/spice-user-manual.html) for help setting up authenticated access ("Ticketing").
```bash
# WARNING deletes all old images, but saves disk space if you make too many containers
# The following command will make your containers RIP
* Start up the container as usual, and remove unnecessary files. A useful way
Then simply do `remote-viewer spice://localhost:3001` and add `--spice-debug` for debugging.
### CI/CD Related Improvements
#### Tips for reducing the size of the image
- Start the container as usual, and remove unnecessary files. A useful way
to do this is to use `du -sh *` starting from the `/` directory, and find
large directories where files can be removed. E.g. unnecessary cached files,
Xcode platforms, etc.
* Once you are satisfied with the amount of free space, enable trim with `sudo trimforce enable`, and reboot.
* Zero out the empty space on the disk with `dd if=/dev/zero of=./empty && rm -f empty`
* Shut down the VM and copy out the qcow image with `docker cp stoppedcontainer:/home/arch/OSX-KVM/mac_hdd_ng.img .`
* Run `qemu-img check -r all mac_hdd_ng.img` to fix any errors.
* Run `qemu-img convert -O qcow2 mac_hdd_ng.img deduped.img` and check for errors again
* OPTIONAL: Run `qemu-img convert -c -O qcow2 deduped.img compressed.img` to further compress the image. This may reduce the runtime speed though, but it should reduce the size by roughly 25%.
* Check for errors again, and build a fresh docker image. E.g. with this Dockerfile
- Once you are satisfied with the amount of free space, enable trim with `sudo trimforce enable`, and reboot.
- Zero out the empty space on the disk with `dd if=/dev/zero of=./empty && rm -f empty`
- Shut down the VM and copy out the qcow image with `docker cp stoppedcontainer:/home/arch/OSX-KVM/mac_hdd_ng.img .`
- Run `qemu-img check -r all mac_hdd_ng.img` to fix any errors.
- Run `qemu-img convert -O qcow2 mac_hdd_ng.img deduped.img` and check for errors again
- **OPTIONAL:** Run `qemu-img convert -c -O qcow2 deduped.img compressed.img` to further compress the image. This may reduce the runtime speed though, but it should reduce the size by roughly 25%.
- Check for errors again, and build a fresh docker image. E.g. with this Dockerfile
First make sure [autoboot is enabled](#autoboot-into-osx-after-youve-installed-everything)
Next, you will want to set up SSH to be automatically started.
@ -769,25 +739,9 @@ Then run it with these arguments.
mycustomimage
```
Optionally, you can enable the SPICE protocol, which allows you to use `remote-viewer` to access it rather than VNC.
Note: `-disable-ticketing` will allow unauthenticated access to the VM. See the [spice manual](https://www.spice-space.org/spice-user-manual.html) for help setting up authenticated access ("Ticketing").
@ -1183,7 +1133,7 @@ You should see the device show up when you do `system_profiler SPUSBDataType` in
Important Note: this will cause the host system to lose access to the USB device while the VM is running!
## What is `${DISPLAY:-:0.0}`?
#### What is `${DISPLAY:-:0.0}`?
`$DISPLAY` is the shell variable that refers to your X11 display server.
@ -1201,12 +1151,14 @@ You can also use `${variable:=fallback}` to set that variable (in your current t
In Docker-OSX, we assume, `:0.0` is your default `$DISPLAY` variable.
You can see what yours is
```bash
echo $DISPLAY
```
Hence, `${DISPLAY:-:0.0}` will use whatever variable your X11 server has set for you, else `:0.0`
## What is `-v /tmp/.X11-unix:/tmp/.X11-unix`?
That way, `${DISPLAY:-:0.0}` will use whatever variable your X11 server has set for you, else `:0.0`
#### What is `-v /tmp/.X11-unix:/tmp/.X11-unix`?
`-v` is a Docker command-line option that lets you pass a volume to the container.
@ -1215,11 +1167,3 @@ The directory that we are letting the Docker container use is a X server display
`/tmp/.X11-unix`
If we let the Docker container use the same display socket as our own environment, then any applications you run inside the Docker container will show up on your screen too! [https://www.x.org/archive/X11R6.8.0/doc/RELNOTES5.html](https://www.x.org/archive/X11R6.8.0/doc/RELNOTES5.html)
sickcodes
4 years ago
committed by
GitHub