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.	All ether nodes	are persistent for as
     long as the interface itself exists.

     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 sin-
	     gle 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 neces-
	     sarily 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
	     packets 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 enabled.

     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.

SHUTDOWN
     This node is persistent for as long as the	corresponding interface
     exists.  Upon receipt of the NGM_SHUTDOWN control message,	all hooks are
     disconnected, promiscuous mode is disabled, and the source	address	over-
     ride flag is re-enabled, but the node is not removed.  If the interface
     itself is detached	(e.g., because of PC Card removal), the	node disap-
     pears 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

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.

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>

FreeBSD	9.3			 May 16, 2004			   FreeBSD 9.3

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

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

home | help