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 interface 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 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 packets are not affected by lower being connected.

     The upper hook is a connection to the upper protocol layers.  When connected, 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 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 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 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 disconnected, 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 protocol 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 Netgraph 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.