.\" $NetBSD: pxeboot.8,v 1.5.6.1 2023/05/13 13:26:56 martin Exp $ .\" .\" Copyright (c) 2003 .\" Matthias Drochner. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .Dd February 17, 2017 .Dt PXEBOOT 8 x86 .Os .Sh NAME .Nm pxeboot .Nd network boot NetBSD/x86 through a PXE BIOS extension .Sh DESCRIPTION .Nm is a .Nx boot program running on top of a .Tn PXE .Tn BIOS extension which is provided by the motherboard or a plug-in network adapter, in accordance with the .Tn Intel Preboot eXecution Environment .Pq Tn PXE specification. .Pp By default, the .Nm program is configured with modules loading and .Xr boot.cfg 5 support disabled. See .Sx EXAMPLES for how to enable these options individually. This manual page assumes that .Xr boot.cfg 5 support is enabled. .Pp Network booting a system through .Tn PXE is a two-stage process: .Pp .Bl -enum .It The .Tn PXE .Tn BIOS issues a .Tn DHCP request and fetches the .Nx .Nm program using .Tn TFTP . .It The .Nx .Nm program takes control. It immediately issues another .Tn DHCP request to get the name of a .Xr boot.cfg 5 file to load, using .Dq boot.cfg by default. If the boot config file is not found, or if the supplied file appears not to be a boot configuration file, the file is skipped. Otherwise it is loaded and obeyed as described in .Xr boot.cfg 5 . If a boot configuration is not loaded, the user has the option to enter a limited version of the standard interactive boot mode by pressing a key within five seconds. After this time, or after the user's .Ic boot command, another .Tn DHCP request is issued and the kernel filename returned by the .Tn DHCP reply, using .Dq netbsd by default, is loaded. To read the kernel file, the .Tn NFS .Pq version 2 or .Tn TFTP protocols can be used. .El .Pp The .Tn DHCP request issued by the .Nx .Nm program has the following special parameters: .Bl -tag -width xxxx .It Bootfile name is set to .Dq boot.cfg during the first request, and then to the .Va filename argument on the .Ic boot command line typed in by the user (can be empty), using .Dq netbsd in the non-interactive case. .It DHCP Vendor class identifier tag is set to .Dq NetBSD:i386:libsa . .El .Pp The .Tn DHCP server can use these fields (i.e. the .Tn DHCP vendor class identifier tag and the requested file name, possibly supplied by the user's command line input to the .Nm program) to distinguish between the various originators of requests (PXE BIOS, first and second .Nm stage, .Nx kernel), and to alter its behaviour. For example, this can be used to support alternative .Nx installations on one machine. .Pp In addition to the standard network interface configuration, the following fields in the .Tn DHCP reply are interpreted: .Bl -tag -width xxxx .It Bootfile name specifies the protocol to be used, and the filename of the boot config or .Nx kernel to be booted, separated by a colon. Available protocols are .Dq nfs and .Dq tftp . The boot config or kernel filename part is interpreted relatively to the NFS root directory (see the .Em Root path reply field below) or the TFTP server's root directory (which might be a subdirectory within the TFTP server's filesystem, depending on the implementation), respectively. If the .Em Bootfile name field replied by the DHCP server does not contain a colon, it is ignored, and the .Va filename typed in at the .Nm command line prompt (or the .Dq netbsd default, see the section about the .Em Bootfile name field in the DHCP request above) is used. If no protocol was specified, .Dq nfs is assumed. .It Next server is used as the location of the tftp server. .It Swap server can be used to override the .Dq server IP address if .Tn NFS is used to access the kernel. This matches the behaviour of the .Nx kernel to access its root file system on .Tn NFS . This way, different .Tn TFTP and .Tn NFS servers can be communicated to the .Tn DHCP client .Po it is actually a deficiency of the .Tn DHCP protocol to provide a .Dq root path field but no corresponding IP address .Pc . .It Root path is used as path to be mounted in the .Tn NFS case to access the kernel file, matching the .Nx kernel's behaviour. .El .Pp See .Xr x86/boot 8 for the commands accepted in interactive mode. .Pp By default the output from .Nm and from the booted kernel will go to the system's BIOS console. This can be changed to be one of the serial ports by using .Nm installboot to modify the boot options contained in the .Pa pxeboot_ia32.bin file. .Sh FILES .Bl -tag -width /usr/mdec/pxeboot_ia32.bin .It Pa /usr/mdec/pxeboot_ia32.bin .El .Sh EXAMPLES To enable .Xr boot.cfg 5 support in the .Nm program: .Bd -literal -offset indent installboot -e -o bootconf pxeboot_ia32.bin .Ed .Pp To enable modules loading support in the .Nm program: .Bd -literal -offset indent installboot -e -o modules pxeboot_ia32.bin .Ed .Pp The first .Pa /etc/dhcpd.conf example shows a simple configuration which just loads .Dq boot.cfg and .Dq netbsd from the client's NFS root directory, using the defaults for protocol and kernel filename. Similar setups should be possible with any BOOTP/DHCP server. .Pp .Bd -literal host myhost { hardware ethernet 00:00:00:00:00:00; fixed-address myhost; option host-name "myhost"; filename "pxeboot_ia32.bin"; option swap-server mynfsserver; option root-path "/export/myhost"; } .Ed .Pp The following .Pa /etc/dhcpd.conf entry sets loads the boot config and kernel over tftp. This can be used, for example, for installing machines by using an install kernel. .Pp .Bd -literal host myhost { hardware ethernet 00:00:00:00:00:00; fixed-address myhost; option host-name "myhost"; next-server mytftpserver; # This section allows dhcpd to respond with different answers # for the different tftp requests for the bootloader and kernel. if substring (option vendor-class-identifier, 0, 20) = "PXEClient:Arch:00000" { filename "pxeboot_ia32.bin"; } elsif substring (option vendor-class-identifier, 0, 17) = "NetBSD:i386:libsa" { if filename = "boot.cfg" { filename "tftp:boot.cfg"; } else if filename = "netbsd" { filename "tftp:netbsd-INSTALL.gz"; } } } .Ed .Pp The following .Pa /etc/dhcpd.conf entry shows how different system installations can be booted depending on the user's input on the .Nm command line. .Pp .Bd -literal host myhost { hardware ethernet 00:00:00:00:00:00; fixed-address myhost; option host-name "myhost"; next-server mytftpserver; if substring (option vendor-class-identifier, 0, 9) = "PXEClient" { filename "pxeboot_ia32.bin"; } elsif filename = "boot.cfg" { filename "tftp:boot.cfg"; } elsif filename = "tftp" { filename "tftp:netbsd.myhost"; } else { option swap-server mynfsserver; option root-path "/export/myhost"; if filename = "generic" { filename "nfs:gennetbsd"; } else { filename "nfs:netbsd"; } } } .Ed .Pp The .Tn TFTP server is supplied using the .Em next-server directive. The .Tn NFS server for the root file system is .Em mynfsserver . The .Em swap-server:root-path is only used in the .Tn NFS case and by the .Nx kernel to mount the root file system. .Sh SEE ALSO .Xr boot.cfg 5 , .Xr dhcpd 8 , .Xr diskless 8 , .Xr installboot 8 , .Xr x86/boot 8 .Rs .%T Preboot Execution Environment (PXE) Specification .%N Version 2.1 .%D September 20, 1999 .%A Intel Corporation .Re .Sh HISTORY The .Nx Ns Tn /x86 .Nm command first appeared in .Nx 1.6 . .Sh BUGS If an error is encountered while reading the .Nx kernel file or if its file format wasn't recognized, it is impossible to retry the operation because the .Tn PXE network stack is already removed from the system RAM. .Pp You need the .Nm from an i386 build to boot an i386 kernel, and that from an amd64 build to boot an amd64 kernel. .Pp In a .Tn Xen setup, the .Nx DOM0 kernel is loaded as a module, and cannot know the device from which the .Tn Xen hypervisor was booted. In this case, the DOM0 kernel will fall back to the default boot device (typically the first disk on the host). If the boot device is different from the default one, consider passing additional arguments, like .Ar bootdev , to the DOM0 kernel as explained in the .Cm load command subsection in .Xr x86/boot 8 .