xref: /openbsd/share/man/man5/hostname.if.5 (revision 51e3b6ac) 
1.\"	$OpenBSD: hostname.if.5,v 1.82 2022/12/16 04:04:25 afresh1 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: December 16 2022 $
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.
43Interfaces are referenced by name and unit,
44such as
45.Dq hostname.fxp0 .
46For some machines,
47autoconfiguration makes this system inconsistent,
48so interfaces can alternatively be referenced by
49their link layer address (lladdr),
50such as
51.Dq hostname.00:00:5e:00:53:af .
52Priority is given to configuration by interface lladdr over name/unit.
53A configuration file is not needed for lo0.
54.Pp
55The configuration information is expressed in a line-by-line packed format
56which makes the most common cases simpler; those dense formats are described
57below.
58Any lines not matching these packed formats are passed directly to
59.Xr ifconfig 8 .
60The packed formats are converted using a somewhat inflexible parser and
61the administrator should not expect magic \(em if in doubt study
62.Xr ifconfig 8
63and the
64per-driver manual pages to see what arguments are permitted.
65.Pp
66Arguments containing either whitespace or single quote
67characters must be double quoted.
68For example:
69.Bd -literal -offset indent
70inet 10.0.0.1 255.255.255.0 10.0.0.255 description "Bob's uplink"
71.Ed
72.Pp
73Each line is processed separately and in order.
74For example:
75.Bd -literal -offset indent
76join mynwid wpakey mywpakey
77inet6 autoconf
78inet autoconf
79.Ed
80.Pp
81would run ifconfig three times to add a wireless network using WPA to the
82join list and enable dynamic address configuration for IPv6 and IPv4.
83.Sh STATIC ADDRESS CONFIGURATION
84The following packed formats are valid for configuring network
85interfaces with static addresses.
86.Pp
87Regular IPv4 network setup:
88.Bd -ragged -offset indent
89.Li inet
90.Op Li alias
91.Va addr
92.Va netmask
93.Va broadcast_addr
94.Va options
95.br
96.Li dest
97.Va dest_addr
98.Ed
99.Pp
100Regular IPv6 network setup:
101.Bd -ragged -offset indent
102.Li inet6
103.Op Li alias
104.Va addr
105.Va prefixlen
106.Va options
107.br
108.Li dest
109.Va dest_addr
110.Ed
111.Pp
112Other network setup:
113.Bd -ragged -offset indent
114.Va addr_family
115.Va options
116.Ed
117.Pp
118A typical file contains only one line, but more extensive files are possible,
119for example:
120.Bd -literal -offset 1n
121media 100baseTX description Uplink
122inet 10.0.1.12 255.255.255.0 10.0.1.255
123inet alias 10.0.1.13 255.255.255.255 10.0.1.13
124inet alias 10.0.1.14 255.255.255.255 NONE
125inet alias 10.0.1.15 255.255.255.255
126inet alias 10.0.1.16 0xffffffff
127# This is an example comment line.
128inet6 alias fec0::1 64
129inet6 alias fec0::2 64 anycast
130!route add 65.65.65.65 10.0.1.13
131up
132.Ed
133.Pp
134The above formats have the following field values:
135.Bl -tag -width indent -offset indent
136.It Va addr_family
137The address family of the interface, generally
138.Dq inet
139or
140.Dq inet6 .
141.It Li alias
142The literal string
143.Dq alias
144if this is an additional network address for the interface.
145.It Va addr
146The optional address that belongs to the interface, such as
147190.191.192.1 or fe80:2::1.
148It is also feasible to use a hostname as specified in
149.Pa /etc/hosts .
150It is recommended that an address be used instead of symbolic information,
151since the latter might activate resolver library routines.
152.Pp
153If no address is specified, the
154.Va netmask ,
155.Va broadcast_addr ,
156.Li dest ,
157and
158.Va dest_addr
159options are invalid and will be ignored.
160.It Va netmask
161The optional network mask for the interface, e.g.,
162255.255.255.0.
163If
164.Va addr
165is specified but
166.Va netmask
167is not, the classful mask based on
168.Va addr
169is used.
170.It Va broadcast_addr
171The optional broadcast address for the interface, e.g.,
172190.191.192.255.
173The word
174.Dq NONE
175can also be specified in order to configure the broadcast address based
176on the
177.Va netmask .
178The
179.Va netmask
180option must be present in order to use this option.
181.It Va options
182Miscellaneous options to set on the interface, e.g.,
183.Dq media 100baseTX mediaopt full-duplex .
184Valid options for a particular interface type can be found in
185.Xr ifconfig 8 .
186When used, the
187.Va netmask
188and
189.Va broadcast_addr
190options must also be present.
191.It Li dest
192If the interface needs a destination address set, this is the literal text
193.Dq dest .
194As shown in the example, this declaration should start on a separate line.
195.It Va dest_addr
196The destination address to be set on the interface, such as
197190.191.192.2.
198It is also feasible to use a hostname as specified in
199.Pa /etc/hosts .
200It is recommended that an address be used instead of symbolic information
201which might activate resolver library routines.
202.It Va prefixlen
203The prefixlen number, or number of bits in the netmask, to be set on
204the interface, such as 64.
205.It Li #
206Comments are allowed.
207Anything following a comment character is treated as a comment.
208.It Li \&! Ns Ar command
209Arbitrary shell commands can be executed using this directive, as
210long as they are available in the single-user environment (for
211instance,
212.Pa /bin
213or
214.Pa /sbin ) .
215Useful for doing interface-specific configuration such as
216setting up custom routes or default source IP address using
217.Xr route 8
218or establishing tunnels using
219.Xr ifconfig 8 .
220It is worth noting that
221.Dq \e$if
222in a command line will be replaced by the interface name.
223.Pp
224For example,
225to set 192.0.2.1 and 2001:db8::1 as source IP addresses for
226outgoing connections:
227.Bd -literal -offset indent
228inet 192.0.2.1/32
229inet6 2001:db8::1/128
230up
231!route sourceaddr -ifp \e$if
232.Ed
233.El
234.Sh DYNAMIC ADDRESS CONFIGURATION
235IPv4 dynamic addressing via DHCP is requested using
236.Dq inet autoconf
237followed by any options to be passed to
238.Xr ifconfig 8 .
239.Bd -ragged -offset indent
240.Li inet autoconf
241.Op Va ifconfig_options
242.Ed
243.Pp
244The token
245.Dq dhcp
246on its own line without any options is short for
247.Dq inet autoconf .
248.Pp
249IPv6 stateless address autoconfiguration is requested using
250the literal string
251.Dq inet6 autoconf
252followed by any options to be passed to
253.Xr ifconfig 8 .
254.Bd -ragged -offset indent
255.Li inet6 autoconf
256.Op Va ifconfig_options
257.Ed
258.Pp
259The
260.Va autoconf
261configurations will communicate learned DNS information to
262.Xr resolvd 8 .
263.Sh FILES
264.Bl -tag -width "/etc/hostname.XXXXXX"
265.It Pa /etc/hostname.XXX
266Interface-specific configuration files.
267.El
268.Sh SEE ALSO
269.Xr hosts 5 ,
270.Xr ifconfig 8 ,
271.Xr netstart 8 ,
272.Xr rc 8 ,
273.Xr slaacd 8
274