1.\" $NetBSD: pxeboot.8,v 1.5 2020/08/29 13:32:27 fcambus 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 223The commands accepted in interactive mode are: 224.\" NOTE: some of this text is duplicated in the MI boot.8 225.\" and in other x86-specific *boot.8 files; 226.\" please try to keep all relevant files synchronized. 227.Bl -tag -width 04n -offset 04n 228.It Ic boot Oo Va device : Oc Ns Oo Va filename Oc Oo Fl 1234abcdmqsvxz Oc 229Boot 230.Nx . 231See 232.Cm boot 233in 234.Xr x86/boot 8 235for full details. 236.It Ic help 237Print an overview about commands and arguments. 238.It Ic quit 239Leave the 240.Nm 241program. 242.El 243.Pp 244By default the output from 245.Nm 246and from the booted kernel will go to the system's BIOS console. 247This can be changed to be one of the serial ports by using 248.Nm installboot 249to modify the boot options contained in the 250.Pa pxeboot_ia32.bin 251file. 252.Sh FILES 253.Bl -tag -width /usr/mdec/pxeboot_ia32.bin 254.It Pa /usr/mdec/pxeboot_ia32.bin 255.El 256.Sh EXAMPLES 257To enable 258.Xr boot.cfg 5 259support in the 260.Nm 261program: 262.Bd -literal -offset indent 263installboot -e -o bootconf pxeboot_ia32.bin 264.Ed 265.Pp 266To enable modules loading support in the 267.Nm 268program: 269.Bd -literal -offset indent 270installboot -e -o modules pxeboot_ia32.bin 271.Ed 272.Pp 273The first 274.Pa /etc/dhcpd.conf 275example shows a simple configuration which just loads 276.Dq boot.cfg 277and 278.Dq netbsd 279from the client's NFS root directory, using the defaults for 280protocol and kernel filename. 281Similar setups should be possible with any BOOTP/DHCP server. 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 filename "pxeboot_ia32.bin"; 289 option swap-server mynfsserver; 290 option root-path "/export/myhost"; 291} 292.Ed 293.Pp 294The following 295.Pa /etc/dhcpd.conf 296entry sets loads the boot config and kernel over tftp. 297This can be used, for example, for installing machines by using 298an install kernel. 299.Pp 300.Bd -literal 301host myhost { 302 hardware ethernet 00:00:00:00:00:00; 303 fixed-address myhost; 304 option host-name "myhost"; 305 next-server mytftpserver; 306 307 # This section allows dhcpd to respond with different answers 308 # for the different tftp requests for the bootloader and kernel. 309 if substring (option vendor-class-identifier, 0, 20) 310 = "PXEClient:Arch:00000" { 311 filename "pxeboot_ia32.bin"; 312 } elsif substring (option vendor-class-identifier, 0, 17) 313 = "NetBSD:i386:libsa" { 314 if filename = "boot.cfg" { 315 filename "tftp:boot.cfg"; 316 } else if filename = "netbsd" { 317 filename "tftp:netbsd-INSTALL.gz"; 318 } 319 } 320} 321.Ed 322.Pp 323The following 324.Pa /etc/dhcpd.conf 325entry shows how different system installations can be booted depending on 326the user's input on the 327.Nm 328command line. 329.Pp 330.Bd -literal 331host myhost { 332 hardware ethernet 00:00:00:00:00:00; 333 fixed-address myhost; 334 option host-name "myhost"; 335 next-server mytftpserver; 336 if substring (option vendor-class-identifier, 0, 9) = "PXEClient" { 337 filename "pxeboot_ia32.bin"; 338 } elsif filename = "boot.cfg" { 339 filename "tftp:boot.cfg"; 340 } elsif filename = "tftp" { 341 filename "tftp:netbsd.myhost"; 342 } else { 343 option swap-server mynfsserver; 344 option root-path "/export/myhost"; 345 if filename = "generic" { 346 filename "nfs:gennetbsd"; 347 } else { 348 filename "nfs:netbsd"; 349 } 350 } 351} 352.Ed 353.Pp 354The 355.Tn TFTP 356server is supplied using the 357.Em next-server 358directive. 359The 360.Tn NFS 361server for the root file system is 362.Em mynfsserver . 363The 364.Em swap-server:root-path 365is only used in the 366.Tn NFS 367case and by the 368.Nx 369kernel to mount the root file system. 370.Sh SEE ALSO 371.Xr boot.cfg 5 , 372.Xr dhcpd 8 , 373.Xr diskless 8 , 374.Xr installboot 8 , 375.Xr x86/boot 8 376.Rs 377.%T Preboot Execution Environment (PXE) Specification 378.%N Version 2.1 379.%D September 20, 1999 380.%A Intel Corporation 381.Re 382.Sh HISTORY 383The 384.Nx Ns Tn /x86 385.Nm 386command first appeared in 387.Nx 1.6 . 388.Sh BUGS 389If an error is encountered while reading the 390.Nx 391kernel file or if its file format wasn't recognized, it is 392impossible to retry the operation because the 393.Tn PXE 394network stack is already removed from the system RAM. 395.Pp 396You need the 397.Nm 398from an i386 build to boot an i386 kernel, 399and that from an amd64 build to boot an amd64 kernel. 400.Pp 401In a 402.Tn Xen 403setup, the 404.Nx 405DOM0 kernel is loaded as a module, and cannot know the device 406from which the 407.Tn Xen 408hypervisor was booted. 409In this case, the DOM0 kernel will fall back to the default boot 410device (typically the first disk on the host). 411If the boot device is different from the default one, consider 412passing additional arguments, like 413.Ar bootdev , 414to the DOM0 kernel as explained 415in the 416.Cm load 417command subsection in 418.Xr x86/boot 8 . 419