ncutil(1) BSD General Commands Manual ncutil(1)NAMEncutil — Darwin Network Configuration Utility 2.1
SYNOPSISncutil [-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 sys‐
tem 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/Prefer‐
ences/SystemConfiguration/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-allocating 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-continua‐
tion 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 ver‐
sion.
listports
Displays the list of qualified network ports gleaned from IOKit.
createloc name
Creates a new location which contains a service for each avail‐
able network port. The services are ordered according to the
precidence 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 asso‐
ciated 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 individual 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 prop‐
erty (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 val‐
ues) 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 com‐
mand 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 pref‐
erence 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)
associated with that property. ∞Given 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 prop‐
erties 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 locations; 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 run‐
time system 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 envi‐
ronment 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 pref‐
erence 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 NCApplica‐
tion.h. Error messages are displayed accordingly during program execu‐
tion, 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 standard
locations for frameworks: /Library/Frameworks or ~/Library/Frameworks.
It is not suggested that you install the framework in /Sys‐
tem/Library/Frameworks.
SEE ALSOniutil(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 environ‐
ments; 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 April 19, 2024 Darwin
