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 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, in
stead of being
passed to the kernel for upper layer processing. Writing to
this hook
results in a raw Ethernet frame being transmitted by the de
vice. 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, in
stead 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 be
ing 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. Unrecog
nized packets
written to upper will be forwarded back out to orphans if
connected.
In all cases, frames are raw Ethernet frames with the stan
dard 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 down
wards.

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 ad
dress.
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 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.
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 mes
sage 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, and the source address
override
flag is re-enabled, but the node is not removed. Node can
be shut down
only using NGM_ETHER_DETACH control message. If the inter
face 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 inter
face ``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, be
cause 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.
BSD February 14, 2005
Copyright © 2010-2024 Platon Technologies, s.r.o.           Home | Man pages | tLDP | Documents | Utilities | About
Design by styleshout