The Sets Dictionary

The Sets dictionary contains a subdictionary for each set defined in the system. Generally, sets represent the locations created by the user in Network preferences, although network-configuration applications can also create them. For example, an ISP might provide an application that defines a new location that makes it easy for a user to connect to the ISP. To offer this new location, the application creates a new set dictionary and some number of new services. The new set dictionary contains configuration information for the location, including a property that holds the ISP’s name, and references to the new services.

Each individual set dictionary within the top-level Sets dictionary contains the following properties:

• UserDefinedName

• Network

The UserDefinedName property is a string that holds the location name the user enters in Network preferences. An application that defines a new location would use this key to provide a suitable location name, for example, the name of the ISP. The ISP’s name is then displayed in the Location menu of Network preferences and in the Apple menu.

The Network property is a dictionary that describes the network configuration for the set, including a list of services defined for the set. Every Network dictionary within a set should contain the following properties, all of which are dictionaries:

• Global

• Interface

• Service

As its name implies, the Global dictionary supplies information that is not specific to any particular service. Currently, the Global dictionary contains two member dictionaries: IPv4 and NetInfo, both of which are required.

The IPv4 dictionary should contain the ServiceOrder key. This key’s value is an array that allows the user to impose an ordering on their network services in Network preferences. When multiple services are active at the same time, the system uses the ServiceOrder array to determine which service should be deemed primary. The primary service determines the default route and the DNS and proxy server configurations.

The IPv4 dictionary may also contain the PPPOverridePrimary key. This is a legacy key that allows any active PPP-based service to be treated as if it were first in the ServiceOrder array. This functionality has been replaced by allowing any individual service to include an OverridePrimary key in its own (per service) IPv4 dictionary.

The NetInfo dictionary contains NetInfo binding preferences. As the use of Directory Services becomes more widespread, however, the NetInfo dictionary will become less common.

The Interface dictionary holds per-interface settings. Each member of the Interface dictionary is a subdictionary identified by the BSD name of the interface, such as en0. Each subdictionary contains a dictionary named Ethernet, which holds the results of a manual configuration of the interface. Speed, duplex, and maximum packet size (maximum transfer unit, or MTU) values are stored here. This information is stored at the interface level to prevent individual services from attempting to configure the same interface in different ways.

Typically, however, the user accepts the default Ethernet configuration by choosing the Automatically option in the Ethernet configuration tab of Network preferences. When this is the case, the Ethernet dictionary is either not present or contains the key __INACTIVE__.

The Service dictionary contains references to the services defined for this set. Every member of the Service dictionary is itself a dictionary that contains a single member—an internal service ID that refers to a service listed in the top-level NetworkServices dictionary. Network preferences uses the information in the Service dictionary to display the services and whether or not they’re enabled. The preferences monitor also uses this information as it loads the current configuration preferences into the dynamic store (for more information on this process, see Preferences Monitor ).

The NetworkServices Dictionary

The top-level NetworkServices dictionary contains all the network services defined for the system. Each network service is represented by a dictionary (identified by a unique key) that contains the configuration properties for the entities associated with that service. The combination of entities is determined by the type of service. For example, a modem-based service needs the Interface, PPP, Modem, and IPv4 entities, but not the AppleTalk entity, because OS X does not support AppleTalk over PPP.

If you are developing an application that adds a service to a new set, you need to create a network service dictionary that describes it. This section outlines the contents of a network service dictionary.

A network service dictionary can include the following properties:

• An interface dictionary that describes the network interface underlying the service

• A variable number of protocol entity dictionaries, each of which describes the configuration of a protocol entity (such as PPP or AppleTalk) that’s defined for the service. (Note that some protocol entity dictionaries may be present in a network service dictionary but be empty or marked as inactive.)

• One hardware entity dictionary, depending on the type of service (the type of service is specified in the interface entity dictionary)

• A proxies dictionary that identifies which proxies are enabled for the service

• A user-visible name for the service

