7. Daemon

Version 0.14, 2008-Apr-28

The NWAM daemon (nominally nwamd) is the policy component in NWAM. Given the current reality it determines if it there is a configuration that can be automatically applied and if not asks the UI to query the user for further data. In order to do this, nwamd needs to integrate information from multiple sources, and in doing so fulfill multiple roles. These are described in the next few sections.

7.1 Daemon Overview

nwamd is the daemon that controls network autoconfiguration; it does this by

• registering for link-related events it needs to detect via routing socket and sysevent registration. This we will term event collection; an example is getting an EC_DEV_ADD sysevent signifying a NIC was hotplug inserted. Events are packaged into the nwamd event structure and sent to the event handling thread, which is responsible for...
• running an event loop thread to respond to events of interest. This we will term event processing. Examples are on receipt of a new link event (from a hotplug insertion), the appropriate action will be taken.
• sending of events to external consumers who registered interest. This we term event propagation. Examples of event propagation include wireless scan events, which contain information about available wireless LANs, useful to the NWAM GUI which can display the options available.
• at a higher level, monitoring network conditions for applicability of profiles, and changing profile if conditions dictate.

7.2 Daemon Startup and Shutdown Behavior

The daemon supports two different startup modes: hard reset and soft reset. When the daemon starts, it checks for the /var/run/nwamd_soft_reset file. This token is used to indicate that on restart, nwamd should carry out a soft reset. If the nwamd_soft_reset file does not exist, nwamd creates it (so that future starts will be soft resets), and performs some specific hard reset initialization steps; if the file does exist, nwamd skips the hard reset initialization steps and continues in soft reset mode.

When nwamd exits, it will remove the soft reset marker. The marker will also be automatically removed on boot, as it is in the /var/run filesystem. This ensures that on the first launch after boot, and on any launch that follows a clean shutdown, nwamd will run in hard reset mode. Any launch that follows an unexpected shutdown will result in nwamd launching in soft reset mode.

The hard reset initialization steps are:

• /var/run/nwamd_soft_reset is created.
• The Legacy Location is created based on the existing system settings.
• All existing links and interfaces are torn down.
• The No-Net Location is activated.
• Event handlers are registered.
• The appropriate NCP is activated: if running in automatic mode (i.e. nwamd/auto_mode is true), this is the automatic NCP; if running in user mode, this is the user NCP. If there is not a saved user NCP, one is created by copying the current version of the automatic NCP.

When doing a soft reset, only the last two steps described above are taken; that is, the event handlers are registered, and the current NCP is activated.

When nwamd is shutdown, the following steps are performed:

• /var/run/nwamd_soft_reset is deleted.
• All existing links and interfaces are torn down.
• The No-Net Location is activated.
• The Legacy Location settings are written out, but not activated, as they may depend on the legacy links and interfaces being configured.
• The Legacy Location is deleted.

Next we discuss the specifics of event handling and event propagation.

7.3 nwamd as Event Handler

The NWAM daemon needs to handle many different events triggered both externally by the system or user and internally by its different threads. For example, it needs to handle the removal of a link, which causes the IP interface that depends on that link to become unavailable. It also needs to handle internally generated events such as completion of the thread responsible for gathering interface information. Here we explain the different event sources monitored and how the events are retrieved and handled by the NWAM daemon. These events then trigger NWAM events that interested parties (including nwamd) can capture and process (NWAM events are discussed in section 7.3).

Event sources:

