Version 1.7, 2008-Sep-30
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. Those profiles include Network Configuration Profiles (NCPs), Locations, and External Network Modifiers (ENMs).
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.
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, or ENMs) 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, or ENM) 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.
End the current profile specification without committing the current changes to persistent storage, and pop up to the next higher scope.
This subcommand is only meaningful in interactive mode.
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).
This subcommand is only meaningful in interactive mode. In non-interactive mode, 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 the values specified for that object type in automatic mode.
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.
This subcommand is only meaningful in interactive mode.
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.
This subcommand is only meaningful in interactive mode.
Print the current configuration 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.
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.
This subcommand is only meaningful in interactive mode.
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.
This subcommand is only meaningful in interactive mode.
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 ncp1; 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.
Example 1: Set an NCU property from the command line (in non-interactive mode)
# nwamcfg "select ncp myncp; select ncu link net1; set mtu=1492"
#
Example 2: List all top-level profiles from the command line
# nwamcfg list
NCPs:
myncp
Locations:
home
office
ENMs:
myenm
enmtest
#
Example 3: Destroy a Location profile from the command line
# nwamcfg destroy loc home
Destroyed location:home.
#
Example 4: Interactively create an NCU profile. # nwamcfg nwamcfg> select ncp myncp nwamcfg:ncp:myncp> create ncu ip net1 nwamcfg:ncp:myncp:ncu:net1> walkprop activation (always) [always|never|manual|prioritized|conditional]> conditional condition ()> link:net1 under (link:net1)> ipversion (all) [ipv4|ipv6|all]> ipv4 ipv4-addr-src (dhcp) [static|dhcp]> static ipv4-static-addr ()> 168.1.2.3 nwamcfg:ncp:myncp:ncu:net1> list NCU:IP:net1 class: ip parent-ncp: myncp activation-mode: conditional condition: link:net1 under: link:net1 ipversion: ipv4 ipv4-addr-src: static ipv4-static-addr: 168.1.2.3 nwamcfg:ncp:myncp:ncu:net1> commit nwamcfg:ncp:myncp:ncu:net1> end nwamcfg:ncp:myncp> 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 state disabled activation manual condition "" fmri "" start "/usr/local/bin/start_myenm" stop "/usr/local/bin/stop_myenm" nwamcfg:enm:myenm>set stop=/bin/alt_stop nwamcfg:enm:myenm>list ENM:myenm state disabled activation manual condition "" fmri "" start "/usr/local/bin/start_myenm" stop "/bin/alt_stop" nwamcfg:enm:myenm>exit nwamcfg:enm:myenm: committing changes...done #
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).
At any given time, there is one active NCP and one active Location on a system. Enabling an NCP or Location will implicitly disable the current active NCP or Location. Explicitly disabling an NCP or Location has the effect of "turning off" that aspect of the system's network configuration. For example, if the current NCP is disabled and no other NCP is then enabled, there will be no configured links or interfaces on the system.
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.
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,
location, or 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 ncp,
location, or enm.
List all available profiles and their current state. If a specific profile is specified, 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.
Example 1: Enable the automatic NCP
# nwamadm enable -t ncp automatic
Disabled ncp 'foo'.
Enabled ncp 'automatic'.
#
Example 2: Disable an ENM
# nwamadm disable -t enm myvpn
Disabled enm 'myvpn'.
#
Example 3: List all Locations
# nwamadm list -t location
TYPE PROFILE STATE
location home inactive
location office inactive
location coffeeshop active
#
| Revision | Date | Changes |
|---|---|---|
| 1.1 | 2008-06-04 | modify to reflect phase 1 spec updates |
| 1.2 | 2008-07-16 | add nwamadm section |
| 1.3 | 2008-08-05 | grammar/usage updates for nwamcfg |
| 1.4 | 2008-08-18 | update (default) [options] syntax in walkprop example |
| 1.5 | 2008-08-27 | syntax cleanup |
| 1.6 | 2008-09-08 | examples cleanup |
| 1.7 | 2008-09-30 | make scope terminology consistent |