Creating Profiles

The netcfg command, which is described in the netcfg(1M) man page, is one
of two administrative commands in the NWAM command-line interface.

The netcfg command can be used to display profile configuration data, and to
display, create, and modify Known WLAN objects, by anyone who has Console User privileges.
These privileges are automatically assigned to any user who is logged in to
the system from /dev/console. Users who have the Network Autoconf Admin profile can also create
and modify all types of NWAM profiles and configuration objects. For more information,
see the Overview of NWAM Security.

You can use the netcfg command to select, create, modify, and destroy user-defined
profiles. The command can be used in either interactive mode or command-line mode.
The netcfg command also supports the export of profile configuration information to command
files.

You can create, modify, and remove the following profiles and configuration objects:

Network Configuration Profiles (NCPs)

Location profiles

External Network Modifiers (ENMs)

Known wireless local area networks (WLANs)

Network Configuration Units (NCUs)

Creating Profiles in Command-Line Mode

The basic command syntax to use to create a profile from the
command line is as follows:

netcfg create [ -t template ] object-type [ class ] object-name

create

Creates an in-memory profile (or configuration object) of the specified type and name.

-ttemplate

Specifies that the new profile be identical to template, where template is the name of an existing profile of the same type. If the -t option is not used, the new profile is created with default values.

object-type

Specifies the type of profile to be created.

You can specify one of the following values for the object-type option:

ncp

ncu

loc

enm

wlan

All profiles that are specified by the object-type option, with the exception of an ncu, must be created at the global scope before you can use the netcfg select command to select the particular object.

class

Specifies the class of profile that is specified by object-type. This parameter is only used for the ncu object type, and has two possible values, phys or ip.

object-name

Specifies the name of the user-defined profile. For an NCU, object-name is the name of the corresponding link or interface. For all the other profile types, object-name is any user-defined name.

For example, to create an NCP named User, you would type the following
command:

$ netcfg create ncp User

where ncp is the object-type and User is the object-name.

Note - For the creation of NCPs, the class option is not required.

Optionally, you can use a copy of the Automatic NCP as your
template, then make changes to that profile, as shown here:

$ netcfg create -t Automatic ncp

To create a Location profile with the name office, you would type the
following command:

$ netcfg create loc office

Interactively Creating Profiles

You can use the netcfg command in interactive mode to perform the following
tasks:

Create a profile.

Select and modify a profile.

Verify that all of the required information about a profile is set and valid.

Commit the changes for a new profile.

Cancel the current profile configuration without committing any changes to persistent storage.

Revert the changes that you made for a profile.

Creating an NCP

Creating a profile in interactive mode results in a command prompt that is
in one of the following scopes:

In the NCP scope, if an NCP is created

In the profile scope, if a Location profile, an ENM, or a WLAN object is created

Creating an NCP or an NCU moves the focus into that object's
scope, walking you through the default properties for the specified profile.

To interactively create an NCP, you begin by initiating a netcfg interactive session.
Then, you use the create subcommand to create the new NCP User, as
follows:

$ netcfg
netcfg> create ncp User
netcfg:ncp:User>

Creating NCUs for an NCP

The NCP is essentially a container that consists of a set of
NCUs. All NCPs contain both link and interface NCUs. Link NCUs specify both
link configuration and link selection policy. Interface NCUs specify interface configuration policy. If IP
connectivity is required, both a link and an interface NCU are required. NCUs
must be added or removed explicitly by using the netcfg command or by
using the GUI.

Note - It is possible to add NCUs that do not correlate to
any link that is currently installed on the system. Additionally, you can remove
NCUs that map to a link that is currently installed on the system.

You can create NCUs by using the netcfg command in either interactive mode
or command-line mode. Because creating an NCU involves several operations, it is easier
and more efficient to create NCUs in interactive mode, rather than trying to
construct a single-line command that creates the NCU and all of its properties.
NCUs can be created when you initially create an NCP or afterward. The
process of creating or modifying an NCU involves setting general NCU properties, as
well as setting properties that specifically apply to each NCU type.

The properties that you are presented with during the process of creating NCUs
for an NCP make the most sense based on the choices that
you made during the creation of that particular NCP.

