Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

netcfg(8)

Name

netcfg - create and modify External Network Modifiers (ENMs)

Synopsis

netcfg
netcfg subcommand [
options...]
netcfg [-d] -f 
command-file
netcfg help [subcommand]

Description

The netcfg utility manipulates External Network Modifiers (ENMs). netcfg can be invoked interactively, with an individual subcommand, or by specifying a command file that contains a series of subcommands.

External Network Modifiers (ENMs) are, as the name suggests, applications external to the NWAM service that can modify and/or create network configuration. nwamd activates or deactivates an ENM depending on conditions that are specified as part of the ENM. Alternatively, the user might choose to manually activate/deactivate ENMs as needed.

ENMs provide additional flexibility, allowing the user to specify changes to SMF service properties and/or state, or any other system settings, to be applied under specific conditions.

The NWAM service manages configuration by storing desired property values in profiles. It then determines which ENMs should be active at a given time, depending on current network conditions.

netcfg commands are performed within a scope. There are two scopes: global and enm. When netcfg is invoked without any arguments, the editing session begins in the global scope. In the global scope, ENMs are available to operate on. Selecting an ENM will move the editing session to the enm scope.

Within a enm scope, its 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 by the user. When commit is invoked, the entire ENM is committed. 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.

Properties

netcfg supports the following ENM properties:

ENM Properties

activation-mode: enumerated value: manual | conditional-all | conditional-any

The type of trigger for automatic activation of this ENM.

The default value is manual.

enabled: boolean: true | false

If the activation-mode is manual, the enabled property reflects the ENM's current state. This property is read-only; it is changed indirectly by enabling or disabling the ENM using netadm(8).

The default value is false.

conditions: list of strings: conditional expressions

If 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 oracle.com” or “interface net0 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 to meet 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. The system domain is the domain which is currently assigned to the system; that is, it is the value returned by the |domainname| command.

fmri: string: service FMRI

If this ENM is implemented as an SMF service, this property identifies that service. If this property is specified, when the ENM is activated, the corresponding SMF service is enabled. When the ENM is deactivated, the SMF service is disabled.

start: string: start command

If this ENM is not implemented as an SMF service, this property identifies the command that should be executed 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 executed to stop or deactivate the ENM. This property will be ignored if the FMRI property is set.

Condition Expressions

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
link|interface|enm
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 
                                                      address
ip-address        is-in-range/is-not-in-range         IPv4 or IPv6 
                                                      address plus
                                                      netmask/prefixlen
advertised-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 particular netcfg subcommand:

–d

Removes all configuration before reading subcommands from the command file (see following option).

–f command_file

Reads and executes netcfg subcommands from command_file.

Sub Commands

The following subcommands are supported.

cancel

End the current ENM specification without committing the current changes to persistent storage, and pop up to the next higher scope.

This subcommand is valid in the enm scope.

clear prop-name

Clear the value for the specified property.

This subcommand is valid in the enm scope.

commit

Commit the current ENM to persistent storage. Because a configuration must be correct to be committed, this operation automatically performs a verify on the ENM 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 enm 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 ] enm-name

Create an in-memory ENM with the given name. The –t template option specifies that the new ENM should be identical to template, where template is the name of an existing ENM. If the –t option is not used, the new ENM is created with default values.

This subcommand is valid in the global scope.

destroy { –a | object-type [ class ] object-name }

Remove all the ENM with the –a option, or the specified ENM from memory and persistent storage. This action is immediate and it does not need to be committed. A destroyed ENM cannot be reverted.

This subcommand is valid in the global scope.

end

End the current ENM specification, and pop up to the next higher scope. The current ENM 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 valid in any scope.

exit

Exit the netcfg 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 valid in any scope.

export [ –d ] [ –f output-file ] [ enm-name ]

Print the current or specified ENM to standard out, 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.

This subcommand is valid in any scope.

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

This subcommand is valid in the enm scope.

help [ subcommand ]

Display general help or help about a specific subcommand.

This subcommand is valid in any scope.

list [ –a ] [ enm-name ]

List all ENMs, property-value pairs and resources that exist at the current or specified scope. When listing properties of an ENM, the default behavior is to only list properties that have values set. Including the –a option will result in all properties being listed, whether or not they have values set.

This subcommand is valid in any scope.

revert

Delete any current changes to the current ENM and revert to the values from persistent storage.

This subcommand is valid in the enm scope.

select enm-name

Select the given ENM and jump down into the ENM scope. The selected ENM will be loaded into memory from persistent storage.

This subcommand is valid in the global scope.

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 (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 enm scope.

verify

Verify that the current in-memory ENM has a valid configuration.

This subcommand is valid in the enm scope.

walkprop [ –a ]

Walk each property associated with the current ENM. 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 activation-mode is set to manual, conditions will not be walked. Including the –a option will result in all available properties being walked.

This subcommand is valid in the enm scope.

This subcommand is only meaningful in interactive mode.

Examples

Example 1 Listing All ENMs

The following command lists all available ENMs from the command line.

# netcfg list
ENMs:
        enmtest
        myenm
Example 2 Creating a conditional ENM

The following command sequence interactively creates an ENM with a condition based on the state of interface net0.

# netcfg
netcfg> create enm1
Created enm 'enm1'.  Walking properties ...
activation-mode (manual) [manual|conditional-any|conditional-all]> conditional-all
conditions> interface net0 is active
fmri>      
start> /usr/bin/start
stop> 
netcfg:enm:enm1> list
enm:enm1
        activation-mode         conditional-all
        conditions              "interface net0 is active"
        enabled                 false
        start                   "/usr/local/bin/enm1"
netcfg:enm:enm1> commit
Committed changes
netcfg:enm:enm1> end
netcfg:> exit
Example 3 Destroying an ENM

The following command destroys an ENM from the command line.

# # netcfg destroy myenm
Example 4 Manipulating an ENM

The following command sequence selects an existing ENM, display its contents, and changes a property value.

# netcfg
netcfg>select myenm
netcfg:enm:myenm>list
enm:myenm
        activation-mode manual
        enabled         true
        start           "/usr/local/bin/myenm start"
        stop            "/usr/local/bin/myenm stop"
netcfg:enm:myenm>set stop="/bin/alt_stop"
netcfg:enm:myenm>list
enm:myenm
        activation-mode manual
        enabled         true
        start           "/usr/local/bin/myenm start"
        stop            "/bin/alt_stop"
netcfg:enm:myenm>exit
Committed changes

Example 5 Exporting Current Configuration to a File

The following command exports the current configuration to a file.

netcfg> export -f /tmp/nwam.config

Or, perform the same task from the Unix command line:

# netcfg export -f /tmp/nwam.config
Example 6 Importing Current Configuration from a File

The following command imports the current configuration from a file.

# netcfg -f /tmp/nwam.config

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/network
Interface Stability
Committed

See Also

attributes(7), netadm(8), netcfgd(8), nwamd(8)