netcfg - create and modify External Network Modifiers (ENMs)
netcfg
netcfg subcommand [ options...]
netcfg [-d] -f command-file
netcfg help [subcommand]
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.
netcfg supports the following ENM properties:
The type of trigger for automatic activation of this ENM.
The default value is manual.
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.
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.
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.
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.
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.
ENMs can be activated based on a set of user specified conditions. The following table summarizes the syntax of those condition expressions.
|
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
The following options are not associated with any particular netcfg subcommand:
Removes all configuration before reading subcommands from the command file (see following option).
Reads and executes netcfg subcommands from command_file.
The following subcommands are supported.
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 the value for the specified property.
This subcommand is valid in the enm scope.
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 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.
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 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 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.
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 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.
Display general help or help about a specific subcommand.
This subcommand is valid in any scope.
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.
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 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 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 that the current in-memory ENM has a valid configuration.
This subcommand is valid in the enm scope.
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.
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 myenmExample 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.configExample 6 Importing Current Configuration from a File
The following command imports the current configuration from a file.
# netcfg -f /tmp/nwam.config
See attributes(7) for descriptions of the following attributes:
|