xref: /openbsd/share/man/man8/autoinstall.8 (revision 09467b48) 
1.\"     $OpenBSD: autoinstall.8,v 1.22 2019/04/27 22:30:39 tj 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: April 27 2019 $
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
35To start unattended installation or upgrade choose '(A)utoinstall' at the
36install prompt.
37If there is only one network interface, the installer fetches the response
38file via that interface.
39If there is more than one network interface, a selection is presented
40and the installer fetches the response file via the selected interface.
41.Pp
42If the machine is netbooted, the
43.Nm
44feature is invoked if the user does not intervene within
45a short time.
46It behaves as if the user selected '(A)utoinstall', but
47always fetches the response file via the netboot interface.
48.Pp
49If either
50.Pa /auto_install.conf
51or
52.Pa /auto_upgrade.conf
53is found on
54.Pa bsd.rd Ns 's
55built-in RAM disk,
56.Nm
57behaves as if the machine is netbooted, but uses the local response file.
58In case both files exist,
59.Pa /auto_install.conf
60takes precedence.
61.Pp
62.Nm
63uses HTTP to fetch one of the files
64.Pa install.conf ,
65.Ar MAC_address Ns - Ns Pa install.conf
66or
67.Ar hostname Ns - Ns Pa install.conf
68for install answers, or one of
69.Pa upgrade.conf ,
70.Ar MAC_address Ns - Ns Pa upgrade.conf
71or
72.Ar hostname Ns - Ns Pa upgrade.conf
73for upgrade answers.
74The URL used to fetch the file is constructed from
75.Xr dhcpd.conf 5
76statements extracted from the
77.Xr dhclient 8
78lease file.
79One of the statements
80.Ic server-name ,
81.Ic option tftp-server-name ,
82or
83.Ic next-server
84(in that order of priority) specify the
85.Ar server .
86One of the statements
87.Ic filename
88or
89.Ic option bootfile-name
90(in that order of priority) specify the
91.Ar filename .
92The statement
93.Ic option host-name
94specifies the
95.Ar hostname
96which is also used as the default hostname during installation.
97.Pp
98If
99.Ar filename
100is
101.Cm auto_install ,
102then the URLs tried are, in order:
103.Sm off
104.Bd -unfilled -offset indent
105.No http:// Ar server No / Ar MAC_address No -install.conf
106.No http:// Ar server No / Ar hostname No -install.conf
107.No http:// Ar server No /install.conf
108.Ed
109.Sm on
110.Pp
111where
112.Ar MAC_address
113is a string of six hex octets separated by colons
114representing the MAC
115address of the interface being used to fetch the files.
116.Pp
117If
118.Ar filename
119is
120.Cm auto_upgrade ,
121the URLs tried are, in order:
122.Sm off
123.Bd -unfilled -offset indent
124.No http:// Ar server No / Ar MAC_address No -upgrade.conf
125.No http:// Ar server No / Ar hostname No -upgrade.conf
126.No http:// Ar server No /upgrade.conf
127.Ed
128.Sm on
129.Pp
130On architectures where the
131.Ic filename
132statement is used to provide the name of the file to netboot
133it is necessary to create symbolic links called
134.Pa auto_install
135and
136.Pa auto_upgrade
137that point to the expected boot program
138and to change the value of the
139.Ic filename
140statement in the
141.Xr dhcpd.conf 5
142file to be
143.Cm auto_install
144or
145.Cm auto_upgrade .
146.Pp
147To use a subdirectory as response file location on the HTTP server, the same
148directory structure containing the symbolic links has to exist in the tftproot
149directory.
150The value of
151.Ic filename
152has to be the full path to these symbolic links, and the HTTP and TFTP servers
153must be on the same machine.
154.Pp
155The response file is a line-oriented ASCII text file.
156The format of each line is:
157.Pp
158.D1 Ar question No = Ar answer
159.Pp
160.Ar question
161is an installer question (not including the question mark) or a non-ambiguous
162part of it, consisting of whitespace separated words.
163.Ar answer
164is the answer to the question.
165Passwords may be in plaintext, encrypted with
166.Xr encrypt 1 ,
167or set to
168.Ql *************
169(13 '*'s) to disable password logins, only permitting alternative access methods
170(for example,
171.Xr ssh 1
172keys).
173.Pp
174If
175.Nm
176does not find an answer in the response file, the default answer as
177provided by the installer is used.
178.Pp
179The response file may contain answers to the following questions, which are
180only available during unattended installation to provide additional installer
181features:
182.Bl -tag -width Ds
183.It Public ssh key for root account = Ar ssh key
184.Ar ssh key
185is stored in
186.Pa /root/.ssh/authorized_keys .
187.It Public ssh key for user puffy = Ar ssh key
188.Ar ssh key
189is stored in
190.Pa ~puffy/.ssh/authorized_keys .
191.It URL to autopartitioning template for disklabel = Ar url
192A template file for
193.Xr disklabel 8
194autopartitioning is fetched from
195.Ar url
196allowing a custom partition layout for the root disk.
197.El
198.Sh FILES
199.Bl -tag -width "/etc/dhcpd.confXXX" -compact
200.It Pa /etc/dhcpd.conf
201.Xr dhcpd 8
202configuration file
203.It Pa install.conf
204response file for unattended installation
205.It Pa upgrade.conf
206response file for unattended upgrade
207.El
208.Sh EXAMPLES
209A typical
210.Pa install.conf
211file will look something like this:
212.Bd -literal -offset indent
213System hostname = server1
214Password for root = $2b$14$Z4xRMg8vDpgYH...GVot3ySoj8yby
215Change the default console to com0 = yes
216Which speed should com0 use = 19200
217Setup a user = puffy
218Password for user = *************
219Public ssh key for user = ssh-ed25519 AAAAC3NzaC1...g3Aqre puffy@ai
220What timezone are you in = Europe/Stockholm
221Location of sets = http
222HTTP Server = cdn.openbsd.org
223.Ed
224.Pp
225The same file could be used for upgrades by creating a symbolic link called
226.Pa upgrade.conf
227that points to
228.Pa install.conf .
229The upgrade process will only use the answers it needs.
230.Pp
231And an example
232.Xr dhcpd.conf 5
233.Ic host
234declaration:
235.Bd -literal -offset indent
236host foo {
237  hardware ethernet 00:50:60:49:8b:84;
238  fixed-address 192.168.2.180;
239  filename "auto_install";
240  option host-name "foo";
241}
242.Ed
243.Sh SEE ALSO
244.Xr dhcpd.conf 5 ,
245.Xr diskless 8
246.Sh HISTORY
247The
248.Nm
249feature first appeared in
250.Ox 5.5 .
251.Sh AUTHORS
252.An Robert Peichaer Aq Mt rpe@openbsd.org
253