Chameleon Users Guide

Users Guide for Chameleon 2.0

(RC1, RC2, RC3, RC4, RC5, etc...)

features:

• boots multiple operating systems off most media (hard drives, DVDs, USB devices)

• "vanilla" installs where the OS installed remains untouched

• supports patched DSDTs (Differentiated System Description Tables)

• hybrid GUID/GPT+MBR & MBR partitioned disks supported, as is Apple software-RAID

• graphical & text interfaces

Chameleon is open source software. 3rd parties have released a number of modifications of Chameleon, and they have every right to do so. Some mods fix issues that are rarely seen, are more timely, or extend features. These projects expand the pool of users who enjoy a more robust Hackintosh experience.

Many 3rd party builds release binaries, but do not release their source code. Perhaps due to not reading the license or a one line fix, the release of code is required - a derived project is subject to the same license as the original. Thanks is best shown with proper credit & RELEASE OF SOURCE. End users who see projects using Chameleon code should ask for the source - or those projects should not release binaries to the public at all.

----------------------------------------------------------------------------------------------------------------------------------------------

How does Chameleon work?

Available media is scanned for an overview of available operating systems. If the selection is Mac OS X for example on an HFS+ partition an environment emulating EFI (an alternative to BIOS) is crafted. Then the loading of additional data (kernel extensions, a DSDT table, device properties) is performed and handed off to the kernel & the OS.

Can Chameleon start Mac OS X on every computer?

Chameleon can start Mac OS X on a great many computers, but with varying degrees of ease & success. For example, some motherboards are better supported than others - stemming from their similarity to components within existing Apple computers. Some components do not have a corollary to a Mac components, and so additional software needs to be included (kernel extensions for a particular audio or ethernet chip for example). Other components like graphics don't have much 3rd party support, requiring a selection that sticks to existing product lines that are known to be supported. There are additional barriers when using AMD CPUs as well.

----------------------------------------------------------------------------------------------------------------------------------------------

device-properties

<key>Kernel</key>

<string>mach_kernel</string>

Holder

config=<file> specifies where to look for a com.apple.Boot.plist file

cpus=1 instructs the kernel to use x CPUs/cores

rd=diskXsY boots the OS on this partition (BSD format; use diskutil list)

uuid=12345678-1234-1234-1234-123456789012

Below are the config keys controlling how Chameleon operates:

Prompt for a key press before starting the kernel. (defaults to yes)

<key>Quiet Boot</key>

No messages or prompts displayed while booting (press F10 while booting to override)

<key>Timeout</key>

Boots the default partition (same device as Chameleon, first bootable partition) automatically after waiting num seconds without further user interaction. Pressing the down arrow allows you to select additional options like verbose booting, or allows you to add additional parameters. Example:

<key>Instant Menu</key>

Force displaying the partition selection menu. (defaults to yes)

<key>Default Partition</key>

Sets the default boot partition where X is the drive & y is the partition.

Disables the graphical Chameleon in favor of the all-text version. GUI mode is enabled by default

<key>Boot Banner</key>

Show boot banner (logo.png in the selected Theme) in GUI mode (defaults to yes)

<key>Legacy Logo</key>

Show the legacy grey apple logo in GUI mode (defaults to no)

<key>Theme</key>

<string>theme_name</string>

Uses the folder Extra/Themes/theme_name as the GUI theme Chameleon uses (default is an embedded "Default" theme)

Below are the config keys that deal with hardware:

<key>Graphics Mode</key>

<string>WIDTHxHEIGHTxDEPTH@Hertz"</string>

Force booting using a fixed resolution. Hertz setting is optional. Examples:

<key>GraphicsEnabler</key>

Automatic device-properties generation for graphics cards Currently supports only nVidia cards. (defaults to no)

<key>VideoROM</key>

Use an alternate ROM image located @ /file/path (default path: /NVIDIA.ROM).

<key>VBIOS</key>

Inject VideoBIOS to device-properties. (defaults to no)

<key>EthernetBuiltIn</key>

Automatic device-properties generation for ethernet interfaces. (defaults to no)

<key>USBBusFix</key>

Enable the EHCI and UHCI fixes (disabled by default). These make the USB ports "built-in", enable waking by pressing a key or moving the mouse & fix waking the OS to prevent device removal errors.

