ncutil(1) BSD General Commands Manual ncutil(1)
NAME
ncutil -- Darwin Network Configuration Utility 2.1
SYNOPSIS
ncutil [-options] command path [...]
DESCRIPTION
Apple provides a network setup control panel with Mac OS X, but the open-source Darwin project has no such utility. While it is possible to
use standard UNIX flat files to configure the network settings under Darwin, that OS explicitly uses the SystemConfiguration framework to
maintain a dynamic, pervasive tree of configurational parameters for the networking component of the kernel. The Apple network control panel
for Mac OS X uses the SystemConfiguration APIs to modify that tree; ncutil was designed expressly to mimic the Mac OS X network control panel
but using a command line interface.
A SERVICE is a complete set of parameters that configure a single network interface: an IP address, gateway address, DNS server addresses,
proxy parameters, etc form a complete configuration of an ethernet card, for instance. Services exist for ethernet, modem, FireWire, and
wireless ports. Services are grouped into LOCATIONS. A location contains one or more services, ranked in order of precidence: as ports come
up or go down, alternate services may be configured in an attempt to keep network service uninterrupted.
ncutil behaves much like Apple's NetInfo command line utility, niutil. Commands that modify the parameter tree require that the user have
root privileges.
OPTIONS
-activate
Any user-modification of the SystemConfiguration preferences tree by means of the above commands will not be noticed by the runtime
system immediately. The user can force the runtime system to make note of his/her changes by specifying this option
-prefpath path
Forces ncutil to work with a preference tree located in an alternate file location. The default is /Library/Preferences/SystemCon-
figuration/preferences.xml. Alternately, the 'ncutil_prefpath' environment variable may be used.
Note that when you use this command-line option ALL properties in the preference tree are unlocked -- including MAC addresses.
-stdin Specifies that a series of commands will be taken, one per line, from standard input. Each time ncutil is invoked there is a small
amount of overhead in opening a connection to the configd daemon, reading command tables from the resource bundle, and pre-allocat-
ing strings. Using this flag turns ncutil into a pseudo-shell and avoids the additional overhead incurred when invoking ncutil once
per command. Note that if no command is supplied on the command line, the program by defaults enters this mode. Incoming text may
make use of the C line-continuation character ( to concatenate lines.
-debug Engages additional output during program execution, mainly of the debugging persuasion
COMMANDS
help Displays a help screen with a summary of commands and options.
info Displays information such as build date/time and program version.
listports
Displays the list of qualified network ports gleaned from IOKit.
createloc name
Creates a new location which contains a service for each available network port. The services are ordered according to the preci-
dence established by Apple's control panel.
cloneloc original [clone]
Makes an exact duplicate of the original location. If no [clone] name is specified then the program will create a unique name by
appending the word "copy" to the name of the location which is being cloned.
destroyloc name
Deletes an existing location from the tree. All services associated with the location are removed.
setprop path propkey value1 [value2 ...]
Given a property tag propkey and a path within the preferences tree path the program will attempt to associate the new value (or
values) with that property. The exact nature of value depends upon the property being set: strings, numbers, IP addresses, and
arrays are all possible data structures within the tree. See the User's Manual for more information of paths, properties, and indi-
vidual property's values.
destroyprop path propkey1 [propkey2 ...]
Given a property tag propkey and a path within the preferences tree path the program will attempt to remove the specified property
(or properties).
addval path propkey value1 [value2 ...]
Given a property tag propkey and a path within the preferences tree path the program will attempt to add a new value (or values) to
the property at the specified path. This command will only work on properties that explicitly can accept more than one value (see
the User's Manual).
destroyval path propkey value1 [value2 ...]
Given a property tag propkey and a path within the preferences tree path the program will attempt to remove an existing value (or
values) from the property at the specified path. This command will only work on properties that explicitly can accept more than one
value (see the User's Manual).
read path
Displays the properties and their values that exist at the preference tree path path given by the user.
readprop path propkey
Given a property tag propkey and a path within the preferences tree path the program will attempt to display only the value(s) asso-
ciated with that property. infinityGiven a property tag propkey and a path within the preferences tree path the program will
attempt to display value(s) associated with that property at particular array indices. This command will only work on properties
that explicitly can accept more than one value (see the User's Manual).
list path
Attempts to list the sub-paths associated with the specified path in the preferences tree. Sub-paths of the root path (/) are loca-
tions; sub-paths of a location are services; sub-paths of a service are configuration entities. See the User's Manual for more
information.
enable | disable path
Configuration entities and services can be marked as enabled or disabled. If disabled, the SystemConfiguration will not attempt to
use that item when configuring a network port. Disabling a service, for example, implies that the SystemConfiguration runtime sys-
tem will not even attempt to use that service at all. On a machine where you want a network setup that does not make use of the
modem, you disable the modem by disabling its service in a location.
propsummary path
Displays a table summarzing all of the properties available for the given path , the type of data associated with each property, and
(for enumerations) the possible values which the property may take.
exit Causes the program to exit if it is running in pseudo-shell mode (amounts to a NOOP when issued from the command line itself). An
end-of-file character will trigger this action; "quit" is a synonym for this command.
All of the commands and options are also summarized by giving ncutil on the command line with the 'help' command.
ENVIRONMENT
ncutil_prefpath
If many calls to ncutil will be made using the same alternate preference tree file path, then you may wish to consider setting this
environment variable. The program will use the content of this variable as the path to the preference file. If this environment
variable is not set the SystemConfiguration framework's default preference file will be used.
Note that when you set this variable ALL properties in the preference tree are unlocked -- including MAC addresses.
RETURN VALUES
At the most basic level, any non-zero return value represents an error. For scripting, etc, the program has a wide variety of error codes
that are returned and can be found in NCUtilFoundationErrors.h and NCApplication.h. Error messages are displayed accordingly during program
execution, as well.
FRAMEWORKS
Starting with version 2.0 of the ncutil program a large amount of the core code for working with the SystemConfiguration preference store has
been bundled into a framework which other programmers may find useful. The NCUtilFoundation framework must be installed in one of the stan-
dard locations for frameworks: /Library/Frameworks or ~/Library/Frameworks. It is not suggested that you install the framework in /Sys-
tem/Library/Frameworks.
SEE ALSO
niutil(1)
HISTORY
2.0 Original release, November 2003.
2.0.2 Minor bug fixes, updated install script for the precompiled binaries [09.Dec.2003]
2.0.3 Updated to include mail and autoconf tags in Proxies entities [09.Jan.2004]
2.1 Revamped text handling to better accomodate non-ASCII environments; much more intelligent preference path handling (including tilde-
expansion); revised for non-negative error values [04.May.2004]
AUTHORS
The ncutil program is written, documented, and supported by Jeffrey Frey. Please direct all comments, suggestions, and bugs to him via email
at frey@chem.udel.edu. The ncutil website can be found at:
http://deaddog.duch.udel.edu/~frey/darwin/ncutil/
Darwin May 31, 2019 Darwin