DarwinOS expedition

Introducing Darwin
The Mac OS X operating system (OS) doesn't need further introduction to the Mac community. However, the link between the Mac and Darwin is less known. Apple, by 'merging' with Next, has become part of the *nix world, i.e. the realm of Linux, *BSD, AIX, True64, ... All of those OS have one common ancestor, the original Unix project. This realm is a key factor for the development of the quantity and quality of many OpenSource software titles. Darwin is the most *nix part of Mac OS X (and the foundation of it) and the closest from the OpenSource community (though the Apple license is not GNU).

The Darwin Adventure
Apple offers to developers and administrators full access to the source code as well as binary ISO images for each of the major releases of the Darwin OS. Their goal is to create a tech community. The OS is clearly not targeted to the casual user.
This article aims at giving you an insight of this still fairly young operating system, one could say almost confidential, and eventually picking your interest in further helping its development. Let's not forget that Mac OS is supposed to be the most closed OS available.
A few notes worth of your interest :
- Darwin is a very advanced OS, stable and powerful.
- Mac OS X Server admins with a *nix background should already know that everything is performed in the CLI.
- Understanding Darwin will further improve your knowledge of Mac OS X.
- Darwin is perfect for those old G3 Mac lying around in that closet in the back.
- It's free.
We cannot cover everything in such short article, but of course everyone is welcome to contribute further.
We'll make the following stops :
- Installing Darwin.
- Basic configuration, including network settings.
- Dual boot (Darwin/Mac OS X).
- Configuring and starting a few services (SSH and Apache).
- "IP Masquerading" between 2 NICs.
- Of network security.
- "XWindow and SSH tunneling".
- Configure Apache SSL with a self-signed key.
- Making a boot cd à la KNOPPIX


Recommendations
In this tutorial, we use a G3 BW 350 mHz with 384 MB of RAM and a 120 GB IDE disk.
One partition of about 60GB for Mac OS X Client and another one for Darwin.
That helps us to make a few comparisons.
For the braves out there, if your Mac can boot Mac OS X Client, then you're ready to try Darwin.
The minimum space requirement for Darwin is 1.5GB
For more info/details, please refer to the text file "Darwin 7.0.1 Release Notes".

Darwin is also available for a few x86 configurations. Anyone willing to try ?
(translator adds : it's virtually the same process on both architectures, I haven't picked up any troublesome differences)
You'll require knowledge of the basic *nix commands.
Tip : Would you like to see the text startup messages of Mac OS X ?
If so, just press Option+v after the startup chime.
It's great to show that to a x86 linux fan.

WARNING :
Everything described in this article has been tested on the reference machine. Everything works as advertised.
The following steps all work on Mac OS X Client as well. We haven't tried on the Server edition yet. Anyone willing to give us a free license ?
For security sake, since some serious data loss can happen if you mistype some of the commands described hereafter, it might be wise to:
-Use a dedicated machine if possible
-Otherwise, backup all your data on an external media and disconnect that from the machine
-Give obvious and simple names (regexp : [a-z][0-9]_) to your drives and/or partitions
-Do not attempt any of the following if you are sleep deprived.
WHENEVER YOU HAVE A PROBLEM UNDER DARWIN AND YOU WANT TO GO BACK TO OSX OR 9:

Use an Apple boot cd to select the boot partition from the graphical installer.

Alright then, now, the Darwin cd is in your CD drive.

