Google is committed to advancing racial equity for Black communities. See how.

fuchsia.net.neighbor

Overview of fuchsia.net.neighbor

The neighbor table helps decide where to send IP packets. It allows for the translation between IP addresses and MAC addresses.

With current implementations, the neighbor table uses the ARP or NDP protocol to dynamically discover new neighbor entries for IPv4 or IPv6 addresses, respectively.

This library enables inspection and manipulation of the neighbor table.

  • See View for viewing neighbor table entries and interface configuration.
  • See Controller for adding static neighbor table entries, removing entries, and updating interface configuration.

Important Concepts

InterfaceID is an identifier for a network interface. Identifiers are assigned and managed by the networking stack. They are the same interface identifiers used by fuchsia.net.stack.

Entry represents a neighboring device and is stored in the neighbor table, which is also managed by the networking stack.

UnreachabilityConfig holds the various parameters used for tweaking the behavior of Neighbor Unreachability Detection (NUD). This allows implementations to operate over links with widely varying performance characteristics.

Privacy Considerations

The Neighbor API deals with MAC addresses, which are device identifiers and should not be exposed to most applications. There are separate protocols for inspecting and modifying the neighbor table; this is done to protect sensitive data.

Security Considerations

The Neighbor API enables clients to view and manipulate the neighbor table, which should both be privileged actions and granted only to trusted applications. Additionally, not all clients will need both read and write access. This has been addressed by splitting methods into two protocols: Viewer for read methods and Controller for write methods.

This API is not concerned with throttling consumption of ARP or NDP messages. If a DoS of ARP/NDP packets reaches this API, the damage had already been done. Once the packets reach the control plane, they are processed by the networking stack where the DoS would first manifest.

PROTOCOLS

Controller

Defined in fuchsia.net.neighbor/neighbor.fidl

Modify the neighbor table and related interface configuration.

AddEntry

Create a static entry. If a conflict is found, overwrite the existing entry. Conflicts occur when two entries have the same interface identifier and IP address.

  • request interface identifier for the interface used for communicating with the neighbor.
  • request neighbor IP address of the neighbor.
  • request mac MAC address of the neighbor.
  • error ZX_ERR_NOT_FOUND if interface does not exist.
  • error ZX_ERR_IO_REFUSED if interface does not keep a neighbor table (e.g. point-to-point links).

Request

NameType
interface InterfaceID
neighbor fuchsia.net/IpAddress
mac fuchsia.hardware.ethernet/MacAddress

Response

NameType
result Controller_AddEntry_Result

ClearEntries

Delete all dynamic and static entries belonging to an interface.

  • request interface identifier for the interface associated with the entries to be deleted.
  • error ZX_ERR_NOT_FOUND if interface does not exist.
  • error ZX_ERR_IO_REFUSED if interface does not keep a neighbor table (e.g. point-to-point links).

Request

NameType
interface InterfaceID

Response

NameType
result Controller_ClearEntries_Result

RemoveEntry

Delete a dynamic or static entry.

  • request interface identifier for the interface associated with the entry to be deleted.
  • request neighbor IP address of the entry to be deleted.
  • error ZX_ERR_NOT_FOUND if no entries match interface and neighbor.
  • error ZX_ERR_IO_REFUSED if interface does not keep a neighbor table (e.g. point-to-point links).

Request

NameType
interface InterfaceID
neighbor fuchsia.net/IpAddress

Response

NameType
result Controller_RemoveEntry_Result

UpdateUnreachabilityConfig

Change the configuration of the neighbor discovery algorithm for an interface.

  • request config used for updating the configuration for an interface. Only the specified fields will be changed. All other fields will remain the same as the original configuration.
  • error ZX_ERR_NOT_FOUND if config references an interface that does not exist.
  • error ZX_ERR_IO_REFUSED if config references an interface that does not keep a neighbor table (e.g. point-to-point links).
  • error ZX_ERR_INVALID_ARGS if config contains an invalid value, see UnreachabilityConfig for the list of constraints.

Request

NameType
config InterfaceUnreachabilityConfig

Response

NameType
result Controller_UpdateUnreachabilityConfig_Result

EntryIterator

Defined in fuchsia.net.neighbor/entry-iterator.fidl

Returns entries and events from the neighbor table. Clients can open an iterator using the View.EntryIterator method.

An atomic snapshot of the neighbor table is queued for clients upon opening an EntryIterator. This snapshot consists of existing entries followed by an IdleEvent. No other types of events will be sent before an IdleEvent.

