Skip site navigation (1)Skip section navigation (2)

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
NG_ETHER(4)	       FreeBSD 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
     compatibility.  In	reality, the two names represent the same hook.

     The lower hook is a connection to the raw Ethernet	device.	 When con-
     nected, 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 packets 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 Ether-
     net 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
     Ethernet header (but no checksum).

     When no hooks are connected, upper	and lower are in effect	connected
     together, 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 affected
	  by other means (e.g.,	bpf(4)).

     NGM_ETHER_SET_AUTOSRC (setautosrc)
	  Sets the automatic source address override flag.  This message
	  includes 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 default
	  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, but the node	is not removed.	 Node
     can be shut down only using 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''
     interface 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 pro-
     tocol 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
     interfaces	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	10.1			 June 23, 2011			  FreeBSD 10.1

NAME | SYNOPSIS | DESCRIPTION | HOOKS | CONTROL MESSAGES | SHUTDOWN | EXAMPLES | SEE ALSO | AUTHORS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=ng_ether&sektion=4&manpath=FreeBSD+10.1-RELEASE>

home | help