When you create an NCU interactively, netcfg walks through each relevant property, displaying
both the default value, where a default exists, and the possible values. Pressing
Return without specifying a value applies the default value (or leaves the property
empty if there is no default), or you can specify an alternate value.
The properties that are displayed during the process of creating NCUs for an
NCP are relevant based on the choices that you have already made. For
example, if you choose dhcp for the ipv4-addrsrc property for an interface NCU,
you are not prompted to specify a value for the ipv4-addr property.

The following table describes all of the NCU properties that you might specify
when creating or modifying an NCU. Some properties apply to both NCU types.
Other properties apply to either a link NCU or an interface NCU.
For a complete description of all of the NCU properties, including rules and
conditions that might apply when you specify these properties, see the netcfg(1M) man
page.

Table 4-1 NCU Properties to Create or Modify an NCU

Property

Description

Possible Values

NCU Type

type

Specifies the NCU type, either link or interface.

link or
interface

Link and interface

class

Specifies the NCU class.

phys (for link NCUs) or ip (for interface
NCUs)

Link and interface

parent

Specifies the NCP to which this NCU belongs.

parent-NCP

Link and interface

enabled

Specifies
whether the NCU is enabled or disabled. This property is read-only. It is
only changed indirectly when you use the netadm command or the NWAM GUI
to enable or disable the NCU.

true or false

Link and interface

activation-mode

Specifies the type
of trigger for the automatic activation of the NCU.

manual or prioritized

The default
value is manual.

Link

priority-group

Specifies the group priority number.

0 (for wired links) or 1
(for wireless links)

For user-defined NCPs, different policies can be specified, for example, wireless link
1 is priority 1, wired link 1 is priority 2, and wired
link 2 is priority 3.

Note - A lower number indicates a higher priority.

Link

priority-mode

Specifies the mode
that is used to determine the activation behavior for a priority group, if
the activation-mode property is set to prioritized.

exclusive, shared, or all

See the netcfg(1M) man page
for the rules that apply when you specify these values.

Link

link-mac-addr

Specifies the MAC
address that is assigned to this link. By default, NWAM uses the factory-assigned
or other default MAC address. A different value can be set here
to override that selection.

A string containing a 48–bit MAC address

link-autopush

Identifies modules that
are automatically pushed over the link when it is opened.

Is automatically
set to the default MTU for the physical link. The value can be
overridden by setting the property to a different value.

MTU size for the
link

Link

ip-version

Specifies the version of IP to use. Multiple values can be assigned.

ipv4
and ipv6

The default value is ipv4, ipv6.

Interface

ipv4-addrsrc

Identifies the source of IPv4 addresses
that are assigned to this NCU. Multiple values can be assigned.

dhcp and static

The
default value is dhcp.

Interface

ipv6-addrsrc

Identifies the source of IPv6 addresses assigned to this
NCU. Multiple values can be assigned.

dhcp, autoconf, or static

The default value is dhcp, autoconf.

Interface

ipv4-addr

Specifies
one or more IPv4 addresses to be assigned to this NCU.

One or
more IPv4 addresses to be assigned

Interface

ipv6-addr

Specifies one or more IPv6 addresses to
be assigned to this NCU.

One or more IPv6 addresses to be assigned

Interface

ipv4-default-route

Specifies
the default route for an IPv4 address.

An IPv4 address

Interface

ipv6-default-route

Specifies the default route
for an IPv6 address.

An IPv6 address

Interface

How to Interactively Create an NCP

The following procedure describes how to create an NCP in interactive mode.

Tip - The walk process that NWAM performs during the initial profile creation ensures that
you are prompted for only those properties that make sense, given the choices
that you made previously. Also, the verify subcommand that is described in this
procedure verifies your configuration. If any required values are missing, you are notified.
You can use the verify subcommand explicitly when creating or modifying a profile
or implicitly by using the commit subcommand to save your changes.

Initiate an netcfg interactive session.

$ netcfg
netcfg>

Create the NCP.

netcfg> create ncp User
netcfg:ncp:User>

where ncp is the profile type and User is the profile name.

Creating the NCP automatically takes you into the NCP scope. If you were
creating a location, an ENM, or a WLAN object, the command prompt
would take you to the profile scope.

where ncu is the object type, ip is the class, and net0 (for
example purposes only) is the object name.

Creating an NCU moves you into that object's scope and walks you
through the default properties for the object.

During the creation of an NCU, the class option is used to differentiate
between the two types of NCUs. This option is especially valuable in situations
where different NCU types share the same name. If the class option
is omitted, it is much more difficult to distinguish NCUs that share the
same name.

