Unix/Linux Go Back    


OpenDarwin 7.2.1 - man page for ncutil (opendarwin section 1)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 con-
     figure the network settings under Darwin, that OS explicitly uses the SystemConfiguration
     framework to maintain a dynamic, pervasive tree of configurational parameters for the net-
     working component of the kernel.  The Apple network control panel for Mac OS X uses the Sys-
     temConfiguration 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 con-
     figuration 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/SystemConfiguration/preferences.xml.	Alter-
	      nately, 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 bun-
	      dle, 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-continuation character
	      ( to concatenate lines.

     -debug   Engages additional output during program execution, mainly of the debugging persua-
	      sion

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 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 associated with the loca-
	      tion are removed.

     setprop path propkey value1 [value2 ...]
	      Given a property tag propkey and a path within the preferences tree path the pro-
	      gram 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 pro-
	      gram 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 pro-
	      gram 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 pro-
	      gram 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 pro-
	      gram will attempt to display only the value(s) associated 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 par-
	      ticular 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 prefer-
	      ences 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 dis-
	      abled, the SystemConfiguration will not attempt to use that item when configuring a
	      network port.  Disabling a service, for example, implies that the SystemConfigura-
	      tion runtime 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
	      environment variable is not set the SystemConfiguration framework's default prefer-
	      ence 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 NCUtil-
     FoundationErrors.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
     standard locations for frameworks:  /Library/Frameworks or ~/Library/Frameworks.  It is not
     suggested that you install the framework in /System/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 25, 2018 				   Darwin
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 04:39 PM.