Annotation of sys/arch/i386/stand/pxeboot/pxeboot.8, Revision 1.1
1.1 ! nbrk 1: .\" $OpenBSD: pxeboot.8,v 1.8 2007/05/31 19:20:03 jmc Exp $
! 2: .\" Copyright (c) 2004 Tom Cosgrove
! 3: .\" Copyright (c) 2003 Matthias Drochner
! 4: .\" Copyright (c) 1999 Doug White
! 5: .\" All rights reserved.
! 6: .\"
! 7: .\" Redistribution and use in source and binary forms, with or without
! 8: .\" modification, are permitted provided that the following conditions
! 9: .\" are met:
! 10: .\" 1. Redistributions of source code must retain the above copyright
! 11: .\" notice, this list of conditions and the following disclaimer.
! 12: .\" 2. Redistributions in binary form must reproduce the above copyright
! 13: .\" notice, this list of conditions and the following disclaimer in the
! 14: .\" documentation and/or other materials provided with the distribution.
! 15: .\"
! 16: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
! 17: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
! 18: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
! 19: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
! 20: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
! 21: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
! 22: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
! 23: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
! 24: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
! 25: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
! 26: .\" SUCH DAMAGE.
! 27: .\"
! 28: .Dd $Mdocdate: May 31 2007 $
! 29: .Dt PXEBOOT 8 i386
! 30: .Os
! 31: .Sh NAME
! 32: .Nm pxeboot
! 33: .Nd
! 34: i386-specific second-stage PXE bootstrap
! 35: .Sh DESCRIPTION
! 36: .Nm
! 37: is a modified version of the i386 second-stage bootstrap program,
! 38: .Xr boot 8 ,
! 39: configured to run under Intel's Preboot Execution Environment (PXE).
! 40: PXE is a form of smart boot ROM, built into many Ethernet cards from Intel,
! 41: 3Com, and other manufacturers.
! 42: .Pp
! 43: The computer's PXE boot ROM contacts a DHCP server by broadcasting a request
! 44: on the network.
! 45: It gets an IP address from the DHCP server,
! 46: then it is told the name of the boot program to download \(em
! 47: in this case, the boot program is
! 48: .Nm .
! 49: The ROM downloads the boot program using TFTP, then executes it.
! 50: .Pp
! 51: The
! 52: .Nm
! 53: boot program will look for an
! 54: .Pa /etc/boot.conf
! 55: configuration
! 56: file on the TFTP server.
! 57: If it finds one, it processes the commands within it.
! 58: .Pa boot.conf
! 59: processing can be skipped by holding down either Control key as
! 60: .Nm
! 61: starts.
! 62: .Pp
! 63: .Nm
! 64: then sits in a loop,
! 65: processing commands given by the user.
! 66: It accepts all the commands accepted by
! 67: .Xr boot 8 .
! 68: .Pp
! 69: If no commands are given for a short time,
! 70: .Nm
! 71: will then attempt to load the
! 72: .Ox
! 73: kernel
! 74: .Pa bsd
! 75: via TFTP.
! 76: It may be told to boot an alternative kernel,
! 77: either by commands in the
! 78: .Pa boot.conf
! 79: file,
! 80: or by commands typed by the user at the
! 81: .Ic boot\*(Gt
! 82: prompt.
! 83: .Nm
! 84: can be used for
! 85: .Xr diskless 8
! 86: setups or to load the
! 87: .Pa bsd.rd
! 88: install kernel
! 89: for network installs.
! 90: .Pp
! 91: To prepare a server to support network booting,
! 92: the
! 93: .Xr dhcpd 8
! 94: and
! 95: .Xr tftpd 8
! 96: services should be enabled and configured.
! 97: It may help to use the
! 98: .Fl s
! 99: option with
! 100: .Xr tftpd 8 ,
! 101: to avoid confusion between files for the server's system
! 102: and files for the client system
! 103: (note that
! 104: .Fl s
! 105: is set by default in
! 106: .Ox ) .
! 107: .Xr ftpd 8
! 108: or
! 109: .Xr httpd 8
! 110: should be enabled, depending on how the install sets will be made available.
! 111: .Pp
! 112: .Nm
! 113: and the kernel should be copied into the TFTP server's root directory
! 114: (typically
! 115: .Pa /tftpboot ) .
! 116: A
! 117: .Pa boot.conf
! 118: file may be created if required
! 119: (e.g.\&
! 120: .Pa /tftpboot/etc/boot.conf ) .
! 121: .Pp
! 122: A sample configuration file for
! 123: .Xr dhcpd 8
! 124: might be as follows:
! 125: .Bd -literal -offset indent
! 126: option domain-name "example.com";
! 127: option routers 10.0.0.1;
! 128: option subnet-mask 255.255.255.0;
! 129: option broadcast-address 10.0.0.255;
! 130: option domain-name-servers 10.0.0.1;
! 131: server-name "DHCPserver";
! 132: server-identifier 10.0.0.1;
! 133:
! 134: default-lease-time 120;
! 135: max-lease-time 120;
! 136:
! 137: subnet 10.0.0.0 netmask 255.255.255.0 {
! 138: filename "pxeboot";
! 139: range 10.0.0.10 10.0.0.254;
! 140: }
! 141: .Ed
! 142: .Pp
! 143: See
! 144: .Xr dhcpd 8
! 145: and
! 146: .Xr dhcpd.conf 5
! 147: for more information.
! 148: .Sh FILES
! 149: .Bl -tag -width /usr/mdec/pxebootxx -compact
! 150: .It Pa /usr/mdec/pxeboot
! 151: PXE-specific second-stage bootstrap
! 152: .It Pa /etc/boot.conf
! 153: .Nm
! 154: configuration file (read from TFTP server)
! 155: .It Pa /etc/dhcpd.conf
! 156: DHCPD configuration file
! 157: .It Pa /tftpboot
! 158: Default root directory for
! 159: .Xr tftpd 8
! 160: .El
! 161: .Sh EXAMPLES
! 162: Boot the install kernel:
! 163: .Pp
! 164: .Dl boot\*(Gt bsd.rd
! 165: .Pp
! 166: The same thing:
! 167: .Pp
! 168: .Dl boot\*(Gt boot tftp:bsd.rd
! 169: .Sh SEE ALSO
! 170: .Xr dhcpd.conf 5 ,
! 171: .Xr boot 8 ,
! 172: .Xr boot_i386 8 ,
! 173: .Xr dhcpd 8 ,
! 174: .Xr diskless 8 ,
! 175: .Xr httpd 8 ,
! 176: .Xr tftpd 8
! 177: .Rs
! 178: .%T Preboot Execution Environment (PXE) Specification
! 179: .%N Version 2.1
! 180: .%D September 20, 1999
! 181: .%A Intel Corporation
! 182: .Re
! 183: .Sh HISTORY
! 184: The
! 185: .Nm
! 186: command first appeared in
! 187: .Ox 3.5 .
CVSweb