ncutil 3

Central to ncutil's treatment of network preferences is the idea of a directory tree. The tree has a root node in which the rest of the directories are embedded: at the root level of ncutil's directory tree are a network interface template subdirectory and a subdirectory for each network set (called a location herein):

	Listing 1: The root directory
	[0 ]$ ls dr- 1 Interfaces Directory drw 7 Office Location drw 45 On the Road Location

The first three characters of each line are just like the permissions flags in a UNIX file listing. The 'd' character indicates that the item is a directory, and not a property associated with a directory (properties display a '-' character instead). The 'r' and 'w' characters indicate read and write permissions on the item; actually, everything is readable in ncutil. In Listing 1, the network interface template directory (Interfaces) is locked and cannot be modified by the user.

The next two columns list the directory ID, a numerical value assigned dynamically to each node of the directory tree, and the directory name. The directory IDs may change from run to run of ncutil as locations and services are added or removed. Likewise, if you rename a location or a service, the directory name will change, as well. You may use a directory ID in place of a directory path in any of ncutil's commands. A directory path is just like a UNIX file path: a hierarchy of subdirectory names are joined by a separator string. By default, ncutil uses the '/' character to separate path components. Thus, the network interface template directory could be referenced either by ID (1) or by path (/Interfaces). Alternatively, if we were using ':::' as our path separator string, the path would be :::Interfaces. The root directory itself has an ID of 0 (zero) and a path consisting of the path separator string alone (/ for the default and ::: for the alternative separator string we've mentioned). Special characters (single- and double-quotes, spaces) can be included in the path using an escape sequence: prefix the character with a '\' character. For example, the On the Road location path could be entered quoted as "/On the Road" or escaped as /On\ the\ Road.

The program has a current directory (also called a working directory) that some of its commands will consult when no explicit directory is specified: the ls command shown in Listing 1 has no directory argument, and thus applies to the current directory (which by default happens to be the root directory). Another useful aspect of the current directory is that it allows the user to enter relative paths rather than typing full, canonical path names. To examine some network service directories in the Office location, for example:

	Listing 2: Changing the current directory
	[0 ]$ read /Office/Built-in\ Ethernet -rw inactive = true -rw name = Built-in Ethernet [0 ]$ read /Office/Built-in\ FireWire -rw name = Built-in FireWire [0 ]$ cd /Office [7 Office]$ read Built-in\ Ethernet -rw inactive = true -rw name = Built-in Ethernet [7 Office]$ read Built-in\ FireWire -rw name = Built-in FireWire

Of course, as paths get longer the current directory feature becomes more and more useful. The ncutil prompt will change to reflect the current directory, and paths meant to be relative to it do NOT begin with the separator string. You can display the current directory using the pwd command.

Let's examine some of the directory node types that appear in an ncutil directory tree.

---

The Network Interface Templates Directory

Each and every network service is constructed around a single network interface. In order for ncutil to create network services, it is important that the user be able to communicate just what network interface is to be used by the new service. To this end, the first directory node to be found in the root directory is the network interface templates directory.

	Listing 3: The network interface templates directory
	[0 ]$ ls 1 dr- 2 Internal Modem Interface dr- 3 Bluetooth Interface dr- 4 Built-in Ethernet Interface dr- 5 Built-in FireWire Interface dr- 6 AirPort Interface

For the computer on which ncutil was run (my PowerBook G4) we can see five different pieces of networking hardware. Notice that each of these items is locked -- the user should NOT be able to modify templates, of course! Notice, as well, that each network interface is a directory (signified by the 'd' in the first column). Network interfaces may have higher-level interfaces layered on top of them: the Internal Modem does not inherently transmit TCP/IP packets, it requires a PPP interface to be installed on top of it for such usage (luckily for you, ncutil knows this and automatically creates modem-based services with a PPP interface installed atop the hardware interface).

Each network interface template also includes some basic information about the hardware involved. Listing 4 shows the properties associated with the Built-in Ethernet interface.

	Listing 4: Properties of the Built-in Ethernet interface template
	[0 ]$ read 4 -r- bsd-device = en0 -r- layerable-interfaces = { PPP } -r- mac-address = XX:XX:XX:XX:XX:XX

Each property has a property key that identifies its value. Here we see the BSD device name (property key of 'bsd-device') and hardware-level address (property key 'mac-address') associated with the device that Mac OS X calls the Built-in Ethernet port. Also displayed are the interfaces that can be layered on top of the Built-in Ethernet network interface: for a network service created to use this network interface, pushing a PPP interface atop its ethernet interface would produce a PPP over Ethernet (or PPPoE) service.

---

A Location Directory

Each location directory consists of a location-wide NetInfo configuration item and the network services defined for that location. The NetInfo object can be used to setup how NetInfo should locate a parent server and to what NetInfo domain it should bind itself. Normally, you would use the Directory Access application to configure this on Mac OS X clients.

Intrinsic to the way network services are used to configure hardware is the idea of a service order. For example, I may have two network services defined in my Office location: one that requests a DHCP IPv4 address and one that uses a statically-allocated IPv4 address. The service order for my Office location dictates which of these network services gets the first crack at getting my ethernet port transmitting.

	Listing 5: Properties of the Office location directory
	[0 ]$ read 7 -rw name = Office -rw service-order = { Built-in Ethernet DHCP Built-in FireWire Internal Modem Bluetooth AirPort }

I could rename this location by resetting the name property; I can modify the ordering of network services by modifying the value of the service-order property. Each network service should be named uniquely within a location.

---

A Network Service Directory

A network service directory contains a network interface stack (one or more interface objects, one atop another in a series of subdirectories) and protocol configurational entities.

	Listing 6: The Built-in Ethernet service for the Office location
	[0 ]$ list 9 drw 10 Built-in Ethernet Interface drw 11 Proxies Protocol drw 12 AppleTalk Protocol drw 13 IPv4 Protocol drw 14 DNS Protocol drw 15 IPv6 Protocol

A network service directory may also have two properties associated with it.

	Listing 7: Properties of the Office location directory
	[0 ]$ read 9 -rw inactive = true -rw name = Built-in Ethernet

The inactive property indicates that as the configd process attempts to configure network hardware using the Office location, it should skip the Built-in Ethernet service without even attempting to utilize it. The enable and disable commands in ncutil can be used to make services active or inactive; to allow configd to use the Built-in Ethernet network service, we would want to enable 9 as far as commands go. Or, using a path rather than an ID: enable "/Office/Built-in Ethernet".

Previous Chapter

Table of Contents

Next Chapter