System Administration Commands nwamcfg(1M)
NAME
nwamcfg - create and modify network configuration profiles
SYNOPSIS
nwamcfg
nwamcfg subcommand [options...]
nwamcfg [-d] -f command-file
nwamcfg help [subcommand]
DESCRIPTION
The nwamcfg utility manipulates system network configuration
profiles. nwamcfg can be invoked interactively, with an
individual subcommand, or by specifying a command file that contains a series of subcommands.nwamcfg commands are performed within a scope. There are
three scopes: global, profile, and NCP. When nwamcfg is
invoked without any arguments, the editing session begins in the global scope. In the global scope, NCPs, Location and ENM profiles, and Known WLAN entries are available tooperate on. (To flesh out the acronyms: NCP is Network Con-
figuration Profiles; ENM is External Network Modifier.) Selecting an NCP will move the editing session to the NCP scope; from there, individual NCUs may be created or selected to move into the profile scope. Also, at the global scope, selecting or creating a Location, ENM, or Known WLAN will move the editing session to the profile scope. Within a given profile scope, profile properties may be viewed and modified. In interactive mode, changes are not stored to persistent storage until commit is invoked. Commit is implicitly invoked at "end" or "exit", or can be explicitly invoked bythe user. When commit is invoked, the entire profile is com-
mitted. In order to maintain the consistency of persistent storage, the commit operation includes a verify step; if verification fails, the commit also fails. If an implicit commit fails, the user will be given the option of ending or exiting without committing the current changes, or remaining in the current scope to make further changes.SunOS 5.11 Last change: 15 Mar 2010 1
System Administration Commands nwamcfg(1M)
PROPERTIESnwamcfg supports the following types of properties:
o NCU properties o properties of interface NCUs o properties common to all link NCUs o location properties o ENM properties o known WLAN properties These properties are described in the following subsections. NCU Properties The following properties are common to all NCUs. type: enumerated value: link | interface Specifies the NCU type, either link or interface. The value is implicitly determined based on the specified class.class: enumerated value: phys for link NCUs; ip for inter-
face NCU Specifies the NCU class. parent: string: name of parent NCP Specifies the NCP of which this NCU is a component. The type, class, and parent properties are set when the NCU is created and cannot be changed later. enabled: boolean: true | falseIf the activation-mode is manual, the enabled property
reflects the NCU's current state. This property isread-only; it is changed indirectly by enabling or disa-
bling the NCU using nwamadm(1M). The default value is true.SunOS 5.11 Last change: 15 Mar 2010 2
System Administration Commands nwamcfg(1M)
Properties of Interface NCUsip-version: list of enumerated values: ipv4 | ipv6
The version(s) of IP that should be used on this NCU. The default value is ipv4,ipv6.ipv4-addrsrc: list of enumerated values: dhcp | static
Identifies the source of IPv4 addresses assigned to this NCU; multiple values may be assigned. If one of thevalues assigned is static, the ipv4-addr property must
include at least one IPv4 address to be assigned to the NCU. The default value is dhcp.ipv4-addr: list of IPv4 address(es)
One or more IPv4 addresses to be assigned to this NCU.ipv4-default-route:IPv4 address
The IPv4 address of the default router; if this propertyis set, a default route for IPv4 traffic will be associ-
ated with this interface when it is brought up.ipv6-addrsrc: list of enumerated values: dhcp | autoconf |
static Identifies the source of IPv6 addresses assigned to this NCU; multiple values can be assigned. If one of thevalues assigned is static, the ipv6-addr property must
include at least one IPv6 address to be assigned to the NCU. The default value is dhcp,autoconf.ipv6-addr: list of IPv6 address(es)
One or more IPv6 addresses to be assigned to this NCU.ipv6-default-route: IPv6 address
The IPv6 address of the default router; if this property is set, a default route for IPv6 traffic will beSunOS 5.11 Last change: 15 Mar 2010 3
System Administration Commands nwamcfg(1M)
associated with this interface when it is brought up. Properties Common to All LINK NCUsactivation-mode: enumerated value: manual | prioritized
The type of trigger for automatic activation of this NCU. The default value is manual.priority-group: uint64: group priority number
If activation-mode is set to prioritized, this property
specifies the priority group to which this NCU belongs. A group consists of one or more NCUs; smaller numbers are higher priority. The highest priority group that is determined to be available will be activated by nwamd(1M), and will remain so until it is no longer available, or until a higher priority group becomes available.priority-mode: enumerated value: exclusive | shared | all
If activation-mode is set to prioritized, this property
specifies the mode used to determine availability and activation behavior for a priority group. exclusive At least one NCU must be available to make the group available, and only one NCU will be activated. If more than one member NCU is available, nwamd(1M) will randomly choose one to activate. shared At least one NCU must be available to make the group available; all available NCUs will be activated. all All group member NCUs must be available to make the group available; all member NCUs will be activated.SunOS 5.11 Last change: 15 Mar 2010 4
System Administration Commands nwamcfg(1M)
link-mac-addr: string: 48-bit MAC address
The MAC address assigned to this link. By default, NWAMwill request the factory-assigned or default MAC address
for the link; set a different value here to override that selection.link-autopush: list of strings: modules to be pushed over
the linkIdentifies a list of modules that should be automati-
cally pushed over the link when it is opened.link-mtu: uint64: MTU size for this link
This property will be automatically set to the default MTU for the physical link; that value may be overridden by setting this property to a different value. Note that the range of allowed MTU values depends on the underlying hardware. Because NCUs may be created before the underlying hardware is present with driver attached, it is not possible to verify the value set at the time the NCU is edited. If an NCU fails to activate because of an invalid MTU size, this will be indicated in the system log, and the NCU will be placed in maintenance state. Location Propertiesactivation-mode: enumerated value: manual | system |
conditional-all | conditional-any
The type of trigger for automatic activation of this location. The default value is manual. enabled: boolean: true | falseIf the activation-mode is manual, the enabled property
reflects the location's current state. This property isread-only; it is changed indirectly by enabling or disa-
bling the location using nwamadm(1M). The default value is false.SunOS 5.11 Last change: 15 Mar 2010 5
System Administration Commands nwamcfg(1M)
conditions: list of strings: conditional expressionsIf activation-mode is set to conditional-all or
conditional-any, this property specifies the test to
determine whether this location should be activated. Theconditional expression is made up of a sequence of con-
ditions that can be assigned a boolean value, such as"advertised-domain is sun.com" or "ip:bge0 is-not
active." The format of these expressions is defined in the "Condition Expressions" section, below. If multiple conditions are specified, either all must be true tomeet the activation requirements (when activation-mode
is conditional-all) or any one may be true (when
activation-mode is conditional-any).
Note the distinction between advertised-domain and
system-domain. The advertised domain is learned by means
of external communication, such as the DNSdmain or NISdmain advertised by a DHCP server. This attribute is useful for conditional activation of locations; for example, if the advertised domain is mycompany.com, activate the "work" location. The system domain is the domain which is currently assigned to the system; thatis, it is the value returned by the domainname(1M) com-
mand. This attribute is useful for conditional activa-
tion of ENMs, as it will only become true after a loca-
tion has been activated and the system is configured for that particular domain.default-domain: string: system domain name
The domain name that should be applied to the system; this domain name will be used by NIS and LDAP. nameservices: enum value list: files | dns | nis | ldap Specifies the name services that should be configured, such as DNS, NIS, and LDAP.nameservices-config-file: string: path to nsswitch.conf file
Specifies the nsswitch.conf file to be used. This pro-
perty must always have a value. If the nameservices pro-
perty specifies a single name service, this property will, by default, contain /etc/nsswitch.nameservice for the name service specified in the nameservices property;this value can be changed by the user. If the nameser-
vices property identifies more than one name service, the user must specify an additional value for thisSunOS 5.11 Last change: 15 Mar 2010 6
System Administration Commands nwamcfg(1M)
property.dns-nameservice-configsrc: enum value list: manual | dhcp
Specifies the source(s) that should be used to obtain configuration information for the DNS name service. Ifmanual is included, the remaining dns-nameservice-* pro-
perties will be used.dns-nameservice-domain: string: domain name
dns-nameservice-servers: string list: name server
address(es)dns-nameservice-search: string: domain search string
If DNS is one of the configured name services and manual is one of its configuration sources, these properties specify its configuration parameters. Only the servers property is required; search and domain are optional.nis-nameservice-configsrc: enum value list: manual | dhcp
Specifies the source(s) that should be used to obtain configuration information for the NIS name service. Ifmanual is included, the remaining nis-nameservice-* pro-
perties will be used.nis-nameservice-servers: string list: name server
address(es) If NIS is one of the configured name services and manual is one of its configuration sources, this property specifies its server address. If this property is not specified, the NIS client will be started in broadcast mode.ldap-nameservice-configsrc: enum value list: manual
Specifies the source that should be used to obtain con-
figuration information for the LDAP name service. manualis currently the only option for LDAP; thus the ldap-
nameservice-* properties must be provided to complete
LDAP configuration.ldap-nameservice-servers: string list: name server
address(es)SunOS 5.11 Last change: 15 Mar 2010 7
System Administration Commands nwamcfg(1M)
If LDAP is one of the configured name services, this property specifies its server address. This property is required, and it is expected that the specified serverwill have a client profile which will be used to com-
plete client configuration.nfsv4-domain: string: domain name to be used for NVSv4
Specifies the NVSv4 domain to be used. If this value is unspecified, the name service domain will be used.ipfilter-config-file: string: path to ipfilter IPv4 confi-
guration fileipfilter-v6-config-file: string: path to ipfilter IPv6
ipnat-config-file: string: path to ipnat configuration file
ippool-config-file: string:path to ippool configuration file
These properties each specify the path to the rules file for a component of the ipfilter(5) configuration. If agiven config-file property is set, the corresponding IP
filter component will be enabled, reading configuration from the specified file.ike-config-file: string: path to IKE configuration file
Specifies the IKE configuration file. If a value is specified, the svc:/network/ipsec/ike service will be enabled, reading configuration from the specified file.ipsecpolicy-config-file: string: path to IPsec policy confi-
guration file Specifies the IPsec policy configuration file. If avalue is specified, the svc:/network/ipsec/policy ser-
vice will be enabled, reading configuration from the specified file. ENM Propertiesactivation-mode: enumerated value: manual | conditional-all
| conditional-any
The type of trigger for automatic activation of this ENM. The default value is manual.SunOS 5.11 Last change: 15 Mar 2010 8
System Administration Commands nwamcfg(1M)
enabled: boolean: true | falseIf the activation-mode is manual, the enabled property
reflects the ENM's current state. This property isread-only; it is changed indirectly by enabling or disa-
bling the ENM using nwamadm(1M). The default value is false. conditions: list of strings: conditional expressionsIf activation-mode is set to conditional-all or
conditional-any, this property specifies the test to
determine whether or not this ENM should be activated. The conditional expression is made up of a sequence of conditions that can be assigned a boolean value, such as"system-domain is sun.com" or "ip:bge0 is-not active."
The format of these expressions is defined in the "Con-
dition Expressions" section below. If multiple condi-
tions are specified, either all must be true to meet theactivation requirements (when activation-mode is
conditional-all) or any one may be true (when
activation-mode is conditional-any).
Note the distinction between advertised-domain and
system-domain. The advertised domain is learned by means
of external communication, such as the DNSdmain or NISdmain advertised by a DHCP server. This attribute is useful for conditional activation of locations; for example, if the advertised domain is mycompany.com, activate the "work" location. The system domain is the domain which is currently assigned to the system; that is, it is the value returned by the |domainname|(1M) command. This attribute is useful for conditional activation of ENMs, as it will only become true after a location has been activated and the system configured for that particular domain. fmri: string: service FMRIIf this ENM is implemented as an SMF service, this pro-
perty identifies that service. If this property is specified, the ENM will be activated by enabling the service and deactivated by disabling the service. start: string: start command If this ENM is not implemented as an SMF service, this property identifies the command that should be exec'edSunOS 5.11 Last change: 15 Mar 2010 9
System Administration Commands nwamcfg(1M)
to start or activate the ENM. This property will be ignored if the FMRI property is set. stop: string: stop command If this ENM is not implemented as an SMF service, this property identifies the command that should be exec'ed to stop/deactivate the ENM. This property will be ignored if the FMRI property is set. Known WLAN Properties bssids: list of strings: WLAN BSSID(s) (AP MAC addresses)If a specific Access Point should be preferred over oth-
ers with the same name/ESSID, this property allows the AP's BSSID to be specified. priority: uint64: a numeric priority value The relative priority of this WLAN; a smaller number represents higher priority. Note that this number can be changed if subsequent changes to the set of Known WLAN objects require such a
change. For example, consider a system that is config-
ured with two Known WLAN objects, wlanA and wlanB. wlanA has priority 1, and wlanB has priority 2. A new Known WLAN, wlanC, is created and assigned priority 2. In this case, the complete list will be updated such that wlanA has priority 1, wlanC has priority 2, and wlanB has priority 3. No two WLANs can have the same priority value, so the addition of wlanC at priority 2 forces wlanB to be shifted down in priority. If any additional WLANs existed at lower priorities than wlanB, they would be shifted accordingly. keyslot: uint64: the key slot to be used for this WLANIf the WLAN uses an encryption mode that supports multi-
ple keyslots, the slot to place the key can be specified in this property. If unspecified, slot 1 is used by default. keyname: list of strings: Secure object name(s) Allows the user to associate secure objects created using dladm(1M) with Known WLANs.SunOS 5.11 Last change: 15 Mar 2010 10
System Administration Commands nwamcfg(1M)
Condition ExpressionsLocations and ENMs can be activated based on a set of user-
specified conditions. The following table summarizes the syntax of those condition expressions. Object Type Object Condition_____________________________________________________________
ncp|ncu|enm|loc name is/is-not active
Object Type Condition Object------------------------------------------------------------
essid is/is-not/contains/does-not-contain name string
bssid is/is-not bssid string
ip-address is/is-not IPv4 or IPv6
addressip-address is-in-range/is-not-in-range IPv4 or IPv6
address plus netmask/prefixlenadvertised-domain is/is-not/contains/does-not-contain name string
system-domain is/is-not/contains/does-not-contain name string
OPTIONS The following options are not associated with any particularnwamcfg subcommand:
-d
Removes all configuration before reading subcommands from the command file (see following option).-f command_file
Reads and executes nwamcfg subcommands from
command_file.
SUB-COMMANDS
The following subcommands are supported. cancel End the current profile specification without committing the current changes to persistent storage, and pop up to the next higher scope. This subcommand is valid in the NCP and profile scopes.SunOS 5.11 Last change: 15 Mar 2010 11
System Administration Commands nwamcfg(1M)
clear prop-name
Clear the value for the specified property. This subcommand is valid in the profile scope. commit Commit the current profile to persistent storage. Because a configuration must be correct to be committed, this operation automatically performs a verify on the object as well. The commit operation is attempted automatically upon leaving the current scope (with either the end or exit subcommand). This subcommand is valid in the profile scope.Note that, in non-interactive mode, a commit is not
required, as the commit is implicit for any subcommand that changes a value.create [ -t template ] object-type [ class ] object-name
Create an in-memory profile of the specified type and
name. The -t template option specifies that the new
object should be identical to template, where template is the name of an existing object of the same type. Ifthe -t option is not used, the new object is created
with default values. For NCPs, only a "User" NCP can be created. This subcommand is valid in the global and NCP scopes.destroy { -a | object-type [ class ] object-name }
Remove all or the specified profile from memory and per-
sistent storage. This action is immediate; it does not need to be committed. A destroyed object cannot be reverted. This subcommand is valid in the global and NCP scopes ifa specific object is specified; the -a option is only
valid in the global scope. end End the current profile specification, and pop up to the next higher scope. The current object is verified andSunOS 5.11 Last change: 15 Mar 2010 12
System Administration Commands nwamcfg(1M)
committed before ending; if either the verify or commit fails, an appropriate error message is issued and the user is given the opportunity to end without committing the current changes, or to remain in the current scope and continue editing. This subcommand is valid in any scope. exitExit the nwamcfg session. The current profile is veri-
fied and committed before ending; if either fails, an appropriate error message is issued and the user is given the opportunity to exit without committing the current changes, or to remain in the current scope and continue editing. This subcommand is valid in any scope.export [ -d ] [ -f output-file ] [ object-type [ class ]
object-name ]
Print the current configuration at the current or speci-
fied scope to standard out, or to a file specified withthe -f option. The -d option generates a destroy -a as
the first line of output. This subcommand produces out-
put in a form suitable for use in a command file. System created objects, including the Automatic NCP and the Automatic, NoNet, and User locations, cannot be exported. This subcommand is valid in any scope.get [ -V ] prop-name
Get the current (in-memory) value of the specified pro-
perty. By default, both the property name and value areprinted; if the -V option is specified, only the pro-
perty value is displayed. This subcommand is valid in the profile scope. help [ subcommand ]Display general help or help about a specific subcom-
mand. This subcommand is valid in any scope.SunOS 5.11 Last change: 15 Mar 2010 13
System Administration Commands nwamcfg(1M)
list [ -a ] [ object-type [ class ] object-name ]
List all profiles, property-value pairs and resources
that exist at the current or specified scope. When list-
ing properties of an object, the default behavior is toonly list properties that apply to the specified confi-
guration. That is, if listing an IP NCU for which ipv4-
addrsrc is dhcp, the ipv4-addr property will not be
listed. Including the -a option will result in all pro-
perties being listed, whether or not they apply to the current settings. This subcommand is valid in any scope. revert Delete any current changes to the current profile and revert to the values from persistent storage. This subcommand is valid in the profile scope.select object-type [ class ] object-name
Select one of the profiles available at the current scope level and jump down into that object's scope. Theselected object will be loaded into memory from per-
sistent storage. This subcommand is valid in the global and NCP scopes.set prop-name=value1[,value2...]
Set the current (in-memory) value of the specified pro-
perty. If performed in non-interactive mode, the change
is also committed to persistent storage.The delimiter for values of multi-valued properties is
"," (comma). If any of the individual values in such a property contains a comma, it must be escaped (that is, written as ,). Commas within properties that can only have a single value are not interpreted as delimiters and need not be escaped. This subcommand is valid in the profile scope. verifyVerify that the current in-memory object has a valid
SunOS 5.11 Last change: 15 Mar 2010 14
System Administration Commands nwamcfg(1M)
configuration. This subcommand is valid in the profile scope.walkprop [ -a ]
Walk each property associated with the current profile. For each property, the name and current value are displayed, and a prompt is given to allow the user to change the current value.The delimiter for values of multi-valued properties is
"," (comma). If any of the individual values in such a property contains a comma, it must be escaped (that is, written as ,). Commas within properties that can only have a single value are not interpreted as delimiters and need not be escaped. By default, only properties that are required based on properties that are already set will be walked; that is,if ipv4-addrsrc is set to dhcp, ipv4-addr will not be
walked. Including the -a option will result in all
available properties being walked. This subcommand is valid in the profile scope. This subcommand is only meaningful in interactive mode.EXAMPLES
Example 1 Setting an NCU Property The following command sets an NCU property from the commandline (that is, in non-interactive mode).
# nwamcfg "select ncp User; select ncu phys net1; set link-mtu=1492"
Example 2 Listing Top-Level Profiles
The following command lists all top-level profiles from the
command line.# nwamcfg list
NCPs: AutomaticSunOS 5.11 Last change: 15 Mar 2010 15
System Administration Commands nwamcfg(1M)
User Locations: Automatic home NoNet office ENMs: enmtest myenm WLANs: sunwifi coffeeshop linksys Example 3 Destoying a Location Profile The following command destroys a Location profile from the command line.# nwamcfg destroy loc home
Destroyed loc 'home' Example 4 Creating an NCU Profile The following command sequence interactively creates an NCU profile.# nwamcfg
nwamcfg> select ncp user
nwamcfg:ncp:User> create ncu ip net1
Created ncu 'net1'. Walking properties ...ip-version (ipv4,ipv6) [ipv4|ipv6]> ipv4
ipv4-addrsrc (dhcp) [dhcp|static]> static
ipv4-addr> 168.1.2.3
nwamcfg:ncp:User:ncu:net1> list
ncu:net1 type: interface class: ip parent: "User" enabled true ip version: ipv4ipv4-addrsrc: static
ipv4-addr: "168.1.2.3"
ipv6-addrsrc dhcp,autoconf
SunOS 5.11 Last change: 15 Mar 2010 16
System Administration Commands nwamcfg(1M)
nwamcfg:ncp:User:ncu:net1> commit
Committed changesnwamcfg:ncp:User:ncu:net1> end
nwamcfg:ncp:User> exit
Example 5 Manipulating an ENM The following command sequence selects an existing ENM, display its contents, and changes a property value.# nwamcfg
nwamcfg>select enm myenm
nwamcfg:enm:myenm>list
ENM:myenmactivation-mode manual
enabled true start "/usr/local/bin/myenm start" stop "/usr/local/bin/myenm stop"nwamcfg:enm:myenm>set stop="/bin/alt_stop"
nwamcfg:enm:myenm>list
ENM:myenmactivation-mode manual
enabled true start "/usr/local/bin/myenm start"stop "/bin/alt_stop"
nwamcfg:enm:myenm>exit
Committed changes Example 6 Configuring a Static Address The following command sequence configures a static address of 192.168.2.12/24 on interface bge0 using the Home NCP. This interface is enabled by default when the Home NCP is activated.# nwamcfg
nwamcfg> create ncp Home
First configure phys NCU:SunOS 5.11 Last change: 15 Mar 2010 17
System Administration Commands nwamcfg(1M)
nwamcfg:ncp:Home> create ncu phys bge0
Created ncu 'bge0'. Walking properties ...activation-mode (manual) [manual|prioritized]>
link-mac-addr>
link-autopush>
link-mtu>
nwamcfg:ncp:Home:ncu:bge0> end
Committed changesnwamcfg:ncp:Home>
Then, configure IP NCU:nwamcfg:ncp:Home> create ncu ip bge0
Created ncu 'bge0'. Walking properties ...ip-version (ipv4,ipv6) [ipv4|ipv6]>
ipv4-addrsrc (dhcp) [dhcp|static]> static
ipv4-addr> 192.168.2.10/24
ipv4-default-route>
ipv6-addrsrc (dhcp,autoconf) [dhcp|autoconf|static]>
ipv6-default-route>
nwamcfg:ncp:Home:ncu:bge0> list
ncu:bge0 type interface class ip parent "Home" enabled trueip-version ipv4,ipv6
ipv4-addrsrc static
ipv4-addr "192.168.2.10/24"
ipv6-addrsrc dhcp,autoconf
nwamcfg:ncp:Home:ncu:bge0> exit
Committed changes#
Switch to the Home NCP using nwamadm(1M). Example 7 Configuring Location Based on a Condition The following command sequences configures a location based on a condition. The location is activated whenever the IPaddress is in the 10.0.8.0/24 subnet. Also, NIS is config-
ured in this location.SunOS 5.11 Last change: 15 Mar 2010 18
System Administration Commands nwamcfg(1M)
nwamcfg> select loc office
nwamcfg:loc:office> list
loc:officeactivation-mode conditional-any
conditions "ip-address is 10.0.8.0/24"
enabled false nameservices dns,nisnameservices-config-file "/etc/nsswitch.nis"
dns-nameservice-configsrc dhcp
nis-nameservice-configsrc manual
nis-nameservice-servers "10.2.18.24"
default-domain "labs.east.sun.com"
nwamcfg:loc:office>
Example 8 Creating a Know WLAN The following command sequence establishes a known WLAN named coffeeshop with a WEP key.nwamcfg> select wlan coffeeshop
nwamcfg:wlan:coffeeshop> list
known wlan:coffeeshop priority 2 keyname "foo"security-mode wep
nwamcfg:wlan:coffeeshop> set priority=1
nwamcfg:wlan:coffeeshop> end
Committed changes Example 9 Exporting Current Configuration to a File The following command exports the current configuration to a file.nwamcfg> export -f /tmp/nwam.config
Or, perform the same task from the Unix command line:# nwamcfg export -f /tmp/nwam.config
SunOS 5.11 Last change: 15 Mar 2010 19
System Administration Commands nwamcfg(1M)
Example 10 Importing Current Configuration from a File The following command imports the current configuration from a file.# nwamcfg -f /tmp/nwam.config
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWcsr ||_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
SEE ALSO
dladm(1M), domainname(1M), netcfgd(1M), nwamadm(1M), nwamd(1M), attributes(5), ipfilter(5)See also nwam-manager(1M), available in the JDS/GNOME man
page collection.SunOS 5.11 Last change: 15 Mar 2010 20