netfilter
firewalling, NAT, and packet mangling for linux
 All Data Structures Namespaces Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Neighbours

The neighbour table establishes bindings between protocol addresses and link layer addresses for hosts sharing the same physical link. More...

Collaboration diagram for Neighbours:

Neighbour Object Allocation/Freeage

struct rtnl_neighrtnl_neigh_alloc (void)
 
void rtnl_neigh_put (struct rtnl_neigh *neigh)
 

Neighbour Cache Managament

int rtnl_neigh_alloc_cache (struct nl_sock *sock, struct nl_cache **result)
 Build a neighbour cache including all neighbours currently configured in the kernel. More...
 
struct rtnl_neighrtnl_neigh_get (struct nl_cache *cache, int ifindex, struct nl_addr *dst)
 Look up a neighbour by interface index and destination address. More...
 

Neighbour Addition

int rtnl_neigh_build_add_request (struct rtnl_neigh *tmpl, int flags, struct nl_msg **result)
 Build netlink request message to add a new neighbour. More...
 
int rtnl_neigh_add (struct nl_sock *sk, struct rtnl_neigh *tmpl, int flags)
 Add a new neighbour. More...
 

Neighbour Deletion

int rtnl_neigh_build_delete_request (struct rtnl_neigh *neigh, int flags, struct nl_msg **result)
 Build a netlink request message to delete a neighbour. More...
 
int rtnl_neigh_delete (struct nl_sock *sk, struct rtnl_neigh *neigh, int flags)
 Delete a neighbour. More...
 

Neighbour States Translations

char * rtnl_neigh_state2str (int state, char *buf, size_t len)
 
int rtnl_neigh_str2state (const char *name)
 

Neighbour Flags Translations

char * rtnl_neigh_flags2str (int flags, char *buf, size_t len)
 
int rtnl_neigh_str2flag (const char *name)
 

Attributes

void rtnl_neigh_set_state (struct rtnl_neigh *neigh, int state)
 
int rtnl_neigh_get_state (struct rtnl_neigh *neigh)
 
void rtnl_neigh_unset_state (struct rtnl_neigh *neigh, int state)
 
void rtnl_neigh_set_flags (struct rtnl_neigh *neigh, unsigned int flags)
 
unsigned int rtnl_neigh_get_flags (struct rtnl_neigh *neigh)
 
void rtnl_neigh_unset_flags (struct rtnl_neigh *neigh, unsigned int flags)
 
void rtnl_neigh_set_ifindex (struct rtnl_neigh *neigh, int ifindex)
 
int rtnl_neigh_get_ifindex (struct rtnl_neigh *neigh)
 
void rtnl_neigh_set_lladdr (struct rtnl_neigh *neigh, struct nl_addr *addr)
 
struct nl_addrrtnl_neigh_get_lladdr (struct rtnl_neigh *neigh)
 
int rtnl_neigh_set_dst (struct rtnl_neigh *neigh, struct nl_addr *addr)
 
struct nl_addrrtnl_neigh_get_dst (struct rtnl_neigh *neigh)
 
void rtnl_neigh_set_family (struct rtnl_neigh *neigh, int family)
 
int rtnl_neigh_get_family (struct rtnl_neigh *neigh)
 
void rtnl_neigh_set_type (struct rtnl_neigh *neigh, int type)
 
int rtnl_neigh_get_type (struct rtnl_neigh *neigh)
 

Detailed Description

The neighbour table establishes bindings between protocol addresses and link layer addresses for hosts sharing the same physical link.

This module allows you to access and manipulate the content of these tables.

Neighbour States
Neighbour Flags
Neighbour Identification
A neighbour is uniquely identified by the attributes listed below, whenever you refer to an existing neighbour all of the attributes must be set. Neighbours from caches automatically have all required attributes set.
Changeable Attributes
Required Caches for Dumping
In order to dump neighbour attributes you must provide the following caches via nl_cache_provide()
  • link cache holding all links
TODO
  • Document proxy settings
  • Document states and their influence
