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