path: root/share/man/man4/ng_ether.4

.\" Copyright (c) 2000 Whistle Communications, Inc.
.\" All rights reserved.
.\" 
.\" Subject to the following obligations and disclaimer of warranty, use and
.\" redistribution of this software, in source or object code forms, with or
.\" without modifications are expressly permitted by Whistle Communications;
.\" provided, however, that:
.\" 1. Any and all reproductions of the source or object code must include the
.\"    copyright notice above and the following disclaimer of warranties; and
.\" 2. No rights are granted, in any manner or form, to use Whistle
.\"    Communications, Inc. trademarks, including the mark "WHISTLE
.\"    COMMUNICATIONS" on advertising, endorsements, or otherwise except as
.\"    such appears in the above copyright notice or in the software.
.\" 
.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND
.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO
.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE,
.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.
.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY
.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS
.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE.
.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES
.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING
.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY,
.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR
.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY
.\" OF SUCH DAMAGE.
.\" 
.\" Author: Archie Cobbs <archie@FreeBSD.org>
.\"
.\" $FreeBSD$
.\"
.Dd June 26, 2000
.Dt NG_ETHER 4
.Os FreeBSD
.Sh NAME
.Nm ng_ether
.Nd Ethernet netgraph node type
.Sh SYNOPSIS
.Fd #include <netgraph/ng_ether.h>
.Sh DESCRIPTION
The
.Nm
netgraph node type allows Ethernet interfaces to interact with
the
.Xr netgraph 4 
networking subsystem.
Once the
.Nm
module is loaded in 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.
All
.Nm
nodes are persistent for as long as the interface itself exists.
.Pp
Three hooks are supported:
.Dv lower ,
.Dv upper ,
and
.Dv orphans .
The hook name
.Dv divert
may be used as an alias for
.Dv lower ,
and is provided for backward compatibility.
In reality the two names represent the same hook.
.Pp
The
.Dv lower
hook is a connection to the raw Ethernet device.
When connected, all incoming packets are diverted out this hook.
Writing to this hook results in a raw Ethernet frame being transmitted
by the device.
Normal outgoing packets are not affected by
.Dv lower
being connected.
.Pp
The
.Dv upper
hook is a connection to the upper protocol layers.
When connected, all outgoing packets are diverted out this hook.
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
.Dv upper
being connected.
.Pp
The
.Dv orphans
hook is equivalent to
.Dv lower ,
except that only unrecognized packets (that would otherwise be discarded)
are written to the hook, and normal incoming traffic is unaffected.
At most one of
.Dv orphans
and
.Dv lower
may be connected at any time.
.Pp
In all cases, frames are raw Ethernet frames with the standard
14 byte Ethernet header (but no checksum).
.Pp
When no hooks are connected,
.Dv upper
and
.Dv lower
are in effect connected together,
so that packets flow normally upwards and downwards.
.Sh HOOKS
This node type supports the following hooks:
.Pp
.Bl -tag -width orphans
.It Dv lower
Connection to the lower device link layer.
.It Dv upper
Connection to the upper protocol layers.
.It Dv orphans
Like
.Dv lower ,
but only receives unrecognized packets.
.El
.Sh CONTROL MESSAGES
This node type supports the generic control messages, plus the following:
.Bl -tag -width foo
.It Dv NGM_ETHER_GET_IFNAME
Returns the name of the associated interface as a NUL-terminated ASCII string.
Normally this is the same as the name of the node.
.It Dv NGM_ETHER_GET_IFINDEX
Returns the global index of the associated interface as a 32 bit integer.
.It Dv NGM_ETHER_GET_ENADDR
Returns the device's unique six byte Ethernet address.
.It Dv NGM_ETHER_SET_ENADDR
Sets the device's unique six byte Ethernet address.
This control message is equivalent to using the
.Dv SIOCSIFLLADDR
.Xr ioctl 2
system call.
.It Dv NGM_ETHER_SET_PROMISC
Enable or disable promiscuous mode.
This message includes a single 32 bit integer flag that enables or
disables promiscuous mode on the interface.
.It Dv NGM_ETHER_GET_PROMISC
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.,
.Xr bpf 4 ) .
.It Dv NGM_ETHER_SET_AUTOSRC
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.
.It Dv NGM_ETHER_GET_AUTOSRC
Get the current value of the node's source address override flag.
The returned value is always either one or zero.
.El
.Sh SHUTDOWN
This node is persistent for as long as the interface exists.
Upon receipt of a
.Dv NGM_SHUTDOWN
control message, all hooks are disconnected, promiscuous mode is disabled,
and the source address override flag is reenabled,
but the node is not removed.
If the interface itself is detached (e.g., because of PCCARD removal), the
node disappears as well.
.Sh EXAMPLES
This command dumps all unrecognized packets received by the
.Dv fxp0
interface to standard output decoded in hex and ASCII:
.Bd -literal -offset indent
nghook -a fxp0: orphans
.Ed
.Pp
This command sends the contents of
.Dv foo.pkt
out the interface
.Dv ed0 :
.Bd -literal -offset indent
cat foo.pkt | nghook fxp0: orphans
.Ed
.Pp
These commands insert an
.Xr ng_tee 4
node between the lower and upper protocol layers, which can be used for
tracing packet flow, statistics, etc.:
.Bd -literal -offset indent
ngctl mkpeer fxp0: tee lower right
ngctl connect fxp0: lower upper left
.Ed
.Sh BUGS
The automatic KLD module loading mechanism that works for most
other netgraph node types does not work for the
.Nm
node type,
because
.Nm
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
.Nm
nodes into existence.
.Sh SEE ALSO
.Xr arp 4 ,
.Xr netgraph 4 ,
.Xr netintro 4 ,
.Xr ifconfig 8 ,
.Xr ngctl 8 ,
.Xr nghook 8
.Sh AUTHORS
.An Julian Elischer Aq julian@FreeBSD.org
.An Archie Cobbs Aq archie@FreeBSD.org