| Skip Navigation Links | |
| Exit Print View | |
|
man pages section 1M: System Administration Commands Oracle Solaris 11.1 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
man pages section 1M: System Administration Commands Oracle Solaris 11.1 Information Library |
- create and modify network configuration profiles
netcfg
netcfg subcommand [options...]
netcfg [-d] -f command-file
netcfg help [subcommand]
The netcfg utility manipulates system network configuration profiles. netcfg can be invoked interactively, with an individual subcommand, or by specifying a command file that contains a series of subcommands.
The netcfg utility operates on several different types of configuration profiles:
Network Configuration Profiles (NCPs)
Locations
External Network Modifiers (ENMs)
Known WLANs
For more details on these profile types, refer to the “Profiles” section.
netcfg commands are performed within a scope. There are three scopes: global, profile, and NCP. When netcfg is invoked without any arguments, the editing session begins in the global scope. In the global scope, NCPs, Location and ENM profiles, and Known WLAN entries are available to operate on. Selecting an NCP will move the editing session to the NCP scope; from there, individual Network Configuration Units (NCUs) may be created or selected to move into the profile scope. Also, at the global scope, selecting or creating a Location, ENM, or Known WLAN will move the editing session to the profile scope.
Within a given profile scope, profile 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 profile 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.
The NWAM service manages network configuration by storing desired property values in profiles. It then determines which profile should be active at a given time, depending on current network conditions, and activates that profile. In addition to the Network Configuration Profiles (NCPs) discussed in the previous section, nwamd also manages Location and ENM profiles.
An NCP specifies the configuration of the local network components, including all datalinks and interfaces. These components are collectively referred to as Network Configuration Units, or NCUs.
NCPs are either 'reactive' or 'fixed'. Reactive NCPs include policy rules which determine when each NCU should be enabled. The policy may be set up such that the network configuration can change in response to changes in the network conditions. Fixed NCPs do not include these policy rules; their configuration is fully applied at the time the NCP is enabled, and will not be changed by the system, regardless of any failures encountered or changes in the network state.
A single fixed NCP, called DefaultFixed, is created by the system. On a newly installed system, this NCP will contain any network configuration that was created during installation, either during an interactive install or with a profile applied during Automated Installation. If no network configuration was specified during system installation, the DefaultFixed NCP will initially be empty.
The system also creates a single reactive NCP. The Automatic NCP is created and managed by nwamd, and cannot be modified by the user. This NCP consists of one link NCU and one interface NCU for each physical link present in the system. As links are added or removed from the system, their corresponding NCUs are added or removed from the Automatic NCP. The policy implemented in this NCP is to prefer wired links over wireless, and to plumb IP on all connected wired links, or one wireless link if no wired links are connected.
The Automatic NCP should not be modified by the user. It is managed by the system to match the current set of links and a specific configuration policy; the system may make change at any time which could overwrite or interfere with changes made by the user. If modifications are desired, a copy may be created and then modified; refer to the create subcommand and its -t option.
Finally, the user can create any number of additional reactive NCPs. These NCPs are managed entirely by the user; NCUs must be added or removed explicitly, and it is possible to add NCUs that do not map to any link currently installed in the system, or to remove NCUs that do map to a link present in the system. The user can determine the policy for these NCPs.
There must always be one active NCP. The active NCP on a newly installed system is determined by the installation method; it will either be the Automatic NCP (in the case of a LiveCD install or an Automated Install with a custom profile specifying the active NCP) or the DefaultFixed for other installation methods. The system will never change the active NCP. The user can do this at any time using the GUI or the netadm(1M) command.
A Location specifies system-wide network configuration, including name services, domain, IP Filter, and IPsec configuration.
External Network Modifiers 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 profile. Alternatively, the user might choose to manually activate/deactivate ENMs as needed.
While Location profiles allow a specific set of network-related services to be configured automatically based on current network conditions, that set of services is limited. 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.
netcfg supports the following types of properties:
NCP properties
NCU properties
properties of interface NCUs
properties common to all link NCUs
location properties
ENM properties
known WLAN properties
These properties are described in the following subsections.
Each NCP has a single, read-only property.
Determines the way in which the NCP is managed by the system. Fixed NCPs have all configuration applied at the time the NCP is activated, with no subsequent system intervention. Reactive NCPs are more actively managed, with nwamd enforcing policy rules that determine when each link or interface should be configured.
The user cannot set or change the value of this property. All NCPs created using netcfg will have management-type set to reactive. There is only one fixed NCP, called DefaultFixed, which is created by the system.
The following properties are common to all NCUs.
Specifies the NCU type, either link or interface. The value is implicitly determined based on the specified class.
Specifies the NCU class.
Specifies the NCP of which this NCU is a component.
The type, class, and parent properties are set when the NCU is created and cannot be changed later.
If the activation-mode is manual, the enabled property reflects the NCU's current state. This property is read-only; it is changed indirectly by enabling or disabling the NCU using netadm(1M).
The default value is true.
The version(s) of IP that should be used on this NCU.
The default value is ipv4,ipv6.
Identifies the source of IPv4 addresses assigned to this NCU; multiple values may be assigned. If one of the values assigned is static, the ipv4-addr property must include at least one IPv4 address to be assigned to the NCU.
The default value is dhcp.
One or more IPv4 addresses to be assigned to this NCU.
The IPv4 address of the default router; if this property is set, a default route for IPv4 traffic will be associated with this interface when it is brought up.
Identifies the source of IPv6 addresses assigned to this NCU; multiple values can be assigned. If one of the values assigned is static, the ipv6-addr property must include at least one IPv6 address to be assigned to the NCU.
The default value is dhcp,autoconf.
One or more IPv6 addresses to be assigned to this NCU.
The IPv6 address of the default router; if this property is set, a default route for IPv6 traffic will be associated with this interface when it is brought up.
The type of trigger for automatic activation of this NCU.
The default value is manual.
If activation-mode is set to prioritized, this property specifies the priority group to which this NCU belongs. A group consists of one or more NCUs; smaller numbers are higher priority. The highest priority group that is determined to be available will be activated by nwamd(1M), and will remain so until it is no longer available, or until a higher priority group becomes available.
If activation-mode is set to prioritized, this property specifies the mode used to determine availability and activation behavior for a priority group.
At least one NCU must be available to make the group available, and only one NCU will be activated. If more than one member NCU is available, nwamd(1M) will randomly choose one to activate.
At least one NCU must be available to make the group available; all available NCUs will be activated.
All group member NCUs must be available to make the group available; all member NCUs will be activated.
The MAC address assigned to this link. By default, NWAM will request the factory-assigned or default MAC address for the link; set a different value here to override that selection.
Identifies a list of modules that should be automatically pushed over the link when it is opened. The string may contain more than one module name; module names are separated by the single character “.” (period).
This property will be automatically set to the default MTU for the physical link; that value may be overridden by setting this property to a different value.
Note that the range of allowed MTU values depends on the underlying hardware. Because NCUs may be created before the underlying hardware is present with driver attached, it is not possible to verify the value set at the time the NCU is edited. If an NCU fails to activate because of an invalid MTU size, this will be indicated in the system log, and the NCU will be placed in maintenance state.
The type of trigger for automatic activation of this location.
The default value is manual.
If the activation-mode is manual, the enabled property reflects the location's current state. This property is read-only; it is changed indirectly by enabling or disabling the location using netadm(1M).
The default value is false.
If activation-mode is set to conditional-all or conditional-any, this property specifies the test to determine whether this location should be activated. The conditional expression is made up of a sequence of conditions that can be assigned a boolean value, such as “advertised-domain is sun.com” or “ip:bge0 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. This attribute is useful for conditional activation of locations; for example, if the advertised domain is mycompany.com, activate the “work” location. The system domain is the domain which is currently assigned to the system; that is, it is the value returned by the domainname(1M) command. This attribute is useful for conditional activation of ENMs, as it will only become true after a location has been activated and the system is configured for that particular domain.
The domain name that should be applied to the system; this domain name will be used by NIS and LDAP.
Specifies the name services that should be configured, such as DNS, NIS, and LDAP.
Specifies the nsswitch.conf file to be used. This property must always have a value. If the nameservices property specifies a single name service, this property will, by default, contain /etc/nsswitch.nameservice for the name service specified in the nameservices property; this value can be changed by the user. If the nameservices property identifies more than one name service, the user must specify an additional value for this property.
Specifies the source(s) that should be used to obtain configuration information for the DNS name service. If manual is included, the remaining dns-nameservice-* properties will be used.
If DNS is one of the configured name services and manual is one of its configuration sources, these properties specify its configuration parameters. Only the servers property is required; search and domain are mutually exclusive and only one can be specified, which will override the domain provided by the DHCP server if dhcp is also used. The format of these values are the same as the respective options in resolv.conf(4).
Specifies the source(s) that should be used to obtain configuration information for the NIS name service. If manual is included, the remaining nis-nameservice-* properties will be used.
If NIS is one of the configured name services and manual is one of its configuration sources, this property specifies its server address. If this property is not specified, the NIS client will be started in broadcast mode.
Specifies the source that should be used to obtain configuration information for the LDAP name service. manual is currently the only option for LDAP; thus the ldap-nameservice-* properties must be provided to complete LDAP configuration.
If LDAP is one of the configured name services, this property specifies its server address. This property is required, and it is expected that the specified server will have a client profile which will be used to complete client configuration.
Specifies the NVSv4 domain to be used. If this value is unspecified, the name service domain will be used.
These properties each specify the path to the rules file for a component of the ipfilter(5) configuration. If a given config-file property is set, the corresponding IP filter component will be enabled, reading configuration from the specified file.
Specifies the IKE configuration file. If a value is specified, the svc:/network/ipsec/ike service will be enabled, reading configuration from the specified file.
Specifies the IPsec policy configuration file. If a value is specified, the svc:/network/ipsec/policy service will be enabled, reading configuration from the specified file.
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(1M).
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 sun.com” or “ip:bge0 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. This attribute is useful for conditional activation of locations; for example, if the advertised domain is mycompany.com, activate the “work” location. The system domain is the domain which is currently assigned to the system; that is, it is the value returned by the |domainname|(1M) command. This attribute is useful for conditional activation of ENMs, as it will only become true after a location has been activated and the system configured for that particular domain.
If this ENM is implemented as an SMF service, this property identifies that service. If this property is specified, the ENM will be activated by enabling the service and deactivated by disabling the service.
If this ENM is not implemented as an SMF service, this property identifies the command that should be exec'ed 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 exec'ed to stop/deactivate the ENM. This property will be ignored if the FMRI property is set.
If a specific Access Point should be preferred over others with the same name/ESSID, this property allows the AP's BSSID to be specified.
The relative priority of this WLAN; a smaller number represents higher priority.
Note that this number can be changed if subsequent changes to the set of Known WLAN objects require such a change. For example, consider a system that is configured with two Known WLAN objects, wlanA and wlanB. wlanA has priority 1, and wlanB has priority 2. A new Known WLAN, wlanC, is created and assigned priority 2. In this case, the complete list will be updated such that wlanA has priority 1, wlanC has priority 2, and wlanB has priority 3. No two WLANs can have the same priority value, so the addition of wlanC at priority 2 forces wlanB to be shifted down in priority. If any additional WLANs existed at lower priorities than wlanB, they would be shifted accordingly.
If the WLAN uses an encryption mode that supports multiple keyslots, the slot to place the key can be specified in this property. If unspecified, slot 1 is used by default.
Allows the user to associate secure objects created using dladm(1M) with Known WLANs.
Locations and 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 stringThe 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 profile specification without committing the current changes to persistent storage, and pop up to the next higher scope.
This subcommand is valid in the NCP and profile scopes.
Clear the value for the specified property.
This subcommand is valid in the profile scope.
Commit the current profile to persistent storage. Because 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 valid in the profile 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 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.
This subcommand is valid in the global and NCP scopes.
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.
This subcommand is valid in the global and NCP scopes if a specific object is specified; the -a option is only valid in the global scope.
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 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 configuration at the current or specified scope 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. System created objects, including the Automatic NCP and the Automatic, NoNet, and User locations, cannot be exported.
This subcommand is limited in that it can only export configuration that can be created using the netcfg command; an NCP may contain NCUs or NCU properties that can only be set using ipadm(1M) or dladm(1M). This sort of configuration will be omitted from what is output by the export subcommand.
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 profile scope.
Display general help or help about a specific subcommand.
This subcommand is valid in any scope.
List all profiles, property-value pairs and resources that exist at the current or specified scope. When listing properties of an object, the default behavior is to only list properties that apply to the specified configuration. That is, if listing an IP NCU for which ipv4-addrsrc is dhcp, the ipv4-addr property will not be listed. Including the -a option will result in all properties being listed, whether or not they apply to the current settings.
This subcommand is valid in any scope.
Delete any current changes to the current profile and revert to the values from persistent storage.
This subcommand is valid in the profile scope.
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.
This subcommand is valid in the global and NCP scopes.
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 profile scope.
Verify that the current in-memory object has a valid configuration.
This subcommand is valid in the profile scope.
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 (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 ipv4-addrsrc is set to dhcp, ipv4-addr will not be walked. Including the -a option will result in all available properties being walked.
This subcommand is valid in the profile scope.
This subcommand is only meaningful in interactive mode.
Example 1 Setting an NCU Property
The following command sets an NCU property from the command line (that is, in non-interactive mode).
# netcfg "select ncp User; select ncu phys net1; set mtu=1492"
Example 2 Listing Top-Level Profiles
The following command lists all top-level profiles from the command line.
# netcfg list
NCPs:
Automatic
User
Locations:
Automatic
home
NoNet
office
ENMs:
enmtest
myenm
WLANs:
sunwifi
coffeeshop
linksysExample 3 Destroying a Location Profile
The following command destroys a Location profile from the command line.
# netcfg destroy loc home Destroyed loc 'home'
Example 4 Creating an NCU Profile
The following command sequence interactively creates an NCU profile.
# netcfg
netcfg> select ncp user
netcfg:ncp:User> create ncu ip net1
Created ncu 'net1'. Walking properties ...
ip-version (ipv4,ipv6) [ipv4|ipv6]> ipv4
ipv4-addrsrc (dhcp) [dhcp|static]> static
ipv4-addr> 168.1.2.3
netcfg:ncp:User:ncu:net1> list
ncu:net1
type: interface
class: ip
parent: "User"
enabled true
ip version: ipv4
ipv4-addrsrc: static
ipv4-addr: "168.1.2.3"
ipv6-addrsrc dhcp,autoconf
netcfg:ncp:User:ncu:net1> commit
Committed changes
netcfg:ncp:User:ncu:net1> end
netcfg:ncp:User> exitExample 5 Manipulating an ENM
The following command sequence selects an existing ENM, display its contents, and changes a property value.
# netcfg
netcfg>select enm 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 changesExample 6 Configuring a Static Address
The following command sequence configures a static address of 192.168.2.12/24 on interface bge0 using the Home NCP. This interface is enabled by default when the Home NCP is activated.
# netcfg netcfg> create ncp Home
First configure phys NCU:
netcfg:ncp:Home> create ncu phys bge0 Created ncu 'bge0'. Walking properties ... activation-mode (manual) [manual|prioritized]> mac-address> autopush> mtu> netcfg:ncp:Home:ncu:bge0> end Committed changes netcfg:ncp:Home>
Then, configure IP NCU:
netcfg:ncp:Home> create ncu ip bge0
Created ncu 'bge0'. Walking properties ...
ip-version (ipv4,ipv6) [ipv4|ipv6]>
ipv4-addrsrc (dhcp) [dhcp|static]> static
ipv4-addr> 192.168.2.10/24
ipv4-default-route>
ipv6-addrsrc (dhcp,autoconf) [dhcp|autoconf|static]>
ipv6-default-route>
netcfg:ncp:Home:ncu:bge0> list
ncu:bge0
type interface
class ip
parent "Home"
enabled true
ip-version ipv4,ipv6
ipv4-addrsrc static
ipv4-addr "192.168.2.10/24"
ipv6-addrsrc dhcp,autoconf
netcfg:ncp:Home:ncu:bge0> exit
Committed changes
#Switch to the Home NCP using netadm(1M).
Example 7 Configuring Location Based on a Condition
The following command sequences configures a location based on a condition. The location is activated whenever the IP address is in the 10.0.8.0/24 subnet. Also, NIS is configured in this location.
netcfg> select loc office
netcfg:loc:office> list
loc:office
activation-mode conditional-any
conditions "ip-address is 10.0.8.0/24"
enabled false
nameservices dns,nis
nameservices-config-file "/etc/nsswitch.nis"
dns-nameservice-configsrc dhcp
nis-nameservice-configsrc manual
nis-nameservice-servers "10.2.18.24"
default-domain "labs.east.sun.com"
netcfg:loc:office>Example 8 Creating a Known WLAN
The following command sequence establishes a known WLAN named coffeeshop with a WEP key.
netcfg> select wlan coffeeshop
netcfg:wlan:coffeeshop> list
known wlan:coffeeshop
priority 2
keyname "foo"
security-mode wep
netcfg:wlan:coffeeshop> set priority=1
netcfg:wlan:coffeeshop> end
Committed changesExample 9 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 10 Importing Current Configuration from a File
The following command imports the current configuration from a file.
# netcfg -f /tmp/nwam.config
See attributes(5) for descriptions of the following attributes:
|
dladm(1M), domainname(1M), ipadm(1M), netadm(1M), netcfgd(1M), nwamd(1M), resolv.conf(4), attributes(5), ipfilter(5)
See also nwam-manager(1M), available in the JDS/GNOME man page collection.
|