<key>EHCIacquire</key>

Enable the EHCI fix only (disabled by default).

<key>UHCOreset</key>

Enable the UHCI fix only (disabled by default).

Disable wake up after hibernation (enabled by default).

<key>ForceWake</key>

Force using the sleepimage (disabled by default).

<key>WakeImage</key>

Use an alternate sleepimage file (default path is /private/var/vm/sleepimage).

Use an alternate DSDT.aml file (DSDT is automatically loaded from default path of /DSDT.aml or Extra/DSDT.aml).

<key>SMBIOS</key>

Use an alternate smbios.plist file (default path: /smbios.plist /Extra/smbios.plist rd(0,0)/Extra/smbios.plist).

<key>SMBIOSdefaults</key>

Don't use the default values for SMBIOS overriding. If smbios.plist doesn't exist, factory values are kept.

<key>Scan Single Drive</key>

Scan the drive only where the booter got loaded from. Fix rescan issues when using a DVD reader in AHCI mode. (defaults to no)

<key>Rescan</key>

Enable DVD/CD-ROM rescan mode.

<key>Rescan Prompt</key>

Prompts for CD-ROM rescan mode.

<key>device-properties</key>

Adds support for devices via a hex base64 encoded "EFI strings". Only entry is supported, but more than 1 device can be included within the encoded string.

----------------------------------------------------------------------------------------------------------------------------------------------

Chameleon command line interface advanced startup options

When Chameleon is booted into GUI (Graphical) mode, pressing any key begins entering text into Chameleon's command line interface at the bottom of the screen. The kernel config keys & most of the hardware config keys work by just typing them on the command line. Keys with a space in them need to be wrapped in quotes. Examples:

arch=i386 -v

mach_kernel rd=disk0s1 -v "Graphics Mode"="1920x1200x32"

USBBusFix=yes rd=uuid boot-uuid=1EAA1BE6-A4CB-35EB-A418-92609A4C730B

----------------------------------------------------------------------------------------------------------------------------------------------

Making a Chameleon 2-based bootCD

bootCDs, hard drives & partitions (oh my)

Chameleon can be the basis of a "bootCD", burned onto a CD & used to boot a retail Mac OS X Install DVD. Typically for a hard drive, Chameleon is installed by using the "boot" file. To boot cdroms, Chameleon needs to be installed as the "cdboot" file, slightly enhanced to boot DVDs.

Begin by making a folder named booter on your desktop & an Extra folder inside booter:

mkdir -p ~/Desktop/booter/Extra

Copy the cdboot file from the Chameleon i386 folder into the booter folder

Create, copy or skip altogether a com.apple.Boot.plist file, a DSDT.aml file & a smbios.plist file into booter/Extra folder. Ammend these files to best support your configuration.

Open the com.apple.Boot.plist and add these key::value pairs after another key::value pair:

<key>Rescan</key>

<key>Instant Menu</key>

(some motherboards also benefit from Kernel Flags of arch=i386 to boot into 32-bit mode)

Open Terminal.app & paste this command to create a 15MB Preboot disk image:

hdiutil create -size 15m -fs HFS+ -volname Preboot -layout MBRSPUD -attach ~/Desktop/booter/Extra/Preboot.dmg && mkdir -p /Volumes/Preboot/Extra/Extensions

Kernel extensions (.kext) go into the Extra/Extensions folder within the Preboot disk image. Make sure that their Info.plist have the required OSBundleRequired key filled with a Root string value.

Unmount the Preboot volume from the desktop (right-click -> Eject)

Create the bootCD by pasting this command into a Terminal window:

hdiutil makehybrid -o ~/Desktop/Boot.iso ~/Desktop/booter/ -iso -hfs -eltorito-boot ~/Desktop/booter/cdboot -no-emul-boot -hfs-volume-name "BootCD"

Burn the Boot.iso disk image onto DVD or CD.

Using a Chameleon 2 based bootCD

Restart the computer. Make sure BIOS is set to boot from CD/DVD before booting from hard drives. If booting a hard drive partition with an existing Mac OS X install, select and press enter. To boot an Install DVD continue reading.