Please refer to http://davespicks.com/writing/programming/mackeys.html
For instance, keep the mouse button pressed at boot time to eject the disc (This doesn't work on the G3 BW).
Zap the PRAM, eject the CD, reboot and press the "d" key to boot off a disk, "c" to boot from a CD. Whatever Operating System is installed on the first partition of the first disk will load.
To select the startup disk on a new world machine (>1999), keep the option key pressed after you hear the boot chime.
(Thank you Anthony)

Let's get into it, shall we ?
A few references :
Darwin - Open Source chez Apple : http://developer.apple.com/darwin/
Apple - Darwin Releases :  http://www.opensource.apple.com/darwinsource/
OpenDarwin :  http://www.opendarwin.org/
The GNU Darwin distribution :  http://gnu-darwin.sourceforge.net/
The Unofficial Darwin FAQ :  http://www.opendarwin.org/en/faq.php
Okay
- download the Darwin 7.0 (The core of Mac OS X 10.3) iso and burn it.
With Safari, copy-paste this URL and download:
http://www.opensource.apple.com/darwinsource/images/darwin-701.iso.gz
- get the release and installation notes:
With Safari, copy-paste this URL and download:
http://www.opensource.apple.com/darwinsource/images/release-notes-7.0.1.txt
or, in the terminal:
curl "http://www.opensource.apple.com/darwinsource/images/release-notes-7.0.1.txt" -o release-notes-7.0.1.txt
- let's verify the authenticity of the archive we've just downloaded
In the terminal (ok, this is just for the kicks) :
test "`md5 darwin-701.iso.gz | cut -d ' ' -f4`" = "57e9cb37e9595436596b2fa5975d5569" && echo "ok"
If the command line prints "ok" after you hit return, you have got yourself a genuine archive.

- extract the archive
Either with Stuffit Expander,
or in the CLI:
gunzip darwin-701.iso.gz
...which might take a while in either case
- burn the .iso to a blank disc
The easiest way to do so is to use "Disk Utility" in the "Utilities" folder of your Mac OS X install.
Click on the "Burn" icon, select the .iso file, make sure you select the option "Verify burn", insert a blank media in your drive and get yourself a cup of coffee. Make sure the verification process is successful.
Or if you want to burn the disc from the CLI:
hdiutil burn darwin-701.iso
Since we have verified both GUI and CLI burns, is there anybody out there who needs a cheap Darwin 7 CD ? uhmmm ?? ^_^

Booting
- Don't forget to glance at the release notes
- Just to be on the safe side, let's list up our partition scheme. In the terminal, enter:
diskutil list

You'll then be presented with a structure tree for each disk present in your system. It might be a good idea to print that output on paper, you're gonna need it later.
It might look like this: (this is an example)
/dev/disk0
57.4 GB darwin disk0s10
57.4 GB Sharing disk0s12
- Insert your Darwin CD in your CD/DVD drive. Make sure you can boot from a rescue Apple cd from that drive.
- Ok, now reboot, and hold the "c" key at startup.
- Wait a bit
If you get some white text on a black background, everything is happening as it should.
- Answer the few questions as the installer walks you through.
1) Which device would you like to install Darwin onto ?
You will be prompted with a list of disks, Input the number of your choice, for instance 1.
If you're not sure about something, do not hesitate to reboot.
2) Which partition would you like to install into ?
That's when we need the list we printed earlier. Be sure to enter the number corresponding to the correct identifier
e.g. : 0 for /dev/disk0s10
3) Would you like a clean install ?
Choose "yes" if you're courageous
- drool at this wonderful ASCII installer..
Once the install process is completed, you will be asked one more question:
Your choice :
Press 1 to reboot in Darwin.
After rebooting, if you see some more white text on a black background, well, congratulations ! you've successfully installed Darwin !
- At the login prompt, enter "root" and just press enter (empty password) for the password prompt.
root is the super-user, but DO NOT CHANGE ITS PASSWORD JUST YET !
The keyboard mapping is US QWERTY, so you might have to try a few times to find all the keys if you are not on a US keyboard.

So now, if you are working on a non US keyboard, we'll want to set things up for X to use the correct mapping.