Add the appropriate properties for the NCU that you created.

Note - Repeat Steps 3 and 4 until all of the required NCUs for
the NCP are created.

During the creation of the NCU, or when setting property values for a
specified NCU, use the verify subcommand to ensure that the changes that you
made are correct.

netcfg:ncp:User:ncu:net0> verify
All properties verified

Commit the properties that you set for the NCU.

netcfg:ncp:User:ncu:net0> commit
committed changes.

Alternatively, you can use the end subcommand to perform an implicit commit, which
moves the interactive session up one level to the next higher scope. In
this instance, if you have completed creating the NCP and adding NCUs to
it, you can exit the interactive session directly from the NCP scope.

Note -

In interactive mode, changes are not saved to persistent storage until you commit them. When you use the commit subcommand, the entire profile is committed. To maintain the consistency of persistent storage, the commit operation also includes a verification step. If the verification fails, the commit also fails. If an implicit commit fails, you are given the option of ending or exiting the interactive session without committing the current changes. Or, you can remain in the current scope and continue making changes to the profile.

To cancel the changes that you made, use the cancel or the revert subcommand.

The cancel subcommand ends the current profile configuration without committing the current changes to persistent storage, then moves the interactive session up on level to the next higher scope. The revert subcommand undoes the changes that you made and rereads the previous configuration. When you use the revert subcommand, the interactive session remains in the same scope.

Use the list subcommand to display the NCP configuration.

When you are finished configuring the NCP, exit the interactive session.

netcfg:ncp:User> exit

Any time that you use the exit subcommand to end a netcfg interactive
session, the current profile is verified and committed. If either the verification or
the commit operation fails, an appropriate error message is issued, and you are
given the opportunity to exit without committing the current changes. Or, you can
remain in the current scope and continue making changes to the profile.

Note - To exit the scope without exiting the netcfg interactive session, type the end
command:

netcfg:ncp:User> end
netcfg>

Example 4-1 Interactively Creating an NCP

In the following example, an NCP and two NCUs (one link and
one interface) are created.

In this example, because the value ipv4 is chosen, no prompt is displayed
for the ipv6-addrsrc property, as this property is unused. Likewise, for the phys
NCU, the default value (manual activation) for the priority-group property is accepted, so no
other conditionally related properties are applied.

Example 4-2 Creating an NCU for an Existing NCP

To create an NCU for an existing NCP or to modify the
properties of any existing profile, use the netcfg command with the select subcommand.

In the following example, an IP NCU is created for an existing
NCP. The process of modifying an existing profile in interactive mode is similar to
creating a profile. The difference between the following example and Example 4-1 is
that in this example, the select subcommand is used instead of the create
subcommand because the NCP already exists.

Creating a Location Profile

A Location profile contains properties that define network configuration settings that are not
directly related to basic link and IP connectivity. Some examples include naming service
and IP filter settings that are applied together, when required. At any given
time, one Location profile and one NCP must be active on the system.
There are system-defined locations and user-defined locations. System locations are the default that
NWAM chooses under certain conditions, for example, if you did not specify a
location, or if no manually activated locations are enabled, and none of the
conditions of the conditionally activated locations has been met. System-defined locations have a
system activation mode. User-defined locations are those that are configured to be manually
or conditionally activated, according to network conditions, for example, an IP address that
is obtained by a network connection.

You can create locations by using the netcfg command in either interactive mode
or command-line mode. When you create a Location profile, you must set the
properties for the location by specifying values that define the particular configuration parameters
for that location. Location properties are categorized by group, where the group signifies
a particular class of configuration preferences.

Location properties are also stored by NWAM in a repository. When a particular
Location profile is activated, NWAM autoconfigures the network, based on the properties that
are set for that location. Creating or modifying locations involves setting the various
properties that define how the profile is configured, which in turn, determines how
NWAM autoconfigures your network. The properties that you are presented with during the
configuration process are those that make the most sense, based on the choices
that you made previously.

The following table describes all of the location properties that can be specified.
Note that location properties are categorized by group. For a complete description of
all of the location properties, including any rules, conditions, and dependencies that might
apply when you specify any of these properties, see the netcfg(1M) man page.

Table 4-2 Location Properties and Their Descriptions

Property Group
and Description

Property Value and Description

Selection criteria

Specifies the criteria for how and when a
location is activated or deactivated.

activation-mode

