Command Line Interface

6.1 Command Line Interface

 Version 1.17, 2009-Aug-21

 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) .

6.1.1 nwamcfg(1M)

6.1.1.1 Overview

 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 and IP interfaces. An IP interface must be associated with an underlying link. 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.

6.1.1.2 Command Reference

 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:

• cancel
   End the current profile specification without committing the current changes to persistent storage, and pop up to the next higher scope.
• clear <prop-name>
   Clear the value for the specified property.
• commit
   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 [ -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. 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 -a
  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
   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
   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.
• export [ -d ] [ -f <output-file> ] [ <object-type> [ <class> ] <object-name> ]
   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. System created objects, including the Automatic NCP and the Automatic, NoNet and Legacy locations, cannot be exported.
• get [ -V ] <prop-name>
   Get the current (in-memory) value of the specified property. By default, both the property name and value are printed; if the -V option is specified, only the property value is printed.
• help [ <subcommand> ]
   Display general help or help about a specific subcommand.
• list [ <object-type> [ <class> ] <object-name> ]
   List all profiles, property-value pairs and resources that exist at the current or specified scope.
• revert
   Delete any current changes to the current profile and revert to the values from persistent storage.
• 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. The selected object will be loaded into memory from persistent storage.
• set <prop-name>=<value1>[,<value2>...]
   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
   Verify that the current in-memory object has a valid configuration.
• walkprop
   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.

6.1.1.3 Objects and Non-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.

6.1.1.4 Examples

 Example 1: Set an NCU property from the command line (in non-interactive mode)

# nwamcfg "select ncp User; select ncu phys 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 (ipv4,ipv6) [ipv4|ipv6]> 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:             interface
        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
#

6.1.2 nwamadm(1M)

6.1.2.1 Overview

 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 Network Configuration Units (NCUs), which are the components that make up 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 (with activation-mode 'manual') will implicitly disable the current active NCP or Location. The current Location (if its activation-mode is 'manual') 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 NCUs is also allowed; the specified NCU must be part of the currently active NCP, and must have its activation mode set to MANUAL. If an NCU class is not specified, all NCUs (one link and/or one interface) with the given name will be enabled/disabled.

 Enabling and disabling of objects is performed asynchronously; thus, the request to enable or disable may succeed, while the action itself fails. A failure of this sort will be reflected in the object state; 'maintenance' state indicates that the last action taken failed.

6.1.2.2 Command Reference

 nwamadm can be invoked as follows:

nwamadm enable [ -p <profile-type> ] [ -c <ncu-class> ] <profile-name>
nwamadm disable [ -p <profile-type> ] [ -c <ncu-class> ] <profile-name>
nwamadm list [ -p <profile-type> ] [ -c <ncu-class> ] [ <profile-name> ]
nwamadm show-events
nwamadm scan-wifi <linkname>
nwamadm select-wifi <linkname>
nwamadm help

 The subcommands are defined as follows:

• enable [ -p <profile-type> ] [ -c <ncu-class> ] <profile-name>
   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. If the profile type is NCU and the name is not unique (i.e. there is both a link and interface NCU with the same name), both NCUs will be enabled, unless the -c option is used to specify the NCU class. Profile type must be one of ncp, ncu, location or enm; NCU class must be one of phys or ip.
• disable [ -p <profile-type> ] [ -c <ncu-class> ] <profile-name>
   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. If the profile type is NCU and the name is not unique (i.e. there is both a link and interface NCU with the same name), both NCUs will be disabled, unless the -c option is used to specify the NCU class. Profile type must be one of ncu, location, or enm; NCU class must be one of phys or ip.
• list [ -p <profile-type> ] [ -c <ncu-class> ] [ <profile-name> ]
   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 and/or NCU class 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:
  • disabled: A manually-activated profile which has not been activated.
  • offline: A conditionally- or system-activated profile which has not been activated. It may not be active because its conditions have not been satisfied; or it may be that another profile has more specific conditions that are met and has been activated instead (in the case of profile types which must be activated one at a time, such as Locations).
  • online: A conditionally- or system-activated profile whose conditions have been met and which has been successfully activated; or a manually-activated profile which has been successfully activated at the request of the user.
  • maintenance: Activation of the profile was attempted, but failed.
  • initialized: The profile represents a valid configuration object for which no action has yet been taken.
  • uninitialized: The profile represents a configuration object not present in the system; for example, an NCU corresponding to a physical link that has been removed.

• show-events
   Listen for and display events from the NWAM daemon.

• scan-wifi <linkname>
   Initiate a wireless scan on the link identified by linkname.

• select-wifi <linkname>
   Select a wireless network to connect to from scan results on link linkname. The user will be prompted for WLAN selection, WiFi key, etc. as needed.

• help
   Print a usage message with short descriptions for each subcommand.

6.1.2.3 Examples

 Example 1: Enable a user-specified location

# nwamadm enable -p loc office
Disabled loc 'home'.
Enabled loc 'office'.
#

 Example 2: Disable an ENM

# nwamadm disable -p enm myvpn
Disabled enm 'myvpn'.
#

 Example 3: List all NCPs

# nwamadm list -p ncp
TYPE         PROFILE         STATE
ncp          User            online
ncu:ip       bge0            online
ncu:phys     bge0            online
ncu:ip       bge1            disabled
ncu:phys     bge1            disabled
ncp          Automatic       offline
#

 Example 4: List all ip NCUs in the active NCP

# nwamadm list -c ip
TYPE         PROFILE         STATE
ncu:ip       bge0            online
ncu:ip       bge1            disabled
#

Revision History