1) Retrieving information about configured neighbours
// The first step is to retrieve a list of all available neighbour within
// the kernel and put them into a cache.
struct nl_cache *cache = rtnl_neigh_alloc_cache(sk);
// Neighbours can then be looked up by the interface and destination
// address:
struct rtnl_neigh *neigh = rtnl_neigh_get(cache, ifindex, dst_addr);
// After successful usage, the object must be given back to the cache
2) Adding new neighbours
// Allocate an empty neighbour handle to be filled out with the attributes
// of the new neighbour.
struct rtnl_neigh *neigh = rtnl_neigh_alloc();
// Fill out the attributes of the new neighbour
rtnl_neigh_set_ifindex(neigh, ifindex);
rtnl_neigh_set_dst(neigh, dst_addr);
// Build the netlink message and send it to the kernel, the operation will
// block until the operation has been completed. Alternatively the required
// netlink message can be built using rtnl_neigh_build_add_request()
// to be sent out using nl_send_auto_complete().
// Free the memory
3) Deleting an existing neighbour
// Allocate an empty neighbour object to be filled out with the attributes
// matching the neighbour to be deleted. Alternatively a fully equipped
// neighbour object out of a cache can be used instead.
struct rtnl_neigh *neigh = rtnl_neigh_alloc();
// Neighbours are uniquely identified by their interface index and
// destination address, you may fill out other attributes but they
// will have no influence.
rtnl_neigh_set_ifindex(neigh, ifindex);
rtnl_neigh_set_dst(neigh, dst_addr);
// Build the netlink message and send it to the kernel, the operation will
// block until the operation has been completed. Alternatively the required
// netlink message can be built using rtnl_neigh_build_delete_request()
// to be sent out using nl_send_auto_complete().
rtnl_neigh_delete(sk, neigh, 0);
// Free the memory
4) Changing neighbour attributes
// Allocate an empty neighbour object to be filled out with the attributes
// matching the neighbour to be changed and the new parameters. Alternatively
// a fully equipped modified neighbour object out of a cache can be used.
struct rtnl_neigh *neigh = rtnl_neigh_alloc();
// Identify the neighbour to be changed by its interface index and
// destination address
rtnl_neigh_set_ifindex(neigh, ifindex);
rtnl_neigh_set_dst(neigh, dst_addr);
// The link layer address may be modified, if so it is wise to change
// its state to "permanent" in order to avoid having it overwritten.
rtnl_neigh_set_lladdr(neigh, lladdr);
// Secondly the state can be modified allowing normal neighbours to be
// converted into permanent entries or to manually confirm a neighbour.
// Build the netlink message and send it to the kernel, the operation will
// block until the operation has been completed. Alternatively the required
// netlink message can be built using rtnl_neigh_build_change_request()
// to be sent out using nl_send_auto_complete().
// Free the memory

Function Documentation

int rtnl_neigh_add ( struct nl_sock sk,
struct rtnl_neigh tmpl,
int  flags 
)

Add a new neighbour.

  • sk Netlink socket.
  • tmpl template with requested changes
  • flags additional netlink message flags

Builds a netlink message by calling rtnl_neigh_build_add_request(), sends the request to the kernel and waits for the next ACK to be received and thus blocks until the request has been fullfilled.

The following attributes must be set in the template:

Returns
0 on sucess or a negative error if an error occured.

References nl_send_auto_complete(), nlmsg_free(), and rtnl_neigh_build_add_request().

Referenced by main().

Here is the call graph for this function:

Here is the caller graph for this function:

struct rtnl_neigh* rtnl_neigh_alloc ( void  )

References nl_object_alloc().

Referenced by nl_cli_neigh_alloc().

Here is the call graph for this function:

Here is the caller graph for this function:

int rtnl_neigh_alloc_cache ( struct nl_sock sock,
struct nl_cache **  result 
)

Build a neighbour cache including all neighbours currently configured in the kernel.

  • sk Netlink socket.
  • result Pointer to store resulting cache.

Allocates a new neighbour cache, initializes it properly and updates it to include all neighbours currently configured in the kernel.

Returns
0 on success or a negative error code.

References nl_cache_alloc_and_fill().

Here is the call graph for this function:

int rtnl_neigh_build_add_request ( struct rtnl_neigh tmpl,
int  flags,
struct nl_msg **  result 
)

Build netlink request message to add a new neighbour.

  • tmpl template with data of new neighbour
  • flags additional netlink message flags
  • result Pointer to store resulting message.

Builds a new netlink message requesting a addition of a new neighbour. The netlink message header isn't fully equipped with all relevant fields and must thus be sent out via nl_send_auto_complete() or supplemented as needed. tmpl must contain the attributes of the new neighbour set via rtnl_neigh_set_* functions.

The following attributes must be set in the template:

Returns
0 on success or a negative error code.

References RTM_NEWNEIGH.

Referenced by rtnl_neigh_add().

Here is the caller graph for this function:

int rtnl_neigh_build_delete_request ( struct rtnl_neigh neigh,
int  flags,
struct nl_msg **  result 
)

Build a netlink request message to delete a neighbour.

  • neigh neighbour to delete
  • flags additional netlink message flags
  • result Pointer to store resulting message.

Builds a new netlink message requesting a deletion of a neighbour. The netlink message header isn't fully equipped with all relevant fields and must thus be sent out via nl_send_auto_complete() or supplemented as needed. neigh must point to an existing neighbour.

Returns
0 on success or a negative error code.

References RTM_DELNEIGH.

