4. Repository

Version 0.18, 2009-Mar-17

NWAM profiles will be stored persistently as files under /etc/nwam, as is the case in the Phase 0 implementation. The organization of the data will be changed to better reflect the architecture, as the Phase 0 file format was only intended to be a simple, short-term solution.

Sections 4.1, 4.2, 4.3, and 4.4 describe the objects to be stored in the repository, and section 4.5 defines the organization of the repository data files and their formats.

4.1 Network Configuration Profile

The Network Configuration Profile, or NCP, defines the network configuration of a system. The NCP is composed of Network Configuration Units, or NCUs; these units represent the individual links and interfaces on the system. There are thus two types of NCUs: link and ip. Each type has a variety of classes, as discussed in the following sections.

4.1.1 Link NCUs

Link NCUs represent datalinks. There are several different classes of datalinks: physical links (ethernet or wifi), tunnels, aggregations, vlans, vnics. In Phase 1, NWAM will initially only support physical links; support for tunnels will be added soon after integration, and support for additional link types should follow after that.

4.1.2 IP NCUs

IP NCUs represent an instance of IP plumbed on a datalink. In addition to the basic IP instance, there are several classes of IP NCUs: IPMP group and vni. NWAM Phase 1 will only support basic IP instances.

4.1.3 Automatic NCP

The automatic NCP will consist of one NCU for each physical link discovered in the system, and one IP NCU plumbed on each link. The automatic NCP will change dynamically upon insertion of additional physical links; as new links are inserted, a link NCU and corresponding IP NCU will be created for each new link. The following table defines the values that will be assigned to each NCU property.

4.2 Locations

The Location is a profile of system-wide network configuration information, which is applied once the basic network configuration has been established. Only one Location is active at a time; before a new Location is enabled, settings from the previous Location are removed.

A Location is made up of properties that are global and generally relate to higher-layer networking configuration.

These attributes are discussed in more detail in the Location page of this specification. The property types and values that make up a stored location in the repository are outlined in sections 4.2.1. Three pre-defined locations will be supplied: the NoNet location, which will be applied when no network interfaces are available; the Automatic location, which will be applied when no other locations are available that match the current conditions; and the Legacy location, which will be a snapshot of the existing settings when NWAM performs a cold start. The property values that make up each of these locations are defined in sections 4.2.2, 4.2.3 and 4.2.4.

4.2.1 Location Properties

4.2.2 Automatic Location

This is the default location; i.e. it will be applied when no other location has conditions that are met. This is identified by

This location may be modified by the user; upon the first load of its values via the API, a read-only copy will be saved, which will be available if the user chooses to restore defaults.

127.0.0.1  localhost loghost
::1        localhost
       

4.2.3 NoNet Location

This location will be applied when none of the local interfaces have an IP address assigned, and as an interim location when NWAM is transitioning between user-defined locations.

Like the Automatic location, this location may be modified by the user; upon the first load of its values via the API, a read-only copy will be saved, which will be available if the user chooses to restore defaults.

127.0.0.1  localhost loghost
::1        localhost
       

4.2.4 Legacy Location

4.3 ENMs

External entities which perform their own link/IP configuration may be installed on the system. These entities are referred to as External Network Modifiers, or ENMs. Configuration performed by an ENM will not be stored as part of the persistent NWAM configuration; doing so would require that the user understand the details of how the service is configured, or that NWAM be designed with that knowledge, neither of which is practical.

Therefore NWAM will take note of externally-initiated network configuration; it will not interfere with this configuration, and in fact will use externally- initiated changes to reevaluate its Location selection criteria. However, if the NWAM service is restarted, it will revert the system to the configuration specified by the persistent NCP, tearing down any externally-initiated changes.

To enable more automatic manipulation of ENMs, NWAM provides a registry interface, allowing NWAM to enable and disable ENMs as needed. Registered ENMs will be stored in the NWAM repository in much the same way as NCUs and Locations. The properties of an ENM are defined in the following table.

4.4 Known WLANs

NWAM maintains a global list of known wireless networks; this list is used to determine the order in which NWAM tries to connect to available wireless networks. If a wireless network that exists in the Known WLAN list is available, NWAM will automatically connect to that network; if two or more Known networks are available, NWAM connects to the wireless network with the highest priority (greatest number).

Any new wireless network that NWAM connects to will be added to the top (current highest priority) of the Known WLAN list.

The properties of a Known WLAN are defined in the following table.

4.4.1 WLAN Priority

As previously noted, Known WLANs are selected in priority order; the priority is given by an unsigned integer. A larger number indicates higher priority.

NWAM will automatically add WLANs to the list when it connects to them. When it does this, it will add the new WLAN at the highest priority; that is, the default behavior will be to prefer WLANs that have been connected to more recently.

Known WLANs may not share the same priority. If a WLAN is added via the API with the same numeric priority value as an existing WLAN entry, the existing entry will be shifted down in priority; this change will further shift the rest of the list as needed to avoid shared priorities.

4.4.2 WLAN Keynames

One or more keynames may also be associated with a Known WLAN. This allows the user to create their own keys (using dladm create-secobj and associate those keys with WLANs by adding the secure object names to the Known WLAN keyname property.

4.5 Repository data files and formats

Configuration for each object type will be stored in a file under /etc/nwam: NCP data in /etc/nwam/ncp-<name>.conf (one file per NCP, with each file entry representing an NCU), Locations in /etc/nwam/loc.conf, ENMs in /etc/nwam/enm.conf, and Known WLANs in /etc/nwam/known-wlan.conf. The file format will be similar to that of /etc/dladm/datalink.conf; for example, an entry in ncp.conf would look like

ncu_name	prop0=type,val[,val];prop1=type,val[,val];

The property name is a free-form string. Property values are stored as a (type,value,[,value]) tuple; where values are of type uint64, the integer value will be stored. It is not intended that these files be editable by hand.

Revision History