home | help
NG_ETHER(4)		     Kernel Interfaces Manual		     NG_ETHER(4)

NAME
     ng_ether -- Ethernet netgraph node type

SYNOPSIS
     #include <netgraph/ng_ether.h>

DESCRIPTION
     The  ether  netgraph  node type allows Ethernet interfaces to interact with
     the netgraph(4) networking subsystem.  Once the ng_ether module  is  loaded
     into  the	kernel, a node is automatically created for each Ethernet inter-
     face in the system.  Each node will attempt to name itself  with  the  same
     name as the associated interface.

     Three hooks are supported: lower, upper, and orphans.  The hook name divert
     may be used as an alias for lower, and is provided for backward compatibil-
     ity.  In reality, the two names represent the same hook.

     The lower hook is a connection to the raw Ethernet device.  When connected,
     all incoming packets are forwarded to this hook, instead of being passed to
     the  kernel  for upper layer processing.  Writing to this hook results in a
     raw Ethernet frame being transmitted by the device.  Normal outgoing  pack-
     ets are not affected by lower being connected.

     The  upper  hook  is  a connection to the upper protocol layers.  When con-
     nected, all outgoing packets are forwarded to this hook, instead  of  being
     transmitted  by the device.  Writing to this hook results in a raw Ethernet
     frame being received by the kernel just as if it had come in over the wire.
     Normal incoming packets are not affected by upper being connected.

     The orphans hook is equivalent to	lower,	except	that  only  unrecognized
     packets  (that would otherwise be discarded) are written to the hook, while
     other normal incoming traffic is unaffected.  Unrecognized packets  written
     to upper will be forwarded back out to orphans if connected.

     In all cases, frames are raw Ethernet frames with the standard 14 byte Eth-
     ernet header (but no checksum).

     When  no  hooks  are connected, upper and lower are in effect connected to-
     gether, so that packets flow normally upwards and downwards.

HOOKS
     This node type supports the following hooks:

     lower    Connection to the lower device link layer.

     upper    Connection to the upper protocol layers.

     orphans  Like lower, but only receives unrecognized packets.

CONTROL MESSAGES
     This node type supports the generic control messages, plus the following:

     NGM_ETHER_GET_IFNAME (getifname)
	     Returns the name of the associated interface  as  a  NUL-terminated
	     ASCII string.  Normally this is the same as the name of the node.

     NGM_ETHER_GET_IFINDEX (getifindex)
	     Returns  the  global  index of the associated interface as a 32 bit
	     integer.

     NGM_ETHER_GET_ENADDR (getenaddr)
	     Returns the device's unique six byte Ethernet address.

     NGM_ETHER_SET_ENADDR (setenaddr)
	     Sets the device's unique six byte Ethernet address.   This  control
	     message  is  equivalent  to using the SIOCSIFLLADDR ioctl(2) system
	     call.

     NGM_ETHER_SET_PROMISC (setpromisc)
	     Enable or disable promiscuous mode.  This message includes a single
	     32 bit integer flag that enables or disables  promiscuous	mode  on
	     the interface.  Any non-zero value enables promiscuous mode.

     NGM_ETHER_GET_PROMISC (getpromisc)
	     Get the current value of the node's promiscuous flag.  The returned
	     value  is	always either one or zero.  Note that this flag reflects
	     the node's own promiscuous setting and does not necessarily reflect
	     the promiscuous state of the actual interface,  which  can  be  af-
	     fected by other means (e.g., bpf(4)).

     NGM_ETHER_SET_AUTOSRC (setautosrc)
	     Sets  the automatic source address override flag.	This message in-
	     cludes a single 32 bit integer flag that causes all outgoing  pack-
	     ets  to  have  their source Ethernet address field overwritten with
	     the device's unique Ethernet address.  If this flag is set to zero,
	     the source address in outgoing packets is not  modified.	The  de-
	     fault setting for this flag is disabled.

     NGM_ETHER_GET_AUTOSRC (getautosrc)
	     Get  the  current value of the node's source address override flag.
	     The returned value is always either one or zero.

     NGM_ETHER_ADD_MULTI (addmulti)
	     Join Ethernet multicast group.  This control message is  equivalent
	     to using the SIOCADDMULTI ioctl(2) system call.

     NGM_ETHER_DEL_MULTI (delmulti)
	     Leave Ethernet multicast group.  This control message is equivalent
	     to using the SIOCDELMULTI ioctl(2) system call.

     NGM_ETHER_DETACH (detach)
	     Detach from underlying Ethernet interface and shut down node.

SHUTDOWN
     Upon  receipt  of	the  NGM_SHUTDOWN control message, all hooks are discon-
     nected, promiscuous mode is disabled, and the source address override  flag
     is re-enabled, but the node is not removed.  Node can be shut down only us-
     ing  NGM_ETHER_DETACH control message.  If the interface itself is detached
     (e.g., because of PC Card removal), the node disappears as well.

EXAMPLES
     This command dumps all unrecognized packets received by the  "fxp0"  inter-
     face to standard output decoded in hex and ASCII:

	   nghook -a fxp0: orphans

     This command sends the contents of sample.pkt out the interface "fxp0":

	   cat sample.pkt | nghook fxp0: orphans

     These  commands insert an ng_tee(4) node between the lower and upper proto-
     col layers, which can be used for tracing packet flow, statistics, etc.:

	   ngctl mkpeer fxp0: tee lower right
	   ngctl connect fxp0: lower upper left

SEE ALSO
     arp(4), netgraph(4), netintro(4), ifconfig(8), ngctl(8), nghook(8)

AUTHORS
     Julian Elischer <julian@FreeBSD.org>
     Archie Cobbs <archie@FreeBSD.org>

BUGS
     The automatic KLD module loading mechanism that works for most  other  Net-
     graph node types does not work for the ether node type, because ether nodes
     are  not  created on demand; instead, they are created when Ethernet inter-
     faces are attached or when the KLD is first loaded.  Therefore, if the  KLD
     is not statically compiled into the kernel, it is necessary to load the KLD
     manually in order to bring the ether nodes into existence.

FreeBSD 8.2			 August 4, 2006 		     NG_ETHER(4)

home | help