When Chameleon displays the GUI, eject the bootCD & insert the retail Mac OS X Install DVD.

Wait a few seconds while the DVD is scanned.

Press F5 to cause Chameleon to rescan the optical drive(s).

When the "Mac OS X Install DVD" icon & name appears, select the DVD & press the Enter key to boot the DVD.

If there are problems, booting in verbose mode can help diagnose what went wrong. After you select the drive you want to boot, but before you press Enter, press the down arrow key & select "Boot in verbose mode" or type -v and then hit Enter.

Simple install of Chameleon onto a hard drive (non-RAID):

Determine which drive & which partition to target for installation. Use this Terminal.app command to view which devices & their identifiers are available:

diskutil list

Change directories to where the Chameleon binaries are. If Chameleon is on the desktop:

cd ~/Desktop/Chameleon-2*/i386

Install the stage0 loader onto the target device:

sudo fdisk -f boot0 -u -y /dev/rdiskX

(where X is the number of the device, Y is the partition, from the diskutil command above)

Install the stage1 loader onto the target volume:

sudo dd if=boot1h of=/dev/rdiskXsY

Copy the Chameleon "boot" file to the destination

sudo cp boot /dest/path

(you can drag & drop the target device onto the Terminal window. What is important is to have all the files on the same device, and boot1h & boot on the same volume & at the top level of the device. example: sudo cp boot /

will copy the boot file onto the root partition.)

Installing Chameleon into a hidden EFI partition on a hard drive (non-RAID):

Determine which drive & which partition you want to install onto. If the target drive is GPT (GUID) partitioned, it may be desirable to install onto a hidden partition that the EFI specification calls for. View the presence of this hidden partition by pasting this command into a Terminal.app window:

diskutil list

where a 200MB partition of type EFI is present for each GUID partitioned drive. This space is unused by Apple though the EFI spec calls for it. It is unprepared for data, requiring extra steps to make it accessible.

There are 2 advantages to using this EFI partition: it doesn't automatically mount so it is more difficult to wreck & since this partition is almost totally isolated from any Mac OS, the OS can be erased and reinstalled while Chameleon survives intact. Installing onto the same device as your Mac OS X install minimizes any problems. To determine which device contains the currently running OS:

diskutil info / | grep "Part Of Whole"

will return something like diskX. To reconfirm, scroll back to the output from the diskutil list command above, and find that diskXs1 is of type EFI. Note that this partition is not normally mounted.

Become the superuser to made these modifications:

sudo -s

(enter your admin password when prompted)

Prepare the hidden partition by formatting:

diskutil eraseVolume HFS+ EFI diskXs1

(ignore any mount errors for now)

Change directories to where Chameleon has its binary files (you can type "cd " with a space there and drag&drop the folder from the Finder onto the Terminal window, let go & hit return):

cd ~/Downloads/Chameleon-2*/i386

Install the stage0 loader onto the target device:

fdisk -f boot0 -u -y /dev/rdiskX

(where X is the number of the device, from the diskutil command above)

Install the stage1 loader onto the target volume (the EFI partition is always first, hence rdiskXs1):

dd if=boot1h of=/dev/rdiskXs1

Make a mountpoint & mount the hidden EFI volume:

mkdir /Volumes/EFI; mount_hfs /dev/diskXs1 /Volumes/EFI

Prevent the File System Events daemon (fseventd) from writing its longs to this volume when mounted, preventing unmounting:

mkdir /Volumes/EFI/.fseventsd; touch /Volumes/EFI/.fseventsd/no_log

Release your root privileges:

exit

You can make the Finder display the drive for non-Terminal file operations:

open /Volumes/EFI

(on 10.5.x systems, this often requires 2 issuances)

Make the required folder structure

mkdir -p /Volumes/EFI/Extra/Extensions

(starting with Chameleon 2.0 RC3, Extra may contain 10.4, 10.5 & 10.6 folders that store .kext kernel extensions for OS specific support in an Extensions folder: /Volumes/EFI/Extra/10.X/Extensions)

Add whatever kernel extensions (.kext) you may have to the Extensions folder.

The Themes folder may be copied into the Extra folder; add 3rd party themes to the Themes folder & set the Themes key in the com.apple.Boot.plist to utilize the new theme.