If EntryIteratorOptions.watch_for_changes was set to true, state change events will be queued after the IdleEvent; otherwise, the channel is closed after returning the IdleEvent.

GetNext

Take items from the iterator. If no items are available, block until one is; otherwise, return immediately with items queued since the last invocation.

This does not guarantee that, when blocking, only one item will be returned; implementations may debounce or batch events.

Attempt to maintain one in-flight GetNext call as much as possible. If GetNext is not constantly polled, the networking stack might hit an upper limit on the number of buffered events, resulting in dropping. Should this happen, this connection will be closed with a ZX_ERR_IO_OVERRUN epitaph.

If there is more than one in-flight GetNext call, callers are put into a queue and will receive responses in FIFO order.

When the networking stack is terminated, this connection will be closed with a ZX_ERR_PEER_CLOSED epitaph.

  • response events a list of events that occurred since the last invocation of this method.

Request

NameType

Response

NameType
events vector<EntryIteratorItem>[314]

View

Defined in fuchsia.net.neighbor/neighbor.fidl

Inspect the neighbor table and related interface configuration.

GetUnreachabilityConfigs

View the current configurations of all interfaces.

Request

NameType

Response

NameType
configs vector<InterfaceUnreachabilityConfig>[259]

OpenEntryIterator

Open a connection to an EntryIterator for listing existing entries and optionally watching for state changes.

  • request it request the server to bind an implementation of EntryIterator to this channel.
  • request options modifies the behavior of the EntryIterator.

Request

NameType
it request<EntryIterator>
options EntryIteratorOptions

STRUCTS

Controller_AddEntry_Response

Defined in fuchsia.net.neighbor/neighbor.fidl

NameTypeDescriptionDefault

Controller_ClearEntries_Response

Defined in fuchsia.net.neighbor/neighbor.fidl

NameTypeDescriptionDefault

Controller_RemoveEntry_Response

Defined in fuchsia.net.neighbor/neighbor.fidl

NameTypeDescriptionDefault

Controller_UpdateUnreachabilityConfig_Response

Defined in fuchsia.net.neighbor/neighbor.fidl

NameTypeDescriptionDefault

IdleEvent

Defined in fuchsia.net.neighbor/entry-iterator.fidl

Empty event for indicating there are no more EntryIteratorItem.existing items to yield.

NameTypeDescriptionDefault

InterfaceUnreachabilityConfig

Defined in fuchsia.net.neighbor/neighbor.fidl

Configuration stored on a per-interface basis for the operation of Neighbor Unreachability Detection (NUD), as defined by RFC 4861 section 7.3.

NameTypeDescriptionDefault
interface InterfaceID

Identifier for the interface affected by this configuration.

No default
config UnreachabilityConfig

Configuration for the operation of Neighbor Unreachability Detection.

No default

TABLES

DelayState

Defined in fuchsia.net.neighbor/entry-state.fidl

OrdinalNameTypeDescription

Entry

Defined in fuchsia.net.neighbor/entry.fidl

Information on a neighboring device in the local network.

There are two types of entries available in the neighbor table.

  1. Dynamic entries are discovered automatically by neighbor discovery protocols (e.g. ARP, NDP). These protocols will attempt to reconfirm reachability with the device once its state becomes EntryState.stale.
  2. Static entries are explicitly added by a user with Controller.AddStaticEntry and have no expiration. Their state is always EntryState.static.
OrdinalNameTypeDescription
1 interface InterfaceID

Identifier for the interface used for communicating with the neighbor.

2 neighbor fuchsia.net/IpAddress

IP address of the neighbor.

3 state EntryState

State of the entry within the Neighbor Unreachability Detection (NUD) state machine defined by RFC 4861 section 7.3.

4 mac fuchsia.hardware.ethernet/MacAddress

MAC address of the neighboring device's network interface controller. Absent for dynamic entries in EntryState.incomplete.

5 updated_at zx/time

Timestamp when this entry has changed state.

EntryIteratorOptions

Defined in fuchsia.net.neighbor/entry-iterator.fidl

Options for modifying the behavior of an EntryIterator.

OrdinalNameTypeDescription
1 watch_for_changes bool

Changes the behavior of the EntryIterator to watch for state changes in the neighbor table after opening the iterator. State change events will only be queued after the IdleEvent.

Defaults to false.

IncompleteState

Defined in fuchsia.net.neighbor/entry-state.fidl

OrdinalNameTypeDescription

ProbeState