Preferences Monitor

The preferences monitor reads the currently active configuration set specified by the user’s CurrentSet preference and loads the associated preferences into the dynamic store. Loading the preferences involves a mapping process that flattens into a single level the hierarchy of nested dictionaries that make up the currently active set. The mapping replaces each nested dictionary with a new key-value pair. The new key is the path from the root of the set dictionary to the nested dictionary and the value is the nested dictionary’s value, minus any additional nested dictionaries. In this way, an arbitrarily deep hierarchy of nested dictionaries can be represented as a series of top-level dictionaries, none of which contain nested dictionaries.

The mapping process also removes dictionaries that are empty or marked inactive and it resolves all references and links. It’s important to note that a dictionary is considered inactive when it contains the __INACTIVE__ key, regardless of the key’s value.

As it maps the contents of the set dictionary into the dynamic store, the preferences monitor prefixes each key with the string Setup:. This identifies these keys as having come from the user’s preferences in the persistent store. Other keys in the dynamic store begin with other strings, such as State:. The State: keys are those the other configuration agents use to hold transient network and system state information.

As an example of the mapping process the preferences monitor performs, Listing 3-1 shows a subset of a user’s preferences as it appears in the persistent store.

Listing 3-1  Subset of service dictionary (ServiceID 100)

<key>100</key>

<dict>

    <key>IPv4</key>

    <dict>

        <key>ConfigMethod</key>

        <string>BootP</string>

    </dict>

    <key>DNS</key>

    </dict>

    <key>Interface</key>

    <dict>

        <key>DeviceName</key>

        <string>en0</string>

        <key>Hardware</key>

        <string>Ethernet</string>

        <key>Type</key>

        <string>Ethernet</string>

        <key>UserDefinedName</key>

        <string>Built-in Ethernet</string>

    </dict>

    <key>UserDefinedName</key>

    <string>Built-in Ethernet</string>

</dict>

Listing 3-2 shows what this dictionary looks like after the preferences monitor maps it.

Listing 3-2  Subset of service dictionary, after mapping into the dynamic store

/Network/Service/100

/Network/Service/100/IPv4

<dictionary>

    <key>ConfigMethod</key>

    <string>BootP</string>

</dictionary>

/Network/Service/100/Interface

<dictionary>

    <key>DeviceName</key>

    <string>en0</string>

    <key>Hardware</key>

    <string>Ethernet</string>

    <key>Type</key>

    <string>Ethernet</string>

    <key>UserDefinedName</key>

    <string>Built-in Ethernet</string>

</dictionary>

<dictionary>

    <key>UserDefinedName</key>

    <string>Built-in Ethernet</string>

</dictionary>

As you can see in Listing 3-2, the IPv4 and Interface subdictionaries are now at the same level as their parent (the service dictionary) and have keys that describe their position in the parent dictionary. In addition, the empty DNS subdictionary in Listing 3-1 is not represented in the mapping.

When it generates a new mapping, the preferences monitor keeps track of the differences from the old mapping. Applying these differences to the dynamic store triggers notifications associated with keys that have changed. This ensures that reconfiguration is automatic when, for example, a user selects a different location in Network preferences or from the Apple menu.

Kernel Event Monitor

The kernel event monitor maintains a list of all network interfaces defined in the system, the link status associated with each interface, and any assigned addresses. It monitors low-level kernel events and watches the network stacks, keeping track of the link status of each network interface. The kernel event monitor’s main job is to post the status of each network interface in the dynamic store. This frees applications from having to reach into the kernel to find out, for example, if the Ethernet cable is plugged in or if the assigned addresses have changed.

Unlike most other agents, the kernel event monitor does not retrieve configuration information from Setup: keys in the dynamic store. Instead, it receives its input directly from the kernel and publishes its observations in some of the State: keys, as shown in Table 3-8.

IPv4 Configuration Agent

