3. NWAM Locations

Version 0.8, 2008-Oct-21

A location ties together additional networking details once basic IP connectivity is established. Locations consist of a required set of properties, which we refer to as 'hardwired' location info, and can also handle additional data - i.e. locations are extensible. Section 3.1 specifies hardwired 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. Section 3.2 discusses extensibility, and again includes some rough initial GUI sketches.

3.1 Hardwired 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 (enum value)
  property: condition (string)

  The activation property is set to one of a list of possible values: MANUAL, CONDITIONAL_ANY, CONDITIONAL_ALL, or SYSTEM. The SYSTEM activation type 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 property set to SYSTEM will fail validation checks.

  If the activation type is CONDITIONAL_ANY or CONDITIONAL_ALL, the condition property is set to a list of strings, each of which is made up of a condition that can be assigned a boolean value, e.g. "sun.com is domain" or "ncu ip:bge0 is-not active". If the activation type is CONDITIONAL_ANY, the condition will be satisfied if any one of the conditions is true; if the activation type 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.

  Attribute	Operations
  NCU|ENM|Location identifier	is/is not active
  WLAN/ESSID	is/is not connected
  IP address range/subnet	is/is not assigned
  Domain name	is/is not domain

• Name Services information: what name service to use, what nsswitch.conf should look like. We would like this to simply be a Duckwater (simplified name services) profile in the future, but if Duckwater is not yet available we will take a Duckwater-like approach.

  In Duckwater, the two approaches to getting name service profile configuration are manual specification and automatic discovery. So we should start with a property that specifies which is in effect:

  property: nameservice-discover(boolean)

  If discovery is specified (nameservice-discover = true), NWAM uses dhcpinfo to determine which name service/server is being used, and installs an appropriate nsswitch.conf. Discovery would be the default for automatic NCPs. No additional name service properties need be specified when discover is true.

  From there, Duckwater separates profiles into nsswitch profiles (at present, a particular nsswitch.conf) and name service profiles, which are associated with nsswitch profiles, and specify a particular domainname, and servers for that nameservice. So we will have:

  property: nameservices (value list)

  Specifies a list of associated nameservices to configure; possible values include FILES, DNS, NIS, NISPLUS, and LDAP. If multiple nameservices are specified, a non-standard nsswitch.conf will be required, so we need an optional property specifying a path to such an nsswitch.conf

  property: nameservices-config-file (string)

  This is 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 does not need to be specified and the standard nsswitch file for that nameservice is used (e.g. /etc/nsswitch.dns).

  Finally, we need to specify configuration information for the configured name services:

  dns_nameservice_servers (ip address list)
  dns_nameservice_domain (string)
  dns_nameservice_search (string)
  nis_nameservice_servers (ip address list)
  nis_nameservice_domain (string)
  nisplus_nameservice_servers (ip address list)
  nisplus_nameservice_domain (string)
  ldap_nameservice_servers (ip address list)
  ldap_nameservice_domain (string)

  

  A rough picture of how name services configuration might be presented to the GUI user is displayed above.

  Instantiation of nameservice properties:

  • If nameservice_discover is true, query for relevant settings from DHCP server (DNSdmain, DNSserv, NISdmain, NISservs, NIS+dom, NIS+serv), and use those values to populate back-end properties (or just to perform the back-end setup).
  • If nameservice_discover is false, set up desired back-end(s), as specified in the nameservices property:
    • dns: update/create /etc/resolv.conf; restart/enable -t dns/client
    • nis: set domain; update/create /var/yp/binding/[domain]/ypservers; restart/enable -t nis/client
    • nisplus: set domain; set up client using /usr/lib/nis/nisclient; restart/enable -t rps/nisplus
    • ldap: set domain; 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.

  

  The GUI for handling such information might look like the above.

  Instantiation:

  • Copy files into place.
  • refresh/enable -t ipfilter service

• Configuration files for IPsec

  property: ike-config-file(string)
  property: ipseckey-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

3.2 Extensible Properties

The hardwired properties describe a minimal set of location information, but there is a desire to support extensibility for locations, so that as new, network-related services are added to the system, they may have configuration properties included in the location.

Service developers can identify properties that should be included in location specifications by creating some additional properties for their service:

• A single nwam/config boolean service property must be defined and set to true
• A property group, along the lines of the existing dependency groups, must be defined for each configurable property. This property group should include a set of values that describe the property NWAM should make available, and how exactly to do so.

When NWAM is asked for the list of attributes of a Location, it will return both the hard-wired attributes it already knows about, and the set of attributes it discovers by walking the SMF repository and looking for the nwam/config property and associated property groups.

The following table lists the service properties that must be defined in order to identify a user-configurable service property.

In essence, this is an extensible property template. The name of the property group here is the name of the property to be managed, and the presence of the nwam_location property set to true identifies this group as an NWAM extensible location property. The group and name of the extensible property are identified by the prop_group and prop_name values; a default, no-net and automatic location value may optionally be specified. An optional test description of the property may be included as well; this will be passed to any consumers of the API to provide explanatory text describing the property.

A possible GUI representation of such extensible properties is below:

The value in a newly created location will be initialized to the default, if it is supplied; it will be empty otherwise. In this design, we assume that each extensible property has a unique name that does not clash with any hardwired property names or any other extensible property name. To ensure this, it is suggested that the service name, or some other unique tag, be included in the extensible property name.

From an API perspective, we will provide additional API functions to discover and set extensible properties. When the configuration daemon (netcfgd) is started or refreshed, it will update the extensible property lists in each location, detecting if extensible properties have been added/removed. When a location is activated, the appropriate extensible values will be set for the service instances in question and they will be refreshed/temporarily enabled as needed.

Revision History