cp -R ../Optional\ Extras/Themes /Volumes/EFI/

When finished with the EFI partition, dismount the volume & remove the mountpoint:

sudo umount -f /Volumes/EFI; sudo rm -rf /Volumes/EFI

NOTE: Some motherboards require an active partition be set to boot the device. For motherboards that don't require this setting, this doesn't hurt. Replace rdiskX with device number from diskutil list.

printf "flag 1\nwrite\ny\nquit\n" | sudo fdisk -e /dev/rdiskX

(ignore: "fdisk: could not open MBR file /usr/standalone/i386/boot0: No such file or directory")

(ignore: "fdisk:*1> Device could not be accessed exclusively.")

Reboot.

Install Chameleon onto an Apple software-RAID:

Create an Apple sofware-RAID, either striped or mirrored. Install Mac OS X onto this RAID.

Determine which drives & which partitions belong to your RAID:

diskutil list

returns information regarding your drives:

/dev/disk0

#: TYPE NAME SIZE IDENTIFIER

0: GUID_partition_scheme *931.5 Gi disk0

1: EFI 200.0 Mi disk0s1

2: Apple_RAID 931.3 Gi disk0s2

3: Apple_Boot Boot OSX 128.0 Mi disk0s3

/dev/disk1

#: TYPE NAME SIZE IDENTIFIER

0: GUID_partition_scheme *931.5 Gi disk1

1: EFI 200.0 Mi disk1s1

2: Apple_RAID 931.3 Gi disk1s2

3: Apple_Boot Boot OSX 128.0 Mi disk1s3

Mac OS X creates a small helper partition at the end of each RAID member disk listed here as diskXs3, as well as a EFI partition.

Install the stage0 loader onto the members of the target RAID:

sudo fdisk -f boot0 -u -y /dev/rdisk0

sudo fdisk -f boot0 -u -y /dev/rdisk1

Install the stage1 loader onto the bootsector of each boot partition of the target RAID:

sudo dd if=boot1h of=/dev/rdisk0s3

sudo dd if=boot1h of=/dev/rdisk1s3

Install Chameleon (the "boot" file) onto each of the "Boot OSX" partitions of the target RAID:

diskutil mount disk0s3

cp boot /Volumes/Boot\ OSX

diskutil unmount disk0s3

diskutil mount disk1s3

cp boot /Volumes/Boot\ OSX

diskutil unmount disk1s3

Open Disk Utility.app, select the raid and lick on the "Info" icon at the top left of the window. Find the "Universal Unique Identifier" (uuid) and copy that hex-a-dec-imal-code. This uuid needs to be added to the kernel flags in the com.apple.Boot.plist file.