The IPv4 configuration agent configures Ethernet-type devices for IP networking. When the preferences monitor loads an updated mapping from the persistent store into the dynamic store, the IPv4 configuration agent receives a notification for each configured service. It gets the configuration information from the relevant Setup: keys and applies that configuration to the indicated interface. It then updates the dynamic store to reflect the actual IP addresses that were assigned. For some configurations, such as DHCP and BootP, the IPv4 configuration agent also updates the dynamic store with any configuration options it received from the server.

When a user switches locations or makes a change to the IP configuration preferences in Network preferences, the preferences monitor loads the new settings into the dynamic store. The IPv4 configuration agent receives notification of the changes and updates the network configuration according to the new settings. It then publishes the new network status information in the appropriate State: keys.

The IPv4 configuration agent also monitors changes in link status. It does this by registering interest in the State: keys the kernel event monitor publishes (shown in Table 3-8). This supports the automatic configuration of network interfaces when the computer is plugged into the network. Table 3-9 shows the keys the IPv4 configuration agent uses.

The IPv4 configuration agent also publishes values in the dynamic store. Table 3-10 shows the keys the IPv4 configuration agent publishes and the circumstances under which it does so.

IPv6 Configuration Agent

Like the IPv4 configuration agent, the IPv6 configuration agent also configures Ethernet-type devices for IP networking. In addition, the IPv6 configuration agent configures FireWire devices and the new 6to4 interface. When the preferences monitor loads an updated mapping from the persistent store into the dynamic store, the IPv6 configuration agent receives a notification for each configured service. It gets the configuration information from the relevant Setup: keys and applies that configuration to the indicated interface. It then updates the dynamic store to reflect the actual IP addresses that were assigned.

The IPv6 configuration agent also monitors changes in link status. It does this by registering interest in the State: keys the kernel event monitor publishes (shown in Table 3-8). This supports the automatic configuration of network interfaces when the computer is plugged into the network. Table 3-11 shows the keys the IPv6 configuration agent uses.

The IPv6 configuration agent also publishes values in the dynamic store. Table 3-12 shows the keys the IPv6 configuration agent publishes and, for some keys, the circumstances under which it does so.

IP Monitor

The main job of the IP monitor agent is to select the primary network service. This is typically the service that is associated with the default route and default DNS for the system. To make its determination, the IP monitor agent examines both the user’s preferred priority of services and the current status of those services. It then selects the currently available service that is highest on the user’s priority list and marks that service as primary in the dynamic store.

The IP monitor agent is driven by information other agents publish in the dynamic store. It monitors the user’s preferences mapped in by the preferences monitor and the configuration status of services published by the IPv4 and IPv6 configuration agents and the PPP controller. Table 3-13 shows the keys the IP monitor agent uses.

The IP monitor also publishes values in the dynamic store. Table 3-14 shows the keys the IP monitor publishes and the circumstances under which it does so.

PPP Controller

The PPP controller configures PPP interfaces for IP networking. It manages connections through dial-up modems and through PPP over Ethernet (PPPoE) and VPN (virtual private network) connections using PPTP (point-to-point tunneling protocol) and L2TP (layer 2 tunneling protocol). The PPP controller interacts with dialer applications and instantiates PPP interfaces as needed.

The PPP controller gets its configuration information from the Setup: keys provided by the preferences monitor and receives notification when these keys change. After an interface is configured, the PPP controller publishes the IP, destination, and router addresses and the DNS information provided by the PPP server. Table 3-15 shows the keys the PPP controller uses.

The PPP controller publishes many keys in the dynamic store. Table 3-16 shows some of them.

Programmatically Setting Preferences

The System Configuration framework provides an API to programmatically set the keys and values that define sets and services. Unfortunately, the API is very low level. For the most part, it consists of functions to get and set individual key-value pairs. It provides no guidance on how to lay out a set or network service dictionary and no support for building these complex structures.