- type :
pico .profile
- then input the following text in this text editor:
export PATH=${PATH}:/usr/X11R6/bin
- once you're done, press control-o and then control-x to save the changes and exit.
- let's start the X server:
startx (if you are on a US keyboard)
or
startx -- -keymap yourcountry.keymapping (if you're on a different locale)
Of course you'll have to substitute "yourcountry" with the appropriate value. You can find the full listing of key maps in /System/Library/Keyboards. (just type : ls /System/Library/Keyboards | less )
Once the X server has started, you'll be presented with 3 windows in a lovely green dress up (note from the translator : yucky, gotta love fvwm ...), and the input should be in the correct locale, according to what you chose in the previous step.
Remark : Keymap management is constantly evolving in Mac OS X. There are currently at least 3 variants (X11, Carbon and via XML).
To terminate the X session, just type in the "login" window:
exit
(translator adds : or simply hit CTRL-ALT-BACKSPACE)
Dual boot
Question : How do I go back to Mac OS X ? Without using the install CD of Mac OS X ?
Answer :
bless -mount /Volumes/"Name of the mac OS X/9 partition " -setBoot; reboot
To check the correct partition name in OpenFirmware
bless -info -verbose -bootBlocks
This command line doesn't seem to function:
bless -folder /Volumes/"Name of the mac OS X partition "/System/Library/CoreServices; reboot
A good habit to take, is to type the following instead of reboot:
shutdown -r now (note the -r switch for "reboot")
There is a nice tab-completion system. Try it !
If you'd like to turn off the machine ?
shutdown -h now (note the -h switch for "halt")

Minimum steps
- If you boot Mac OS X, use System Preferences -> Startup Disk to select which partition to boot from, then restart
- login as root
- start the X server.
Create a new user
Taken from:
http://www.opendarwin.org/en/faq.php#newusr
http://developer.apple.com/documentation/P..._section_9.html
http://web.brandeis.edu/pages/view/Bio/Man...acOSX#Example_1
We'll look at the man pages first:
man niutil
In an exterm terminal, type:
niutil -create / /users/darwinuser
If darwinuser is the desired login for your new user, this command has created a new user in the NetInfo database.
In Mac OS X, you can view all these information via the NetInfo Manager app.
niutil -createprop / /users/darwinuser shell /bin/bash
Let's give that new user a shell (sh, csh, zsh, tcsh or bash as you see fit, bash is recommended)

niutil -createprop / /users/darwinuser realname "darwinuser on Darwin"
Let's define the real name of our new user

niutil -createprop / /users/darwinuser uid 1000
In both Darwin and OS X, the uid (user ID) must be higher than 500
niutil -createprop / /users/darwinuser gid 1000
In both Darwin and OS X, the gid (group ID) must be higher than 500
(the terminal keeps track of the previous commands, press the "up" arrow to check it out)
Thanks to cha and all of you who contributed to the list of Mac OS X/Darwin shortcuts:
http://forum.macbidouille.com/index.php?showtopic=76705

niutil -createprop / /users/darwinuser home /Users/darwinuser
Ahhhh feels more like home now...

niutil -createprop / /users/darwinuser _shadow_passwd
We create the password field. we haven't set it yet though

passwd darwinuser
Now we set the password (be careful of the keymap if you do not use a US keyboard)
This user management system described in the Darwin official FAQs is a bit different from OS X, where the passwd is defined.
By the way after a reboot, the password for our user is undefined, so no go...
So, we shall mimic Mac OS X structure :
niutil -createprop / /users/darwinuser passwd

passwd -i netinfo darwinuser
we input the same password
Let's check if it's in order:
niutil -read / /users/darwinuser
Yeah ! works ! so, let's recap :
1) The official docs have errors
2) Darwin inherits NetInfo from NextStep
3) Forget about your Linux or *BSD preconceptions.

niutil -appendprop / /groups/admin users darwinuser
We shall add this user to the admin group. Important step ! otherwise we won't be able to use sudo !
niutil -create / /groups/darwinuser
niutil -destroyprop / /groups/darwinuser gid
niutil -createprop / /groups/darwinuser gid 1000
we now add the darwinuser group with the gid we have set for this user
So, you have your account set, but the home directory has not yet been created:
cd /Users
We enter the Users top directory

We create our directory :
mkdir darwinuser

We set the owner of that folder (uid:gid) :
chown 1000:1000 darwinuser
All Unix gurus must already have realized that there are no adduser command, meaning you have to go through each step or create a script. In any case, the whole mentality for adding users is totally different from the Unix world.
Let's use this new account of ours:
su - darwinuser
pwd
The prompt must have changed to /Users/darwinuser
Are we who we think we are ?:
whoami
darwinuser should be displayed by return Be careful, whoami is different from who am i.
Let's create a file:
touch myfirstfile.txt
Let's list up what's in our directory:
ls -lsa
The myfirstfile.txt file should belong to darwinuser.
Let's make things easier for the next time we log in:
sudo cp /var/root/.profile /Users/darwinuser
sudo chown 1000:1000 /Users/darwinuser/.profile
Let's edit our personal bash shell properties, shall we ?:
pico .profile
In the text editor, let's add these few lines below the "export ..." section:
alias stx='startx -- -keymap yourcountry.keymapping'
alias macx='sudo bless -mount /Volumes/"Name of the OS X/9 partition" -setBoot; sudo shutdown -r now'
Hit ctrl + o, enter, ctrl + x to save and exit .
you can, of course use the text editor of your choice, be it vi or emacs, or joe
So, from now on, when you log as darwinuser, you'll just have to run stx to start the X server in your locale
Let's make sure that we can sudo from the darwinuser account.
DO NOT SKIP THAT STEP!
Let's reboot:
sudo shutdown -r now
Once logged in as darwinuser :
stx
If you see the X server than you're all good.
If you want to switch back to Mac OS X :
macx
N.B.: the /etc/passwd file does exist but, according to the docs, it is only used in single-user mode.