Mount each "Boot OS X" partition of the target RAID (here there are 2 drives, so 2 "Boot OS X" partitions to mount:

diskutil mount disk0s3

Open the com.apple.Boot.plist and add the uuid:

<key>Kernel Flags</key>

If you don't have a com.apple.Boot.plist or an Extra folder on the "Boot OS X" partition, make one & copy the original found @ /Library/Preferences/SystemConfiguration/com.apple.Boot.plist to each "Boot OSX" partition of the target RAID.

NOTE: Apple software-based RAID is support, BIOS RAID is not.

What is Chameleon?

Chameleon is a bootloader. It loads right after the bios sets up the computer and tries to find an operating system to start. Chameleon can start numerous operating systems (Windows, Mac OS X, Linux, FreeBSD…) but primarily it is used when Mac OS X is installed on non-Apple hardware. Chameleon is an evolution of David Elliot's (dfe) original modification of Apple's own boot-132. Chameleon is comprised of a series of loaders:

boot & cdboot - stage2 booters; Chameleon binaries; cdboot is used to boot DVDs
boot0 - locates active partition & loads the partition booter for MBR & GUID/MBR hybrids
chain0 - loaded by another booter to jump booting yet another booter
boot1h - partition booter for HFS+ that loads the stage2 booter
boot1f32 - booter for FAT32 partitions on MBR
boot1he - booter for extended sectors
boot1hp - partition booter for HFS+ that finds a boot1h extended loader

Configuration

There is 1 file that configures how Chameleon behaves (the com.apple.Boot.plist file), and 4 areas where you can alter how Chameleon starts Mac OS X: kext kernel extensions, DSDT.aml compiled table, smbios.plist & the previously mentioned com.apple.Boot.plist file. Of these, only kernel extensions are required to start Mac OS X, the other files are optional.

Chameleon gets configuration data from a number of places:

Extra folder containing the 3 configuration files:

Extra (next to "boot" file on an non-OS partition; example: /Volumes/EFI/Extra)

/Extra (root folder of the booted Mac OS X volume)

Extra folder on a Preboot.dmg loaded as a ramdisk in the above locations

Kernel extensions (in either stand-alone .kext or cached .mkext) can be loaded from:

Extra/Extensions (same volume as "boot" file; example: /Volumes/EFI/Extra/Extensions)

Extra/10.x/Extensions (OS version specific folder of above)

/Extra/Extensions (on the booted Mac OS X volume)

/Extra/10.x/Extensions (OS version specific folder of above)

/System/Library/Extensions (modifications here require rebuilding the kext cache)

inside Extra/Exensions on a Preboot.dmg loaded as a ramdisk in the above locations

(note: sometimes a stubborn kernel extension needs to be in /System/Library/Extensions to work)

Only 1 com.apple.Boot.plist, smbios.plist & DSDT.aml is used from these locations, but starting with Chameleon 2.0 RC3, kernel extensions can be in an Extensions folder within the above mentioned folders, or an Mac OS X version specific folder. This means that you can have Extra/10.5/Extensions & Extra/10.6/Extensions each with different extensions targeted for each major version of Mac OS X.

Its is best to pick a single location for all files

smbios.plist

This is the a simple text file with few parameters. Mostly this information is reflected in system profiler information. This file is in an extended XML format called a property list (or plist as the suffix shows).

DSDT.aml

This file is not human readable, but represents a description of a motherboard, its capabilities & feature. The human readable quasi-programming DSDT.dst is compiled via an Intel cli tool called iasl into this file. Chameleon can then present this to the Mac OS X kernel for OS use. Amending this file can support or add support in ways that make your computer more stable - or less stable if the coding is not done properly. Adding support for an audio chip can be done by chaining a few lines, but support can also come in the form of a kernel extension, so it can be a matter of preference.

com.apple.Boot.plist

Chameleon uses this file as a preferences file - many aspects of Chameleon can also be configured by adding them in key::string form into this file. The kernel also gets some configuration preferences from this file (64/32bit for example). System-specific features are also entered here in the form of device properties for inclusion into the EFI tree that Chameleon presents to the kernel. These device properties emulate how EFI sets up things like graphics cards, audio & LAN. Search for a guide to "EFI strings". You can always revert back to a fresh, bare copy of this file found in /Library/Preferences/SystemConfiguration/com.apple.Boot.plist

kernel extensions

Chameleon presents these supplemental files to the kernel during booting & remain active during runtime. They extend OS support to additional components (a LAN chip), remedy components that work, but imperfectly (an audio chip), or nullify existing Apple components that cause problems (like CPU power management). Kernel extensions are a sort of nested folder structure that presents as a single file to Mac OS X. For the kernel to work with these files, their embedded plist needs to include OSBundleRequired::Root key. These additional kernel extensions reside in Extra/Extensions folder (see above for locations). Note: using kextcache to built an Extensions.mkext is no longer required, but is supported.

com.apple.Boot.plist Chameleon available keys:

Kernel

Kernel Flags

Wait

Quiet Boot

Timeout

Instant Menu

Default Partition

GUI

Boot Banner

Legacy Logo

Theme

GraphicsMode

GraphicsEnabler

VideoROM

VBIOS

EthernetBuiltIn

USBBusFix

EHCIacquire

UHCOreset

Wake

ForceWake

WakeImage

DSDT

SMBIOS

SMBIOSdefaults

Scan Single Drive

Rescan

Rescan Prompt

specifies which kernel on the target partition to use; useful for booting with an alternate kernel while keeping both on the same hard drive

<key>Kernel Flags</key>

add optional kernel flags here. Some flags are:

-v verbose

-s single user

-x safe mode

arch=x86_64 force kernel into 64-bit mode

arch=i386 force kernel into 32-bit mode