3. NWAM Locations

Version 0.14, 2009-Mar-17

A location ties together additional networking details once basic IP connectivity is established. Locations consist of a set of properties which apply to higher-level, or more global network configuration. The following section 3.1 specifies those properties, and provides some very rough initial GUI sketches for those hardwired properties which are not covered in the current revision of the GUI spec.

3.1 Location Properties

We discuss these by group, where a group signifies a particular class of configuration preferences.

Location Name: a string identifier to associate with the Location.
property: name (string)

Selection criteria: when changes occur in the network configuration, NWAM will reevaluate the selection criteria for all configured locations, disabling the current location and enabling a new one as needed. The selection criteria for each location are specified by in two properties:

property: activation-mode (enum value)
property: conditions (string)

The activation-mode property is set to one of a list of possible values: MANUAL, CONDITIONAL_ANY, CONDITIONAL_ALL, or SYSTEM. The SYSTEM activation-mode may only be assigned to the system-provided locations, the Automatic and No-Net locations; it indicates that the system will determine when to activate these locations. It is defined so the settings of these locations may be viewed by libnwam consumers; attempts to commit any other location with activation-mode property set to SYSTEM will fail validation checks.

If the activation-mode is CONDITIONAL_ANY or CONDITIONAL_ALL, the conditions property is set to a string made up of conditional expressions. Each expression is made up of a condition that can be assigned a boolean value, e.g. "system-domain is sun.com" or "ncu ip:bge0 is-not active". If the activation-mode is CONDITIONAL_ANY, the condition will be satisfied if any one of the conditions is true; if the activation-mode is CONDITIONAL_ALL, the condition is satisfied only if all of the conditions are true. The criteria and operations that may be used to construct the condition strings are defined in the table below.

Note the distinction between "advertised-domain" and "system-domain". The advertised domain is learned via external communication; for example, 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.

Object Type	Object	Condition
NCU\|ENM\|Location	name	is/is-not active
Object Type	Condition	Object
WLAN/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

System domain: the system-wide domain used for RPC exchanges; most commonly used for NIS and LDAP.
property: default-domain (string)
Instantiation:
- Set domain using domainname(1M)
Name Services information: what name service to use, what nsswitch.conf should look like. One property lists all name services which are to be configured; additional groups of properties specify configuration strategy and details for each name service.
- nameservices (value list)
  Specifies a list of associated nameservices to configure; possible values include FILES, DNS, NIS, and LDAP. If multiple nameservices are specified, a non-standard nsswitch.conf will be required, so the user must specify an nsswitch.conf file in the nameservices-config-file property.
- nameservices-config-file (string)
  The full path to a valid nsswitch.conf file to be used with the set of name services to be enabled. For a single nameservice (e.g. DNS), this property is optional, and the standard nsswitch file (e.g. /etc/nsswitch.dns) for that nameservice is used if it is not specified.
- dns-nameservice-configsrc (value list)
  nis-nameservice-configsrc (value list)
  ldap-nameservice-configsrc (value list)
  
  A list of sources of configuration information for the specified name service. Possible values are DHCP and MANUAL for DNS and NIS; (currently) only MANUAL for LDAP. If (and only if) this property includes the value MANUAL, the following properties will be used to configure the relevant name service. If this property includes the value DHCP, all available DHCP servers will be queried for name service configuration information, and any information received for the relevant name service will be used to configure that name service. If information is specified and received from multiple sources, it will be merged.
- dns-nameservice-domain (string list)
  
  The optional MANUAL DNS domain name.
  Other name services (NIS, LDAP), if configured manually, will use the system domain, specified by the default-domain property.
- dns-namservice-servers (string list)
  nis-namservice-servers (string list)
  ldap-namservice-servers (string list)
  
  The IP address(es) of the server(s) for the specified name service. Optional for MANUAL NIS configuration; required for MANUAL DNS and LDAP configuration.
- dns-nameservice-search (string list)
  
  Optional string values for the DNS search path.
Instantiation of nameservices:
- When an interface (IP NCU) is being plumbed, nwamd will either obtain Name Service configuration data via the DHCP lease (if DHCP is being used to obtain the IP address) or via a DHCPINFORM transaction. This information will be cached by dhcpagent.
- On location activation, for each name service specified in the nameservices property, the relevant configsrc property will be checked; data will be retrieved from DHCP and/or properties based on the value(s) present. All information gathered will be merged, resulting in e.g. multiple search entries in resolv.conf. If multiple NIS domains are specified, one will be chosen as the default and NIS will be bound to that. However, all domains with their corresponding servers will be configured so they will be available for use as alternately specified domains.
- The configuration values will then be installed:
  - dns: update/create /etc/resolv.conf; restart/enable -t dns/client
  - nis: update/create /var/yp/binding/[domain]/ypservers; restart/enable -t nis/client
  - ldap: set up client using /usr/sbin/ldapclient; restart/enable -t ldap/client
- Copy nsswitch file into place
- restart/enable -t name-service-cache
Local hosts/ipnodes database
property: hosts-file (string)
Instantiation:
- Copy file into place
- restart/enable -t name-service-cache
NFSv4 domain
property: nfsv4-domain (string)
Instantiation:
- Update /etc/default nfs file
- refresh/enable -t mapid service
IP Filter configuration
Here we need to specify paths to appropriate ipf and ipnat files (containing filter and NAT rules)
properties:
ipfilter-config-file (string)
ipfilter-v6-config-file (string)
ipnat-config-file (string)
ippool-config-file (string)

If a config file is specified, the rules contained in the identified file will be applied to the appropriate ipfilter subsystem.
Instantiation:
- set firewall_config_default/policy to "custom"
- set firewall_config_default/custom_policy_file to ipfilter-config-file value
- for {ipfilter-v6|ipnat|ippool}-config-file, set {ipf6|ipnat|ippool}_config_file properties as needed.
- refresh/enable -t ipfilter service
Configuration files for IPsec
property: ike-config-file(string)
property: ipsecpolicy-config-file(string)

Instantiation:
- For each file, set appropriate service's config/config_file property
- refresh/enable -t the service
SMF services to be enabled/disabled
These simply consist of FMRI lists of service instances to enable and disable, i.e.
property 1: enable-svcs (string list of FMRIs to enable)
property 2: disable-svcs (string list of FMRIs to disable)
Instantiation:
- enable-svcs: restart/enable -t each service in list
- disable-svcs: disable -t each service in list

Revision History

Revision	Date	Changes
0.1	2008-Apr-15	initial draft
0.2	2008-Apr-17	remove nodename property; add hosts-file
0.3	2008-Apr-18	add predefined locations - no-net and automatic locations
0.4	2008-Apr-28	merge/reorganize data in repository and location pages
0.5	2008-Apr-29	add property instantiation details
0.6	2008-Sep-09	update hard-wired properties
0.7	2008-Sep-23	minor cleanup/clarification in activation and nameservices props
0.8	2008-Oct-21	more cleanup/clarification in activation props
0.9	2008-Dec-23	update based on implementation experience: extensible locations are post-phase-1; clarify conditional components; one domainname prop, rather than per-ns; remove ipseckey-config-file property.
0.10	2009-Jan-27	miscellaneous clean-up
0.11	2009-Feb-13	Design review feedback; more implementation changes
0.12	2009-Feb-27	more tweaks of nameservice properties; clarification of domain conditional attribute.
0.13	2009-Mar-11	fix system-domain and advertised-domain references; clarify condition syntax table (align headings with code).
0.14	2009-Mar-17	pre-psarc review feedback