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.\" 37.Dd June 26, 2000 38.Dt NG_ETHER 4 39.Os 40.Sh NAME 41.Nm ng_ether 42.Nd Ethernet netgraph node type 43.Sh SYNOPSIS 44.In netgraph/ether/ng_ether.h 45.Sh DESCRIPTION 46The 47.Nm 48netgraph node type allows Ethernet interfaces to interact with 49the 50.Xr netgraph 4 51networking subsystem. 52Once the 53.Nm 54module is loaded in the kernel, a node is automatically created 55for each Ethernet interface in the system. 56Each node will attempt to name itself with the same name 57as the associated interface. 58All 59.Nm 60nodes are persistent for as long as the interface itself exists. 61.Pp 62Three hooks are supported: 63.Dv lower , 64.Dv upper , 65and 66.Dv orphans . 67The hook name 68.Dv divert 69may be used as an alias for 70.Dv lower , 71and is provided for backward compatibility. 72In reality the two names represent the same hook. 73.Pp 74The 75.Dv lower 76hook is a connection to the raw Ethernet device. 77When connected, all incoming packets are diverted out this hook. 78Writing to this hook results in a raw Ethernet frame being transmitted 79by the device. 80Normal outgoing packets are not affected by 81.Dv lower 82being connected. 83.Pp 84The 85.Dv upper 86hook is a connection to the upper protocol layers. 87When connected, all outgoing packets are diverted out this hook. 88Writing to this hook results in a raw Ethernet frame being received by 89the kernel just as if it had come in over the wire. 90Normal incoming packets are not affected by 91.Dv upper 92being connected. 93.Pp 94The 95.Dv orphans 96hook is equivalent to 97.Dv lower , 98except that only unrecognized packets (that would otherwise be discarded) 99are written to the hook, and normal incoming traffic is unaffected. 100At most one of 101.Dv orphans 102and 103.Dv lower 104may be connected at any time. 105.Pp 106In all cases, frames are raw Ethernet frames with the standard 10714 byte Ethernet header (but no checksum). 108.Pp 109When no hooks are connected, 110.Dv upper 111and 112.Dv lower 113are in effect connected together, 114so that packets flow normally upwards and downwards. 115.Sh HOOKS 116This node type supports the following hooks: 117.Bl -tag -width orphans 118.It Dv lower 119Connection to the lower device link layer. 120.It Dv upper 121Connection to the upper protocol layers. 122.It Dv orphans 123Like 124.Dv lower , 125but only receives unrecognized packets. 126.El 127.Sh CONTROL MESSAGES 128This node type supports the generic control messages, plus the following: 129.Bl -tag -width foo 130.It Dv NGM_ETHER_GET_IFNAME 131Returns the name of the associated interface as a NUL-terminated ASCII string. 132Normally this is the same as the name of the node. 133.It Dv NGM_ETHER_GET_IFINDEX 134Returns the global index of the associated interface as a 32 bit integer. 135.It Dv NGM_ETHER_GET_ENADDR 136Returns the device's unique six byte Ethernet address. 137.It Dv NGM_ETHER_SET_ENADDR 138Sets the device's unique six byte Ethernet address. 139This control message is equivalent to using the 140.Dv SIOCSIFLLADDR 141.Xr ioctl 2 142system call. 143.It Dv NGM_ETHER_SET_PROMISC 144Enable or disable promiscuous mode. 145This message includes a single 32 bit integer flag that enables or 146disables promiscuous mode on the interface. 147.It Dv NGM_ETHER_GET_PROMISC 148Get the current value of the node's promiscuous flag. 149The returned value is always either one or zero. 150Note that this flag reflects the node's own promiscuous setting 151and does not necessarily reflect the promiscuous state of the actual 152interface, which can be affected by other means (e.g., 153.Xr bpf 4 ) . 154.It Dv NGM_ETHER_SET_AUTOSRC 155Sets the automatic source address override flag. 156This message includes a single 32 bit integer flag that causes 157all outgoing packets to have their source Ethernet 158address field overwritten with the device's unique Ethernet address. 159If this flag is set to zero, the source address in outgoing packets 160is not modified. 161The default setting for this flag is enabled. 162.It Dv NGM_ETHER_GET_AUTOSRC 163Get the current value of the node's source address override flag. 164The returned value is always either one or zero. 165.El 166.Sh SHUTDOWN 167This node is persistent for as long as the interface exists. 168Upon receipt of a 169.Dv NGM_SHUTDOWN 170control message, all hooks are disconnected, promiscuous mode is disabled, 171and the source address override flag is reenabled, 172but the node is not removed. 173If the interface itself is detached (e.g., because of PCCARD removal), the 174node disappears as well. 175.Sh EXAMPLES 176This command dumps all unrecognized packets received by the 177.Dv fxp0 178interface to standard output decoded in hex and ASCII: 179.Bd -literal -offset indent 180nghook -a fxp0: orphans 181.Ed 182.Pp 183This command sends the contents of 184.Dv foo.pkt 185out the interface 186.Dv fxp0 : 187.Bd -literal -offset indent 188cat foo.pkt | nghook fxp0: orphans 189.Ed 190.Pp 191These commands insert an 192.Xr ng_tee 4 193node between the lower and upper protocol layers, which can be used for 194tracing packet flow, statistics, etc.: 195.Bd -literal -offset indent 196ngctl mkpeer fxp0: tee lower right 197ngctl connect fxp0: lower upper left 198.Ed 199.Sh SEE ALSO 200.Xr arp 4 , 201.Xr netgraph 4 , 202.Xr netintro 4 , 203.Xr ifconfig 8 , 204.Xr ngctl 8 , 205.Xr nghook 8 206.Sh AUTHORS 207.An Julian Elischer Aq Mt julian@FreeBSD.org 208.An Archie Cobbs Aq Mt archie@FreeBSD.org 209.Sh BUGS 210The automatic KLD module loading mechanism that works for most 211other netgraph node types does not work for the 212.Nm 213node type, 214because 215.Nm 216nodes are not created on demand; instead, they are created when 217Ethernet interfaces are attached or when the KLD is first loaded. 218Therefore, if the KLD is not statically compiled into the kernel, 219it is necessary to load the KLD manually in order to bring the 220.Nm 221nodes into existence. 222