1.\" $NetBSD: pxeboot.8,v 1.6 2023/04/24 13:55:45 manu Exp $ 2.\" 3.\" Copyright (c) 2003 4.\" Matthias Drochner. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25.\" SUCH DAMAGE. 26.\" 27.Dd February 17, 2017 28.Dt PXEBOOT 8 x86 29.Os 30.Sh NAME 31.Nm pxeboot 32.Nd network boot NetBSD/x86 through a PXE BIOS extension 33.Sh DESCRIPTION 34.Nm 35is a 36.Nx 37boot program running on top of a 38.Tn PXE 39.Tn BIOS 40extension which is 41provided by the motherboard or a plug-in network adapter, 42in accordance with the 43.Tn Intel 44Preboot eXecution Environment 45.Pq Tn PXE 46specification. 47.Pp 48By default, the 49.Nm 50program is configured with modules loading and 51.Xr boot.cfg 5 52support disabled. 53See 54.Sx EXAMPLES 55for how to enable these options individually. 56This manual page assumes that 57.Xr boot.cfg 5 58support is enabled. 59.Pp 60Network booting a system through 61.Tn PXE 62is a two-stage process: 63.Pp 64.Bl -enum 65.It 66The 67.Tn PXE 68.Tn BIOS 69issues a 70.Tn DHCP 71request and fetches the 72.Nx 73.Nm 74program using 75.Tn TFTP . 76.It 77The 78.Nx 79.Nm 80program takes control. 81It immediately issues another 82.Tn DHCP 83request to get the name of a 84.Xr boot.cfg 5 85file to load, using 86.Dq boot.cfg 87by default. 88If the boot config file is not found, or if the supplied file appears 89not to be a boot configuration file, the file is skipped. 90Otherwise it is loaded and obeyed as described in 91.Xr boot.cfg 5 . 92If a boot configuration is not loaded, the user has the option to 93enter a limited version of the standard interactive boot mode by 94pressing a key within five seconds. 95After this time, or after the user's 96.Ic boot 97command, another 98.Tn DHCP 99request is issued and the kernel filename returned by the 100.Tn DHCP 101reply, using 102.Dq netbsd 103by default, 104is loaded. 105To read the kernel file, the 106.Tn NFS 107.Pq version 2 108or 109.Tn TFTP 110protocols can be used. 111.El 112.Pp 113The 114.Tn DHCP 115request issued by the 116.Nx 117.Nm 118program has the following special parameters: 119.Bl -tag -width xxxx 120.It Bootfile name 121is set to 122.Dq boot.cfg 123during the first request, and then to 124the 125.Va filename 126argument on the 127.Ic boot 128command line typed in by the user (can be empty), using 129.Dq netbsd 130in the non-interactive case. 131.It DHCP Vendor class identifier tag 132is set to 133.Dq NetBSD:i386:libsa . 134.El 135.Pp 136The 137.Tn DHCP 138server can use these fields (i.e. the 139.Tn DHCP 140vendor class identifier tag and the requested file name, possibly 141supplied by the user's command line input to the 142.Nm 143program) to distinguish between the various originators of requests 144(PXE BIOS, first and second 145.Nm 146stage, 147.Nx 148kernel), and to alter its behaviour. 149For example, this can be used to support alternative 150.Nx 151installations on one machine. 152.Pp 153In addition to the standard network interface configuration, 154the following fields in the 155.Tn DHCP 156reply are interpreted: 157.Bl -tag -width xxxx 158.It Bootfile name 159specifies the protocol to be used, and the filename of the 160boot config or 161.Nx 162kernel to be booted, separated by a colon. 163Available protocols are 164.Dq nfs 165and 166.Dq tftp . 167The boot config or kernel filename part is interpreted relatively to 168the NFS root directory (see the 169.Em Root path 170reply field below) or the TFTP server's root directory (which might be a 171subdirectory within the TFTP server's filesystem, depending on the 172implementation), respectively. 173If the 174.Em Bootfile name 175field replied by the DHCP server does not contain a colon, 176it is ignored, and the 177.Va filename 178typed in at the 179.Nm 180command line prompt (or the 181.Dq netbsd 182default, see the section about the 183.Em Bootfile name 184field in the DHCP request above) is used. 185If no protocol was specified, 186.Dq nfs 187is assumed. 188.It Next server 189is used as the location of the tftp server. 190.It Swap server 191can be used to override the 192.Dq server IP address 193if 194.Tn NFS 195is used to access the kernel. 196This matches the behaviour of the 197.Nx 198kernel to access its root file system on 199.Tn NFS . 200This way, different 201.Tn TFTP 202and 203.Tn NFS 204servers can be communicated to 205the 206.Tn DHCP 207client 208.Po 209it is actually a deficiency of the 210.Tn DHCP 211protocol to provide a 212.Dq root path 213field but no corresponding IP address 214.Pc . 215.It Root path 216is used as path to be mounted in the 217.Tn NFS 218case to access the kernel file, matching the 219.Nx 220kernel's behaviour. 221.El 222.Pp 223See 224.Xr x86/boot 8 225for the commands accepted in interactive mode. 226.Pp 227By default the output from 228.Nm 229and from the booted kernel will go to the system's BIOS console. 230This can be changed to be one of the serial ports by using 231.Nm installboot 232to modify the boot options contained in the 233.Pa pxeboot_ia32.bin 234file. 235.Sh FILES 236.Bl -tag -width /usr/mdec/pxeboot_ia32.bin 237.It Pa /usr/mdec/pxeboot_ia32.bin 238.El 239.Sh EXAMPLES 240To enable 241.Xr boot.cfg 5 242support in the 243.Nm 244program: 245.Bd -literal -offset indent 246installboot -e -o bootconf pxeboot_ia32.bin 247.Ed 248.Pp 249To enable modules loading support in the 250.Nm 251program: 252.Bd -literal -offset indent 253installboot -e -o modules pxeboot_ia32.bin 254.Ed 255.Pp 256The first 257.Pa /etc/dhcpd.conf 258example shows a simple configuration which just loads 259.Dq boot.cfg 260and 261.Dq netbsd 262from the client's NFS root directory, using the defaults for 263protocol and kernel filename. 264Similar setups should be possible with any BOOTP/DHCP server. 265.Pp 266.Bd -literal 267host myhost { 268 hardware ethernet 00:00:00:00:00:00; 269 fixed-address myhost; 270 option host-name "myhost"; 271 filename "pxeboot_ia32.bin"; 272 option swap-server mynfsserver; 273 option root-path "/export/myhost"; 274} 275.Ed 276.Pp 277The following 278.Pa /etc/dhcpd.conf 279entry sets loads the boot config and kernel over tftp. 280This can be used, for example, for installing machines by using 281an install kernel. 282.Pp 283.Bd -literal 284host myhost { 285 hardware ethernet 00:00:00:00:00:00; 286 fixed-address myhost; 287 option host-name "myhost"; 288 next-server mytftpserver; 289 290 # This section allows dhcpd to respond with different answers 291 # for the different tftp requests for the bootloader and kernel. 292 if substring (option vendor-class-identifier, 0, 20) 293 = "PXEClient:Arch:00000" { 294 filename "pxeboot_ia32.bin"; 295 } elsif substring (option vendor-class-identifier, 0, 17) 296 = "NetBSD:i386:libsa" { 297 if filename = "boot.cfg" { 298 filename "tftp:boot.cfg"; 299 } else if filename = "netbsd" { 300 filename "tftp:netbsd-INSTALL.gz"; 301 } 302 } 303} 304.Ed 305.Pp 306The following 307.Pa /etc/dhcpd.conf 308entry shows how different system installations can be booted depending on 309the user's input on the 310.Nm 311command line. 312.Pp 313.Bd -literal 314host myhost { 315 hardware ethernet 00:00:00:00:00:00; 316 fixed-address myhost; 317 option host-name "myhost"; 318 next-server mytftpserver; 319 if substring (option vendor-class-identifier, 0, 9) = "PXEClient" { 320 filename "pxeboot_ia32.bin"; 321 } elsif filename = "boot.cfg" { 322 filename "tftp:boot.cfg"; 323 } elsif filename = "tftp" { 324 filename "tftp:netbsd.myhost"; 325 } else { 326 option swap-server mynfsserver; 327 option root-path "/export/myhost"; 328 if filename = "generic" { 329 filename "nfs:gennetbsd"; 330 } else { 331 filename "nfs:netbsd"; 332 } 333 } 334} 335.Ed 336.Pp 337The 338.Tn TFTP 339server is supplied using the 340.Em next-server 341directive. 342The 343.Tn NFS 344server for the root file system is 345.Em mynfsserver . 346The 347.Em swap-server:root-path 348is only used in the 349.Tn NFS 350case and by the 351.Nx 352kernel to mount the root file system. 353.Sh SEE ALSO 354.Xr boot.cfg 5 , 355.Xr dhcpd 8 , 356.Xr diskless 8 , 357.Xr installboot 8 , 358.Xr x86/boot 8 359.Rs 360.%T Preboot Execution Environment (PXE) Specification 361.%N Version 2.1 362.%D September 20, 1999 363.%A Intel Corporation 364.Re 365.Sh HISTORY 366The 367.Nx Ns Tn /x86 368.Nm 369command first appeared in 370.Nx 1.6 . 371.Sh BUGS 372If an error is encountered while reading the 373.Nx 374kernel file or if its file format wasn't recognized, it is 375impossible to retry the operation because the 376.Tn PXE 377network stack is already removed from the system RAM. 378.Pp 379You need the 380.Nm 381from an i386 build to boot an i386 kernel, 382and that from an amd64 build to boot an amd64 kernel. 383.Pp 384In a 385.Tn Xen 386setup, the 387.Nx 388DOM0 kernel is loaded as a module, and cannot know the device 389from which the 390.Tn Xen 391hypervisor was booted. 392In this case, the DOM0 kernel will fall back to the default boot 393device (typically the first disk on the host). 394If the boot device is different from the default one, consider 395passing additional arguments, like 396.Ar bootdev , 397to the DOM0 kernel as explained 398in the 399.Cm load 400command subsection in 401.Xr x86/boot 8 . 402