ncutil man page on OpenDarwin

Man page or keyword search:  
man Server   3202 pages
apropos Keyword Search (all sections)
Output format
OpenDarwin logo
[printable version]

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 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 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 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			       October 23, 2018				Darwin
[top]

List of man pages available for OpenDarwin

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net