PXEBOOT(8)            NetBSD/x86 System Manager's Manual            PXEBOOT(8)

NAME
     pxeboot -- network boot NetBSD/x86 through a PXE BIOS extension

DESCRIPTION
     pxeboot is a NetBSD boot program running on top of a PXE BIOS extension
     which is provided by the motherboard or a plug-in network adapter, in
     accordance with the Intel Preboot eXecution Environement (PXE) specifica-
     tion.

     By default, the pxeboot program is configured with modules loading and
     boot.cfg(5) support disabled.  See EXAMPLES for how to enable these
     options individually.  This manual page assumes that boot.cfg(5) support
     is enabled.

     Network booting a system through PXE is a two-stage process:

     1.   The PXE BIOS issues a DHCP request and fetches the NetBSD pxeboot
          program using TFTP.

     2.   The NetBSD pxeboot program takes control.  It immediately issues
          another DHCP request to get the name of a boot.cfg(5) file to load,
          using ``boot.cfg'' by default.  If the boot config file is not
          found, or if the supplied file appears not to be a boot configura-
          tion file, the file is skipped.  Otherwise it is loaded and obeyed
          as described in 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 boot command, another DHCP request is
          issued and the kernel filename returned by the DHCP reply, using
          ``netbsd'' by default, is loaded.  To read the kernel file, the NFS
          (version 2) or TFTP protocols can be used.

     The DHCP request issued by the NetBSD pxeboot program has the following
     special parameters:

     Bootfile name
           is set to ``boot.cfg'' during the first request, and then to the
           filename argument on the boot command line typed in by the user
           (can be empty), using ``netbsd'' in the non-interactive case.

     DHCP Vendor class identifier tag
           is set to ``NetBSD:i386:libsa''.

     The DHCP server can use these fields (i.e. the DHCP vendor class identi-
     fier tag and the requested file name, possibly supplied by the user's
     command line input to the pxeboot program) to distinguish between the
     various originators of requests (PXE BIOS, first and second pxeboot
     stage, NetBSD kernel), and to alter its behaviour.  For example, this can
     be used to support alternative NetBSD installations on one machine.

     In addition to the standard network interface configuration, the follow-
     ing fields in the DHCP reply are interpreted:

     Bootfile name
           specifies the protocol to be used, and the filename of the boot
           config or NetBSD kernel to be booted, separated by a colon.  Avail-
           able protocols are ``nfs'' and ``tftp''.  The boot config or kernel
           filename part is interpreted relatively to the NFS root directory
           (see the 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
           Bootfile name field replied by the DHCP server does not contain a
           colon, it is ignored, and the filename typed in at the pxeboot com-
           mand line prompt (or the ``netbsd'' default, see the section about
           the Bootfile name field in the DHCP request above) is used.  If no
           protocol was specified, ``nfs'' is assumed.

     Next server
           is used as the location of the tftp server.

     Swap server
           can be used to override the ``server IP address'' if NFS is used to
           access the kernel.  This matches the behaviour of the NetBSD kernel
           to access its root file system on NFS.  This way, different TFTP
           and NFS servers can be communicated to the DHCP client (it is
           actually a deficiency of the DHCP protocol to provide a ``root
           path'' field but no corresponding IP address).

     Root path
           is used as path to be mounted in the NFS case to access the kernel
           file, matching the NetBSD kernel's behaviour.

     The commands accepted in interactive mode are:

         boot [device:][filename] [-1234abcdmqsvxz]
               Boot NetBSD.  See boot in boot(8) for full details.

         help  Print an overview about commands and arguments.

         quit  Leave the pxeboot program.

     By default the output from pxeboot 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 installboot to modify the boot options contained in the
     pxeboot_ia32.bin file.

FILES
     /usr/mdec/pxeboot_ia32.bin

EXAMPLES
     To enable boot.cfg(5) support in the pxeboot program:

           installboot -e -o bootconf pxeboot_ia32.bin

     To enable modules loading support in the pxeboot program:

           installboot -e -o modules pxeboot_ia32.bin

     The first /etc/dhcpd.conf example shows a simple configuration which just
     loads ``boot.cfg'' and ``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.

     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";
     }

     The following /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.

     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";
             }
         }
     }

     The following /etc/dhcpd.conf entry shows how different system installa-
     tions can be booted depending on the user's input on the pxeboot command
     line.

     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";
             }
         }
     }

     The TFTP server is supplied using the next-server directive.  The NFS
     server for the root file system is mynfsserver.  The
     swap-server:root-path is only used in the NFS case and by the NetBSD ker-
     nel to mount the root file system.

SEE ALSO
     boot.cfg(5), boot(8), dhcpd(8), diskless(8), installboot(8)

     Intel Corporation, Preboot Execution Environment (PXE) Specification,
     Version 2.1, September 20, 1999.

HISTORY
     The NetBSD/x86 pxeboot command first appeared in NetBSD 1.6.

BUGS
     If an error is encountered while reading the NetBSD kernel file or if its
     file format wasn't recognized, it is impossible to retry the operation
     because the PXE network stack is already removed from the system RAM.

     You need the pxeboot from an i386 build to boot an i386 kernel, and that
     from an amd64 build to boot an amd64 kernel.

     In a Xen setup, the NetBSD DOM0 kernel is loaded as a module, and cannot
     know the device from which the 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 bootdev, to the
     DOM0 kernel as explained in the load command subsection in boot(8).

NetBSD 7.0                      August 16, 2014                     NetBSD 7.0

You can also request any man page by name and (optionally) by section:

Command: 
Section: 
Architecture: 
Collection: 
 

Use the DEFAULT collection to view manual pages for third-party software.


©1994 Man-cgi 1.15, Panagiotis Christias <christia@softlab.ntua.gr>
©1996-2014 Modified for NetBSD by Kimmo Suominen