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, 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 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.