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