1.\" Copyright (c) 2000 Whistle Communications, Inc. 2.\" All rights reserved. 3.\" 4.\" Subject to the following obligations and disclaimer of warranty, use and 5.\" redistribution of this software, in source or object code forms, with or 6.\" without modifications are expressly permitted by Whistle Communications; 7.\" provided, however, that: 8.\" 1. Any and all reproductions of the source or object code must include the 9.\" copyright notice above and the following disclaimer of warranties; and 10.\" 2. No rights are granted, in any manner or form, to use Whistle 11.\" Communications, Inc. trademarks, including the mark "WHISTLE 12.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as 13.\" such appears in the above copyright notice or in the software. 14.\" 15.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND 16.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO 17.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, 18.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF 19.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. 20.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY 21.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS 22.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. 23.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES 24.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING 25.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, 26.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR 27.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY 28.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 29.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 30.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY 31.\" OF SUCH DAMAGE. 32.\" 33.\" Author: Archie Cobbs <archie@FreeBSD.org> 34.\" 35.\" $FreeBSD: src/share/man/man4/ng_ether.4,v 1.4.2.12 2002/04/07 04:57:13 dd Exp $ 36.\" $DragonFly: src/share/man/man4/ng_ether.4,v 1.3 2006/02/17 19:37:09 swildner Exp $ 37.\" 38.Dd June 26, 2000 39.Dt NG_ETHER 4 40.Os 41.Sh NAME 42.Nm ng_ether 43.Nd Ethernet netgraph node type 44.Sh SYNOPSIS 45.In netgraph/ng_ether.h 46.Sh DESCRIPTION 47The 48.Nm 49netgraph node type allows Ethernet interfaces to interact with 50the 51.Xr netgraph 4 52networking subsystem. 53Once the 54.Nm 55module is loaded in the kernel, a node is automatically created 56for each Ethernet interface in the system. 57Each node will attempt to name itself with the same name 58as the associated interface. 59All 60.Nm 61nodes are persistent for as long as the interface itself exists. 62.Pp 63Three hooks are supported: 64.Dv lower , 65.Dv upper , 66and 67.Dv orphans . 68The hook name 69.Dv divert 70may be used as an alias for 71.Dv lower , 72and is provided for backward compatibility. 73In reality the two names represent the same hook. 74.Pp 75The 76.Dv lower 77hook is a connection to the raw Ethernet device. 78When connected, all incoming packets are diverted out this hook. 79Writing to this hook results in a raw Ethernet frame being transmitted 80by the device. 81Normal outgoing packets are not affected by 82.Dv lower 83being connected. 84.Pp 85The 86.Dv upper 87hook is a connection to the upper protocol layers. 88When connected, all outgoing packets are diverted out this hook. 89Writing to this hook results in a raw Ethernet frame being received by 90the kernel just as if it had come in over the wire. 91Normal incoming packets are not affected by 92.Dv upper 93being connected. 94.Pp 95The 96.Dv orphans 97hook is equivalent to 98.Dv lower , 99except that only unrecognized packets (that would otherwise be discarded) 100are written to the hook, and normal incoming traffic is unaffected. 101At most one of 102.Dv orphans 103and 104.Dv lower 105may be connected at any time. 106.Pp 107In all cases, frames are raw Ethernet frames with the standard 10814 byte Ethernet header (but no checksum). 109.Pp 110When no hooks are connected, 111.Dv upper 112and 113.Dv lower 114are in effect connected together, 115so that packets flow normally upwards and downwards. 116.Sh HOOKS 117This node type supports the following hooks: 118.Pp 119.Bl -tag -width orphans 120.It Dv lower 121Connection to the lower device link layer. 122.It Dv upper 123Connection to the upper protocol layers. 124.It Dv orphans 125Like 126.Dv lower , 127but only receives unrecognized packets. 128.El 129.Sh CONTROL MESSAGES 130This node type supports the generic control messages, plus the following: 131.Bl -tag -width foo 132.It Dv NGM_ETHER_GET_IFNAME 133Returns the name of the associated interface as a NUL-terminated ASCII string. 134Normally this is the same as the name of the node. 135.It Dv NGM_ETHER_GET_IFINDEX 136Returns the global index of the associated interface as a 32 bit integer. 137.It Dv NGM_ETHER_GET_ENADDR 138Returns the device's unique six byte Ethernet address. 139.It Dv NGM_ETHER_SET_ENADDR 140Sets the device's unique six byte Ethernet address. 141This control message is equivalent to using the 142.Dv SIOCSIFLLADDR 143.Xr ioctl 2 144system call. 145.It Dv NGM_ETHER_SET_PROMISC 146Enable or disable promiscuous mode. 147This message includes a single 32 bit integer flag that enables or 148disables promiscuous mode on the interface. 149.It Dv NGM_ETHER_GET_PROMISC 150Get the current value of the node's promiscuous flag. 151The returned value is always either one or zero. 152Note that this flag reflects the node's own promiscuous setting 153and does not necessarily reflect the promiscuous state of the actual 154interface, which can be affected by other means (e.g., 155.Xr bpf 4 ) . 156.It Dv NGM_ETHER_SET_AUTOSRC 157Sets the automatic source address override flag. 158This message includes a single 32 bit integer flag that causes 159all outgoing packets to have their source Ethernet 160address field overwritten with the device's unique Ethernet address. 161If this flag is set to zero, the source address in outgoing packets 162is not modified. 163The default setting for this flag is enabled. 164.It Dv NGM_ETHER_GET_AUTOSRC 165Get the current value of the node's source address override flag. 166The returned value is always either one or zero. 167.El 168.Sh SHUTDOWN 169This node is persistent for as long as the interface exists. 170Upon receipt of a 171.Dv NGM_SHUTDOWN 172control message, all hooks are disconnected, promiscuous mode is disabled, 173and the source address override flag is reenabled, 174but the node is not removed. 175If the interface itself is detached (e.g., because of PCCARD removal), the 176node disappears as well. 177.Sh EXAMPLES 178This command dumps all unrecognized packets received by the 179.Dv fxp0 180interface to standard output decoded in hex and ASCII: 181.Bd -literal -offset indent 182nghook -a fxp0: orphans 183.Ed 184.Pp 185This command sends the contents of 186.Dv foo.pkt 187out the interface 188.Dv fxp0 : 189.Bd -literal -offset indent 190cat foo.pkt | nghook fxp0: orphans 191.Ed 192.Pp 193These commands insert an 194.Xr ng_tee 4 195node between the lower and upper protocol layers, which can be used for 196tracing packet flow, statistics, etc.: 197.Bd -literal -offset indent 198ngctl mkpeer fxp0: tee lower right 199ngctl connect fxp0: lower upper left 200.Ed 201.Sh SEE ALSO 202.Xr arp 4 , 203.Xr netgraph 4 , 204.Xr netintro 4 , 205.Xr ifconfig 8 , 206.Xr ngctl 8 , 207.Xr nghook 8 208.Sh AUTHORS 209.An Julian Elischer Aq julian@FreeBSD.org 210.An Archie Cobbs Aq archie@FreeBSD.org 211.Sh BUGS 212The automatic KLD module loading mechanism that works for most 213other netgraph node types does not work for the 214.Nm 215node type, 216because 217.Nm 218nodes are not created on demand; instead, they are created when 219Ethernet interfaces are attached or when the KLD is first loaded. 220Therefore, if the KLD is not statically compiled into the kernel, 221it is necessary to load the KLD manually in order to bring the 222.Nm 223nodes into existence. 224