| blob | 161769ad4fd5728c9b473203705d775e9589fc81 |
1 .\" $OpenBSD: hostname.if.5,v 1.60 2013/01/18 21:48:43 jmc Exp $
2 .\" $NetBSD: hosts.5,v 1.4 1994/11/30 19:31:20 jtc Exp $
3 .\"
4 .\" Copyright (c) 1983, 1991, 1993
5 .\" The Regents of the University of California. All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\" 1. Redistributions of source code must retain the above copyright
11 .\" notice, this list of conditions and the following disclaimer.
12 .\" 2. Redistributions in binary form must reproduce the above copyright
13 .\" notice, this list of conditions and the following disclaimer in the
14 .\" documentation and/or other materials provided with the distribution.
15 .\" 3. Neither the name of the University nor the names of its contributors
16 .\" may be used to endorse or promote products derived from this software
17 .\" without specific prior written permission.
18 .\"
19 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29 .\" SUCH DAMAGE.
30 .\"
31 .\" @(#)hosts.5 8.2 (Berkeley) 12/11/93
32 .\"
33 .Dd $Mdocdate: January 18 2013 $
34 .Dt HOSTNAME.IF 5
35 .Os
36 .Sh NAME
37 .Nm hostname.if
38 .Nd interface-specific configuration files
39 .Sh DESCRIPTION
40 The
41 .Nm hostname.*\&
42 files contain information regarding the configuration of each network interface.
43 One file should exist for each interface that is to be configured, such as
44 .Pa hostname.fxp0
45 or
46 .Pa hostname.bridge0 .
47 A configuration file is not needed for lo0.
48 .Pp
49 The configuration information is expressed in a line-by-line packed format
50 which makes the most common cases simpler; those dense formats are described
51 below.
52 Any lines not matching these packed formats are passed directly to
53 .Xr ifconfig 8 .
54 The packed formats are converted using a somewhat inflexible parser and
55 the administrator should not expect magic \(em if in doubt study
56 .Xr ifconfig 8
57 and the
58 per-driver manual pages to see what arguments are permitted.
59 .Pp
60 Arguments containing either whitespace or single quote
61 characters must be double quoted.
62 For example:
63 .Bd -literal -offset indent
64 inet 10.0.0.1 255.255.255.0 10.0.0.255 description "Bob's uplink"
65 .Ed
66 .Pp
67 Each line is processed separately and in order.
68 For example:
69 .Bd -literal -offset indent
70 nwid mynwid
71 wpakey mywpakey
72 dhcp
73 .Ed
74 .Pp
75 would run ifconfig to set the nwid of the interface, run it again to set the wpakey of the interface, and then start
76 .Xr dhclient 8 .
77 .Sh STATIC ADDRESS CONFIGURATION
78 The following packed formats are valid for configuring network
79 interfaces with static addresses:
80 .Pp
81 Regular IPv4 network setup:
82 .Bd -ragged -offset indent
83 .Li inet
84 .Op Li alias
85 .Va addr
86 .Va netmask
87 .Va broadcast_addr
88 .Va options
89 .br
90 .Li dest
91 .Va dest_addr
92 .Ed
93 .Pp
94 Regular IPv6 network setup:
95 .Bd -ragged -offset indent
96 .Li inet6
97 .Op Li alias
98 .Va addr
99 .Va prefixlen
100 .Va options
101 .br
102 .Li dest
103 .Va dest_addr
104 .Ed
105 .Pp
106 Other network setup:
107 .Bd -ragged -offset indent
108 .Va addr_family
109 .Va options
110 .Ed
111 .Pp
112 A typical file contains only one line, but more extensive files are possible,
113 for example:
114 .Bd -literal -offset 1n
115 inet 10.0.1.12 255.255.255.0 10.0.1.255 media 100baseTX description Uplink
116 inet alias 10.0.1.13 255.255.255.255 10.0.1.13
117 inet alias 10.0.1.14 255.255.255.255 NONE
118 inet alias 10.0.1.15 255.255.255.255
119 inet alias 10.0.1.16 0xffffffff
120 # This is an example comment line.
121 inet6 alias fec0::1 64
122 inet6 alias fec0::2 64 anycast
123 !route add 65.65.65.65 10.0.1.13
124 up
125 .Ed
126 .Pp
127 The above formats have the following field values:
128 .Bl -tag -width indent -offset indent
129 .It Va addr_family
130 The address family of the interface, generally
131 .Dq inet
132 or
133 .Dq inet6 .
134 .It Li alias
135 The literal string
136 .Dq alias
137 if this is an additional network address for the interface.
138 .It Va addr
139 The optional address that belongs to the interface, such as
140 190.191.192.1 or fe80:2::1.
141 It is also feasible to use a hostname as specified in
142 .Pa /etc/hosts .
143 It is recommended that an address be used instead of symbolic information,
144 since the latter might activate
145 .Xr resolver 3
146 library routines.
147 .Pp
148 If no address is specified, the
149 .Va netmask ,
150 .Va broadcast_addr ,
151 .Li dest ,
152 and
153 .Va dest_addr
154 options are invalid and will be ignored.
155 .It Va netmask
156 The optional network mask for the interface, e.g.,
157 255.255.255.0.
158 If
159 .Va addr
160 is specified but
161 .Va netmask
162 is not, the classful mask based on
163 .Va addr
164 is used.
165 .It Va broadcast_addr
166 The optional broadcast address for the interface, e.g.,
167 190.191.192.255.
168 The word
169 .Dq NONE
170 can also be specified in order to configure the broadcast address based
171 on the
172 .Va netmask .
173 The
174 .Va netmask
175 option must be present in order to use this option.
176 .It Va options
177 Miscellaneous options to set on the interface, e.g.,
178 .Dq media 100baseTX mediaopt full-duplex .
179 Valid options for a particular interface type can be found in
180 .Xr ifconfig 8 .
181 When used, the
182 .Va netmask
183 and
184 .Va broadcast_addr
185 options must also be present.
186 .It Li dest
187 If the interface needs a destination address set, this is the literal text
188 .Dq dest .
189 As shown in the example, this declaration should start on a separate line.
190 .It Va dest_addr
191 The destination address to be set on the interface, such as
192 190.191.192.2.
193 It is also feasible to use a hostname as specified in
194 .Pa /etc/hosts .
195 It is recommended that an address be used instead of symbolic information
196 which might activate
197 .Xr resolver 3
198 library routines.
199 .It Va prefixlen
200 The prefixlen number, or number of bits in the netmask, to be set on
201 the interface, such as 64.
202 .It Li #
203 Comments are allowed.
204 Anything following a comment character is treated as a comment.
205 .It Li \&! Ns Ar command
206 Arbitrary shell commands can be executed using this directive, as
207 long as they are available in the single-user environment (for
208 instance,
209 .Pa /bin
210 or
211 .Pa /sbin ) .
212 Useful for doing interface-specific configuration such as
213 setting up custom routes using
214 .Xr route 8
215 or establishing tunnels using
216 .Xr ifconfig 8 .
217 It is worth noting that
218 .Dq \e$if
219 in a command line will be replaced by the interface name.
220 .El
221 .Sh DYNAMIC ADDRESS CONFIGURATION
222 The following packed formats are valid for configuring network
223 interfaces with dynamic addresses:
224 .Pp
225 A DHCP-configured network interface setup consists of
226 .Bd -ragged -offset indent
227 .Li dhcp
228 .Va options
229 .Ed
230 .Pp
231 The above format has the following field values:
232 .Bl -tag -width indent -offset indent
233 .It Li dhcp
234 The literal string
235 .Dq dhcp
236 if the interface is to be configured using DHCP.
237 See
238 .Xr dhclient 8
239 and
240 .Xr dhclient.conf 5
241 for more details.
242 .It Va options
243 Miscellaneous options to set on the interface, e.g.,
244 .Dq media 100baseTX mediaopt full-duplex .
245 Valid options for a particular interface type can be found in
246 .Xr ifconfig 8 .
247 .El
248 .Pp
249 IPv6 stateless address autoconfiguration:
250 .Bd -ragged -offset indent
251 .Li rtsol
252 .Va options
253 .Ed
254 .Pp
255 The above format has the following field values:
256 .Bl -tag -width indent -offset indent
257 .It Li rtsol
258 The literal string
259 .Dq rtsol
260 if the interface is to be configured using
261 IPv6 stateless address autoconfiguration.
262 This should be used on single interface hosts only,
263 since the IPv6 specifications are silent about the
264 behavior on multi-interface hosts.
265 Also note that the kernel must be configured to accept IPv6
266 router advertisement, and configured as a host (i.e. non-router).
267 Add the following lines into
268 .Xr sysctl.conf 5 :
269 .Bd -literal -offset indent
270 net.inet6.ip6.forwarding=0
271 net.inet6.ip6.accept_rtadv=1
272 .Ed
273 .It Va options
274 Miscellaneous options to set on the interface, e.g.,
275 .Dq media 100baseTX mediaopt full-duplex .
276 Valid options for a particular interface type can be found in
277 .Xr ifconfig 8 .
278 .El
279 .Sh BRIDGE INTERFACE CONFIGURATION
280 If the network interface is a bridge, the options described in
281 the bridge section of the
282 .Xr ifconfig 8
283 manual page apply.
284 .Pp
285 For example:
286 .Bd -literal -offset indent
287 add fxp0
288 add ep1
289 -learn fxp0
290 #
291 !ipsecctl -F
292 #
293 static fxp0 8:0:20:1e:2f:2b
294 up # and finally enable it
295 .Ed
296 .Sh FILES
297 .Bl -tag -width "/etc/hostname.XXXXXX"
298 .It Pa /etc/hostname.XXX
299 Interface-specific configuration files.
300 .El
301 .Sh SEE ALSO
302 .Xr hosts 5 ,
303 .Xr dhcp 8 ,
304 .Xr ifconfig 8 ,
305 .Xr lmccontrol 8 ,
306 .Xr netstart 8 ,
307 .Xr rc 8