Referenced by rtnl_neigh_delete().

Here is the caller graph for this function:

int rtnl_neigh_delete ( struct nl_sock sk,
struct rtnl_neigh neigh,
int  flags 
)

Delete a neighbour.

  • sk Netlink socket.
  • neigh neighbour to delete
  • flags additional netlink message flags

Builds a netlink message by calling rtnl_neigh_build_delete_request(), sends the request to the kernel and waits for the next ACK to be received and thus blocks until the request has been fullfilled.

Returns
0 on sucess or a negative error if an error occured.

References nl_send_auto_complete(), nlmsg_free(), and rtnl_neigh_build_delete_request().

Here is the call graph for this function:

char* rtnl_neigh_flags2str ( int  flags,
char *  buf,
size_t  len 
)

References __flags2str(), and ARRAY_SIZE.

Here is the call graph for this function:

struct rtnl_neigh* rtnl_neigh_get ( struct nl_cache cache,
int  ifindex,
struct nl_addr dst 
)

Look up a neighbour by interface index and destination address.

  • cache neighbour cache
  • ifindex interface index the neighbour is on
  • dst destination address of the neighbour
    Returns
    neighbour handle or NULL if no match was found.

References nl_cache::c_items, rtnl_neigh::n_dst, rtnl_neigh::n_ifindex, nl_addr_cmp(), nl_list_for_each_entry, nl_object_get(), and NULL.

Here is the call graph for this function:

struct nl_addr* rtnl_neigh_get_dst ( struct rtnl_neigh neigh)

References rtnl_neigh::n_dst, and NULL.

int rtnl_neigh_get_family ( struct rtnl_neigh neigh)

References rtnl_neigh::n_family.

Referenced by nl_cli_neigh_parse_dst().

Here is the caller graph for this function:

unsigned int rtnl_neigh_get_flags ( struct rtnl_neigh neigh)

References rtnl_neigh::n_flags.

int rtnl_neigh_get_ifindex ( struct rtnl_neigh neigh)

References rtnl_neigh::n_ifindex.

struct nl_addr* rtnl_neigh_get_lladdr ( struct rtnl_neigh neigh)

References rtnl_neigh::n_lladdr, and NULL.

int rtnl_neigh_get_state ( struct rtnl_neigh neigh)

References rtnl_neigh::n_state.

int rtnl_neigh_get_type ( struct rtnl_neigh neigh)

References rtnl_neigh::n_type.

void rtnl_neigh_put ( struct rtnl_neigh neigh)

References nl_object_put().

Here is the call graph for this function:

int rtnl_neigh_set_dst ( struct rtnl_neigh neigh,
struct nl_addr addr 
)

References rtnl_neigh::n_dst.

Referenced by nl_cli_neigh_parse_dst().

Here is the caller graph for this function:

void rtnl_neigh_set_family ( struct rtnl_neigh neigh,
int  family 
)

References rtnl_neigh::n_family.

Referenced by nl_cli_neigh_parse_family().

Here is the caller graph for this function:

void rtnl_neigh_set_flags ( struct rtnl_neigh neigh,
unsigned int  flags 
)
void rtnl_neigh_set_ifindex ( struct rtnl_neigh neigh,
int  ifindex 
)

References rtnl_neigh::n_ifindex.

Referenced by nl_cli_neigh_parse_dev().

Here is the caller graph for this function:

void rtnl_neigh_set_lladdr ( struct rtnl_neigh neigh,
struct nl_addr addr 
)

References rtnl_neigh::n_lladdr.

Referenced by nl_cli_neigh_parse_lladdr().

Here is the caller graph for this function:

void rtnl_neigh_set_state ( struct rtnl_neigh neigh,
int  state 
)

References rtnl_neigh::n_state, rtnl_neigh::n_state_mask, and state.

Referenced by nl_cli_neigh_parse_state().

Here is the caller graph for this function:

void rtnl_neigh_set_type ( struct rtnl_neigh neigh,
int  type 
)

References rtnl_neigh::n_type, and type.

char* rtnl_neigh_state2str ( int  state,
char *  buf,
size_t  len 
)

References __flags2str(), and ARRAY_SIZE.

Here is the call graph for this function:

int rtnl_neigh_str2flag ( const char *  name)

References __str2type(), and ARRAY_SIZE.

Here is the call graph for this function:

int rtnl_neigh_str2state ( const char *  name)

References __str2type(), and ARRAY_SIZE.

Referenced by nl_cli_neigh_parse_state().

Here is the call graph for this function:

Here is the caller graph for this function:

void rtnl_neigh_unset_flags ( struct rtnl_neigh neigh,
unsigned int  flags 
)
void rtnl_neigh_unset_state ( struct rtnl_neigh neigh,
int  state 
)