diff options
Diffstat (limited to 'share/man/man4/ng_ether.4')
-rw-r--r-- | share/man/man4/ng_ether.4 | 242 |
1 files changed, 242 insertions, 0 deletions
diff --git a/share/man/man4/ng_ether.4 b/share/man/man4/ng_ether.4 new file mode 100644 index 000000000000..9fd409db00ed --- /dev/null +++ b/share/man/man4/ng_ether.4 @@ -0,0 +1,242 @@ +.\" 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 August 4, 2006 +.Dt NG_ETHER 4 +.Os +.Sh NAME +.Nm ng_ether +.Nd Ethernet netgraph node type +.Sh SYNOPSIS +.In netgraph/ng_ether.h +.Sh DESCRIPTION +The +.Nm ether +netgraph node type allows Ethernet interfaces to interact with +the +.Xr netgraph 4 +networking subsystem. +Once the +.Nm +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. +.Pp +Three hooks are supported: +.Va lower , upper , +and +.Va orphans . +The hook name +.Va divert +may be used as an alias for +.Va lower , +and is provided for backward compatibility. +In reality, the two names represent the same hook. +.Pp +The +.Va 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 +.Va lower +being connected. +.Pp +The +.Va 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 +.Va upper +being connected. +.Pp +The +.Va orphans +hook is equivalent to +.Va 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 +.Va upper +will be forwarded back out to +.Va orphans +if connected. +.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, +.Va upper +and +.Va lower +are in effect connected together, +so that packets flow normally upwards and downwards. +.Sh HOOKS +This node type supports the following hooks: +.Bl -tag -width ".Va orphans" +.It Va lower +Connection to the lower device link layer. +.It Va upper +Connection to the upper protocol layers. +.It Va orphans +Like +.Va lower , +but only receives unrecognized packets. +.El +.Sh CONTROL MESSAGES +This node type supports the generic control messages, plus the following: +.Bl -tag -width indent +.It Dv NGM_ETHER_GET_IFNAME Pq Li getifname +Returns the name of the associated interface as a +.Dv NUL Ns -terminated +.Tn ASCII +string. +Normally this is the same as the name of the node. +.It Dv NGM_ETHER_GET_IFINDEX Pq Li getifindex +Returns the global index of the associated interface as a 32 bit integer. +.It Dv NGM_ETHER_GET_ENADDR Pq Li getenaddr +Returns the device's unique six byte Ethernet address. +.It Dv NGM_ETHER_SET_ENADDR Pq Li setenaddr +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 Pq Li 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. +.It Dv NGM_ETHER_GET_PROMISC Pq Li 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., +.Xr bpf 4 ) . +.It Dv NGM_ETHER_SET_AUTOSRC Pq Li 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. +.It Dv NGM_ETHER_GET_AUTOSRC Pq Li getautosrc +Get the current value of the node's source address override flag. +The returned value is always either one or zero. +.It Dv NGM_ETHER_ADD_MULTI Pq Li addmulti +Join Ethernet multicast group. +This control message is equivalent to using the +.Dv SIOCADDMULTI +.Xr ioctl 2 +system call. +.It Dv NGM_ETHER_DEL_MULTI Pq Li delmulti +Leave Ethernet multicast group. +This control message is equivalent to using the +.Dv SIOCDELMULTI +.Xr ioctl 2 +system call. +.It Dv NGM_ETHER_DETACH Pq Li detach +Detach from underlying Ethernet interface and shut down node. +.El +.Sh SHUTDOWN +Upon receipt of the +.Dv 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 +.Dv NGM_ETHER_DETACH +control message. +If the interface itself is detached (e.g., because of PC Card removal), the +node disappears as well. +.Sh EXAMPLES +This command dumps all unrecognized packets received by the +.Dq Li fxp0 +interface to standard output decoded in hex and +.Tn ASCII : +.Pp +.Dl "nghook -a fxp0: orphans" +.Pp +This command sends the contents of +.Pa sample.pkt +out the interface +.Dq Li fxp0 : +.Pp +.Dl "cat sample.pkt | nghook fxp0: orphans" +.Pp +These commands insert an +.Xr ng_tee 4 +node between the +.Va lower +and +.Va 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 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 +.Sh BUGS +The automatic KLD module loading mechanism that works for most +other Netgraph node types does not work for the +.Nm ether +node type, +because +.Nm 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 +.Nm ether +nodes into existence. |