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