xref: /openbsd-src/share/man/man5/hostname.if.5 (revision 46035553bfdd96e63c94e32da0210227ec2e3cf1) 
1.\"	$OpenBSD: hostname.if.5,v 1.73 2020/12/23 17:22:07 krw 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 23 2020 $
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.Pp
67Each line is processed separately and in order.
68For example:
69.Bd -literal -offset indent
70nwid mynwid wpakey mywpakey
71inet6 autoconf
72dhcp
73.Ed
74.Pp
75would run ifconfig to set the nwid and wpakey of the interface, run it again to set the AUTOCONF6 flag, and then start
76.Xr dhclient 8 .
77.Sh STATIC ADDRESS CONFIGURATION
78The following packed formats are valid for configuring network
79interfaces with static addresses.
80.Pp
81Regular 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
94Regular 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
106Other network setup:
107.Bd -ragged -offset indent
108.Va addr_family
109.Va options
110.Ed
111.Pp
112A typical file contains only one line, but more extensive files are possible,
113for example:
114.Bd -literal -offset 1n
115media 100baseTX description Uplink
116inet 10.0.1.12 255.255.255.0 10.0.1.255
117inet alias 10.0.1.13 255.255.255.255 10.0.1.13
118inet alias 10.0.1.14 255.255.255.255 NONE
119inet alias 10.0.1.15 255.255.255.255
120inet alias 10.0.1.16 0xffffffff
121# This is an example comment line.
122inet6 alias fec0::1 64
123inet6 alias fec0::2 64 anycast
124!route add 65.65.65.65 10.0.1.13
125up
126.Ed
127.Pp
128The above formats have the following field values:
129.Bl -tag -width indent -offset indent
130.It Va addr_family
131The address family of the interface, generally
132.Dq inet
133or
134.Dq inet6 .
135.It Li alias
136The literal string
137.Dq alias
138if this is an additional network address for the interface.
139.It Va addr
140The optional address that belongs to the interface, such as
141190.191.192.1 or fe80:2::1.
142It is also feasible to use a hostname as specified in
143.Pa /etc/hosts .
144It is recommended that an address be used instead of symbolic information,
145since the latter might activate resolver library routines.
146.Pp
147If no address is specified, the
148.Va netmask ,
149.Va broadcast_addr ,
150.Li dest ,
151and
152.Va dest_addr
153options are invalid and will be ignored.
154.It Va netmask
155The optional network mask for the interface, e.g.,
156255.255.255.0.
157If
158.Va addr
159is specified but
160.Va netmask
161is not, the classful mask based on
162.Va addr
163is used.
164.It Va broadcast_addr
165The optional broadcast address for the interface, e.g.,
166190.191.192.255.
167The word
168.Dq NONE
169can also be specified in order to configure the broadcast address based
170on the
171.Va netmask .
172The
173.Va netmask
174option must be present in order to use this option.
175.It Va options
176Miscellaneous options to set on the interface, e.g.,
177.Dq media 100baseTX mediaopt full-duplex .
178Valid options for a particular interface type can be found in
179.Xr ifconfig 8 .
180When used, the
181.Va netmask
182and
183.Va broadcast_addr
184options must also be present.
185.It Li dest
186If the interface needs a destination address set, this is the literal text
187.Dq dest .
188As shown in the example, this declaration should start on a separate line.
189.It Va dest_addr
190The destination address to be set on the interface, such as
191190.191.192.2.
192It is also feasible to use a hostname as specified in
193.Pa /etc/hosts .
194It is recommended that an address be used instead of symbolic information
195which might activate resolver library routines.
196.It Va prefixlen
197The prefixlen number, or number of bits in the netmask, to be set on
198the interface, such as 64.
199.It Li #
200Comments are allowed.
201Anything following a comment character is treated as a comment.
202.It Li \&! Ns Ar command
203Arbitrary shell commands can be executed using this directive, as
204long as they are available in the single-user environment (for
205instance,
206.Pa /bin
207or
208.Pa /sbin ) .
209Useful for doing interface-specific configuration such as
210setting up custom routes or default source IP address using
211.Xr route 8
212or establishing tunnels using
213.Xr ifconfig 8 .
214It is worth noting that
215.Dq \e$if
216in a command line will be replaced by the interface name.
217.Pp
218For example,
219to set 192.0.2.1 and 2001:db8::1 as source IP addresses for
220outgoing connections:
221.Bd -literal -offset indent
222inet 192.0.2.1/32
223inet6 2001:db8::1/128
224up
225!route sourceaddr -ifp \e$if
226.Ed
227.El
228.Sh DYNAMIC ADDRESS CONFIGURATION
229The following packed formats are valid for configuring network interfaces
230with dynamic addresses.
231.Pp
232For IPv4 dynamic addressing using DHCP, the literal string
233.Dq dhcp
234followed first by
235.Xr dhclient 8
236options and then by
237.Xr ifconfig 8
238options.
239Note that
240.Xr ifconfig 8
241is executed before
242.Xr dhclient 8 .
243.Bd -ragged -offset indent
244.Li dhcp
245.Op Va dhclient_options
246.Op Va ifconfig_options
247.Ed
248.Pp
249For IPv6 stateless address autoconfiguration the literal string
250.Dq inet6 autoconf
251followed by any options to be passed to
252.Xr ifconfig 8 .
253Note that
254.Xr slaacd 8
255must also be enabled.
256.Bd -ragged -offset indent
257.Li inet6 autoconf
258.Op Va ifconfig_options
259.Ed
260.Sh BRIDGE INTERFACE CONFIGURATION
261If the network interface is a bridge, the options described in
262the bridge section of the
263.Xr ifconfig 8
264manual page apply.
265.Pp
266For example:
267.Bd -literal -offset indent
268add fxp0
269add ep1
270-learn fxp0
271#
272!ipsecctl -F
273#
274static fxp0 8:0:20:1e:2f:2b
275up    # and finally enable it
276.Ed
277.Sh FILES
278.Bl -tag -width "/etc/hostname.XXXXXX"
279.It Pa /etc/hostname.XXX
280Interface-specific configuration files.
281.El
282.Sh SEE ALSO
283.Xr dhclient.conf 5 ,
284.Xr hosts 5 ,
285.Xr dhclient 8 ,
286.Xr ifconfig 8 ,
287.Xr netstart 8 ,
288.Xr rc 8 ,
289.Xr slaacd 8
290