I'm sponsoring this case for Renee Danson Sommerfeld, it times out on
10/29/2009. The release binding for this case is the same as the case
that it updates (PSARC 2008/532 NWAM Phase 1), namely Minor release
binding.
In the course of completing the implementation of NWAM Phase 1, several
interface changes were made. Most were relatively minor; they are all
documented below.
1. Nomenclature change
Refer to NCU types as link and interface, instead of link and ip.
Link-type NCUs currently have one possible class: phys; Interface-type
NCUs also have one possible class: ip. There is an expectation that as
support for more sophisticated network configurations is added,
additional classes will be created. However, the class will always
imply the type; therefore commands will generally only use the class
descriptor.
This is primarily a documentation change; though the CLI tools do have
some flag changes as well, described in the next item.
2. Updates to the nwamadm options
* Added a new parameter to specify NCU class, to allow differentiation
between Link and IP NCUs, if desired.
* Change the option letter for specifying the profile-type from 't' to 'p'
* Remove the subcommand 'interact'
* Add new subcommands: show-events, scan-wifi, select-wifi
show-events reports the events published by nwamd.
scan-wifi requests a wireless scan on the specified link and prints
result list. Much like 'dladm scan-wifi', only it has the effect
of updating nwamd's cached list, as well.
select-wifi prints the list of available wlans for the specified link,
and prompts the user to select one to connect to.
* Add option to list subcommand, '-x', which includes explanation of state
New subcommand list/syntax for nwamadm:
help
enable [ -p <profile-type> ] [ -c <ncu-class> ] <object-name>
disable [ -p <profile-type> ] [ -c <ncu-class> ] <object-name>
list [ -x ] [ -p <profile-type> ] [ -c <ncu-class> ] [ <object-name> ]
show-events
scan-wifi <linkname>
select-wifi <linkname>
3. Updates to nwamadm output
The output of the 'list' subcommand will include information about the
state of the NCUs that make up the currently active NCP.
4. Add '-V' option to nwamcfg's 'get' subcommand
Default output from the get command is 'propname=propval'. For ease
of scripting, the -V option outputs the value only.
Example:
% nwamcfg "select wlan Asbury; get priority"
priority 0
% nwamcfg "select wlan Asbury; get -V priority"
0
5. Clarification of command-line output stability
PSARC 2008/532 incorrectly defined command-line output stability to be
Uncommitted; it should be Volatile.
6. Make 'enabled' property common to all NCUs, not just Link NCUs.
This change makes the plumbing of ip on a link independent of making the
link active. Bringing up a link and plumbing ip on it can still be
accomplished with one command ('nwamadm enable -p ncu wpi0'); but it is
also possible to separate the two steps ('nwamadm enable -p ncu -c link
wpi0' and 'nwamadm enable -p ncu -c ip wpi0').
7. Use 'enabled' property on all locations, not just those that have manual
activation mode. This means that users can choose to activate any location
at any given time, even if, for example, the location has conditional
activation specified and its conditions are not currently met.
If a user does activate a location, effectively overriding automatic
selection by nwamd, that location must be explicitly disabled in order
to restore automatic selection.
8. 'all' is no longer a valid value for the ip-version property
This property allows multiple values; so the value 'all' is not needed,
as the desired IP versions may simply be enumerated. This change also
means the default value of the property is "ipv4,ipv6" rather than "all".
9. ipv6-addrsrc value change
The value 'dhcpv6' is now simply 'dhcp'. Assigning the value to the
ipv6-addrsrc property implies that the v6 version of the protocol should
be used, no need to differentiate in the names.
Also, dhcp and autoconf values must be included if ipv6-addrsrc is set;
disabling these two address configuration methods is not allowed at this
time. Though this is a change from the legacy Solaris behavior, it is
actually more in keeping with the IPv6 specifications, which state that
the use of those two address configuration methods is specified by the
router, not the host. Adding or removing the value 'static' to/from the
ipv6-addrsrc property is allowed.
10. Remove hosts-file, enable-svcs and disable-svcs properties from Location
profile
Use of the hosts-file property, to replace the /etc/hosts file when
changing location, was not particularly useful, and could lead to
confusion if some locations specified an alternate file, while others
did not.
The enable-svcs and disable-svcs properties could lead to similar
problems, as naming a service in one of these states what the state of
the service should be when the location is active, but is not explicit
about what to do when the location is de-activated. The initial state
is not taken into account, and really can't be, if each location may--
but is not required to--specify a state for a given service.
11. Add default-route properties to IP Interface NCUs
Two new properties, ipv4-default-route and ipv6-default-route, allow
the user to specify statically configured default router address(es),
to be associated with a specific interface. This provides a static
alternative to a DHCP-specified default router, which may be associated
with an interface if DHCP is in use.
12. Add support for storing keyslot info with known_wlans
Includes addition of a 'keyslot' property to the known_wlan object,
extensions to the interfaces and CLIs for setting that value, and
support in nwamd for specifying the keyslot when making connections.
13. Change 'upgraded' nwam service property to 'version'
Rather than having a simple boolean to indicate whether or not legacy
configuration has been updated, we will have a count property which can
evolve as needed. It will not exist when the phase 1 bits are installed,
and will be set to a value of '1' once pre-phase-1 configuration, if any,
has been updated.
14. Clarification of scan_interval service property values
If this property is set to 0, periodic wireless scans will not happen
while a link is connected.
15. New nwam service property 'condition_check_interval'
Allows the user to tune the interval at which conditions are validated
for conditionally-activated objects. Asynchronous events can result in
changes at any time, but in the absence of events, the conditions will
always be re-evaluated at the interval specified by this property.
Default value is 120 seconds; minimum is 30 seconds. If set to a value
lower than the minimum, the minimum will be used.
The stability level of this property is, like all the properties in the
nwamd property group, Volatile.
16. Effect on Automatic and User NCPs when links are added/removed
Earlier behavior was to add newly-discovered links to all NCPs, both
User and Automatic. This had the unfortunate side effect of preventing
the user from permanently removing links that they really did not want
NWAM to manage from the User NCP: upon restart, nwamd would see that a
link was present in the system that did not exist in the User NCP, and
promptly add it. This also would force the user to continually recreate
configuration for a device that was sometimes removed, e.g. a PC-card
wireless adapter.
Revised behavior is to make such changes to the Automatic NCP, but not
the User NCP. If a link is added to the system, the user must explicitly
add it to the User NCP if desired; on removal from the system, it will
not be removed from the User NCP.
17. Change upgrade behavior
Upon upgrade, earlier nwam link and interface configuration will be
imported into the User NCP. However, the Automatic NCP will be active
by default. The rationale for this change is that the default config
implemented in earlier nwam versions is the same as the Automatic NCP
behavior, and we expect that most users will not have made changes, and
therefore will want the Automatic NCP. The previously discussed change
with respect to automatic addition/removal of inserted/removed links
makes this especially desirable. Users who actually modified their
earlier configuration (which should be a small minority) can switch to
the User NCP to get their changes.
There is one exception: if any static addresses are specified in the
llp file, it is very clear that the user did in fact modify that file;
therefore, if a static address is found, the User NCP will be active
upon upgrade.
Location profiles did not exist in earlier versions of NWAM, so any
configuration that NWAM does based on Location specifications may
overwrite previous system configuration. On upgrade, the existing
configuration will be saved into a User location. This location will
be activated if it includes an nsswitch.conf file which uses a nameservice
other than DNS (i.e. a nameservice that cannot be configured by NWAM
based solely on information obtained from the network).
18. Add the following functions and flags to the consolidation-private
libnwam interface:
* nwam_error_t nwam_ncp_get_active_priority_group(int64_t *);
Returns the currently active priority group. In addition, changes
to the active priority group are reported with an
NWAM_EVENT_TYPE_PRIORITY_GROUP event. This allows consumers to
track changes to the active group.
* NWAM_FLAG_KNOWN_WLAN_NO_COLLISION_CHECK flag
As each known_wlan must have a unique priority value, the default
behavior upon commit of a known_wlan object is to check for a
priority collision and shift existing values as needed. However,
in cases where the consumer is writing the complete list, having
explicitly set each priority value, such checking is not needed.
Passing this flag in the flags parameter of the commit function
will skip collision checking.
* nwam_error_t nwam_wlan_get_scan_results(const char *linkname,
uint_t *num_wlansp, nwam_wlan_t **wlansp);
Consumers need a way of requesting the results of the most recent
wireless scan; this function provides that.
* nwam_*_get_state(nwam_*_handle_t handle, nwam_state_t *state,
nwam_aux_state_t *aux_state);
Returns the current state of the specified object.
* nwam_error_t nwam_wlan_get_selection(const char *linkname,
char **essidp, char **bssidp);
Returns the selected wlan, if applicable, for the specified link.
* add argument to nwam_wlan_select()
Additional boolean parameter added to this function to specify
whether or not the selected wlan should be added to the known_wlan
list.
* add property status functions
Specific objects and properties may be read-only (or only modifiable
by nwamd). Add functions to the API allowing consumers to check for
read-only status of objects and properties:
nwam_error_t nwam_loc_prop_read_only(const char *prop, boolean_t *ro);
nwam_error_t nwam_ncu_prop_read_only(const char *prop, boolean_t *ro);
nwam_error_t nwam_enm_prop_read_only(const char *prop, boolean_t *ro);
nwam_error_t nwam_ncp_get_read_only(nwam_ncp_handle_t ncph,
boolean_t *ro);
nwam_error_t nwam_ncu_get_read_only(nwam_ncu_handle_t ncuh,
boolean_t *ro);
boolean_t nwam_loc_can_set_name(nwam_loc_handle_t loch);
boolean_t nwam_enm_can_set_name(nwam_enm_handle_t enmh);
boolean_t nwam_known_wlan_can_set_name(nwam_known_wlan_handle_t kwh);
19. Remove support for renaming of NCU objects
These objects map to physical links and IP interfaces; renaming thus
involves vanity naming and questions of what exactly is intended. For
phase 1, renaming of these objects will not be allowed; determining how
exactly this should work and implementing appropriately remains future
work.
Renaming of links can be accommodated by disabling the nwam service,
performing the rename, and then enabling nwam. The new link name will
be detected and updated in the Automatic NCP; the User NCP will require
the user to make appropriate updates.
20. Remove iptun references from the libnwam interface
Support for iptun datalinks is planned for a future phase; hooks were
included in the API details included with the earlier case. These should
be removed until full support is available.
21. Cleanup of exported interfaces in libinetcfg
Two functions originally included in the list of exported functions for
the consolidation-private libinetcfg are not needed externally, and so
will not be exported: icfg_if_protocol() and icfg_is_loopback().
22. Upgrade the stability level of an interface from PSARC 2006/366,
which is consumed by this case: the zone_check_datalink() function
was integrated as project-private; the submitter of that case, Erik
Nordmark, has agreed to the upgrade of this interface, as documented
in PSARC 2006/366, to consolidation private.