To help meet the needs of developers, Apple’s Developer Technical Support provides a large library of sample code that wraps some of the low-level System Configuration API in higher-level functions. Not only does this library insulate you from much of the low-level manipulation of key-value pairs, it also provides a streamlined template you can use to define a basic service. When you get this basic service working, you can then tweak the settings, using the information in Layout of the Persistent Store as a guide.

Getting Detailed PPP Connection-Status Information

The System Configuration framework provides API that allows you to get detailed information about the current PPP connection. Available in OS X version 10.3 and later, this API gives you access to information gathered by the PPP controller. To use this API, you should be familiar with the layout of the network service dictionary and PPP protocol entity dictionary, as defined by the schema. This is because the information the API returns to you follows the same structure.

Recall that the preferences monitor reads the persistent store and populates the dynamic store with flattened keys and values that describe the user’s currently active configuration. This information is in the setup portion of the dynamic store, using keys prefixed by Setup: (for more information on how these keys are created, see Preferences Monitor ). The other configuration agents read the setup keys they’re interested in, monitor sources of network status information, and publish the results of their observations and configuration actions in the state portion of the dynamic store. Although it is tempting to go directly to the dynamic store and get the value of a specific key, in some cases, it’s not as effective as you might expect.

In particular, to get current PPP status, it’s much better to use the SCNetworkConnectionCopyExtendedStatus function in the SCNetworkConnection API (defined in the SCNetworkConnection.h file in the System Configuration framework). Using this function, you can get very detailed connection-status information from the PPP controller, including some information that is never copied into the state portion of the dynamic store.

For example, when a user chooses to make a PPP connection through a modem, there are several steps the modem takes before connection is finally established. If you register for notification on the PPP Status key in the dynamic store (State:/Network/Service/serviceID/PPP/Status), you’ll receive notification when this key’s value is updated. If you need connection-status information sooner, you might choose to retrieve the value of the PPP Status key immediately after a connection is initiated. When you do this, however, you’ll receive the value Disconnected until after the connection completes. This is because the PPP controller does not update the dynamic store PPP Status key until after the connection is complete. If, instead, you use the SCNetworkConnectionCopyExtendedStatus function to request immediate notification, you’ll be able to observe intermediate states, such as Initialize, Connect, Negotiate, Authenticate, and Connected. In this way, you can get much more detailed (and more accurate) information than if you simply watched the dynamic store.

It’s important to remember that the SCNetworkConnection API, like most other System Configuration APIs, depends on the schema-defined layout of network-service dictionaries and of the dynamic store. When you use the SCNetworkConnectionCopyExtendedStatus function to get PPP connection-status information, you receive a dictionary that contains a subdictionary for each of the service’s subcomponents, such as PPP, IPv4, and Modem. To successfully interpret the information in these dictionaries, you need to know how the schema defines the layout of the key-value pairs. For more information on the structure of these dictionaries, see the appropriate sections in The NetworkServices Dictionary.

Getting Notifications

Understanding how the schema positions the information in the dynamic store gives you a lot of power. In particular, it gives you access to a great deal of low-level network status information. On the other hand, it also fosters the notion that you should be paying attention to every small change in network status. Conceivably, you could write an application that watches large numbers of keys and provides the user with constant updates on every network status change. This is seldom necessary, however, and it is not advisable.

Although the System Configuration framework enables you to request information at this level, it also provides APIs that abstract some of it and provide it in more palatable forms. Therefore, it’s important to know when it’s appropriate to request notifications on individual keys and when it’s appropriate to use the API to get information.

For example, if your application needs to be aware of changes to network proxy settings while it runs, you should watch the dynamic store key associated with the network proxy settings. This is will ensure you receive a notification when any of these settings change. If, instead, you call the SCDynamicStoreCopyProxies function to get the proxy settings in force when your application starts, you won’t get notified of changes as your application runs.

On the other hand, watching configuration keys (the Setup: keys in the dynamic store) is usually a bad idea unless you’re developing a configuration agent. This is because your application has no way of knowing if, or more importantly when, configuration changes are reflected in the system’s running configuration.