Chapter 2. Administration

Table of Contents

Configuring
How do I manage users and groups?
How do I configure networking?
How do I set the timezone?
How do I configure power management?
What is the hostconfig file?
What is NetInfo and how do I use it?
How do I change the order that lookupd resolves things?
How do I make DNS sortlist work?
How do i setup NFS configuration in NetInfo?
Where are all the startup scripts?
What is a Kernel Extension (KEXT)? How do I use it?
How do I control the mounting of filesystems? Where are they mounted?
How do I enable HFS+ journalling from the command line?
In MacOS X, how do I get something other than the loginwindow to start on boot?
Ports and packages
Are binary packages for OpenDarwin available?
How do I access the available packages?
Which packaging format does OpenDarwin use?
Where can I get third-party software for Darwin, and is there anything like the FreeBSD Ports Collection?
General usage
Where is ldd?
How do I see what devices are on my system?
What is synthfs?
How are drive numbers determined?
Can I mount my Darwin filesystems under Linux?
Troubleshooting
What is Open Firmware and how do I enter it?
I've messed up my Open Firmware settings, how do I fix it?
How do I make Darwin display information while booting?
How do I boot into single user mode?
What is this "unable to bind to parent" error?
I get an 'AllocateKernelMemory' error and the system freezes. How do I fix this?
When I try to manually mount a disk partition, why do I get an "operation not supported" error?
Why is it telling me the file already exists, when clearly it doesn't?
I can't get X working on my G3 Powerbook!
After installing and rebooting, all I get is a "Still waiting for root device" message over and over. How can I fix it?

Configuring

How do I manage users and groups?

Out of the box on Darwin, users and groups are managed by NetInfo, not the so-called "flat files" in /etc.

Creating a user

This creates an entry in the database for a user called 'bbraun':

niutil -create / /users/bbraun
        

This sets the shell for the user:

niutil -createprop / /users/bbraun shell /bin/tcsh
        

This sets the "Real Name" of the user:

niutil -createprop / /users/bbraun realname "Rob Braun"
        

This sets the uid of the user:

niutil -createprop / /users/bbraun uid 1000
        

This sets the gid of the user:

niutil -createprop / /users/bbraun gid 1000
        

This sets the home directory of the user:

niutil -createprop / /users/bbraun home /Users/bbraun
        

This creates an entry in the directory for the password, but does not set it:

niutil -createprop / /users/bbraun _shadow_password
        

And finally you have to set the user's password:

passwd bbraun
        

There are also various third-party adduser scripts available for Darwin.

Adding a user to a group

This adds the user 'bbraun' to the group 'wheel':

niutil -appendprop / /groups/wheel users bbraun
        

For more information, it is suggested that you look at the existing users and groups with niutil or nicl.

How do I configure networking?

Please read http://www.opendarwin.org/en/articles/network_config/.

How do I set the timezone?

Darwin's descriptions of timezones live in /usr/share/zoneinfo. If you live in the US, look under the US directory there. To tell Darwin which of this timezones your computer is actually in, create asymbolic link from one of these files to the file /etc/localtime. For instance, my Darwin machine is in the Mountain timezone, so I would do:

rm -f /etc/localtime
ln -s /usr/share/zoneinfo/US/Mountain /etc/localtime

I first did the rm to make sure there wasn't already an existing timezone file. If you do an ls -l on the file, you can tell what it is currently pointing at.

How do I configure power management?

Power management is configured via the file /Library/Preferences/SystemConfiguration/com.apple.PowerManagement.plist and the utility pmset. See the pmset(1) man-page for more information.

What is the hostconfig file?

The hostconfig file in /etc is a configuration file read by the startup scripts to figure out whether certain services should be turned on, and how to get certain information when configuring the system. The # is the comment character. Anything after it on the same line will be ignored.

Usually, the first line of hostconfig is for configuring the system's hostname (the HOSTNAME variable). This variable can be two values: either -AUTOMATIC- to have the hostname dynamically configured via it's IP address, or it can be a string that is the machine's hostname. Here are examples of the possible configurations:

# Automatically determine the hostname via reverse lookup of IP
HOSTNAME=-AUTOMATIC-
# Set the hostname to "looks-like-a-vacuum-cleaner"
HOSTNAME=looks-like-a-vacuum-cleaner
# Set the hostname to "darwin"
HOSTNAME=darwin
      