• routing socket: nwamd opens a routing socket and listens for messages of type RTM_NEWADDR, signifying an IP interface having acquired a new address (e.g. via DHCP), RTM_DELADDR, signifying an IP interface having lost an address (e.g. due to its lease being revoked), and RTM_IFINFO, signifying a change in the interface flags.
• devfs sysevents: nwamd uses libsysevent(3LIB) to register for EC_DEV_ADD and EC_DEV_REMOVE events, both of subclass ESC_NETWORK. These indicate the hotplug insertion/removal of a NIC.
• dlmgmtd sysevents: nwamd uses libsysevent(3LIB) to register for EC_DLADM sysevents, subclasses DLADM_EV_ADD, DLADM_EV_REMOVE, and DLADM_EV_RENAME. These indicate that a link has been created, destroyed, or renamed. Note that in Phase 1, only events that relate to tunnel links will be processed by nwamd. Note also that these events have not yet been implemented in nevada; an initial implementation is planned with the fix for CR 6637329 , and any additions needed will be added as part of the NWAM Phase 1 project work.
• DLPI notifications: nwamd uses libdlpi(3LIB) to register for link state change notifications from ethernet drivers that support DL_NOTE_LINK_{UP,DOWN}; this indicates that the cable has been plugged in/unplugged.

7.4 nwamd as Event Dispatcher

nwamd is the network configuration policy engine of the system. There are also UI components which inform the system about how the configuration of the system is changing (link up/down) and which query the user when information is needed (connect to an essid).

Below is a table of events that nwamd captures or creates and turns into event messages of type NWAM_EVENTS_... for consumption by interested processes. Event listeners register interest in NWAM events by calling the libnwam function nwam_events_register() and supplying a callback. The callback is free to ignore events that are not of interest. nwamd itself will often carry out actions in response to events it detects, as well as signaling that the event has occurred to interested parties. The doors IPC mechanism is used for event dispatch from nwamd to registered event listeners.

A simple example of an event listener is the NWAM GUI, which listens for NWAM_EVENT_TYPE_SCAN_REPORT event, which provides the GUI a list of available wireless networks garnered by nwamd via dladm_wlan_scan().

7.4.1 IP Interface Events

The first two events pertain to IP interfaces, and occur when an IP interface is assigned an address (via DHCP or statically) or an address is removed (via DHCP lease expiry). These events are delivered via routing socket and converted into NWAM events.

7.4.2 Datalink Events

The next four events provide information about datalinks. First are the two LINK_STATE events, which indicate layer 2 connection to or disconnect from a network: either the cable has been plugged in/unplugged in the case of an 802.3 link, or a connection to a wlan has been made/lost to the case of an 802.11 link. nwamd receives these events via a libdlpi(3LIB) notification callback.

The LINK_CREATE and LINK_DESTROY events are generated when a sysevent indicating that a NIC has been inserted or removed, or a non-physical link has been created/destroyed. NIC hotplug events are reported by EC_DEV_ADD and EC_DEV_REMOVE events of subclass ESC_NETWORK; non-physical link events are reported via EC_DLADM sysevents of subclass DLADM_EV_ADD, DLADM_EV_REMOVE, and DLADM_EV_RENAME.

7.4.3 Wireless Notification Events

Event clients that wish to receive information regarding wireless configuration should use the *_REPORT events. The SCAN_REPORT event supplies the results of wireless scans; while the CONNECTION_REPORT event is a notification of successful connection to a wireless network. This report includes information, such as signal strength, about the connected wlan.

7.4.4 NO_MAGIC Event

The NO_MAGIC event is an indication that nwamd cannot determine the next action to take in configuring a specific NCU; thus, it needs more information from the user.

One example would be the case where nwamd finds that there is one wireless AP, broadcasting essid "ap7", which is not in the preferred wlan list. Thus nwamd cannot connect to this wlan. In this case, nwamd will send a NO_MAGIC event to advertise the fact that it needs more information from the user (is it okay to connect to this AP?) in order to proceed. If the user chooses to go forward with the connection, the UI can update the preferred essid list in the configuration repository; this update will cause NWAM to reevaluate its configuration and determine that it can now proceed with configuration of the wireless NCU.

Our philosophy for dealing with this situation is that nwamd will send the NO_MAGIC event to any registered listeners (which will typically be UIs) indicating that nwamd is trying to configure an NCU, but has reached a point where it cannot proceed without additional information. The name of the NCU in question and the type of problem will be sent with the NO_MAGIC event. After successfully sending the event, nwamd will mark the NCU as 'waiting-for-response' and go on with its work without blocking on or otherwise waiting for a response to the NO_MAGIC event.

