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