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