Email: [freyguy77@gmail.com]
Office: [302.831.6034]
Dr. Jeffrey T. Frey

 Frey:/ Programming Research Recipes Literature 
 Frey:/programming/ Clustering Dropbox2 MacNetworkInfo NetworkingAdditions UDCarillonServices ncutil TubeGen stigma 
 Frey:/programming/ncutil/ User's Guide (v3) 
About ncutil... June 2, 2005
Within the heart of the Darwin OS is a beautiful piece of OS engineering called the SystemConfiguration framework, which among other things implements:
  • Dynamic network configuration: the user can modify parameters on-the-fly and the changes are noted without a restart of the entire OS.
  • Configuration sets: the user can create multiple sets of parameters, termed "locations," which may be activated dynamically
  • Centrally-defined, XML storage form: all parameters are stored in a central plist file; the multitude of files in /etc need not be modified
The UNIX-esque method of editing text files with strict, non-uniform text formats is thus replaced with a more standardized method of storing and managing the network configuration.

While this sounds wonderful, there was a key piece of software missing from the picture: a program which allowed the user to actually enter the information and parameters! As a result, old-time configuration methods -- editing those text files in /etc -- have proliferated and presented a general air of disarray in the Darwin community when it comes to network setup under the OS.

The ncutil project is an open source initiative to provide that missing piece of software and is provided to you under the BSD licensing scheme.
» Email me for access to the CVS tree
ncutil: update for Mac OS X 10.5 January 26, 2008
Ready to do some beta testing, folks? An early beta of ncutil 3.3 is ready for you! The package includes variants for pure Darwin versus full Mac OS X, OS releases 10.4 and 10.5.

Starting with this version of ncutil I've dropped the framework+utility separation of functionality. The only real loss in moving toward a single, self-contained executable for ncutil is that as of now I've stripped all string localization from the code. But then I don't think anyone had bothered to localize ncutil anyway, so it's not much of a loss I suppose!

File Description
 ncutil-3.3-beta.tar.bz
ncutil 3.3.18b (beta) package (10.4/10.5) [updated 2008-03-03]


Within the next week I should finally get my hands on a copy of Mac OS X 10.5. There will assuredly be changes to the SystemConfiguration framework — new properties, new configuration entities, etc.

The NCTree class seems to be behaving problematically, so I will be doing some revisions to it; this will (hopefully!) fix the issues some of you were having with segfaults and bus errors when creating new locations, etc.

Another area where I've done a bit of work is the built-in CLI. Previous versions of ncutil used a simplistic readline-esque function of my own crafting; as such, it lacked a command history and other expected features of a modern CLI prompt. The next release of ncutil uses the readline library to include:
  • a command history
  • readline inline editing
In addition, I've already implemented completion of ncutil commands; if time permits I'll add path completion, as well.

My hope is that my changes, plus any bug fixes to the evolving SystemConfiguration APIs that Apple includes in 10.5, will bring ncutil back to being a reliable, indispensible tool for CLI-based network configuration on Mac OS X and Darwin.

Cheers,
Jeff Frey
» Email me for info
ncutil 3 September 20, 2007
NOTE! The ncutil312U_install.pkg has been updated so that it will install on systems running 10.4.10; the script which checks for OS release compatibility wasn't prepared to deal with two-digit minor release numbers!

Mac OS X 10.4 includes several interesting new additions to the SystemConfiguration framework that should make it much easier for other programs (e.g. ncutil) to add/remove locations and services. I've evaluated version 2 of ncutil and NCUtilFoundation and have decided to slim-down the code base and make it more straight-forward while merging into it the new capabilities afforded by the API changes in SystemConfiguration.

3.1.1 included a fix for a nasty little bug that was fun to track down. The property lists in the NCUtilFoundation framework were being sorted by a function that used case-insensitive string comparisons, while the "lookup" routine was case-sensitive. Since the lookup routine used a binary search, the search would fail to find the "account-name" property, for example, because of the differing case-sensitivities. Thanks to Ian Vännman for notifying me of the problem that led to this bug track-down.

Version 3.1.2 fixes a glitch that existed when removing locations: the services for a location were not being removed from the preference store. This update also attempts to resolve some weird issues on Intel-based Macs. The Mac OS X installer package also now checks to be sure that the user is not attempting to install ncutil 3.1.2 on a pre-10.4 machine (ncutil 3.x requires Mac OS X 10.4 / Darwin 8).

A small bug fix in the NCUtilFoundation framework has been rolled into the 3.1.2 installers. There is also a Mac OS X installer package to update to version 3.1.3 of the framework.

File Description
 ncutil313U_install.tgz
ncutil 3.1.3 (Universal Binary) for Darwin (updated 05/26/2009 to remove Foundation and AppKit dependency)
 ncutil312U_install.pkg.zip
ncutil 3.1.2 (Universal Binary) for MacOS X 10.4 (updated 09/20/2007)
 NCUtilFoundation313U_install.pkg.zip
NCUtilFoundation 3.1.3 (Universal Binary) for Mac OS X 10.4
 ncutil312U_install.tgz
ncutil 3.1.2 (Universal Binary) for Darwin (updated 09/13/2006)
 ncutil311U_install.tgz
ncutil 3.1.1 (Universal Binary) for Darwin (updated 05/28/2006)
 ncutil311U_install.pkg.zip
ncutil 3.1.1 (Universal Binary) for MacOS X 10.4 (updated 04/17/2006)
 ncutil30b1U_install.tgz
