updated README.md

Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md Update README.md
2016-10-07 15:08:06 -04:00 · 2016-10-07 15:08:06 -04:00 · 65621a0e33
commit 65621a0e33
parent b0154001a4
1 changed files with 145 additions and 2 deletions
--- a/README.md
+++ b/README.md
@ -1,5 +1,148 @@
 # osximage

-# bugs
+This is a repo for building an NBI (never-booted image) of an OS X (pron: oh ess **ten**) root partition, which can be easily and quickly (&lt;10m) imaged onto a Mac with the `asr` utility readily available on OSX boot media.

-* is slow
+## TODO / Known Bugs
+
+* `new-system-setup` tries to update some system python packages that are protected by System Integrity Protection and fails.
+    * fix: move those packages to the `new-user-setup` script instead (`pip install --user $PKG`)
+* a wrong password passed to `fdesetup` in `new-system-setup` offers no attempt to retry
+    * fix: put in shell loop based on exit code
+
+# HOWTO: Creating the NBI
+
+## Prerequisites
+
+Per AutoDMG, you have to be on the same OS as you're building.  To build a 10.12 image, the build system must be running Sierra.
+
+* Install the following to /Applications:
+    * `Xcode.app`
+        * pkg offline non-app-store version available [here](https://developer.apple.com/download/more/)] (requires appleId but does not developer membership)
+    * `Install macOS Sierra.app`
+        * [free download via App Store](https://itunes.apple.com/us/app/macos-sierra/id1127487414)
+    * `AutoDMG.app`
+        * [GitHub Download](https://github.com/MagerValp/AutoDMG/releases)
+    * `CreateUserPkg.app`
+        * [GitHub Pages Download](http://magervalp.github.io/CreateUserPkg/)
+
+* create `~/Documents/packages.10.12`
+    * put in all those apple printer driver `pkg`s you can download
+    * the "enhanced dictation" offline speech recognition 800mb `pkg` that system preferences will download if you ask it
+        * run [this](https://gist.github.com/sneak/958df7165ce5b9e4dd4c89da5764a8e1) while it's downloading to find the temp file, then hardlink it to `whatever.pkg`
+    * any other packages you want preinstalled on the root but not:
+        * Virtualbox (won't work unless installed from inside the running OS for some reason)
+        
+## My `packages.10.12`
+
+```
+48516a7b6e5286cc44ab30ff3c5aa171e0888519  200.BrotherPrinterDrivers.pkg
+ebf0abac1483fd6de9262e92b047dcc80ceabeab  200.CanonPrinterDrivers.pkg
+b8442185bfa0e182b84a7f6f5f298deb04d81a74  200.EPSONPrinterDrivers.pkg
+2cd5d3bfc434226125d068bb09e90cbb2157a7ba  200.FujiXeroxPrinterDrivers.pkg
+f44f5769579f3be7a771f54690de221e04f496cf  200.HewlettPackardPrinterDrivers.pkg
+9c303c08e76aaef2fc9d1599aeea9ff15e8bce2b  200.InfoPrintPrinterDrivers.pkg
+c45d3616f5995846313b9afc159ca6793b00ed08  200.LanierPrinterDrivers.pkg
+9bcdb8492b00b0d7079dde23e1db4ac8da4fe0c0  200.LexmarkPrinterDrivers.pkg
+c6218afb33b68fe6fab803d5b327e4f628857039  200.RicohPrinterDrivers.pkg
+1ef9a998e680df23ca0cf8ba1426ed7673a2c37a  200.SamsungPrinterDrivers.pkg
+df267df6198781d3fae736112a66a4a150c46b67  200.SavinPrinterDrivers.pkg
+59b0306fe33693a73dc709641262f0ed2d63285a  200.XeroxPrinterDrivers.pkg
+b77920f32f36f3229611ea0e10c01f2dad157ceb  20161003.EnhancedDictation.pkg
+```
+
+## Build Image
+
+Finally, just run `make` in the cloned repo to build the NBI.  You will need to enter your sudo password up front, **but don't go get coffee yet**... AutoDMG will ask for it again about 30-60 seconds later.  *Then* go and kill an hour.
+
+The OSX Installer .app, AutoDMG, CreateUserPkg, and Xcode (for `make`) will all be included in the built image, so if you're *using* the image so built it will have everything you need to make further images later.
+
+If you aren't installing any extra packages, edit the `Makefile` to remove the `~/packages.10.12/*.pkg` part.
+
+It writes the image as it's building to /tmp (to leverage fast internal SSD in case your `osximage` clone is on removable media) then moves it to the repo directory in the last step.
+
+# HOWTO: Imaging A Mac
+
+## Before You Begin
+
+Get all data to be saved *off* of target system.  Recommended: install Google Drive and log in to your Google account and put everything to be saved in there.  Wait for sync (upload) to complete.
+
+## Create bootable USB media
+
+* Install OS installer .app bundle to /Applications
+* Insert USB3 media.  64GB or larger to store OS installer and image.
+
+e.g. USB disk named "Untitled":
+
+    sudo /Applications/Install\ macOS\ Sierra.app/Contents/Resources/createinstallmedia \
+      --volume /Volumes/Untitled \
+      --applicationpath "/Applications/Install macOS Sierra.app"
+
+## Copy image to USB
+
+Copy the never-booted disk image (nbi) ending with `.dmg` to the root of the newly-imaged bootable USB disk, alongside the installer `.app` the `createinstallmedia` tool placed on the disk.
+
+## Image Mac
+
+* Insert the bootable USB drive into the machine to be imaged and boot holding the Option key on a wired keyboard.  (Alt on a PC keyboard.)
+* Select `Terminal` from the `Utilities` menu.
+* Run the following commands:
+
+### Repartition and Reformat disk0
+
+⚠️⚠️ **This will delete all data on the internal disk. Proceed with caution.** ⚠️⚠️
+
+`diskutil partitionDisk /dev/disk0 1 GPT jhfs+ root R`
+
+### Write OS NBI to disk0
+
+`asr restore --source file:///Volumes/Image\ Volume/nbi.dmg --target /Volumes/root --erase`
+
+# HOWTO: Using the Custom Image
+
+## 1/4 Initial Password
+
+* The password for the `admin` user is `admin`.  Log in as admin.
+
+## 2/4 Create User Accounts
+
+The example user in this document is John P Smith, username `jps`.  Replace the name and username with your own.
+
+* Create an administrator user account for yourself.
+    * Username: `jpsadmin`
+    * Real Name: `John Smith (admin)`
+* Create a second non-administrator local user account for daily job tasks.
+    * Username: `jps`
+    * Real Name: `John Smith`
+* Create a third non-administrator local user account `personal` for personal use.
+
+## 3/4 Set Up Systemwide Configuration
+
+* Log out of `admin` and into `jpsadmin`.
+* Delete the `admin` user in `System Preferences > Users & Groups`. Choose to delete the user's home folder.
+* Open `System Preferences > Sharing` and set the machine hostname.
+* Connect machine to network (potentially entering wifi password).
+* Open a terminal and run `new-system-setup`.  Enter the `jpsadmin` password when initially prompted.
+    * When prompted to "Enter the user name:", enter your normal username (e.g. `jps`)
+        * This is for FileVault (FDE) to enable the specified user from the encrypted disk.
+* Wait for the script to finish, then enter `sudo reboot`.
+
+## 4/4 Set Up User-specific Configuration
+
+* Log in with your normal user. (e.g. `jps`)
+* You may log in to your personal iCloud account/Apple ID, however, **make sure you disable iCloud Drive as soon as you log in**.
+    * Uncheck `Store files from Documents and Desktop in iCloud Drive` when prompted!
+* Disable iCloud Drive and Mail in `System Preferences > iCloud` if you logged in to iCloud.
+* Open a terminal, and run `new-user-setup`.
+    * This will take a while, as it will be downloading and installing a full set of apps.
+* Log out, and log back in again with the same user so that changed preferences will take effect.
+* Log in to Google Drive (already installed under ~/Applications) with your Google Apps account.
+* Avoid installing any additional software to the machine unless strictly necessary.  Prefer web applications and built-in apps.
+* Do not install third-party software to `/Applications` except via the App Store.
+
+# Credits
+
+* `DefaultDesktop.jpg`
+    * rotated version of [space](http://simpledesktops.com/browse/desktops/2012/feb/19/space-2/) by [Nané](http://www.smplz.com/)
+* other desktops
+    * a whole bunch of 5120px wide (5K Retina iMac res) images from [InterfaceLIFT](https://interfacelift.com/wallpaper/downloads/date/wide_16:9/5120x2880/)
+