add .Mt to man pages in bin/ games/ sys/ tools/
[dragonfly.git] / sys / boot / pc32 / pxeldr / pxeboot.8
CommitLineData
984263bc
MD
1.\" Copyright (c) 1999 Doug White
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\" notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\" notice, this list of conditions and the following disclaimer in the
11.\" documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
5ee58eed 25.\" $FreeBSD: src/sys/boot/i386/pxeldr/pxeboot.8,v 1.7 2002/12/12 17:25:59 ru Exp $
984263bc 26.\"
b5ef8da1 27.Dd October 6, 2010
984263bc
MD
28.Dt PXEBOOT 8
29.Os
30.Sh NAME
31.Nm pxeboot
32.Nd Preboot Execution Environment (PXE) bootloader
33.Sh DESCRIPTION
5ee58eed 34The
984263bc 35.Nm
5ee58eed 36bootloader is a modified version of the system third-stage bootstrap
984263bc
MD
37.Xr loader 8
38configured to run under Intel's Preboot Execution Environment (PXE) system.
39PXE is a form of smart boot ROM, built into Intel EtherExpress Pro/100 and
403Com 3c905c Ethernet cards, and Ethernet-equipped Intel motherboards.
41PXE supports DHCP configuration and provides low-level NIC access services.
5ee58eed 42The
984263bc 43.Nm
5ee58eed 44bootloader retrieves the kernel, modules,
423d6aa0
MD
45and other files either via NFS over UDP.
46In combination with a NFS-mounted root file system,
984263bc
MD
47.Nm
48allows for easy,
49EEPROM-burner free construction of diskless machines.
50.Pp
51The
52.Nm
53binary is loaded just like any other boot file,
54by specifying it in the DHCP server's configuration file.
55Below is a sample configuration for the ISC DHCP v2 server:
56.Bd -literal -offset indent
57option domain-name "example.com";
58option routers 10.0.0.1;
59option subnet-mask 255.255.255.0;
60option broadcast-address 10.0.0.255;
61option domain-name-servers 10.0.0.1;
62server-name "DHCPserver";
63server-identifier 10.0.0.1;
64
65default-lease-time 120;
66max-lease-time 120;
67
68subnet 10.0.0.0 netmask 255.255.255.0 {
0ebf8b32 69 filename "boot/pxeboot";
984263bc 70 range 10.0.0.10 10.0.0.254;
0ebf8b32 71 option root-path "10.0.0.1:/netbootroot";
984263bc
MD
72}
73
74.Ed
75.Nm
76recognizes
77.Va next-server
78and
79.Va option root-path
80directives as the server and path to NFS mount for file requests,
81respectively, or the server to make TFTP requests to.
82Note that
83.Nm
84expects to fetch
b5ef8da1 85.Pa /boot/dloader.rc
984263bc
MD
86from the specified server before loading any other files.
87.Pp
0ebf8b32
MD
88.Nm
89uses
b5ef8da1
TN
90.Pa /boot/kernel.BOOTP
91and
92.Pa /boot/loader-bootp.conf
0ebf8b32
MD
93and
94.Pa nextboot-bootp.conf
95instead of
b5ef8da1 96.Pa /boot/kernel
0ebf8b32 97and
b5ef8da1 98.Pa /boot/loader.conf .
0ebf8b32
MD
99Note that the TFTP version
100.Xr pxeboot_tftp 8
101uses the standard boot loader files.
102The NFS version uses different files to allow BOOTP boots via NFS to
103be overloaded onto the same directory structure as a normal boot,
104though many other changes would have to be made to actually make
105that work.
106However, this is more for historical reasons.
107Current day PXE boot code can handle complex root-path specifications
108allowing the root image to be contained in a sub-directory of the NFS
109export.
110.Pp
984263bc
MD
111In all other respects,
112.Nm
113acts just like
114.Xr loader 8 .
115.Pp
116As PXE is still in its infancy, some firmware versions may not work
117properly.
5ee58eed 118The
984263bc 119.Nm
5ee58eed 120bootloader has been extensively tested on version 0.99 of Intel firmware;
984263bc
MD
121pre-release versions of the newer 2.0 firmware are known to have
122problems.
123Check with the device's manufacturer for their latest stable release.
124.Pp
125For further information on Intel's PXE specifications and Wired for
126Management (WfM) systems, see
cb5730a1 127.Pa http://developer.intel.com/ial/wfm/ .
b5ef8da1
TN
128.Sh FILES
129.Bl -tag -width ".Pa /boot/defaults/loader-bootp.conf" -compact
130.It Pa /boot/kernel.BOOTP
131Default kernel for
132.Nm .
133.It Pa /boot/defaults/loader-bootp.conf
134.Nm
135configuration file -- do not change this file.
136.It Pa /boot/loader-bootp.conf
137.Nm
138configuration file.
139.El
984263bc 140.Sh SEE ALSO
c8e8a2e5 141.Xr dhcpd 8 Pq Pa net/isc-dhcp42-server ,
cadcac6a 142.Xr diskless 8 ,
423d6aa0 143.Xr loader 8 ,
cadcac6a
TN
144.Xr nfsd 8 ,
145.Xr pxeboot_tftp 8 ,
146.Xr tftpd 8
984263bc 147.Sh HISTORY
5ee58eed 148The
984263bc 149.Nm
5ee58eed 150bootloader first appeared in
984263bc
MD
151.Fx 4.1 .
152.Sh AUTHORS
153.An -nosplit
5ee58eed 154The
984263bc 155.Nm
5ee58eed 156bootloader was written by
0240e8a7 157.An John Baldwin Aq Mt jhb@FreeBSD.org
984263bc 158and
0240e8a7 159.An Paul Saab Aq Mt ps@FreeBSD.org .
984263bc 160This manual page was written by
0240e8a7 161.An Doug White Aq Mt dwhite@FreeBSD.org .