From 7ea2b8ec48f0cb91e2b61aeba18736bca2eb92b9 Mon Sep 17 00:00:00 2001 From: Panagiotis Vasilopoulos Date: Mon, 22 Mar 2021 13:20:09 +0200 Subject: [PATCH] Made further improvements to the README --- README.md | 405 +++++++++++++++++++++++------------------------------- 1 file changed, 175 insertions(+), 230 deletions(-) diff --git a/README.md b/README.md index d96ef55..e0409dc 100644 --- a/README.md +++ b/README.md @@ -6,25 +6,53 @@ 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 ## Docker 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. @@ -40,7 +68,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)! @@ -58,6 +86,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. +### 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 Product names, logos, brands and other trademarks referred to within this project are the property of their respective trademark holders. These trademark holders are not affiliated with our repository in any capacity. They do not sponsor or endorse our materials. @@ -127,22 +159,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 @@ -235,55 +284,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 @@ -296,12 +297,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)! @@ -316,11 +314,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`. @@ -422,9 +419,12 @@ docker run \ newImageName ``` -# Troubleshooting +## Troubleshooting + +### LibGTK - Permission denied + +Thanks [@raoulh](https://github.com/raoulh) and [@arsham](https://github.com/arsham) for contributing this section. -libgtk permissions denied error, thanks @raoulh + @arsham ```bash echo $DISPLAY @@ -442,7 +442,9 @@ xhost + ``` -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 \ @@ -453,7 +455,8 @@ docker run \ sickcodes/docker-osx ``` -PulseAudio debugging: +#### PulseAudio debugging + ```bash docker run \ --device /dev/kvm \ @@ -464,7 +467,9 @@ docker run \ sickcodes/docker-osx pactl list ``` -Alternative run, thanks @roryrjb +#### Alternative soltuion + +Thanks [@roryrjb](https://github.com/roryrjb) for contributing this section. ```bash docker run \ @@ -477,39 +482,43 @@ docker run \ sickcodes/docker-osx ``` -Check if your hardware virt is on +### Routine checks + +#### Confirm that your CPU supports virtualization ```bash egrep -c '(svm|vmx)' /proc/cpuinfo ``` -Try adding yourself to the docker group +#### Try adding yourself to the docker group ```bash sudo usermod -aG docker "${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 \ @@ -519,7 +528,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)" @@ -529,9 +539,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,' @@ -539,13 +549,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 @@ -560,36 +568,15 @@ sudo tee -a /etc/sysctl.conf <