6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyCDDL HEADER START
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyThe contents of this file are subject to the terms of the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyCommon Development and Distribution License (the "License").
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyYou may not use this file except in compliance with the License.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyYou can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeySee the License for the specific language governing permissions
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyand limitations under the License.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyWhen distributing Covered Code, include this CDDL HEADER in each
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyfile and include the License file at usr/src/OPENSOLARIS.LICENSE.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyIf applicable, add the following below this CDDL HEADER, with the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyfields enclosed by brackets "[]" replaced with your own identifying
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyinformation: Portions Copyright [yyyy] [name of copyright owner]
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyCDDL HEADER END
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyCopyright 2010 Sun Microsystems, Inc. All rights reserved.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyUse is subject to license terms.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyImplementation Overview for the NetWork AutoMagic daemon
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyJohn Beck, Renee Danson, Michael Hunter, Alan Maguire, Kacheong Poon,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyGarima Tripathi, Jan Xie, Anurag Maskey
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey[Structure and some content shamelessly stolen from Peter Memishian's
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydhcpagent architecture overview.]
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyDetails about the NWAM requirements, architecture, and design are
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyavailable via the NWAM opensolaris project at
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyhttp://opensolaris.org/os/project/nwam. The point of this document is
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyto place details relevant to somebody attempting to understand the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyimplementation close to the source code.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeySOURCE FILE ORGANIZATION
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey=======================
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyevent sources:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyobject-specific event handlers:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeylegacy config upgrade
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeynwam door requests:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyHere we discuss the essential objects and subtle aspects of the NWAM
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydaemon implementation. Note that there is of course much more that is
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeynot discussed here, but after this overview you should be able to fend
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyfor yourself in the source code.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyEvents and Objects
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey==================
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyEvents come to NWAM from a variety of different sources asyncronously.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo routing socket
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyRouting sockets and dlpi (DL_NOTE_LINK_UP|DOWN events) are handled by
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydedicated threads. Sysevents and doors are both seen as callbacks into
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythe process proper and will often post their results to the main event
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyqueue. All event sources post events onto the main event queue. In
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyaddition state changes of objects and door requests (requesting current
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeystate or a change of state, specification of a WiFi key etc) can
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeylead to additional events. We have daemon-internal events (object
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyinitialization, periodic state checks) which are simply enqueued
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyon the event queue, and external events which are both enqueued on
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythe event queue and sent to registered listeners (via nwam_event_send()).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeySo the structure of the daemon is a set of threads that drive event
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeygeneration. Events are posted either directly onto the event queue
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyor are delayed by posting onto the pending event queue. SIGALARMs
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyare set for the event delay, and when the SIGALARM is received
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeypending events that have expired are moved onto the event queue
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyproper. Delayed enqueueing is useful for periodic checks.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyDecisions to change conditions based upon object state changes are
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydelayed until after bursts of events. This is achieved by marking a
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyflag when it is deemed checking is necessary and then the next time the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyqueue is empty performing those checks. A typical event profile will
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeybe one event (e.g. a link down) causing a flurry of other events (e.g.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyrelated interface down). By waiting until all the consequences of the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyinitial event have been carried out to make higher level decisions we
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyimplicitly debounce those higher level decisions.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAt the moment queue quiet actually means that the queue has been quiet
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyfor some short period of time (.1s). Typically the flurry of events we
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywant to work through are internally generated and are back to back in
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythe queue. We wait a bit longer in case there are reprucussions from
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywhat we do that cause external events to be posted on us. We are not
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyinterested in waiting for longer term things to happen but merely to
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeycatch immediate changes.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyWhen running, the daemon will consist of a number of threads:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo the event handling thread: a thread blocking until events appear on the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey event queue, processing each event in order. Events that require
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey time-consuming processing are spawned in worker threads (e.g. WiFi
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey connect, DHCP requests etc).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo door request threads: the door infrastructure manages server threads
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey which process synchronous NWAM client requests (e.g. get state of an
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey object, connect to a specific WLAN, initiate a scan on a link etc).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo various wifi/IP threads: threads which do asynchronous work such as
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey DHCP requests, WLAN scans etc that cannot hold up event processing in
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey the main event handling thread.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo routing socket threads: process routing socket messages of interest
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey (address additons/deletions) and package them as NWAM messages.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo dlpi threads: used to monitor for DL_NOTE_LINK messages on links
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyThe daemon is structured around a set of objects representing NCPs[1],
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyNCUs[2], ENMs[3] and known WLANs and a set of state machines which
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyconsume events which act on those objects. Object lists are maintained
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyfor each object type, and these contain both a libnwam handle (to allow
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyreading the object directly) and an optional object data pointer which
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeycan point to state information used to configure the object.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyEvents can be associated with specific objects (e.g. link up), or associated
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywith no object in particular (e.g. shutdown).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyEach object type registers a set of event handler functions with the event
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyframework such that when an event occurs, the appropriate handler for the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyobject type is used. The event handlers are usually called
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeynwamd_handle_*_event().
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey[1] NCP Network Configuration Profile; the set of link- and IP-layer
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyconfiguration units which collectively specify how a system should be
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyconnected to the network
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey[2] NCU Network Configuration Unit; the individual components of an NCP
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey[3] ENM External Network Modifiers; user executable scripts often used
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyto configure a VPN
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyDoors and External Events
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey=========================
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyThe command interface to nwamd is thread a door at NWAM_DOOR
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey(/etc/svc/volatile/nwam/nwam_door). This door allows external program to send
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeymessages to nwamd. The way doors work is to provide a mechanism for
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyanother process to execute code in your process space. This looks like
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeya CSPish send/receive/reply in that the receiving process provide a
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeysyncronization point (via door_create(3C)), the calling process uses
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythat syncronization point to rendezvous with and provide arguments (via
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydoor_call(3C), and then the receive process reply (via
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydoor_return(3C))) passing back data as required. The OS makes it such
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythat the memory used to pass data via door_call(3C) is mapped into the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyreceiving process which can write back into it and then transparently
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyhave it mapped back to the calling process.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAs well as handling internal events of interest, the daemon also needs
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyto send events of interest (link up/down, WLAN scan/connect results etc)
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyto (possibly) multiple NWAM client listeners. This is done via
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeySystem V message queues. On registering for events via a libnwam door
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyrequest into the daemon (nwam_events_register()), a per-client
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey(identified by pid) message queue file is created. The
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydaemon sends messages to all listeners by examining the list of
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeymessage queue files (allowing registration to be robust across
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydaemon restarts) and sending events to each listener. This is done
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyvia the libnwam function nwam_event_send() which hides the IPC
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeymechanism from the daemon.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyFour object lists are maintained within the daemon - one each for
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythe configuration objects libnwam manages. i.e.:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo NCUs of the current active NCP
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyObjects have an associated libnwam handle and an optional data
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyfield (which is used for NCUs only).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyLocking is straightforward - nwamd_object_init() will initialize
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyan object of a particular type in the appropriate object list,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyreturning it with the object lock held. When it is no longer needed,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeynwamd_object_unlock() should be called on the object.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyTo retrieve an existing object, nwamd_object_find() should be
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeycalled - again this returns the object in a locked state.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeynwamd_object_lock() is deliberately not exposed outside of objects.c,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeysince object locking is implicit in the above creation/retrieval
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAn object is removed from the object list (with handle destroyed)
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyvia nwamd_object_fini() - the object data (if any) is returned
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyfrom this call to allow deallocation.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeynwamd deals with 3 broad types of object that need to maintain
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyinternal state: NCUs, ENMs and locations (known WLANs are configuration
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyobjects but don't have a state beyond simply being present).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyNWAM objects all share a basic set of states:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyState Description
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey===== ===========
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyuninitialized object representation not present on system or in nwamd
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyinitialized object representation present in system and in nwamd
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydisabled disabled manually
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyoffline external conditions are not satisfied
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyoffline* external conditions are satisfied, trying to move online
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyonline* external conditions no longer satisfied, trying to move offline
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyonline conditions satisfied and configured
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeymaintenance error occurred in applying configuration
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyThese deliberately mimic SMF states.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyThe states of interest are offline, offline* and online.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAn object (link/interface NCU, ENM or location) should only move online
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywhen its conditions are satisfied _and_ its configuration has been successfully
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyapplied. This occurs when an ENM method has run or a link is up, or an
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyinterface has at least one address assigned.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyTo understand the distinction between offline and offline*, consider the case
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywhere a link is of prioritized activation, and either is a lower priority
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeygroup - and hence inactive (due to cable being unplugged or inability to
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyconnect to wifi) - or a higher priority group - and hence active. In general,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywe want to distinguish between two cases:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey1) when we are actively configuring the link with a view to moving online
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey(offline*), as would be the case when the link's priority group is
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey2) when external policy-based conditions prevent a link from being active.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyoffline should be used for such cases. Links in priority groups above and
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeybelow the currently-active group will be offline, since policy precludes them
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyfrom activating (as less-prioritized links).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeySo we see that offline and offline* can thus be used to distinguish between
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeycases that have the potentiality to move online (offline*) from a policy
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyperspective - i.e. conditions on the location allow it, or link prioritization
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyallows it - and cases where external conditions dictate that it should not
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyOnce an object reaches offline*, its configuration processes should kick in.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyThis is where auxiliary state is useful, as it allows us to distinguish between
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyvarious states in that configuration process. For example, a link can be
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywaiting for WLAN selection or key data, or an interface can be waiting for
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyDHCP response. This auxiliary state can then also be used diagnostically by
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeylibnwam consumers to determine the current status of a link, interface, ENM
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyWiFi links present a problem however. On the one hand, we want them
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyto be inactive when they are not part of the current priority grouping,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywhile on the other we want to watch out for new WLANs appearing in
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyscan data if the WiFi link is of a higher priority than the currently-selected
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeygroup. The reason we watch out for these is they represent the potential
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyto change priority grouping to a more preferred group. To accommodate this,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyWiFi links of the same or lower (more preferred) priority group will always
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeybe trying to connect (and thus be offline* if they cannot).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyIt might appear unnecessary to have a separate state value/machine for
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyauxiliary state - why can't we simply add the auxiliary state machine to the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyglobal object state machine? Part of the answer is that there are times we
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyneed to run through the same configuration state machine when the global
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyobject state is different - in paticular either offline* or online. Consider
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyWiFi - we want to do periodic scans to find a "better" WLAN - we can easily
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydo this by running back through the link state machine of auxiliary
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeystates, but we want to stay online while we do it, since we are still
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyconnected (if the WLAN disconnects of course we go to LINK_DOWN and offline).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAnother reason we wish to separate the more general states (offline, online
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyetc) from the more specific ones (WIFI_NEED_SELECTION etc) is to ensure
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythat the representation of configuration objects closely matches the way
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyFor an NCU physical link, the following link-specific auxiliary states are
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAuxiliary state Description
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey=============== ===========
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyLINK_WIFI_SCANNING Scan in progress
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyLINK_WIFI_NEED_SELECTION Need user to specify WLAN
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyLINK_WIFI_NEED_KEY Need user to specify a WLAN key for selection
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyLINK_WIFI_CONNECTING Connecting to current selection
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyA WiFI link differs from a wired one in that it always has the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeypotential to be available - it just depends if visited WLANs are in range.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeySo such links - if they are higher in the priority grouping than the
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeycurrently-active priority group - should always be able to scan, as they
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyare always "trying" to be activated.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyWired links that do not support DL_NOTE_LINK_UP/DOWN are problematic,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeysince we have to simply assume a cable is plugged in. If an IP NCU
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyis activated above such a link, and that NCU uses DHCP, a timeout
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywill be triggered eventually (user-configurable via the nwamd/ncu_wait_time
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeySMF property of the network/physical:nwam instance) which will cause
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyus to give up on the link.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyFor an IP interface NCU, the following auxiliary states are suggested.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAuxiliary state Description
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey=============== ===========
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyNWAM_AUX_STATE_IF_WAITING_FOR_ADDR Waiting for an address to be assigned
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyNWAM_AUX_STATE_IF_DHCP_TIMED_OUT DHCP timed out on interface
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyA link can have multiple logical interfaces plumbed on it consisting
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyof a mix of static and DHCP-acquired addresses. This means that
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywe need to decide how to aggregate the state of these logical
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyinterfaces into the NCU state. The concept of "up" we use here
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydoes not correspond to IFF_UP or IFF_RUNNING, but rather
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywhen we get (via getting RTM_NEWADDR events with non-zero
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyaddresses) at least one address assigned to the link.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyWe use this concept of up as it represents the potential for
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeynetwork communication - e.g. after assigning a static
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyaddress, if the location specifies nameserver etc, it
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyis possible to communicate over the network. One important
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyedge case here is that when DHCP information comes
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyin, we need to reassess location activation conditions and
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeypossibly change or reapply the current location. The problem
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyis that if we have a static/DHCP mix, and if we rely on
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythe IP interface's notion of "up" to trigger location activation,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywe will likely first apply the location when the static address
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyhas been assigned and before the DHCP information has
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeybeen returned (which may include nameserver info). So
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythe solution is that on getting an RTM_NEWADDR, we
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeycheck if the (logical) interface associated is DHCP, and
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyeven if the interface NCU is already up, we reassess
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeylocation activation. This will lead to a reapplication of
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythe current location or possibly a location switch.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyIn order to move through the various states, a generic
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAPI is supplied
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeynwamd_object_set_state(nwamd_object_t obj, nwamd_state_t state,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey nwamd_aux_state_t aux_state);
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyThis function creates an OBJECT_STATE event containing
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythe new state/aux_state and enqueues it in the event
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyqueue. Each object registers its own handler for this
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyevent, and in response to the current state/aux state and
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeydesired aux state it responds appropriately in the event
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyhandling thread, spawning other threads to carry out
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyactions as appropriate. The object state event is
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeythen sent to any registered listeners.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeySo for NCUs, we define a handle_object_state() function
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyto run the state machine for the NCU object.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyLink state and NCP policy
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey=========================
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyNCPs can be either:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo prioritized: where the constituent link NCUs specify priority group
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey numbers (where lower are more favoured) and grouping types. These
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey are used to allow link NCUs to be either grouped separately (exclusive)
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey or together (shared or all).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo manual: their activation is governed by the value of their enabled
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo a combination of the above.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyIP interface NCUs interit their activation from the links below them,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyso an IP interface NCU will be active if its underlying link is (assuming
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyit hasn't been disabled).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAt startup, and at regular intervals (often triggered by NWAM
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyevents), the NCP policy needs to be reassessed. There
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyare a number of causes for NCP policy to be reassessed -
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo a periodic check of link state that occurs every N seconds
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo a link goes from offline(*) to online (cable plug/wifi connect)
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo a link goes from online to offline (cable unplug/wifi disconnect).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAny of these should cause the link selecton algorithm to rerun.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyThe link selection algorithm works as follows:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyStarting from the lowest priority grouping value, assess all links
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyin that priority group.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyThe current priority-group is considered failed if:
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo "exclusive" NCUs exist and none are offline*/online,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo "shared" NCUs exist and none are offline*/online,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo "all" NCUs exist and all are not offline*/online,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyo no NCUs are offline*/online.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyWe do not invalidate a link that is offline* since its configuration
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyis in progress. This has the unfortunate side-effect that
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywired links that do not do DL_NOTE_LINK_UP/DOWN will never
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyfail. If such links wish to be skipped, their priority group value
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyshould be increased (prioritizing wireless links).
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyOne a priority group has been selected, all links in groups above
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey_and_ below it need to be moved offline.
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyLocation Activation
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey===================
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyA basic set of system-supplied locations are supplied - NoNet and
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyAutomatic. nwamd will apply the NoNet location until such a time
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyas an interface NCU is online, at which point it will switch
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyto the Automatic location. If a user-supplied location is supplied,
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyand it is either manually enabled or its conditions are satisfied, it
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeywill be preferred and activated instead. Only one location can be
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyactive at once since each location has its own specification of nameservices
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyENM Activation
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskey==============
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. MaskeyENMs are either manual or conditional in activation and will be
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyactivated if they are enabled (manual) or if the conditions
6ba597c56d749c61b4f783157f63196d7b2445f0Anurag S. Maskeyare met (conditional). Multiple ENMs can be active at once.