README revision 6ba597c56d749c61b4f783157f63196d7b2445f0
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox UserCDDL HEADER START
6fe48fb46e53ffc37542853a1edb74cb481b7d94Automatic UpdaterThe contents of this file are subject to the terms of the
c7fd128f8ea8a527fe27c1b95ab46df7155bc8e4Tinderbox UserCommon Development and Distribution License (the "License").
c7fd128f8ea8a527fe27c1b95ab46df7155bc8e4Tinderbox UserYou may not use this file except in compliance with the License.
1f9754245cbd5eec2d2a667bb292f62f72386d4bMark AndrewsYou can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsSee the License for the specific language governing permissions
1f9754245cbd5eec2d2a667bb292f62f72386d4bMark Andrewsand limitations under the License.
1ca2cf024391992fe14b2df7d3ae0f575d074452Evan HuntWhen distributing Covered Code, include this CDDL HEADER in each
0726d872f6f36901ea09321df57084614e5bb6faTinderbox Userfile and include the License file at usr/src/OPENSOLARIS.LICENSE.
1ca2cf024391992fe14b2df7d3ae0f575d074452Evan HuntIf applicable, add the following below this CDDL HEADER, with the
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox Userfields enclosed by brackets "[]" replaced with your own identifying
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox Userinformation: Portions Copyright [yyyy] [name of copyright owner]
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCDDL HEADER END
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsCopyright 2010 Sun Microsystems, Inc. All rights reserved.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsUse is subject to license terms.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsImplementation Overview for the NetWork AutoMagic daemon
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark AndrewsJohn Beck, Renee Danson, Michael Hunter, Alan Maguire, Kacheong Poon,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsGarima Tripathi, Jan Xie, Anurag Maskey
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews[Structure and some content shamelessly stolen from Peter Memishian's
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsdhcpagent architecture overview.]
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsDetails about the NWAM requirements, architecture, and design are
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsavailable via the NWAM opensolaris project at
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewshttp://opensolaris.org/os/project/nwam. The point of this document is
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userto place details relevant to somebody attempting to understand the
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsimplementation close to the source code.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsSOURCE FILE ORGANIZATION
415d630b6309922caee8469384a6fab75cf05032Mark Andrews=======================
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsevent sources:
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox Userobject-specific event handlers:
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewslegacy config upgrade
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsgeneric code:
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updaternwam door requests:
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsHere we discuss the essential objects and subtle aspects of the NWAM
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsdaemon implementation. Note that there is of course much more that is
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsnot discussed here, but after this overview you should be able to fend
eabc9c3c07cd956d3c436bd7614cb162dabdda76Mark Andrewsfor yourself in the source code.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark AndrewsEvents and Objects
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User==================
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox UserEvents come to NWAM from a variety of different sources asyncronously.
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrewso routing socket
2ae159b376dac23870d8005563c585acf85a4b5aEvan HuntRouting sockets and dlpi (DL_NOTE_LINK_UP|DOWN events) are handled by
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsdedicated threads. Sysevents and doors are both seen as callbacks into
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsthe process proper and will often post their results to the main event
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userqueue. All event sources post events onto the main event queue. In
2ae159b376dac23870d8005563c585acf85a4b5aEvan Huntaddition state changes of objects and door requests (requesting current
7cc0a5d21ef046bfd630c4769943d896a7d7472cTinderbox Userstate or a change of state, specification of a WiFi key etc) can
3ccf87473f7cf6d9faac156df38a935a238f96fdTinderbox Userlead to additional events. We have daemon-internal events (object
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsinitialization, periodic state checks) which are simply enqueued
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Useron the event queue, and external events which are both enqueued on
551e6d2414c4f47d58a9bb0b37f206f915a4f5acTinderbox Userthe event queue and sent to registered listeners (via nwam_event_send()).
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox UserSo the structure of the daemon is a set of threads that drive event
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsgeneration. Events are posted either directly onto the event queue
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Useror are delayed by posting onto the pending event queue. SIGALARMs
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userare set for the event delay, and when the SIGALARM is received
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewspending events that have expired are moved onto the event queue
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrewsproper. Delayed enqueueing is useful for periodic checks.
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox UserDecisions to change conditions based upon object state changes are
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userdelayed until after bursts of events. This is achieved by marking a
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsflag when it is deemed checking is necessary and then the next time the
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsqueue is empty performing those checks. A typical event profile will
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafssonbe one event (e.g. a link down) causing a flurry of other events (e.g.
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsrelated interface down). By waiting until all the consequences of the
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsinitial event have been carried out to make higher level decisions we
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userimplicitly debounce those higher level decisions.
415d630b6309922caee8469384a6fab75cf05032Mark AndrewsAt the moment queue quiet actually means that the queue has been quiet
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrewsfor some short period of time (.1s). Typically the flurry of events we
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewswant to work through are internally generated and are back to back in
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userthe queue. We wait a bit longer in case there are reprucussions from
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewswhat we do that cause external events to be posted on us. We are not
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsinterested in waiting for longer term things to happen but merely to
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafssoncatch immediate changes.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark AndrewsWhen running, the daemon will consist of a number of threads:
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewso the event handling thread: a thread blocking until events appear on the
415d630b6309922caee8469384a6fab75cf05032Mark Andrews event queue, processing each event in order. Events that require
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson time-consuming processing are spawned in worker threads (e.g. WiFi
415d630b6309922caee8469384a6fab75cf05032Mark Andrews connect, DHCP requests etc).
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewso door request threads: the door infrastructure manages server threads
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox User which process synchronous NWAM client requests (e.g. get state of an
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews object, connect to a specific WLAN, initiate a scan on a link etc).
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrewso various wifi/IP threads: threads which do asynchronous work such as
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews DHCP requests, WLAN scans etc that cannot hold up event processing in
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews the main event handling thread.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewso routing socket threads: process routing socket messages of interest
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews (address additons/deletions) and package them as NWAM messages.
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewso dlpi threads: used to monitor for DL_NOTE_LINK messages on links
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsThe daemon is structured around a set of objects representing NCPs[1],
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsNCUs[2], ENMs[3] and known WLANs and a set of state machines which
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrewsconsume events which act on those objects. Object lists are maintained
2a31bd531072824ef252c18303859d6af7451b00Francis Dupontfor each object type, and these contain both a libnwam handle (to allow
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsreading the object directly) and an optional object data pointer which
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewscan point to state information used to configure the object.
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsEvents can be associated with specific objects (e.g. link up), or associated
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewswith no object in particular (e.g. shutdown).
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsEach object type registers a set of event handler functions with the event
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsframework such that when an event occurs, the appropriate handler for the
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsobject type is used. The event handlers are usually called
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsnwamd_handle_*_event().
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrews[1] NCP Network Configuration Profile; the set of link- and IP-layer
7f9e2fff07b9c17e0d7a0ea7abc9304ce9d01b61Tinderbox Userconfiguration units which collectively specify how a system should be
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsconnected to the network
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews[2] NCU Network Configuration Unit; the individual components of an NCP
66317da170ed35b08f5847db2d48b225826327cbTinderbox User[3] ENM External Network Modifiers; user executable scripts often used
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsto configure a VPN
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsDoors and External Events
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews=========================
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox UserThe command interface to nwamd is thread a door at NWAM_DOOR
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews(/etc/svc/volatile/nwam/nwam_door). This door allows external program to send
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsmessages to nwamd. The way doors work is to provide a mechanism for
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updateranother process to execute code in your process space. This looks like
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsa CSPish send/receive/reply in that the receiving process provide a
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Usersyncronization point (via door_create(3C)), the calling process uses
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsthat syncronization point to rendezvous with and provide arguments (via
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsdoor_call(3C), and then the receive process reply (via
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updaterdoor_return(3C))) passing back data as required. The OS makes it such
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsthat the memory used to pass data via door_call(3C) is mapped into the
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsreceiving process which can write back into it and then transparently
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userhave it mapped back to the calling process.
415d630b6309922caee8469384a6fab75cf05032Mark AndrewsAs well as handling internal events of interest, the daemon also needs
fa0326cc2cf428f67575b6ba3b97b528a31b0010Tinderbox Userto send events of interest (link up/down, WLAN scan/connect results etc)
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsto (possibly) multiple NWAM client listeners. This is done via
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark AndrewsSystem V message queues. On registering for events via a libnwam door
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userrequest into the daemon (nwam_events_register()), a per-client
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews(identified by pid) message queue file is created. The
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsdaemon sends messages to all listeners by examining the list of
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updatermessage queue files (allowing registration to be robust across
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsdaemon restarts) and sending events to each listener. This is done
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsvia the libnwam function nwam_event_send() which hides the IPC
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Usermechanism from the daemon.
415d630b6309922caee8469384a6fab75cf05032Mark AndrewsFour object lists are maintained within the daemon - one each for
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsthe configuration objects libnwam manages. i.e.:
415d630b6309922caee8469384a6fab75cf05032Mark Andrewso NCUs of the current active NCP
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox UserObjects have an associated libnwam handle and an optional data
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsfield (which is used for NCUs only).
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic UpdaterLocking is straightforward - nwamd_object_init() will initialize
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsan object of a particular type in the appropriate object list,
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsreturning it with the object lock held. When it is no longer needed,
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Usernwamd_object_unlock() should be called on the object.
415d630b6309922caee8469384a6fab75cf05032Mark AndrewsTo retrieve an existing object, nwamd_object_find() should be
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafssoncalled - again this returns the object in a locked state.
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsnwamd_object_lock() is deliberately not exposed outside of objects.c,
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Usersince object locking is implicit in the above creation/retrieval
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox UserAn object is removed from the object list (with handle destroyed)
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsvia nwamd_object_fini() - the object data (if any) is returned
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsfrom this call to allow deallocation.
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox Usernwamd deals with 3 broad types of object that need to maintain
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox Userinternal state: NCUs, ENMs and locations (known WLANs are configuration
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox Userobjects but don't have a state beyond simply being present).
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsNWAM objects all share a basic set of states:
5b3dd19d815f0389d566d20c2fee57cb37d1dd47Tinderbox UserState Description
1fce11b1d3f2d461d261156b8cdc64ab864f06a9Tinderbox User===== ===========
fab54780409846f7c71f6026d665f18c77c649efTinderbox Useruninitialized object representation not present on system or in nwamd
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsinitialized object representation present in system and in nwamd
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox Userdisabled disabled manually
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsoffline external conditions are not satisfied
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox Useroffline* external conditions are satisfied, trying to move online
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsonline* external conditions no longer satisfied, trying to move offline
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsonline conditions satisfied and configured
689fb19ba11ed40363cbc031d0396befdb409b89Tinderbox Usermaintenance error occurred in applying configuration
8927a982bde7e4b665966b55f0fa57c5cf21b9d8Mark AndrewsThese deliberately mimic SMF states.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsThe states of interest are offline, offline* and online.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsAn object (link/interface NCU, ENM or location) should only move online
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewswhen its conditions are satisfied _and_ its configuration has been successfully
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsapplied. This occurs when an ENM method has run or a link is up, or an
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsinterface has at least one address assigned.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsTo understand the distinction between offline and offline*, consider the case
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewswhere a link is of prioritized activation, and either is a lower priority
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsgroup - and hence inactive (due to cable being unplugged or inability to
361967ea970ea8f0ef8875e769505ecdac74bfb0Tinderbox Userconnect to wifi) - or a higher priority group - and hence active. In general,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewswe want to distinguish between two cases:
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews1) when we are actively configuring the link with a view to moving online
c317b09bf112121245fafe61f38b95dc6e96acabTinderbox User(offline*), as would be the case when the link's priority group is
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews2) when external policy-based conditions prevent a link from being active.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsoffline should be used for such cases. Links in priority groups above and
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsbelow the currently-active group will be offline, since policy precludes them
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsfrom activating (as less-prioritized links).
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsSo we see that offline and offline* can thus be used to distinguish between
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewscases that have the potentiality to move online (offline*) from a policy
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsperspective - i.e. conditions on the location allow it, or link prioritization
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsallows it - and cases where external conditions dictate that it should not
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsOnce an object reaches offline*, its configuration processes should kick in.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsThis is where auxiliary state is useful, as it allows us to distinguish between
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsvarious states in that configuration process. For example, a link can be
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewswaiting for WLAN selection or key data, or an interface can be waiting for
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsDHCP response. This auxiliary state can then also be used diagnostically by
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewslibnwam consumers to determine the current status of a link, interface, ENM
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsWiFi links present a problem however. On the one hand, we want them
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsto be inactive when they are not part of the current priority grouping,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewswhile on the other we want to watch out for new WLANs appearing in
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsscan data if the WiFi link is of a higher priority than the currently-selected
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsgroup. The reason we watch out for these is they represent the potential
a2c370ca12bb0360ff7e969474ead3f788c65fffTinderbox Userto change priority grouping to a more preferred group. To accommodate this,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsWiFi links of the same or lower (more preferred) priority group will always
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsbe trying to connect (and thus be offline* if they cannot).
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsIt might appear unnecessary to have a separate state value/machine for
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsauxiliary state - why can't we simply add the auxiliary state machine to the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsglobal object state machine? Part of the answer is that there are times we
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsneed to run through the same configuration state machine when the global
2ca9cf1582ae972f8edc2b03bd846973b05dee6bTinderbox Userobject state is different - in paticular either offline* or online. Consider
e1ebc476b08b4a498fcf3477e42c986eb1991360Tinderbox UserWiFi - we want to do periodic scans to find a "better" WLAN - we can easily
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsdo this by running back through the link state machine of auxiliary
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox Userstates, but we want to stay online while we do it, since we are still
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsconnected (if the WLAN disconnects of course we go to LINK_DOWN and offline).
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsAnother reason we wish to separate the more general states (offline, online
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsetc) from the more specific ones (WIFI_NEED_SELECTION etc) is to ensure
076e51f1ff9497ae61a99994189ed8bf5a0d3472Tinderbox Userthat the representation of configuration objects closely matches the way
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsFor an NCU physical link, the following link-specific auxiliary states are
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox UserAuxiliary state Description
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson=============== ===========
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox UserLINK_WIFI_SCANNING Scan in progress
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox UserLINK_WIFI_NEED_SELECTION Need user to specify WLAN
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsLINK_WIFI_NEED_KEY Need user to specify a WLAN key for selection
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsLINK_WIFI_CONNECTING Connecting to current selection
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsA WiFI link differs from a wired one in that it always has the
6c2a76b3e2ccd32c35814b6e0f54da00190749d7Evan Huntpotential to be available - it just depends if visited WLANs are in range.
b886b04d8d2b085cbf3e1bf4442dee87f43ba5e4Tinderbox UserSo such links - if they are higher in the priority grouping than the
3ccf87473f7cf6d9faac156df38a935a238f96fdTinderbox Usercurrently-active priority group - should always be able to scan, as they
3857cb6fcabeb79d85de4b3e3e4ab99912b701f8Mark Andrewsare always "trying" to be activated.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsWired links that do not support DL_NOTE_LINK_UP/DOWN are problematic,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewssince we have to simply assume a cable is plugged in. If an IP NCU
415d630b6309922caee8469384a6fab75cf05032Mark Andrewsis activated above such a link, and that NCU uses DHCP, a timeout
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafssonwill be triggered eventually (user-configurable via the nwamd/ncu_wait_time
415d630b6309922caee8469384a6fab75cf05032Mark AndrewsSMF property of the network/physical:nwam instance) which will cause
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsus to give up on the link.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsFor an IP interface NCU, the following auxiliary states are suggested.
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark AndrewsAuxiliary state Description
8292deab031e7599cd7622aa7675fbe139ca6095Mark Andrews=============== ===========
c1e2310a3725eeed45e5e7c86750c64c5a02e993Francis DupontNWAM_AUX_STATE_IF_WAITING_FOR_ADDR Waiting for an address to be assigned
4b61b671f5de767ec1d1b8e6cf7b849bddf08e98Tinderbox UserNWAM_AUX_STATE_IF_DHCP_TIMED_OUT DHCP timed out on interface
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark AndrewsA link can have multiple logical interfaces plumbed on it consisting
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupontof a mix of static and DHCP-acquired addresses. This means that
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewswe need to decide how to aggregate the state of these logical
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsinterfaces into the NCU state. The concept of "up" we use here
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsdoes not correspond to IFF_UP or IFF_RUNNING, but rather
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupontwhen we get (via getting RTM_NEWADDR events with non-zero
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsaddresses) at least one address assigned to the link.
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark AndrewsWe use this concept of up as it represents the potential for
f1a2709aad7baa4161fdb6f63edf99b0150af252Evan Huntnetwork communication - e.g. after assigning a static
f1a2709aad7baa4161fdb6f63edf99b0150af252Evan Huntaddress, if the location specifies nameserver etc, it
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsis possible to communicate over the network. One important
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrewsedge case here is that when DHCP information comes
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsin, we need to reassess location activation conditions and
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewspossibly change or reapply the current location. The problem
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrewsis that if we have a static/DHCP mix, and if we rely on
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsthe IP interface's notion of "up" to trigger location activation,
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updaterwe will likely first apply the location when the static address
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewshas been assigned and before the DHCP information has
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsbeen returned (which may include nameserver info). So
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userthe solution is that on getting an RTM_NEWADDR, we
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewscheck if the (logical) interface associated is DHCP, and
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewseven if the interface NCU is already up, we reassess
e8fc8c884b44371784805e1e0d3100da403dd3f1Automatic Updaterlocation activation. This will lead to a reapplication of
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsthe current location or possibly a location switch.
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox UserIn order to move through the various states, a generic
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsAPI is supplied
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsnwamd_object_set_state(nwamd_object_t obj, nwamd_state_t state,
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews nwamd_aux_state_t aux_state);
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsThis function creates an OBJECT_STATE event containing
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsthe new state/aux_state and enqueues it in the event
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsqueue. Each object registers its own handler for this
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsevent, and in response to the current state/aux state and
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsdesired aux state it responds appropriately in the event
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Userhandling thread, spawning other threads to carry out
dedefc0bdbb4e6e39eeb98aa2fc6883efec2ddb0Mark Andrewsactions as appropriate. The object state event is
ab833877278ad5535eef57e4f62291becaea5bc5Mark Andrewsthen sent to any registered listeners.
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark AndrewsSo for NCUs, we define a handle_object_state() function
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsto run the state machine for the NCU object.
168cf0ede1cf13a095e48af6749d88fbc432f096Evan HuntLink state and NCP policy
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews=========================
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark AndrewsNCPs can be either:
3bd8b5a8fb126e45c67ff53b68183c889cc27918Tinderbox Usero prioritized: where the constituent link NCUs specify priority group
ab833877278ad5535eef57e4f62291becaea5bc5Mark Andrews numbers (where lower are more favoured) and grouping types. These
3bd8b5a8fb126e45c67ff53b68183c889cc27918Tinderbox User are used to allow link NCUs to be either grouped separately (exclusive)
168cf0ede1cf13a095e48af6749d88fbc432f096Evan Hunt or together (shared or all).
ab833877278ad5535eef57e4f62291becaea5bc5Mark Andrewso manual: their activation is governed by the value of their enabled
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark Andrewso a combination of the above.
1f9754245cbd5eec2d2a667bb292f62f72386d4bMark AndrewsIP interface NCUs interit their activation from the links below them,
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark Andrewsso an IP interface NCU will be active if its underlying link is (assuming
8927a982bde7e4b665966b55f0fa57c5cf21b9d8Mark Andrewsit hasn't been disabled).
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark AndrewsAt startup, and at regular intervals (often triggered by NWAM
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark Andrewsevents), the NCP policy needs to be reassessed. There
8927a982bde7e4b665966b55f0fa57c5cf21b9d8Mark Andrewsare a number of causes for NCP policy to be reassessed -
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark Andrewso a periodic check of link state that occurs every N seconds
4840ef4581a577a29a18d180b6bc2e7355378ed7Mark Andrewso a link goes from offline(*) to online (cable plug/wifi connect)
bcfc5188be220e1334218dfe638dffce4744e792Tinderbox Usero a link goes from online to offline (cable unplug/wifi disconnect).
8927a982bde7e4b665966b55f0fa57c5cf21b9d8Mark AndrewsAny of these should cause the link selecton algorithm to rerun.
ab833877278ad5535eef57e4f62291becaea5bc5Mark AndrewsThe link selection algorithm works as follows:
ab833877278ad5535eef57e4f62291becaea5bc5Mark AndrewsStarting from the lowest priority grouping value, assess all links
ab833877278ad5535eef57e4f62291becaea5bc5Mark Andrewsin that priority group.
ab833877278ad5535eef57e4f62291becaea5bc5Mark AndrewsThe current priority-group is considered failed if:
3bd8b5a8fb126e45c67ff53b68183c889cc27918Tinderbox Usero "exclusive" NCUs exist and none are offline*/online,
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox Usero "shared" NCUs exist and none are offline*/online,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewso "all" NCUs exist and all are not offline*/online,
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewso no NCUs are offline*/online.
fab54780409846f7c71f6026d665f18c77c649efTinderbox UserWe do not invalidate a link that is offline* since its configuration
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsis in progress. This has the unfortunate side-effect that
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewswired links that do not do DL_NOTE_LINK_UP/DOWN will never
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsfail. If such links wish to be skipped, their priority group value
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsshould be increased (prioritizing wireless links).
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark AndrewsOne a priority group has been selected, all links in groups above
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews_and_ below it need to be moved offline.
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsLocation Activation
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson===================
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsA basic set of system-supplied locations are supplied - NoNet and
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark AndrewsAutomatic. nwamd will apply the NoNet location until such a time
9218b940febade3085fd6d95a15e67d5f94833f0Tinderbox Useras an interface NCU is online, at which point it will switch
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsto the Automatic location. If a user-supplied location is supplied,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsand it is either manually enabled or its conditions are satisfied, it
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrewswill be preferred and activated instead. Only one location can be
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsactive at once since each location has its own specification of nameservices
3a988722ad9e209ba4064604d482dc4efe0e19ebTinderbox UserENM Activation
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian Wellington==============
9e3a7b0faf417a10f5f689edf288807b2d5eedc5Brian WellingtonENMs are either manual or conditional in activation and will be
e1ebc476b08b4a498fcf3477e42c986eb1991360Tinderbox Useractivated if they are enabled (manual) or if the conditions
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrewsare met (conditional). Multiple ENMs can be active at once.