ncutil 3.0b1 (Universal Binary) for Darwin
 ncutil30b1_install.pkg.zip
ncutil 3.0b1 (ppc) for MacOS X 10.4
 index.html
ncutil 3 User's Guide (view online)
 ncutil31-UsersGuide.zip
ncutil 3 User's Guide (downloadable)
» Email info/feedback
ncutil 2.1.2 June 2, 2005
I've been lucky enough to have several ncutil users provide me with copies of the installer package and pages from the old web site, so I've not had too tough a time getting things back in order in this spot of my site. I'm reproducing the basic information that was on the old site for version 2 of ncutil here (the link to download the installer is below):

 Better Path Handling
  In all its releases ncutil has featured a user-level directory-type layout of the SystemConfiguration database. Complicated paths like /Sets/1/Ethernet contain no information regarding to which location or service they apply. While the design employed for this feature in previous versions worked most of the time, it required all location names and network service names to be devoid of the / character. This part of the codebase was also very memory-hungry.

Version 2.0 of ncutil included a brand new implementation of the directory mapping. Memory usage has been cut beyond simply "dramatic" improvement, and the / character no longer offers the problems seen in previous builds. Anyone familiar with regular expressions and sed will recognize the fix: path components may be delimited using any non-numerical character that is not repeated in the path components themselves. For instance, :Office/Classroom:Built-in Ethernet:IPv4 is a valid path specification.

In addition, when using ncutil 2.1.2 in shell mode the ! character functions as a reference to the path which was used in the previous command:
      read "/Office/Built-in Ethernet/IPv4"
       :
      setprop ! ip-address 192.0.0.1
 
 Improved Objective-C Core
  While Mac OS X offers the programmer a glorious set of frameworks to use when crafting new code, bare-bones Darwin only offers the CoreFoundation framework. Older versions of ncutil used a very minimal set of my own Objective-C classes, and as a result a majority of the code was just straight C. Version 2.0 makes much more extensive use of Objective-C classes. All of this makes the code better-written and more easily maintained and extended in the future.
 
 Introducing the NCUtilFoundation Framework
  There are literally hundreds of hours of research, programming, debugging, and documenting that went into creating the core set of classes for this version of ncutil. Some of this includes:
  • Improvements to the class cluster which finds network ports
  • Addition of a class to use IOKit to find the media sub-types and options available for network interfaces
  • A class cluster which provides a high-level, directory-like interface layer between userland code and the SystemConfiguration preference store
  • Convenience functions to create SystemConfiguration dictionary paths, to retrieve the current location name, to set the current location name
When taken as a whole, the underpinnings of my ncutil program could truly benefit other programmers who need to access the SystemConfiguration preference store and would like to do so in a simple manner. What would be easier than:
      NCDirectory*     preferenceTree = [NCDirectory directoryTree];
      
      if (preferenceTree)
        [preferenceTree cloneLocation:CFSTR("Home") CloneName:CFSTR("Home Too")];
Starting with version 2.0 of ncutil, much of the core code that I've written to make it easier to work with the SystemConfiguration preference store is housed in the NCUtilFoundation framework. The framework is sprinkled very liberally with HeaderDoc comments to promote its use by other programmers.
 
 Pseudo-Shell Mode
  There's a bit of overhead involved each time you run the ncutil exectable: a connection to the configd daemon must be made and a few of the classes must immediately initialize themselves. On today's faster and faster Macs and versions of Mac OS X, this doesn't amount to too much overhead, but it seems silly that so much effort be expended to perform a sequence of commands that could just as easily be streamed through a single invocation of ncutil.

Starting in version 2.0, if no command is specified on the command-line, then the program will run in a shell-like mode which will accept a sequence of commands from standard input. This not only allows the user to work interactively, but also allows "scripts" to be written.
 
 Updated for Mac OS X 10.3
  The last delays in releasing this new version of ncutil came exclusively on the heels of the release of Panther. I've added most of the new features which are boasted by the new OS X network control panel:
  • Support for IPv6 configuration
  • Support for AirPort configuration
  • Support for Bluetooth modem configuration
  • Support for Ethernet hardware options configuration
    • Media sub-type (100baseTX, autoselect, 10baseT/UTP, etc)
    • Maximum transmit unit size
    • half-/full-duplex
  • Support for IP-over-Firewire configuration
 
 New Features, Too
 
  • Clone an existing location.
  • Forget what properties can be assigned to a PPP entity? View a table of all configurable properties for any path.
  • Pseudo-shell mode to execute multiple commands or scripts.
  • Binary (entered as hexidecimal text) password support.
 
 Building the Program
  Since we are post-10.3 now, the project was developed exclusively in Apple's XCode IDE, and the CVS archive contains the project file for building ncutil under XCode. Since this utility is meant to help out on the Darwin end of the OS, though, the source also contains a Makefile so that the project may be build on the command line under Darwin via make.

Compatibility-wise, I have built and tested ncutil 2.1.2 under OpenDarwin 6.6.2 and Mac OS X 10.3 and in both cases the program works properly. Note that the SystemConfiguration framework differs slightly between late 10.2 (corresponding to OpenDarwin 6.6.2) and 10.3 (Darwin 7), so there is a bit of magic behind the scenes when using the Makefiles under OpenDarwin 6.6.2 (and Mac OS X 10.2).

File Description
 ncutil-install-212.tgz
ncutil 2.1.2 installer package (10.1 - 10.4)