Version 1.13, 2009-Mar-17
Two administrative commands make up the NWAM command line interface: nwamcfg(1M), which allows the administrator to create and modify network profiles, and nwamadm(1M), which allows the administrator to perform actions (e.g. activate, deactivate) on network profiles. These commands are analogous to zonecfg(1M) and zoneadm(1M).
NWAM configuration consists of properties and values associated with several different types of profiles and configuration objects. Those include Network Configuration Profiles (NCPs), Locations, External Network Modifiers (ENMs), and Known WLANs.
An NCP specifies the configuration of the local network components, including physical links, IP tunnel links, and IP interfaces. An IP interface must be associated with an underlying link of either type. These components are collectively referred to as Network Configuration Units, or NCUs. For more detail about the NCP and NCUs, please refer to section 2 of this document.
A Location specifies system-wide network configuration, including areas such as name services, domain, IP Filter and IPsec configuration. More details about Locations can be found in section 3 of this document.
External Network Modifiers are, as the name suggests, applications external to NWAM that may modify and/or create network configuration. NWAM can be configured to activate and deactivate these external applications under conditions specified by the administrator. ENMs are discussed in more detail in section 4.3 of this document.
Known WLANs are used to maintain a list of known wireless networks. These are wireless networks that the user has added or connected to in the past. Known WLANs are discussed in more detail in section 4.4 of this document.
nwamcfg operates in a hierarchical manner that is most easily understood in an interactive shell style. The command is executed from the command line, which results in a prompt at the global scope. From there, top level profiles (NCPs, Locations, ENMs, or Known WLANs) may be selected for modification or created.
Selecting or creating a top-level profile results in a command prompt that is in the profile scope for Locations and ENMs, or the NCP scope if an NCP is selected. From the NCP scope, an NCU may be created or selected, which will result in a profile-scope prompt. In the profile scope, all properties associated with the current profile (NCU, Location, ENM, or Known WLAN) may be viewed and set.
At any given scope, the command prompt will indicate the currently selected profile. The profile may be committed, which writes changes that have been made back to the persistent repository; upon exit from a scope, if uncommitted changes exist, those changes will be committed. If the user wishes to prevent changes from being committed, a revert subcommand is provided, which will undo any uncommitted changes to the currently selected profile, reverting to the last committed state.
nwamcfg may also be used in non-interactive mode, with complete commands entered on a single command line.
nwamcfg can be invoked as follows:
nwamcfg (interactive mode) nwamcfg <subcommand> [options...] nwamcfg [-d] -f <command-file> nwamcfg help [<subcommand>]The following subcommands are supported:
End the current profile specification without committing the current changes to persistent storage, and pop up to the next higher scope.
Clear the value for the specified property.
Commit the current profile to persistent storage. Since 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).
Note that in non-interactive mode a commit is not required, as the commit is implicit for any subcommand which changes a value.
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. If the -t option is not used, the new object is created with default values. For NCPs, only a "User" NCP can be created.
destroy <object-type> [ <class> ] <object-name>
Remove all or the specified profile from memory and persistent storage. This action is immediate; it does not need to be committed. A destroyed object cannot be reverted.
End the current profile specification, and pop up to the next higher scope. The current object is verified and 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.
Exit the nwamcfg session. The current profile is verified 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.
Print the current configuration at the current or specified scope to standard output, or to a file specified with the -f option. The -d option generates a "destroy -a" as the first line of output. This subcommand produces output in a form suitable for use in a command file. The Automatic NCP and the Automatic and NoNet locations cannot be exported.
Get the current (in-memory) value of the specified property.
Display general help or help about a specific subcommand.
List all profiles, property-value pairs and resources that exist at the current or specified scope.
Delete any current changes to the current profile and revert to the values from persistent storage.
Select one of the profiles available at the current scope level and jump down into that object's scope. The selected object will be loaded into memory from persistent storage.
Set the current (in-memory) value of the specified property. 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 (i.e., written as "\,"). Commas within properties that can only have a single value are not interpreted as delimiters, and need not be escaped.
Verify that the current in-memory object has a valid configuration.
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 (i.e., 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 only meaningful in interactive mode.
Subcommands that affect a specific object or property must be performed in the scope in which that object or property exists. For example, in order to get the value of a property of an NCU, the 'get' subcommand must be issued in the scope of that particular NCU. This is straightforward when done in interactive mode, but is somewhat less obvious in non-interactive mode.
Objects and properties that exist outside the global scope may be modified from the command-line, in non-interactive mode, with an appropriate sequence of commands. Thus, to get property foo which is an attribute of NCU myncu in NCP ncp1, the following command would be used:
# nwamcfg "select ncp User; select ncu ip myncu; get foo"Note that the quotes are required to prevent the shell from interpreting the semi-colons.
Refer to the following section for additional examples of this usage.
# nwamcfg "select ncp User; select ncu link net1; set mtu=1492"
#
Example 2: List all top-level profiles from the command line
# nwamcfg list
NCPs:
Automatic
User
Locations:
Automatic
NoNet
home
office
ENMs:
myenm
enmtest
WLANs:
sunwifi
coffeeshop
linksys
#
Example 3: Destroy a Location profile from the command line
# nwamcfg destroy loc home
Destroyed loc 'home'
#
Example 4: Interactively create an NCU profile.
# nwamcfg nwamcfg> select ncp User nwamcfg:ncp:User> create ncu ip net1 Created ncu 'net1'. Walking properties ... ipversion (all) [ipv4|ipv6|all]> ipv4 ipv4-addr-src (dhcp) [static|dhcp]> static ipv4-static-addr ()> 168.1.2.3 nwamcfg:ncp:User:ncu:net1> list NCU:IP:net1 type: ip class: ip parent-ncp: "User" ipversion: ipv4 ipv4-addr-src: static ipv4-static-addr: 168.1.2.3 nwamcfg:ncp:User:ncu:net1> commit Committed changes nwamcfg:ncp:User:ncu:net1> end nwamcfg:ncp:User> exit #Example 5: Select an existing enm, display its contents, and change a property value
# nwamcfg nwamcfg>select enm myenm nwamcfg:enm:myenm>list ENM:myenm activation-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:myenm activation-mode manual enabled true start "/usr/local/bin/myenm start" stop "/bin/alt_stop" nwamcfg:enm:myenm>exit Committed changes #
The nwamadm utility is used to administer NWAM profiles. As discussed in the preceding section, there are three different profile types: Network Configuration Profiles (NCPs), Locations, and External Network Modifiers (ENMs). nwamadm can also be used to administer individual link Network Configuration Units (NCUs), which are the link components that are part of an NCP, and to interact with the NWAM daemon in the absence of a Graphical User Interface.
At any given time, there is one active NCP and one active Location on a system. Enabling a different NCP or Location will implicitly disable the current active NCP or Location. The current Location may also be disabled, though the effect of this will be to "turn off" some aspects of the system's networking capabilities, such as name services. Explicitly disabling an NCP is not permitted, as that would effectively shut down the basic network connectivity of the system. An NCP is only disabled implicitly when a different NCP is enabled.
Conversely, there may be zero or more active ENMs at any given time. Thus enabling or disabling an ENM has no effect on other active ENMs.
Enabling and disabling of individual link NCUs is also allowed; the specified NCU must be part of the currently active NCP, and must have its activation mode set to MANUAL.
nwamadm can be invoked as follows:
nwamadm enable [ -t <profile-type> ] <profile-name> nwamadm disable [ -t <profile-type> ] <profile-name> nwamadm list [ -t <profile-type> ] [ <profile-name> ] nwamadm interact [ -v ] nwamadm helpThe subcommands are defined as follows:
Enable the specified profile. If the profile name is not unique (i.e. there
is a profile of a different type with the same name), the profile type must
be included to differentiate. Profile type must be one of ncp,
ncu, location, enm.
Disable the specified profile. If the profile name is not unique (i.e. there
is a profile of a different type with the same name), the profile type must
be included to differentiate. Profile type must be one of ncu,
location, or enm.
List all available profiles and their current state. If a specific profile is specified by name, list only the current state of that profile. If the profile name is not unique, all profiles with the given name will be listed; or the profile type may be included to identify a specific profile. If only a type is provided, list all profiles of that type. Listing the active NCP will include the NCUs that make up that NCP.
Possible state values include:
Listen for events from the NWAM daemon, requesting user input (such as selection of a WLAN, or entry of a key) when needed. By default, only events requesting information are displayed; if the -v (verbose) option is specified, all events will be displayed.
Print a usage message with short descriptions for each subcommand.
# nwamadm enable -t loc office
Disabled loc 'home'.
Enabled loc 'office'.
#
Example 2: Disable an ENM
# nwamadm disable -t enm myvpn
Disabled enm 'myvpn'.
#
Example 3: List all NCPs
# nwamadm list -t ncp
TYPE PROFILE STATE
ncp User online
ncu bge0 online
ncu bge1 disabled
ncp Automatic offline
#
| Revision | Date | Changes |
|---|---|---|
| 1.1 | 2008-Jun-04 | modify to reflect phase 1 spec updates |
| 1.2 | 2008-Jul-16 | add nwamadm section |
| 1.3 | 2008-Aug-05 | grammar/usage updates for nwamcfg |
| 1.4 | 2008-Aug-18 | update (default) [options] syntax in walkprop example |
| 1.5 | 2008-Aug-27 | syntax cleanup |
| 1.6 | 2008-Sep-08 | examples cleanup |
| 1.7 | 2008-Sep-30 | make scope terminology consistent |
| 1.8 | 2009-Jan-07 | add Known WLAN list details |
| 1.9 | 2009-Jan-27 | miscellaneous clean-up |
| 1.10 | 2009-Feb-13 | Design review feedback; more implementation changes |
| 1.11 | 2009-Feb-27 | Fix text alignment nits |
| 1.12 | 2009-Mar-11 | update enable/disable constraints; add enable/disable of NCUs; add interact subcommand |
| 1.13 | 2009-Mar-17 | pre-psarc review feedback |