1.\" Copyright (c) 1996-1999 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.\" $Whistle: ng_iface.8,v 1.5 1999/01/25 23:46:26 archie Exp $ 35.\" 36.Dd July 31, 2020 37.Dt NG_IFACE 4 38.Os 39.Sh NAME 40.Nm ng_iface 41.Nd interface netgraph node type 42.Sh SYNOPSIS 43.In netgraph/ng_iface.h 44.Sh DESCRIPTION 45An 46.Nm iface 47node is both a netgraph node and a system networking interface. 48When an 49.Nm iface 50node is created, a new interface appears which is accessible via 51.Xr ifconfig 8 . 52.Nm Iface 53node interfaces are named 54.Dv ng0 , 55.Dv ng1 , 56etc. 57When a node is shutdown, the corresponding interface is removed 58and the interface name becomes available for reuse by future 59.Nm iface 60nodes; new nodes always take the first unused interface. 61The node itself is assigned the same name as its interface, unless the name 62already exists, in which case the node remains unnamed. 63.Pp 64An 65.Nm iface 66node has a single hook corresponding to each supported protocol. 67Packets transmitted via the interface flow out the corresponding 68protocol-specific hook. 69Similarly, packets received on a hook appear on the interface as 70packets received into the corresponding protocol stack. 71The currently supported protocols are IP and IPv6. 72.Pp 73An 74.Nm iface 75node can be configured as a point-to-point interface or a broadcast interface. 76The configuration can only be changed when the interface is down. 77The default mode is point-to-point. 78.Pp 79.Nm Iface 80nodes support the Berkeley Packet Filter (BPF). 81.Sh HOOKS 82This node type supports the following hooks: 83.Bl -tag -width ".Va inet6" 84.It Va inet 85Transmission and reception of IP packets. 86.It Va inet6 87Transmission and reception of IPv6 packets. 88.El 89.Sh CONTROL MESSAGES 90This node type supports the generic control messages, plus the following: 91.Bl -tag -width foo 92.It Dv NGM_IFACE_GET_IFNAME Pq Ic getifname 93Returns the name of the associated interface as a 94.Dv NUL Ns -terminated 95.Tn ASCII 96string. 97Normally this is the same as the name of the node. 98.It Dv NGM_IFACE_GET_IFINDEX Pq Ic getifindex 99Returns the global index of the associated interface as a 32 bit integer. 100.It Dv NGM_IFACE_POINT2POINT Pq Ic point2point 101Set the interface to point-to-point mode. 102The interface must not currently be up. 103.It Dv NGM_IFACE_BROADCAST Pq Ic broadcast 104Set the interface to broadcast mode. 105The interface must not currently be up. 106.El 107.Sh SHUTDOWN 108This node shuts down upon receipt of a 109.Dv NGM_SHUTDOWN 110control message. 111The associated interface is removed and becomes available 112for use by future 113.Nm iface 114nodes. 115.Pp 116Unlike most other node types, an 117.Nm iface 118node does 119.Em not 120go away when all hooks have been disconnected; rather, and explicit 121.Dv NGM_SHUTDOWN 122control message is required. 123.Sh ALTQ Support 124The 125.Nm 126interface supports ALTQ bandwidth management feature. 127However, 128.Nm 129is a special case, since it is not a physical interface with limited bandwidth. 130One should not turn ALTQ on 131.Nm 132if the latter corresponds to some tunneled connection, e.g.\& PPPoE or PPTP. 133In this case, ALTQ should be configured on the interface that is used to 134transmit the encapsulated packets. 135In case when your graph ends up with some kind of serial line, either 136synchronous or modem, the 137.Nm 138is the right place to turn ALTQ on. 139.Sh Nesting 140.Nm 141supports nesting, a configuration when traffic of one 142.Nm 143interface flows through the other. 144The default maximum allowed nesting level is 2. 145It can be changed at runtime setting 146.Xr sysctl 8 147variable 148.Va net.graph.iface.max_nesting 149to the desired level of nesting. 150.Sh SEE ALSO 151.Xr altq 4 , 152.Xr bpf 4 , 153.Xr netgraph 4 , 154.Xr ng_cisco 4 , 155.Xr ifconfig 8 , 156.Xr ngctl 8 157.Xr sysctl 158.Sh HISTORY 159The 160.Nm iface 161node type was implemented in 162.Fx 4.0 . 163.Sh AUTHORS 164.An Archie Cobbs Aq Mt archie@FreeBSD.org 165