.\"	$NetBSD: pxeboot.8,v 1.7 2003/11/17 21:29:37 wiz 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 November 17, 2003
.Os
.Dt PXEBOOT 8 i386
.Sh NAME
.Nm pxeboot
.Nd network boot NetBSD/i386 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 Environement
.Pq Tn PXE
specification.
.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.
An interactive mode is entered if the
user presses 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
is loaded as specified in the
.Tn DHCP
reply.
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 the
.Va filename
argument on the
.Ic boot
command line typed in by the user (can be empty), or to
.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 to distinguish between
the various originators of requests (first and second
.Tn PXE
stage,
.Nx
kernel), and to control conditional behaviour depending on the
user's command line input to the
.Nm
program, e.g. 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
.Nx
kernel to be booted, separated by a colon.
Available protocols are
.Dq nfs
and
.Dq tftp .
The 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 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
The commands accepted in interactive mode are:
.\" NOTE: much of this text is duplicated in boot.8; please try to
.\" keep both files synchronized.
.Bl -tag -width 04n -offset 04n
.It Xo Ic boot
.Op Va filename
.Op Fl adqsv
.Xc
Boot
.Nx .
See
.Cm boot
in
.Xr boot 8
for full details.
.It Ic help
Print an overview about commands and arguments.
.It Ic quit
Leave the
.Nm
program.
.El
.Sh EXAMPLES
The first
.Pa /etc/dhcpd.conf
example shows a simple configuration which just loads a file
.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 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";
    if substring (option vendor-class-identifier, 0, 9) = "PXEClient" {
        filename "pxeboot_ia32.bin";
    } 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
It is assumed that the
.Tn TFTP
server is the same as the
.Tn DHCP
server unless a
.Em next-server
directive is specified somewhere else in
.Pa dhcpd.conf ,
and that 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 8 ,
.Xr dhcpd 8 ,
.Xr diskless 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 /i386
.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.