The possible values for the activation-mode property are manual, conditional-any, and conditional-all.

conditions

System domain

Determines a host's domain name for direct use
by the NIS naming service.

The system-domain property consists of the default-domain property.
This property specifies the system-wide domain that is used for Remote Procedure Call
(RPC) exchanges.

Name services information

Specifies the naming service to use and the naming service switch
configuration.

The following is a list of properties for the specified naming service:

domain-name

nameservices

nameservices-config-file

dns-nameservice-configsrc

dns-nameservice-domain

dns-namservice-servers

dns-nameservice-search

dns-nameservice-sortlist

dns-nameservice-options

nis-nameservice-configsrc

nis-namservice-servers

ldap-nameservice-configsrc

ldap-namservice-servers

For
more information about these properties, see the “Location Properties” section in the netcfg(1M)
man page.

NFSv4 domain

Specifies the NFSv4 domain.

The value that is used for the system's
nfsmapid_domain property. This value is used to set the nfsmapid_domain SMF property, as described
in the nfsmapid man page, while the location is active. If this property
is not set, the system's nfsmapid_property is cleared when the location is active.
See the nfsmapid(1M) man page for more information.

IP Filter configuration

Specifies the parameters that are
used for IP Filter configuration. For these properties, the paths to the appropriate
ipf and ipnat files containing IP filter and NAT rules are specified.

ipfilter-config-file

ipfilter-v6-config-file

ipnat-config-file

ippool-config-file

If a configuration file is specified, the rules that are contained in the identified file are applied to the appropriate ipfilter subsystem.

Configuration files for IPsec

Specifies
which files to use for IPsec configuration.

ike-config-file

ipsecpolicy-config-file

How to Interactively Create a Location Profile

The following procedure describes how to create a Location profile.

Tip - The walk process that NWAM performs during an initial profile creation only prompts
you for those properties that make sense, given the values that you entered
previously. Also, the verify subcommand checks to make sure your configuration is correct.
If any required values are missing, you are notified. Note that you can
use the verify subcommand explicitly when you creating or modifying a profile configuration
or implicitly by using the commit subcommand to save your changes.

Initiate an netcfg interactive session.

$ netcfg
netcfg>

Create or select the location.

netcfg> create loc office
netcfg:loc:office>

In this example, the location office is created.

Creating the location automatically moves you to into the profile scope for this
location.

Set the appropriate properties for the location.

Display the profile configuration.

For example, the following output displays the properties for the location office:

In the following example, the configuration for the location office is verified:

netcfg:loc:office> verify
All properties verified

When you complete the verification, commit the Location profile to persistent storage.

netcfg:loc:office> commit
Committed changes

Alternatively, you can use the end subcommand to end the session, which also
saves the profile configuration.

netcfg:loc:office> end
Committed changes

Note -

In interactive mode, changes are not saved to persistent storage until you commit them. When you use the commit subcommand, the entire profile is committed. To maintain the consistency of persistent storage, the commit operation also includes a verification step. If the verification fails, the commit also fails. If an implicit commit fails, you are given the option of ending or exiting the interactive session without committing the current changes. Or, you can remain in the current scope and continue making changes to the profile.

To cancel the changes that you made, use the cancel subcommand.

The cancel subcommand ends the current profile configuration without committing the current changes to persistent storage, then moves the interactive session up one level to the next higher scope.

In this example, the following properties were specified for the office location:

The activation-mode property was set to conditional-any, which resulted in a command prompt that enabled the conditions for activation to be specified.

The condition for activation was specified as: ncu ip:wpi0 is active.

Note - The conditions property was required because the conditional-any property was specified in the previous step. If, for example, the manual property had been specified, the conditions property would not be required.

The following default values were accepted by pressing Return:

nameservices

nameservices-config-file

dns-nameservice-configsrc

nfsv4-domain

For the ipfilter-config-file property, the /export/home/test/wifi.ipf.conf file was specified.

The following default values were accepted by pressing Return:

ipfilter-v6-config-file

ipnat-config-file

ippool-config-file

ike-config-file

ipsecpolicy-config-file

The list subcommand was used to view the properties of the Location profile.

The verify subcommand was used to perform a verification of the configuration.

The commit subcommand was used to commit the changes to persistent storage.

The list subcommand was used again to ensure that the new location was created correctly and that it contains the correct information.

The exit subcommand was used to exit the netcfg interactive session.