Defined in fuchsia.net.neighbor/entry-state.fidl

OrdinalNameTypeDescription

ReachableState

Defined in fuchsia.net.neighbor/entry-state.fidl

OrdinalNameTypeDescription
1 expires_at zx/time

When reachability expires and the entry should be considered stale; when to transition from reachable to stale EntryState.

This is not the only way to transition into EntryState.stale. The entry will transition into stale before this time when an unsolicited reachability confirmation is received with a different MAC address than the one cached.

StaleState

Defined in fuchsia.net.neighbor/entry-state.fidl

OrdinalNameTypeDescription

StaticState

Defined in fuchsia.net.neighbor/entry-state.fidl

OrdinalNameTypeDescription

UnreachabilityConfig

Defined in fuchsia.net.neighbor/unreachability-config.fidl

Configuration options related to the operation of Neighbor Unreachability Detection (NUD), as defined by RFC 4861 section 7.3.

Field names loosely follow RFC 4861 sections 6.3.2 and 10, any deviations are noted. Descriptions are kept implementation-independent by using a set of generic terminology.

,-------------------------------------------------------------------. | Generic Term | ARP Protocol | NDP Protocol | |---------------------------+--------------+------------------------| | Reachability Probe | ARP Request | Neighbor Solicitation | | Reachability Confirmation | ARP Reply | Neighbor Advertisement | `---------------------------+--------------+------------------------'

OrdinalNameTypeDescription
1 base_reachable_time zx/duration

A base duration for computing the random reachable time.

Reachable time is the duration for which a neighbor is considered reachable after a positive reachability confirmation is received. It is a function of a uniformly distributed random value between min_random_factor and max_random_factor multiplied by base_reachable_time. Using a random component eliminates the possibility that Neighbor Unreachability Detection messages will synchronize with each other.

After this time, an entry will transition from REACHABLE to STALE state.

Referred to as "BaseReachableTime" by RFC 4861.

Must be greater than 0.

2 learn_base_reachable_time bool

Learn base_reachable_time during runtime from the neighbor discovery protocol, if supported.

3 min_random_factor float32

The minimum value of the random factor used for computing reachable time.

See base_reachable_time for more information on computing the reachable time.

Must be greater than 0.

4 max_random_factor float32

The maximum value of the random factor used for computing reachable time.

See base_reachable_time for more information on computing the reachable time.

Must be greater than or equal to min_random_factor.

5 retransmit_timer zx/duration

Duration between retransmissions of reachability probes in the PROBE state.

Referred to as "RetransTimer" by RFC 4861.

Must be greater than 0.

6 learn_retransmit_timer bool

Learn retransmit_timer during runtime from the neighbor discovery protocol, if supported.

7 delay_first_probe_time zx/duration

Duration to wait for a non-Neighbor-Discovery related protocol to reconfirm reachability after entering the DELAY state. After this time, a reachability probe will be sent and the entry will transition to the PROBE state.

Must be greater than 0.

8 max_multicast_probes uint32

The number of reachability probes to send before concluding negative reachability and deleting the entry from the INCOMPLETE state.

Referred to as "MAX_MULTICAST_SOLICIT" by RFC 4861.

Must be greater than 0.

9 max_unicast_probes uint32

The number of reachability probes to send before concluding retransmissions from within the PROBE state should cease and the entry SHOULD be deleted.

Referred to as "MAX_UNICAST_SOLICIT" by RFC 4861.

Must be greater than 0.

10 max_anycast_delay_time zx/duration

If the target address is an anycast address, the stack SHOULD delay sending a response for a random time between 0 and this duration.

11 max_reachability_confirmations uint32

A node MAY send up to this amount of unsolicited reachability confirmations messages to all-nodes multicast address when a node determines its link-layer address has changed.

Referred to as "MAX_NEIGHBOR_ADVERTISEMENT" by RFC 4861.

UNIONS

Controller_AddEntry_Result

Defined in fuchsia.net.neighbor/neighbor.fidl

NameTypeDescription
response Controller_AddEntry_Response
err zx/status

Controller_ClearEntries_Result

Defined in fuchsia.net.neighbor/neighbor.fidl

NameTypeDescription
response Controller_ClearEntries_Response
err zx/status

Controller_RemoveEntry_Result

Defined in fuchsia.net.neighbor/neighbor.fidl

NameTypeDescription
response Controller_RemoveEntry_Response
err zx/status

Controller_UpdateUnreachabilityConfig_Result

Defined in fuchsia.net.neighbor/neighbor.fidl

NameTypeDescription
response Controller_UpdateUnreachabilityConfig_Response
err zx/status

EntryIteratorItem

Defined in fuchsia.net.neighbor/entry-iterator.fidl

Items returned from EntryIterator.GetNext.

NameTypeDescription
existing Entry

An existing entry in the neighbor table. Does not indicate that an event occurred.

idle IdleEvent

Event indicating the iterator will no longer return existing items.

added Entry

Event indicating an entry has been added into the neighbor table.

changed Entry

Event indicating an entry has been changed EntryState.

removed Entry

Event indicating an entry has been removed from the neighbor table.

EntryState

Defined in fuchsia.net.neighbor/entry-state.fidl

Neighbor table entry state.

Modeled after RFC 4861 section 7.3.2. Descriptions are kept implementation-independent by using a set of generic terminology.

,------------------------------------------------------------------. | Generic Term | ARP Term | NDP Term | |---------------------------+-------------+------------------------| | Reachability Probe | ARP Request | Neighbor Solicitation | | Reachability Confirmation | ARP Reply | Neighbor Advertisement | `---------------------------+-------------+------------------------'

