diff --git a/README.md b/README.md index 84baac7..c8d0767 100644 --- a/README.md +++ b/README.md @@ -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! -### Features requests and updates +### Feature requests and updates Follow [@sickcodes](https://twitter.com/sickcodes)! @@ -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 ``` -### 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`) - -- 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. This lets you use other disks instead of skipping the boot menu, e.g. recovery disk or disk utility. + - 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. + + 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"` -- Kubernetes Helm Chart. [See ./helm](https://github.com/sickcodes/Docker-OSX/tree/master/helm) -- [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` -- Xfvb headless mode - -# Download the image manually - -```bash -wget https://images2.sick.codes/mac_hdd_ng_auto.img - -docker run -it \ - --device /dev/kvm \ - -p 50922:10022 \ - -v "${PWD}/mac_hdd_ng_auto.img:/image" \ - -v /tmp/.X11-unix:/tmp/.X11-unix \ - -e "DISPLAY=${DISPLAY:-:0.0}" \ - sickcodes/docker-osx:naked - -``` - -### Other cool Docker-QEMU based projects: - -[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! +### LibGTK - Permission denied + [https://github.com/sickcodes/Docker-OSX/blob/master/CREDITS.md](https://github.com/sickcodes/Docker-OSX/blob/master/CREDITS.md) #### libgtk permissions denied error + ```bash echo $DISPLAY @@ -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: -`host:10023 <-> 10023:container:10023 <-> 80:guest` +``` +host:10023 <-> 10023:container:10023 <-> 80:guest +``` + +On the host machine, you should run: -```bash -On the host ```bash docker run -it \ --device /dev/kvm \ @@ -601,7 +609,8 @@ docker run -it \ sickcodes/docker-osx:auto ``` -Inside the container: +In a Terminal session running the container, you should run: + ```bash /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" @@ -611,9 +620,9 @@ sudo sed -i -e 's/8080/80/' /usr/local/etc/nginx/nginx.confcd sudo nginx ``` -nginx should appear on the host at port 10023. +**nginx should now be reachable on the port 10023.** -You can string multiple statements, for example: +Additionally, you can string multiple statements, for example: ```bash -e ADDITIONAL_PORTS='hostfwd=tcp::10023-:80,hostfwd=tcp::10043-:443,' @@ -621,13 +630,11 @@ You can string multiple statements, for example: -p 10043:10043 \ ``` -# How to Enable Network Forwarding +### Enable IPv4 forwarding for bridged network connections -Allow ipv4 forwarding for bridged networking connections: +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/). -This is not required for LOCAL installations and may cause containers behind [VPN's to leak host IP](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 <