xref: /openbsd/share/man/man8/autoinstall.8 (revision a3154df3) 
1.\"     $OpenBSD: autoinstall.8,v 1.25 2021/11/08 16:12:10 kn Exp $
2.\"
3.\" Copyright (c) 2013 Robert Peichaer <rpe@openbsd.org>
4.\"
5.\" Permission to use, copy, modify, and distribute this software for any
6.\" purpose with or without fee is hereby granted, provided that the above
7.\" copyright notice and this permission notice appear in all copies.
8.\"
9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16.\"
17.Dd $Mdocdate: November 8 2021 $
18.Dt AUTOINSTALL 8
19.Os
20.Sh NAME
21.Nm autoinstall
22.Nd unattended OpenBSD installation and upgrade
23.Sh DESCRIPTION
24.Nm
25allows unattended installation or upgrade of
26.Ox
27by automatically responding to installer questions with
28answers from a response file.
29.Nm
30uses DHCP to discover the location of the response
31file and HTTP to fetch the file.
32If that fails, the installer asks for the location which can either be
33a URL or a local path.
34.Pp
35See
36.Xr install.site 5
37for how to provide custom configuration.
38.Pp
39To start unattended installation or upgrade choose '(A)utoinstall' at the
40install prompt.
41If there is only one network interface, the installer fetches the response
42file via that interface.
43If there is more than one network interface, a selection is presented
44and the installer fetches the response file via the selected interface.
45.Pp
46If the machine is netbooted, the
47.Nm
48feature is invoked if the user does not intervene within
49a short time.
50It behaves as if the user selected '(A)utoinstall', but
51always fetches the response file via the netboot interface.
52.Pp
53If either
54.Pa /auto_install.conf
55or
56.Pa /auto_upgrade.conf
57is found on
58.Pa bsd.rd Ns 's
59built-in RAM disk,
60.Nm
61behaves as if the machine is netbooted, but uses the local response file.
62In case both files exist,
63.Pa /auto_install.conf
64takes precedence.
65.Pp
66.Nm
67uses HTTP to fetch one of the files
68.Pa install.conf ,
69.Ar MAC_address Ns - Ns Pa install.conf
70or
71.Ar hostname Ns - Ns Pa install.conf
72for install answers, or one of
73.Pa upgrade.conf ,
74.Ar MAC_address Ns - Ns Pa upgrade.conf
75or
76.Ar hostname Ns - Ns Pa upgrade.conf
77for upgrade answers.
78.Pp
79The URL used to fetch the file is constructed from
80.Xr dhcp-options 5
81statements extracted from the DHCP lease file.
82.Ic next-server
83specifies the
84.Ar server .
85.Ic filename
86specifies the
87.Ar filename .
88The statement
89.Ic option host-name
90specifies the
91.Ar hostname
92which is also used as the default hostname during installation.
93.Pp
94If
95.Ar filename
96is
97.Cm auto_install ,
98then the URLs tried are, in order:
99.Sm off
100.Bd -unfilled -offset indent
101.No http:// Ar server No / Ar MAC_address No -install.conf
102.No http:// Ar server No / Ar hostname No -install.conf
103.No http:// Ar server No /install.conf
104.Ed
105.Sm on
106.Pp
107where
108.Ar MAC_address
109is a string of six hex octets separated by colons
110representing the MAC
111address of the interface being used to fetch the files.
112.Pp
113If
114.Ar filename
115is
116.Cm auto_upgrade ,
117the URLs tried are, in order:
118.Sm off
119.Bd -unfilled -offset indent
120.No http:// Ar server No / Ar MAC_address No -upgrade.conf
121.No http:// Ar server No / Ar hostname No -upgrade.conf
122.No http:// Ar server No /upgrade.conf
123.Ed
124.Sm on
125.Pp
126On architectures where the
127.Ic filename
128statement is used to provide the name of the file to netboot
129it is necessary to create symbolic links called
130.Pa auto_install
131and
132.Pa auto_upgrade
133that point to the expected boot program
134and to change the value of the
135.Ic filename
136statement in the
137.Xr dhcpd.conf 5
138file to be
139.Cm auto_install
140or
141.Cm auto_upgrade .
142.Pp
143To use a subdirectory as response file location on the HTTP server, the same
144directory structure containing the symbolic links has to exist in the tftproot
145directory.
146The value of
147.Ic filename
148has to be the full path to these symbolic links, and the HTTP and TFTP servers
149must be on the same machine.
150.Pp
151The response file is a line-oriented ASCII text file.
152The format of each line is:
153.Pp
154.D1 Ar question No = Ar answer
155.Pp
156.Ar question
157is an installer question (not including the question mark) or a non-ambiguous
158part of it, consisting of whitespace separated words.
159.Ar answer
160is the answer to the question.
161Passwords may be in plaintext, encrypted with
162.Xr encrypt 1 ,
163or set to
164.Ql *************
165(13 '*'s) to disable password logins, only permitting alternative access methods
166(for example,
167.Xr ssh 1
168keys).
169.Pp
170If
171.Nm
172does not find an answer in the response file, the default answer as
173provided by the installer is used.
174.Pp
175The response file may contain answers to the following questions, which are
176only available during unattended installation to provide additional installer
177features:
178.Bl -tag -width Ds
179.It Public ssh key for root account = Ar ssh key
180.Ar ssh key
181is stored in
182.Pa /root/.ssh/authorized_keys .
183.It Public ssh key for user puffy = Ar ssh key
184.Ar ssh key
185is stored in
186.Pa ~puffy/.ssh/authorized_keys .
187.It URL to autopartitioning template for disklabel = Ar url
188A template file for
189.Xr disklabel 8
190autopartitioning is fetched from
191.Ar url
192allowing a custom partition layout for the root disk.
193.El
194.Sh FILES
195.Bl -tag -width "/etc/dhcpd.confXXX" -compact
196.It Pa /etc/dhcpd.conf
197.Xr dhcpd 8
198configuration file
199.It Pa install.conf
200response file for unattended installation
201.It Pa upgrade.conf
202response file for unattended upgrade
203.El
204.Sh EXAMPLES
205A typical
206.Pa install.conf
207file will look something like this:
208.Bd -literal -offset indent
209System hostname = server1
210Password for root = $2b$14$Z4xRMg8vDpgYH...GVot3ySoj8yby
211Change the default console to com0 = yes
212Which speed should com0 use = 19200
213Setup a user = puffy
214Password for user = *************
215Public ssh key for user = ssh-ed25519 AAAAC3NzaC1...g3Aqre puffy@ai
216What timezone are you in = Europe/Stockholm
217Location of sets = http
218HTTP Server = cdn.openbsd.org
219.Ed
220.Pp
221The same file could be used for upgrades by creating a symbolic link called
222.Pa upgrade.conf
223that points to
224.Pa install.conf .
225The upgrade process will only use the answers it needs.
226.Pp
227And an example
228.Xr dhcpd.conf 5
229.Ic host
230declaration:
231.Bd -literal -offset indent
232host foo {
233  hardware ethernet 00:50:60:49:8b:84;
234  fixed-address 192.168.2.180;
235  filename "auto_install";
236  option host-name "foo";
237}
238.Ed
239.Sh SEE ALSO
240.Xr dhcp-options 5 ,
241.Xr dhcpd.conf 5 ,
242.Xr install.site 5 ,
243.Xr diskless 8
244.Sh HISTORY
245The
246.Nm
247feature first appeared in
248.Ox 5.5 .
249.Sh AUTHORS
250.An Robert Peichaer Aq Mt rpe@openbsd.org
251