Ubuntu Manpage: ng_ether — Ethernet netgraph node type

Provided by: freebsd-manpages_9.2+1-1_all

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

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.

Debian                                            June 23, 2011                                      NG_ETHER(4)