Multiple clients can register and receive NO_MAGIC events, including GUI and CLI programs. How they go about getting the information needed is up to the client. After information is obtained from the user, the client will simply update the NWAM configuration database and poke nwamd to reread its configuration. At this point, with the updated information, nwamd may be able to make more progress in configuring the NCU.

Returning to the original example: a GUI receiving the NO_MAGIC event indicating that no preferred wlan is available may choose to pop up a window notifying the user of this condition. The user may simply dismiss the window and ignore the event; or the user may choose to go ahead and connect to ap7. In the former case, no configuration updates will take place, and the NCU will not progress out of the 'waiting-for-response' state. In the latter case, the configuration update will cause nwamd to restart configuration of the NCU, and this time will find ap7 in the preferred list, and will be able to connect to this wlan.

7.5 nwamd as Policy Engine

The reason nwamd needs to collect, dispatch and handle events relating to links, locations and ENMs is of course to implement as much of the desired configuration policy as is possible given current system state. The structures NWAM deals in, NCUs, Locations and ENMs, are used to describe desired configurations and circumstances under which they should be (de-)activated. Of course, the system realities may preclude a complete application of policy (a NIC card may have been removed, or a cable unplugged, etc). More significantly, the goal of NWAM is to respond to changes in circumstances and reconfigure as needed; for example if a VPN tunnel appears, we may wish to change to a "work" profile, and the location used will effect the necessary changes, enabling the appropriate name services, etc.

Examples of policy engine behavior include:

• NCU contingencies: NCU activation can be specified to be contingent on specified conditions, as described above. Contingencies are created on NCU creation/modification
• Locations: Locations also specify conditions for activation, but these can be more complex, e.g. "apply when a network with IP addresses in the range 129.144.0.0/12 is detected". Events coming into nwamd trigger location (re-)evaluation.

Need to fill in state machine details here. Specific items that need to be included:

• Need to take into account what DL_NOTE_LINK_{UP|DOWN} notifications mean for wireless vs. wired links.

7.5.N Preventing Automatic Unload of WiFi Drivers

At present, NWAM plumbs IP on all available datalinks on the system. This is done in part to prevent WiFi drivers from being automatically unloaded if their module reference count is zero, which will happen periodically. If a WiFi device has successfully connected and associated with an AP, unloading can still occur, and it has the unfortunate side-effect of losing all WiFi configuration preferences associated with the device, so a successful association with an AP can be lost.

Moving forward, we would like to remove this dependency on IP plumbing, as it violates one of the key aims of Clearview, which is to separate the datalink and IP layer functionality cleanly.

CR 6684460 wifi drivers must not unload while connected ultimately needs to be fixed, with dladm_wlan_connect() holding a reference to the driver which is released by dladm_wlan_disconnect(). Another possible approach mentioned was to have detach entrypoints for WiFi drivers fail with EBUSY if connected, but this would involve modifying all WiFi driver source - it seems that a framework-based approach is more feasible.

Some application-level options are available in the short term:

1. We will be using DLPI for wired links to get link status notifications via dlpi_enabnotify() anyway, so we could simply dlpi_open() the WiFi datalinks too for their lifetime. This should be enough to ensure the drivers aren't unloaded.
2. We make nwamd explicitly load the drivers for all WiFi devices via modctl() - the equivalent of modload'ing the drivers in other words. This has the side-effect of setting MOD_NOAUTOUNLOAD for the driver in question, which prevents auto-unloading occurring. This would allow us to have the flexibility of not plumbing IP on all datalinks, while being sure that there is no danger of losing WiFi connections.

Option 1 is the simplest, since we will need to dlpi_open() wired datalinks anyway in order to get link notifications, so that will be the short-term approach taken.

Revision History