1 |
.\" $MidnightBSD$ |
2 |
.\" Copyright (c) 1996-1999 Whistle Communications, Inc. |
3 |
.\" All rights reserved. |
4 |
.\" |
5 |
.\" Subject to the following obligations and disclaimer of warranty, use and |
6 |
.\" redistribution of this software, in source or object code forms, with or |
7 |
.\" without modifications are expressly permitted by Whistle Communications; |
8 |
.\" provided, however, that: |
9 |
.\" 1. Any and all reproductions of the source or object code must include the |
10 |
.\" copyright notice above and the following disclaimer of warranties; and |
11 |
.\" 2. No rights are granted, in any manner or form, to use Whistle |
12 |
.\" Communications, Inc. trademarks, including the mark "WHISTLE |
13 |
.\" COMMUNICATIONS" on advertising, endorsements, or otherwise except as |
14 |
.\" such appears in the above copyright notice or in the software. |
15 |
.\" |
16 |
.\" THIS SOFTWARE IS BEING PROVIDED BY WHISTLE COMMUNICATIONS "AS IS", AND |
17 |
.\" TO THE MAXIMUM EXTENT PERMITTED BY LAW, WHISTLE COMMUNICATIONS MAKES NO |
18 |
.\" REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SOFTWARE, |
19 |
.\" INCLUDING WITHOUT LIMITATION, ANY AND ALL IMPLIED WARRANTIES OF |
20 |
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT. |
21 |
.\" WHISTLE COMMUNICATIONS DOES NOT WARRANT, GUARANTEE, OR MAKE ANY |
22 |
.\" REPRESENTATIONS REGARDING THE USE OF, OR THE RESULTS OF THE USE OF THIS |
23 |
.\" SOFTWARE IN TERMS OF ITS CORRECTNESS, ACCURACY, RELIABILITY OR OTHERWISE. |
24 |
.\" IN NO EVENT SHALL WHISTLE COMMUNICATIONS BE LIABLE FOR ANY DAMAGES |
25 |
.\" RESULTING FROM OR ARISING OUT OF ANY USE OF THIS SOFTWARE, INCLUDING |
26 |
.\" WITHOUT LIMITATION, ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, |
27 |
.\" PUNITIVE, OR CONSEQUENTIAL DAMAGES, PROCUREMENT OF SUBSTITUTE GOODS OR |
28 |
.\" SERVICES, LOSS OF USE, DATA OR PROFITS, HOWEVER CAUSED AND UNDER ANY |
29 |
.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
30 |
.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF |
31 |
.\" THIS SOFTWARE, EVEN IF WHISTLE COMMUNICATIONS IS ADVISED OF THE POSSIBILITY |
32 |
.\" OF SUCH DAMAGE. |
33 |
.\" |
34 |
.\" Author: Archie Cobbs <archie@FreeBSD.org> |
35 |
.\" |
36 |
.\" $FreeBSD: stable/10/share/man/man4/ng_iface.4 242997 2012-11-13 20:41:36Z joel $ |
37 |
.\" $Whistle: ng_iface.8,v 1.5 1999/01/25 23:46:26 archie Exp $ |
38 |
.\" |
39 |
.Dd October 28, 2005 |
40 |
.Dt NG_IFACE 4 |
41 |
.Os |
42 |
.Sh NAME |
43 |
.Nm ng_iface |
44 |
.Nd interface netgraph node type |
45 |
.Sh SYNOPSIS |
46 |
.In netgraph/ng_iface.h |
47 |
.Sh DESCRIPTION |
48 |
An |
49 |
.Nm iface |
50 |
node is both a netgraph node and a system networking interface. |
51 |
When an |
52 |
.Nm iface |
53 |
node is created, a new interface appears which is accessible via |
54 |
.Xr ifconfig 8 . |
55 |
.Nm Iface |
56 |
node interfaces are named |
57 |
.Dv ng0 , |
58 |
.Dv ng1 , |
59 |
etc. |
60 |
When a node is shutdown, the corresponding interface is removed |
61 |
and the interface name becomes available for reuse by future |
62 |
.Nm iface |
63 |
nodes; new nodes always take the first unused interface. |
64 |
The node itself is assigned the same name as its interface, unless the name |
65 |
already exists, in which case the node remains unnamed. |
66 |
.Pp |
67 |
An |
68 |
.Nm iface |
69 |
node has a single hook corresponding to each supported protocol. |
70 |
Packets transmitted via the interface flow out the corresponding |
71 |
protocol-specific hook. |
72 |
Similarly, packets received on a hook appear on the interface as |
73 |
packets received into the corresponding protocol stack. |
74 |
The currently supported protocols are IP, IPv6, AppleTalk, IPX, ATM, |
75 |
NATM, and NS. |
76 |
.Pp |
77 |
An |
78 |
.Nm iface |
79 |
node can be configured as a point-to-point interface or a broadcast interface. |
80 |
The configuration can only be changed when the interface is down. |
81 |
The default mode is point-to-point. |
82 |
.Pp |
83 |
.Nm Iface |
84 |
nodes support the Berkeley Packet Filter (BPF). |
85 |
.Sh HOOKS |
86 |
This node type supports the following hooks: |
87 |
.Bl -tag -width ".Va inet6" |
88 |
.It Va inet |
89 |
Transmission and reception of IP packets. |
90 |
.It Va inet6 |
91 |
Transmission and reception of IPv6 packets. |
92 |
.It Va atalk |
93 |
Transmission and reception of AppleTalk packets. |
94 |
.It Va ipx |
95 |
Transmission and reception of IPX packets. |
96 |
.It Va atm |
97 |
Transmission and reception of ATM packets. |
98 |
.It Va natm |
99 |
Transmission and reception of NATM packets. |
100 |
.It Va ns |
101 |
Transmission and reception of NS packets. |
102 |
.El |
103 |
.Sh CONTROL MESSAGES |
104 |
This node type supports the generic control messages, plus the following: |
105 |
.Bl -tag -width foo |
106 |
.It Dv NGM_IFACE_GET_IFNAME Pq Ic getifname |
107 |
Returns the name of the associated interface as a |
108 |
.Dv NUL Ns -terminated |
109 |
.Tn ASCII |
110 |
string. |
111 |
Normally this is the same as the name of the node. |
112 |
.It Dv NGM_IFACE_GET_IFINDEX Pq Ic getifindex |
113 |
Returns the global index of the associated interface as a 32 bit integer. |
114 |
.It Dv NGM_IFACE_POINT2POINT Pq Ic point2point |
115 |
Set the interface to point-to-point mode. |
116 |
The interface must not currently be up. |
117 |
.It Dv NGM_IFACE_BROADCAST Pq Ic broadcast |
118 |
Set the interface to broadcast mode. |
119 |
The interface must not currently be up. |
120 |
.It Dv NGM_CISCO_GET_IPADDR Pq Ic getipaddr |
121 |
This message is defined by the |
122 |
.Xr ng_cisco 4 |
123 |
node type; see |
124 |
.Xr ng_cisco 4 |
125 |
for a description. |
126 |
.El |
127 |
.Sh SHUTDOWN |
128 |
This node shuts down upon receipt of a |
129 |
.Dv NGM_SHUTDOWN |
130 |
control message. |
131 |
The associated interface is removed and becomes available |
132 |
for use by future |
133 |
.Nm iface |
134 |
nodes. |
135 |
.Pp |
136 |
Unlike most other node types, an |
137 |
.Nm iface |
138 |
node does |
139 |
.Em not |
140 |
go away when all hooks have been disconnected; rather, and explicit |
141 |
.Dv NGM_SHUTDOWN |
142 |
control message is required. |
143 |
.Sh ALTQ Support |
144 |
The |
145 |
.Nm |
146 |
interface supports ALTQ bandwidth management feature. |
147 |
However, |
148 |
.Nm |
149 |
is a special case, since it is not a physical interface with limited bandwidth. |
150 |
One should not turn ALTQ on |
151 |
.Nm |
152 |
if the latter corresponds to some tunneled connection, e.g.\& PPPoE or PPTP. |
153 |
In this case, ALTQ should be configured on the interface that is used to |
154 |
transmit the encapsulated packets. |
155 |
In case when your graph ends up with some kind of serial line, either |
156 |
synchronous or modem, the |
157 |
.Nm |
158 |
is the right place to turn ALTQ on. |
159 |
.Sh SEE ALSO |
160 |
.Xr altq 4 , |
161 |
.Xr bpf 4 , |
162 |
.Xr netgraph 4 , |
163 |
.Xr ng_cisco 4 , |
164 |
.Xr ifconfig 8 , |
165 |
.Xr ngctl 8 |
166 |
.Sh HISTORY |
167 |
The |
168 |
.Nm iface |
169 |
node type was implemented in |
170 |
.Fx 4.0 . |
171 |
.Sh AUTHORS |
172 |
.An Archie Cobbs Aq archie@FreeBSD.org |