For instructions on which values can be specified for these properties, see the
netcfg(1M) man page.

Creating an ENM Profile

ENMs pertain to the configuration of applications that are external to NWAM, for
example, a VPN application. These applications can create and modify network configuration. ENMs
can also be defined as services or applications that directly modify network configuration
when they are activated or deactivated. You can configure NWAM to activate and
deactivate ENMs under conditions that you specify. Unlike an NCP or a Location
profile, where only one of each profile type can be active on a
system at any given time, multiple ENMs can potentially be active on a
system at the same time. The ENMs that are active on a
system at any given time do not necessarily depend on the NCP or
Location profile that is also active on the system at the same time.

Note - NWAM does not automatically recognize an application for which you might create an
ENM. These applications must first be installed and then configured on your system
before you can use the netcfg command to create an ENM for them.

The process of creating the ENM takes you to the profile scope
for the newly created ENM, and automatically begins a walk of the properties
in the newly created ENM. From here, you can set properties for the
ENM that dictate when and how the ENM is activated, as well as
other conditions, including the ENM's start and stop method.

For further instructions on specifying ENM properties, see the netcfg(1M) man page.

The following table describes the properties that you might specify when creating or
modifying an ENM.

Property Name

Description

Possible Values

activation-mode

Mode that is used to determine activation of
an ENM

conditional-any, conditional-all, manual

conditions

If activation-mode is conditional-any or conditional-all, specifies the test
to determine whether the ENM must be activated.

A string or strings formatted
as specified in the “Condition Expressions” section of the netcfg(1M) man page, if the
property is used.

start

(Optional) Absolute path to the script to be executed upon
activation

Path to script, if this property is used

stop

(Optional) Absolute path to the
script to be executed upon deactivation

In this example, an ENM named test-enm was created with the following property
values:

The default value (manual) for the activation-mode property was accepted by pressing the Return key.

The SMF FMRI property svc:/application/test-enm:default was specified as the method to use for activating and deactivating the application.

Note that because an FMRI was specified, the start and stop method properties were bypassed.

The list subcommand was used to view the properties of the ENM.

The verify subcommand was used to ensure that the profile configuration is correct.

The end subcommand was used to implicitly save the configuration.

The end subcommand was used again to end the interactive session.

Creating WLANs

NWAM maintains a system-wide list of known WLANs. WLANs are configuration objects that
contain history and configuration information for the wireless networks that you connect to
from your system. This list is used to determine the order in which
NWAM attempts to connect to available wireless networks. If a wireless network that
exists in the Known WLAN list is available, NWAM automatically connects to that
network. If two or more known networks are available, NWAM connects to the
wireless network that has the highest priority (lowest number). Any new wireless network
that NWAM connects to is added to the top of the Known WLAN
list and becomes the new highest priority wireless network.

The process of creating a WLAN object takes you to the profile
scope for the newly created WLAN, and automatically begins a walk of the
properties in the newly created WLAN. From here, you can set properties for
the WLAN that define its configuration.

The following table describes the properties that you might specify when creating or
modifying WLANs.

Known WLAN Property

Data Type for Property

name

ESSID (wireless network name)

bssids

Base Station IDs
of WLANs that your system has connected to while connected to the specified
WLAN

priority

WLAN connection preference (lower values are preferred)

keyslot

Slot number (1–4) in which the
WEP key is contained

keyname

Name of the WLAN key that is created by
using the dladm create-secobj command.

security-mode

The type of encryption key in use. The type
must be none, wep, or wpa.

Example 4-5 Creating a WLAN

In the following example, a WLAN object named mywifi is created.

This example assumes that a secure object named mywifi-key, which contains the key
that is specified by the keyname property for the WLAN mywifi, is created
before adding the WLAN.

The priority number can change as other WLANs are added or removed. Note
that no two WLANs can be assigned the same priority number. Lower
numbers indicate a higher priority, in terms of which WLANs are preferred. In
this example, the WLAN is assigned the priority number 100 to ensure that
it has a lower priority than any other known WLANs.

When the list subcommand is used at the end of the procedure, the
new WLAN is added to the bottom of the list, indicating that it
has the lowest priority of all the existing known WLANs. If the
WLAN was assigned a priority number of zero (0), which is the default, it
would have been displayed at the top of the list, indicating the
highest priority. Subsequently, the priority of all other existing WLANs would have shifted down
in priority and would have been displayed in the list after the newly
added WLAN.