1.\"	$MirOS: src/share/man/man5/hostname.if.5,v 1.4 2006/01/11 20:43:00 tg Exp $
2.\"	$OpenBSD: hostname.if.5,v 1.42 2005/06/10 00:01:12 joel Exp $
3.\"	$NetBSD: hosts.5,v 1.4 1994/11/30 19:31:20 jtc Exp $
4.\"
5.\" Copyright (c) 1983, 1991, 1993
6.\"	The Regents of the University of California.  All rights reserved.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)hosts.5	8.2 (Berkeley) 12/11/93
33.\"
34.Dd September 2, 1999
35.Dt HOSTNAME.IF 5
36.Os
37.Sh NAME
38.Nm hostname.if ,
39.Nm bridgename.if
40.Nd interface-specific configuration files
41.Sh DESCRIPTION
42The
43.Nm hostname.*\&
44and
45.Nm bridgename.*\&
46files contain information regarding the configuration of each network interface.
47One file should exist for each interface that is to be configured, such as
48.Pa hostname.fxp0
49or
50.Pa bridgename.bridge0 .
51However, a configuration file is not needed for lo0.
52Note that multiple entries can be used per configuration file.
53.Pp
54Arguments containing either whitespace or single quote
55characters must be double quoted.
56For example:
57.Bd -literal -offset indent
58inet 10.0.0.1 255.255.255.0 10.0.0.255 description "Bob's uplink"
59.Ed
60.Sh STATIC ADDRESS CONFIGURATION
61The following three
62.Nm hostname.*\&
63formats are valid for configuring network interfaces with static
64addresses:
65.Pp
66Regular IPv4 network setup:
67.Bd -ragged -offset indent
68.Va addr_family
69.Op Va alias
70.Va addr
71.Va netmask
72.Va broadcast_addr
73.Va options
74.br
75.Li dest
76.Va dest_addr
77.br
78.Li route
79.Op \+n
80.Va options
81.Ed
82.Pp
83Regular IPv6 network setup:
84.Bd -ragged -offset indent
85.Va addr_family
86.Op Va alias
87.Va addr
88.Va prefixlen
89.Va options
90.br
91.Li route
92.Op \+n
93.Va options
94.Ed
95.Pp
96Other network setup:
97.Bd -ragged -offset indent
98.Va addr_family
99.Va options
100.Ed
101.Pp
102A typical file contains only one line, but more extensive files are possible,
103for example:
104.Bd -literal -offset 1n
105inet 10.0.1.12 255.255.255.0 10.0.1.255 media 100baseTX description Uplink
106inet alias 10.0.1.13 255.255.255.255 10.0.1.13
107inet alias 10.0.1.14 255.255.255.255 NONE
108inet alias 10.0.1.15 255.255.255.255
109inet alias 10.0.1.16 0xffffffff
110inet6 alias fec0::1 64
111inet6 alias fec0::2 64 anycast
112route add default 10.0.1.254
113route +n add -inet6 default myrouter.mydomain.com
114# This is an example comment line.
115!wicontrol \e$if -t 2  # Set to 2Mbps
116.Ed
117.Pp
118The above formats have the following field values:
119.Bl -tag -width indent -offset indent
120.It Va addr_family
121The address family of the interface, generally
122.Dq inet
123or
124.Dq inet6 .
125.It Va addr
126The optional address that belongs to the interface, such as
127190.191.192.1 or fe80:2::1.
128It is also feasible to use a hostname as specified in
129.Pa /etc/hosts .
130It is recommended that an address be used instead of symbolic information,
131since the latter might activate
132.Xr resolver 3
133library routines.
134.Pp
135If no address is specified, the
136.Va netmask ,
137.Va broadcast_addr ,
138.Li dest ,
139and
140.Va dest_addr
141options are invalid and will be ignored.
142.It Va netmask
143The optional network mask for the interface, e.g.,
144255.255.255.0.
145If
146.Va addr
147is specified but
148.Va netmask
149is not, the classful mask based on
150.Va addr
151is used.
152.It Va broadcast_addr
153The optional broadcast address for the interface, e.g.,
154190.191.192.255.
155The word
156.Dq NONE
157can also be specified in order to configure the broadcast address based
158on the
159.Va netmask .
160The
161.Va netmask
162option must be present in order to use this option.
163.It Va options
164Miscellaneous options to set on the interface, e.g.,
165.Dq media 100baseTX mediaopt full-duplex .
166Valid options for a particular interface type can be found in
167.Xr ifconfig 8 .
168When used, the
169.Va netmask
170and
171.Va broadcast_addr
172options must also be present.
173.It Li dest
174If the interface needs a destination address set, this is the literal text
175.Dq dest .
176As shown in the example, this declaration should start on a separate line.
177.It Va dest_addr
178The destination address to be set on the interface, such as
179190.191.192.2.
180It is also feasible to use a hostname as specified in
181.Pa /etc/hosts .
182It is recommended that an address be used instead of symbolic information
183which might activate
184.Xr resolver 3
185library routines.
186.It Va prefixlen
187The prefixlen number, or number of bits in the netmask, to be set on
188the interface, such as 64.
189.It route Op \+n
190This command starts the
191.Xr route 8
192command with
193.Fl n ,
194unless \fB\+n\fR
195is given as second word, and the
196.Va options
197as parameters.
198.It Li #
199Comments are allowed.
200Anything following a comment character is treated as a comment.
201.It Li \&! Ns Ar command-line
202Arbitrary shell commands can be executed using this directive.
203Useful for doing interface specific configuration using commands like
204.Xr wicontrol 8 ,
205setting up custom routes using
206.Xr route 8 ,
207or establishing tunnels using
208.Xr ifconfig 8 .
209It is worth noting that
210.Dq \e$if
211in a command line will be replaced by the interface name.
212.El
213.Sh DYNAMIC ADDRESS CONFIGURATION
214The following
215.Nm hostname.*\&
216formats are valid for configuring network interfaces with dynamic
217addresses:
218.Pp
219A DHCP-configured network interface setup consists of
220.Bd -ragged -offset indent
221.Li dhcp
222.Va options
223.Ed
224.Pp
225For example:
226.Bd -literal -offset indent
227dhcp media 100baseTX mediaopt full-duplex
228.Ed
229.Pp
230The above format has the following field values:
231.Bl -tag -width indent -offset indent
232.It Li dhcp
233The literal string
234.Dq dhcp
235if the interface is to be configured using DHCP.
236See
237.Xr dhclient 8
238and
239.Xr dhclient.conf 5
240for more details.
241.It Va options
242Miscellaneous options to set on the interface, e.g.,
243.Dq media 100baseTX mediaopt full-duplex .
244Valid options for a particular interface type can be found in
245.Xr ifconfig 8 .
246The
247.Ox
248installation script will create
249.Nm hostname.if
250with options of
251.Dq NONE NONE NONE
252when DHCP configuration is chosen.
253This is the same as specifying just
254.Dq dhcp .
255.El
256.Pp
257IPv6 stateless address autoconfiguration:
258.Bd -ragged -offset indent
259.Li rtsol
260.Va options
261.Ed
262.Pp
263The above format has the following field values:
264.Bl -tag -width indent -offset indent
265.It Li rtsol
266The literal string
267.Dq rtsol
268if the interface is to be configured using
269IPv6 stateless address autoconfiguration.
270This should be used on single interface hosts only,
271since the IPv6 specifications are silent about the
272behavior on multi-interface hosts.
273Also note that the kernel must be configured to accept IPv6
274router advertisement, and configured as a host (ie. non-router).
275Add the following lines into
276.Xr sysctl.conf 5 :
277.Bd -literal -offset indent
278net.inet6.ip6.forwarding=0
279net.inet6.ip6.accept_rtadv=1
280.Ed
281.It Va options
282Miscellaneous options to set on the interface, e.g.,
283.Dq media 100baseTX mediaopt full-duplex .
284Valid options for a particular interface type can be found in
285.Xr ifconfig 8 .
286.El
287.Sh ADDRESS-LESS CONFIGURATION
288A network interface that does not require an IP address
289(such as
290.Xr bridge 4
291member interfaces and interfaces to be used with
292.Xr ppp 8
293and
294.Xr pppoe 8 )
295consists of
296.Bd -ragged -offset indent
297.Va state
298.Va options
299.Ed
300.Pp
301The above format has the following field values:
302.Bl -tag -width indent -offset indent
303.It Va state
304The administrative state in which to put the interface, either
305.Dq up
306or
307.Dq down .
308.It Va options
309Miscellaneous options to set on the interface, e.g.,
310.Dq media 100baseTX mediaopt full-duplex .
311Valid options for a particular interface type can be found in
312.Xr ifconfig 8 .
313.El
314.Sh BRIDGE INTERFACE CONFIGURATION
315The final file format only applies to
316.Nm bridgename.bridge*
317files.
318A bridge interface setup consists of
319.Bd -ragged -offset indent
320.Va brconfig-arguments
321.br
322.Va brconfig-arguments
323.br
324\&...
325.Ed
326.Pp
327For example:
328.Bd -literal -offset indent
329add fxp0
330add ep1
331-learn fxp0
332#
333!ipsecadm flush
334#
335static fxp0 8:0:20:1e:2f:2b
336up    # and finally enable it
337.Ed
338.Pp
339The options are as follows:
340.Bl -tag -width indent -offset indent
341.It Va brconfig-arguments
342.Xr brconfig 8
343is called for each successive line.
344Comments starting with
345.Ql #
346and commands to be executed
347prefixed by
348.Ql \&!
349are permitted.
350.El
351.Sh SEE ALSO
352.Xr hosts 5 ,
353.Xr ancontrol 8 ,
354.Xr brconfig 8 ,
355.Xr dhcp 8 ,
356.Xr ifconfig 8 ,
357.Xr lmccontrol 8 ,
358.Xr netstart 8 ,
359.Xr rc 8 ,
360.Xr spppcontrol 8 ,
361.Xr wicontrol 8
362.Sh CAVEATS
363The file
364.Pa /etc/hostname.local
365is a shell script, no
366.Xr hostname.if 5
367file.
368