Get the network up and running
Once you popped in a NIC in your mac, 2 interfaces are available in Darwin.
We picked up an el'cheapo NIC that works fine in Mac OS X.
For now, we will concentrate on getting the NIC fetch its settings from DHCP (Dynamic Host Configuration Protocol) or giving it a static IP.
Here is the related documentation:
http://www.opendarwin.org/documentation/network_config.php
The /etc/iftab file doesn't exist by default in Darwin, well, it doesn't exist in Mac OS X either..
So, we are going to create /etc/iftab (we're not talking about /etc/fstab which is a totally different animal) :
sudo pico /etc/iftab
Then we edit the file as follow - we choose a DHCP setup :
lo0 inet 127.0.0.1 netmask 255.0.0.0 up
en0 inet -DHCP-

or, if you choose a static IP setup :
lo0 inet 127.0.0.1 netmask 255.0.0.0 up
en0 inet 192.168.1.101 netmask 255.255.255.0 up
lo1 is the loopback device, i.e. what enables the system to connect back to itself.
en0 is the interface for the actual NIC.
DHCP will fetch an IP address from your DSL router, for instance.
Static IP will set the NIC to an address like 192.168.1/24 on the LAN
ctrl+o then ctrl+x to save the changes
So now we reach the newer parts of Darwin.
The discovery of 2 Macintosh is possible thanks to RendezVous.
Even if 2 machines were set with dynamic IPs, they can find each other according to their .local address
This is very handy for SSH sessions (Secure Shell).
please refer to http://developer.apple.com/macosx/rendezvous/
To set RendezVous up, we need to modify an XML file (eXtensible Markup Language) according to the DTD (Document Type Definition) of Apple's preference files (http://www.apple.com/DTDs/PropertyList-1.0.dtd).
To be on the safe side, we create a backup of the file we are about to modify:

sudo cp /Library/Preferences/SystemConfiguration/preferences.plist /Library/Preferences/SystemConfiguration/preferences.plist.old
(That's a one-liner)

Then we shall proceed:
sudo pico /Library/Preferences/SystemConfiguration/preferences.plist
Right at the end of the file, you'll find a key (<key></key>) contained in an empty dictionary (<dict></dict>).
In Mac OSX, it is already set to some value. You can modify the value as follows :

<key>System</key>
<dict>
 <key>Network</key>
 <dict>
 <key>HostNames</key>
 <dict>
 <key>LocalHostName</key>
 <string>MacDarwin</string>
 </dict>
 </dict>
 <key>System</key>
 <dict>
 <key>ComputerName</key>
 <string>MacDarwin</string>
 <key>ComputerNameEncoding</key>
 <integer>0</integer>
 </dict>
</dict>
 The string "MacDarwin" can be set to any other name (stick to regexp [a-z][A-Z] to avoid headaches)
-  Reboot your machine.
That's the no-brainer way to get the machine to take the changes into account.
- From another mac hooked up to the same network as the Darwin box, you can try :
ping MacDarwin.local
If the packets go through, congratulations ! you're done with that part.

Setting up sshd
Another novelties packed in Darwin 7 is the superserver xinetd. Replaces the good ol' inetd.
Please refer to. http://www.xinetd.org/faq.html
The superserver launches the services only when they are requested.
The config files reside in /etc :
- /etc/xinetd.conf
- /etc/xinetd.d
That last directory contains a file named ssh.
- first we make a backup of the default file:
sudo cp ssh ssh.old
- now we edit the configuration:
sudo pico ssh
The config file is setup in an antic style
- at the disable entry, replace yes by no
- Save and quit
- Reboot
- Try to connect via SSH from another machine
Do not forget to modify the known_hosts file to accommodate your setup
Now you can remove the screen, the keyboard and the mouse, since you can access the machine remotely.
Thanks to all of you that contributed to this on our forums.
Thanks to the MacBidouille team.

Translated by kurisu