The hostname can be just about anything you want, however it is usually good if the machine's hostname matches the hostname in DNS.

The next variable in the file is the ROUTER variable. This variable sets what your default router will be. This can be set to 3 types of values: -AUTOMATIC- to have the default router configured via DHCP or BootP, the IP address of your default router, or the hostname of your default router. The last form of the ROUTER is discouraged because it can fail depending on your configuration. For instance, if you're using DNS and your nameserver is off your local subnet, then you'll need your default route set before you can resolve the hostname of your default router. Here are some configuration examples:

# Have the default router set by DHCP
ROUTER=-AUTOMATIC-
# Have the default route set to the IP of 192.168.1.1
ROUTER=192.168.1.1
# Have the default route set to router (this better be
# resolvable!)
ROUTER=router
      

The rest of the file contains variables taht are used for setting up services on the system. The settings for these can vary, depending on the service, but in general they can be set to -NO- if you don't want the service started on bootup, or it can be set to -YES- if you do want the service started on bootup. For instance, if you wanted a mail server (sendmail) to run when you booted your machine, you can set MAILSERVER=-YES-.

To figure out exactly what variable does what, and what the potential values are, you'll need to look through the startup scripts in /System/Library/StartupItems.

What is NetInfo and how do I use it?

NetInfo is Darwin's built-in directory system. It stores administrative information in a heirarchical database of nodes called directories. It is used instead of flat files for a lot of configuration, such as user accounts.

To just view the current databases in NetInfo you can use the niutil -list . / command and it will return a list of databases:

1        machines
5        aliases
10       groups
24       users
41       networks
46       protocols
57       rpcs
87       services
140      mounts
141      printers
142      locations
143      fax_modems
      

Some of these have "subdirectories", such as locations. To view these subdirectories, tell niutil to look under /locations (since we just looked under /):

[darwin:xnu/bsd/conf] root# niutil -list . /locations
146      renderers
154      resolver
      

To actually view what is in a field, you can use niutil's -read option:

[darwin:xnu/bsd/conf] root# niutil -read . /locations/resolver
name: resolver
nameserver: 198.11.19.15
domain: synack.net
      

If you'd prefer an interactive session for manipulating the directory, you could use the nicl tool.

You can also use the nidump utility to have certain NetInfo databases displayed in the form of the corresponding UNIX file. For example, to spit out a reasonable looking resolv.conf file you can use:

[darwin:xnu/bsd/conf] root# nidump resolv.conf . /locations/resolver
domain synack.net
nameserver 198.11.19.15
      

There is also the niload utility that will take files in a traditional unix format (such as resolv.conf or passwd) and insert the information contained in the file info the NetInfo database. For example,

niload passwd . < /etc/passwd
        

would load all of the entries in the /etc/passwd into the NetInfo database. However, niload only understands the following formats: aliases, bootparams, bootptab, exports, fstab, group, hosts, networks, passwd, printcap, protocols, rpc and services.

For more information, see the NetInfo HOWTO and the manpages for the utilities introduced above.

How do I change the order that lookupd resolves things?

When you query lookupd for accounts or hosts, it can be configured to look in it's cache, local files, NetInfo or NIS in any order. To configure this functionality, use the following command:

# nicl / 
/ > create /locations/lookupd LookupOrder "AgentList"
        

Where AgentList can be one of the following:

  • CacheAgent - looks up information in lookupd's cache

  • FFAgent - looks up information in flat files (/etc/hosts, etc.)

  • NIAgent - looks up information in NetInfo

  • DNSAgent - looks up information in DNS

  • NISAgent - looks up information in NIS

  • DSAgent - looks up information in Open Directory (Directory Services)

See the lookupd(8) manpage for more information on configuring the behaviour of lookupd.

How do I make DNS sortlist work?

The DNS sortlist and search keywords should work under Darwin just fine. If you're using NetInfo for your DNS configuration, you can create a sortlist entry under /locations/resolver.

nicl . -create /locations/resolver sortlist list-of-args
      

Likewise, you can use the searchkeyword:

nicl . -create /locations/resolver search list-of-domains
      

How do i setup NFS configuration in NetInfo?

Mark Majka, the NetInfo God, has provided us with this explaination for the usetting up the NFS information inside NetInfo:

At present, there is no utility for loading exports from an /etc/exports format file into NetInfo. This is a known bug. Until that's fixed, NFS exports may be created using the nicl command (a "NetInfo Command Line" utility). Say you want to export /foobar:

nicl . -create /exports/mumble clients mygroup
nicl . -create /exports/mumble opts alldirs maproot=nobody
nicl . -create /exports/mumble name /foobar
      

This temporarily creates a NetInfo directory named mumble, later resetting the value of the name (mumble) to /foobar. This might seem a bit strange, but both NetInfo and the filesystem use "/" characters as delimiters, so using a temporary name is easier than trying to create a name that includes embeded slash characters.

Note that the export options (like alldirs) do not have a leading "-" character. If you want to export to everyone (the example above exports to the mygroup netgroup), you can omit the line that creates a "clients" attribute, or create it with no value.

An alternative way to do this is to use nicl's "interactive" mode:

nicl .
/ > create /exports/mumble
/ > cd /exports
/exports > ls
174        mumble
/exports > cd 174
/exports/mumble > create . clients mygroup
/exports/mumble > create . opts alldirs maproot=nobody
/exports/mumble > create . name /foobar
/exports//foobar > cat .
name: /foobar
clients: mygroup
opts: alldirs maproot=nobody
/exports//foobar > quit
        

Where are all the startup scripts?

Please read the StartupItems HOWTO.

Also note that as of Darwin 7.x some daemons are launched by registering with the bootstrap environment. See the Mac OS X System Startup documentation for more information. Note however that startup items are NOT deprecated, that is a mistake in the documentation.

What is a Kernel Extension (KEXT)? How do I use it?

A Kernel Extension is code that can be inserted into the Kernel dynamically. Kernel Extensions are often abbreviated to KEXT and are similar in concept to Linux's Kernel Loadable Modules. KEXTs are implemented as a "Bundle", and must contain an Info.plist, Kernel Modules (the actual code that is linked into the running kernel) and a KEXT can, optionally, contain various resources used by the Extension such as libraries for access the kext from user space. The Info.plist file describes the extension and contains various settings or other information regarding the KEXT.

You can manually manipulate Kernel Modules using the kextload, kextunload and kextstat commands, all of which have man pages. Kernel Extensions are automatically loaded and unloaded when they are placed in the /System/Library/Extensions directory. In that directory you will see System.kext and ppp.kext. If you add a KEXT to that directory, be sure to execute:

# sudo touch /System/Library/Extensions
        

This will change the modification date and time so that the kernel extension cache is rebuilt on the next boot.

How do I control the mounting of filesystems? Where are they mounted?

IOKit automatically detects all fixed and removable media, and kicks off the probing process by diskarbitrationd. HFS, HFS+ and Darwin UFS volumes all have a header before the filesystem begins. Within this header contains the name of the filesystem, and this name determines where the filesystem gets mounted. After determining the correct filesystem, diskarbitrationd creates a unique mountpoint in /Volumes and mounts the volume there. For example, Warp Drive gets mounted under /Volumes/Warp Drive

fstab can be used to fine-tune the mounting process. For example, you may want to mount your large FireWire drive as /mp3 instead of /Volumes/mp3. Filesystems can be specified either using their volume lable or the UUID value that is unique for each formatted filesystem. See the diskarbitrationd(8) manpage for examples of how to do this.

How do I enable HFS+ journalling from the command line?

As root, execute:

# /System/Library/Filesystems/hfs.fs/hfs.util -J /
      

This must be executed on an HFS+ filesystem. Attempting to turn on HFS+ journaling on a UFS partition will fail.

In MacOS X, how do I get something other than the loginwindow to start on boot?

Normally when you boot Mac OS X, the WindowServer and loginwindow will automatically start. It is, however, possible to modify this behaviour.

Prior to Mac OS X v10.3, both the WindowServer and loginwindow were launched as a result of being specified in /etc/ttys. Just edit that file.

Since Mac OS X v10.3, only loginwindow is launched by /etc/ttys. The WindowServer is launched by mach_init whenever an application tries to initiate a connection to it. You will have to either delete or move out of the way /etc/mach_init.d/WindowServer.plist to prevent this from happening.

You may also like to enable verbose booting, as otherwise you will not get any progress feedback from SystemStarter.