NameTypeDescription
incomplete IncompleteState

Reachability is in the process of being confirmed for a newly created, non-static entry.

reachable ReachableState

Positive reachability has been confirmed; the path to the neighbor is functioning properly.

stale StaleState

Reachability is considered unknown.

Occurs in one of two ways:

  1. Too much time has elapsed since the last positive reachability confirmation was received.
  2. Received a reachability confirmation from a neighbor with a different MAC address than the one cached.
delay DelayState

A packet was recently sent while reachability was considered unknown.

This state is an optimization that gives non-Neighbor-Discovery related protocols time to confirm reachability after the last confirmation of reachability has expired due to lack of recent traffic.

probe ProbeState

A reachability confirmation is actively sought by periodically retransmitting reachability probes until a reachability confirmation is received, or until the max amount of probes has been sent.

static StaticState

Static entries are explicitly added with Controller.AddEntry. They do not expire and are not deleted until explicitly removed with Controller.RemoveEntry.

CONSTANTS

NameValueTypeDescription
DEFAULT_BASE_REACHABLE_TIME 30000000000 int64

Default value for UnreachabilityConfig.base_reachable_time as recommended by RFC 4861 section 10.

DEFAULT_DELAY_FIRST_PROBE_TIME 5000000000 int64

Default value for UnreachabilityConfig.delay_first_probe_time as recommended by RFC 4861 section 10.

DEFAULT_MAX_ANYCAST_DELAY_TIME 1000000000 int64

Default value for UnreachabilityConfig.max_anycast_delay_time as recommended by RFC 4861 section 10.

DEFAULT_MAX_MULITCAST_PROBES 3 uint32

Default value for UnreachabilityConfig.max_multicast_probes as recommended by RFC 4861 section 10.

DEFAULT_MAX_RANDOM_FACTOR 1.5 float32

Default value for UnreachabilityConfig.max_random_factor as recommended by RFC 4861 section 10.

DEFAULT_MAX_REACHABILITY_CONFIRMATIONS 3 uint32

Default value for UnreachabilityConfig.max_reachability_confirmations as recommended by RFC 4861 section 10.

DEFAULT_MAX_UNICAST_PROBES 3 uint32

Default value for UnreachabilityConfig.max_unicast_probes as recommended by RFC 4861 section 10.

DEFAULT_MIN_RANDOM_FACTOR 0.5 float32

Default value for UnreachabilityConfig.min_random_factor as recommended by RFC 4861 section 10.

DEFAULT_RETRANSMIT_TIMER 1000000000 int64

Default value for UnreachabilityConfig.retransmit_timer as recommended by RFC 4861 section 10.

MAX_INTERFACE_CONFIG_BATCH_SIZE 259 uint64

The maximum number of InterfaceUnreachabilityConfig returned in a View.GetUnreachabilityConfigs response.

MAX_ITEM_BATCH_SIZE 314 uint64

The maximum number of EntryIteratorItem returned in a EntryIterator.GetNext response.

TYPE ALIASES

NameValueDescription
InterfaceID uint64

An opaque identifier for an interface, assigned by the networking stack. This identifier will never be 0, and will not be reused even if the device is removed and subsequently re-added. It is not stable across netstack instances.

These identifiers can be retrieved using fuchsia.net.stack/Stack.ListInterfaces.