xref: /openbsd-src/share/man/man5/hostname.if.5 (revision d13be5d47e4149db2549a9828e244d59dbc43f15) 
1.\"	$OpenBSD: hostname.if.5,v 1.56 2011/07/08 01:30:26 deraadt 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: July 8 2011 $
34.Dt HOSTNAME.IF 5
35.Os
36.Sh NAME
37.Nm hostname.if
38.Nd interface-specific configuration files
39.Sh DESCRIPTION
40The
41.Nm hostname.*\&
42files contain information regarding the configuration of each network interface.
43One file should exist for each interface that is to be configured, such as
44.Pa hostname.fxp0
45or
46.Pa hostname.bridge0 .
47A configuration file is not needed for lo0.
48.Pp
49The configuration information is expressed in a line-by-line packed format
50which makes the most common cases simpler; those dense formats are described
51below.
52Any lines not matching these packed formats are passed directly to
53.Xr ifconfig 8 .
54The packed formats are converted using a somewhat inflexible parser and
55the administrator should not expect magic \(em if in doubt study
56.Xr ifconfig 8
57and the
58per-driver manual pages to see what arguments are permitted.
59.Pp
60Arguments containing either whitespace or single quote
61characters must be double quoted.
62For example:
63.Bd -literal -offset indent
64inet 10.0.0.1 255.255.255.0 10.0.0.255 description "Bob's uplink"
65.Ed
66.Sh STATIC ADDRESS CONFIGURATION
67The following packed formats are valid for configuring network
68interfaces with static addresses:
69.Pp
70Regular IPv4 network setup:
71.Bd -ragged -offset indent
72.Li inet
73.Op Li alias
74.Va addr
75.Va netmask
76.Va broadcast_addr
77.Va options
78.br
79.Li dest
80.Va dest_addr
81.Ed
82.Pp
83Regular IPv6 network setup:
84.Bd -ragged -offset indent
85.Li inet6
86.Op Li alias
87.Va addr
88.Va prefixlen
89.Va options
90.br
91.Li dest
92.Va dest_addr
93.Ed
94.Pp
95Other network setup:
96.Bd -ragged -offset indent
97.Va addr_family
98.Va options
99.Ed
100.Pp
101A typical file contains only one line, but more extensive files are possible,
102for example:
103.Bd -literal -offset 1n
104inet 10.0.1.12 255.255.255.0 10.0.1.255 media 100baseTX description Uplink
105inet alias 10.0.1.13 255.255.255.255 10.0.1.13
106inet alias 10.0.1.14 255.255.255.255 NONE
107inet alias 10.0.1.15 255.255.255.255
108inet alias 10.0.1.16 0xffffffff
109# This is an example comment line.
110inet6 alias fec0::1 64
111inet6 alias fec0::2 64 anycast
112!route add 65.65.65.65 10.0.1.13
113up
114.Ed
115.Pp
116The above formats have the following field values:
117.Bl -tag -width indent -offset indent
118.It Va addr_family
119The address family of the interface, generally
120.Dq inet
121or
122.Dq inet6 .
123.It Li alias
124The literal string
125.Dq alias
126if this is an additional network address for the interface.
127.It Va addr
128The optional address that belongs to the interface, such as
129190.191.192.1 or fe80:2::1.
130It is also feasible to use a hostname as specified in
131.Pa /etc/hosts .
132It is recommended that an address be used instead of symbolic information,
133since the latter might activate
134.Xr resolver 3
135library routines.
136.Pp
137If no address is specified, the
138.Va netmask ,
139.Va broadcast_addr ,
140.Li dest ,
141and
142.Va dest_addr
143options are invalid and will be ignored.
144.It Va netmask
145The optional network mask for the interface, e.g.,
146255.255.255.0.
147If
148.Va addr
149is specified but
150.Va netmask
151is not, the classful mask based on
152.Va addr
153is used.
154.It Va broadcast_addr
155The optional broadcast address for the interface, e.g.,
156190.191.192.255.
157The word
158.Dq NONE
159can also be specified in order to configure the broadcast address based
160on the
161.Va netmask .
162The
163.Va netmask
164option must be present in order to use this option.
165.It Va options
166Miscellaneous options to set on the interface, e.g.,
167.Dq media 100baseTX mediaopt full-duplex .
168Valid options for a particular interface type can be found in
169.Xr ifconfig 8 .
170When used, the
171.Va netmask
172and
173.Va broadcast_addr
174options must also be present.
175.It Li dest
176If the interface needs a destination address set, this is the literal text
177.Dq dest .
178As shown in the example, this declaration should start on a separate line.
179.It Va dest_addr
180The destination address to be set on the interface, such as
181190.191.192.2.
182It is also feasible to use a hostname as specified in
183.Pa /etc/hosts .
184It is recommended that an address be used instead of symbolic information
185which might activate
186.Xr resolver 3
187library routines.
188.It Va prefixlen
189The prefixlen number, or number of bits in the netmask, to be set on
190the interface, such as 64.
191.It Li #
192Comments are allowed.
193Anything following a comment character is treated as a comment.
194.It Li \&! Ns Ar command-line
195Arbitrary shell commands can be executed using this directive, as
196long as they are available in the single-user environment (for
197instance,
198.Pa /bin
199or
200.Pa /sbin ) .
201Useful for doing interface-specific configuration such as
202setting up custom routes using
203.Xr route 8
204or establishing tunnels using
205.Xr ifconfig 8 .
206It is worth noting that
207.Dq \e$if
208in a command line will be replaced by the interface name.
209.El
210.Sh DYNAMIC ADDRESS CONFIGURATION
211The following packed formats are valid for configuring network
212interfaces with dynamic addresses:
213.Pp
214A DHCP-configured network interface setup consists of
215.Bd -ragged -offset indent
216.Li dhcp
217.Va options
218.Ed
219.Pp
220The above format has the following field values:
221.Bl -tag -width indent -offset indent
222.It Li dhcp
223The literal string
224.Dq dhcp
225if the interface is to be configured using DHCP.
226See
227.Xr dhclient 8
228and
229.Xr dhclient.conf 5
230for more details.
231.It Va options
232Miscellaneous options to set on the interface, e.g.,
233.Dq media 100baseTX mediaopt full-duplex .
234Valid options for a particular interface type can be found in
235.Xr ifconfig 8 .
236The
237.Ox
238installation script will create
239.Nm hostname.if
240with options of
241.Dq NONE NONE NONE
242when DHCP configuration is chosen.
243This is the same as specifying just
244.Dq dhcp .
245.El
246.Pp
247IPv6 stateless address autoconfiguration:
248.Bd -ragged -offset indent
249.Li rtsol
250.Va options
251.Ed
252.Pp
253The above format has the following field values:
254.Bl -tag -width indent -offset indent
255.It Li rtsol
256The literal string
257.Dq rtsol
258if the interface is to be configured using
259IPv6 stateless address autoconfiguration.
260This should be used on single interface hosts only,
261since the IPv6 specifications are silent about the
262behavior on multi-interface hosts.
263Also note that the kernel must be configured to accept IPv6
264router advertisement, and configured as a host (i.e. non-router).
265Add the following lines into
266.Xr sysctl.conf 5 :
267.Bd -literal -offset indent
268net.inet6.ip6.forwarding=0
269net.inet6.ip6.accept_rtadv=1
270.Ed
271.It Va options
272Miscellaneous options to set on the interface, e.g.,
273.Dq media 100baseTX mediaopt full-duplex .
274Valid options for a particular interface type can be found in
275.Xr ifconfig 8 .
276.El
277.Sh BRIDGE INTERFACE CONFIGURATION
278If the network interface is a bridge, the options described in
279the bridge section of the
280.Xr ifconfig 8
281manual page apply.
282.Pp
283For example:
284.Bd -literal -offset indent
285add fxp0
286add ep1
287-learn fxp0
288#
289!ipsecctl -F
290#
291static fxp0 8:0:20:1e:2f:2b
292up    # and finally enable it
293.Ed
294.Sh SEE ALSO
295.Xr hosts 5 ,
296.Xr dhcp 8 ,
297.Xr ifconfig 8 ,
298.Xr lmccontrol 8 ,
299.Xr netstart 8 ,
300.Xr rc 8
301