"Fossies" - the Fresh Open Source Software Archive

Member "syslinux-6.03/doc/pxelinux.txt" (6 Oct 2014, 16817 Bytes) of package /linux/misc/syslinux-6.03.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1                                PXELINUX
    2 
    3     A bootloader for Linux using the PXE network booting protocol
    4 
    5        Copyright 1994-2008 H. Peter Anvin - All Rights Reserved
    6        Copyright 2009-2011 Intel Corporation; author: H. Peter Anvin
    7 
    8 This program is provided under the terms of the GNU General Public
    9 License, version 2 or, at your option, any later version.  There is no
   10 warranty, neither expressed nor implied, to the function of this
   11 program.  Please see the included file COPYING for details.
   12 
   13 This documentation file is slightly out of date; please check the NEWS
   14 file for changes.
   15 
   16 ----------------------------------------------------------------------
   17 
   18 PXELINUX is a Syslinux derivative, for booting Linux off a network
   19 server, using a network ROM conforming to the Intel PXE (Pre-Execution
   20 Environment) specification.  PXELINUX is *not* a program that is
   21 intended to be flashed or burned into a PROM on the network card; if
   22 you want that, check out Etherboot (http://www.etherboot.org/).
   23 Etherboot 5.4 or later can also be used to create a PXE-compliant boot
   24 PROM for many network cards.
   25 
   26 
   27     ++++ HOW TO CONFIGURE PXELINUX ++++
   28 
   29 PXELINUX operates in many ways like SYSLINUX.  If you are not familiar
   30 with SYSLINUX, read syslinux.txt first, since this documentation only
   31 explains the differences.
   32 
   33 On the TFTP server, create the directory "/tftpboot", and copy the
   34 following files to it:
   35 
   36 	pxelinux.0		- from the Syslinux distribution
   37 
   38 	any kernel or initrd images you want to boot
   39 
   40 Finally, create the directory "/tftpboot/pxelinux.cfg".  The
   41 configuration file (equivalent of syslinux.cfg -- see syslinux.txt for
   42 the options here) will live in this directory.  Because more than one
   43 system may be booted from the same server, the configuration file name
   44 depends on the IP address of the booting machine.  PXELINUX will
   45 search for its config file on the boot server in the following way:
   46 
   47   First, it will search for the config file using the client UUID, if
   48   one is provided by the PXE stack (note, some BIOSes don't have a
   49   valid UUID, and you might end up with something like all 1's.)  This is
   50   in the standard UUID format using lower case hexadecimal digits, e.g.
   51   b8945908-d6a6-41a9-611d-74a6ab80b83d.
   52 
   53   Next, it will search for the config file using the hardware type
   54   (using its ARP type code) and address, all in lower case hexadecimal
   55   with dash separators; for example, for an Ethernet (ARP type 1)
   56   with address 88:99:AA:BB:CC:DD it would search for the filename
   57   01-88-99-aa-bb-cc-dd.
   58 
   59   Next, it will search for the config file using its own IP address
   60   in upper case hexadecimal, e.g. 192.0.2.91 -> C000025B
   61   (you can use the included progam "gethostip" to compute the
   62   hexadecimal IP address for any host.)
   63 
   64   If that file is not found, it will remove one hex digit and try
   65   again.  Ultimately, it will try looking for a file named "default"
   66   (in lower case).
   67 
   68   As an example, if the boot file name is /mybootdir/pxelinux.0, the
   69   UUID is b8945908-d6a6-41a9-611d-74a6ab80b83d, the Ethernet MAC
   70   address is 88:99:AA:BB:CC:DD and the IP address 192.0.2.91, it will
   71   try:
   72 
   73 	/mybootdir/pxelinux.cfg/b8945908-d6a6-41a9-611d-74a6ab80b83d
   74 	/mybootdir/pxelinux.cfg/01-88-99-aa-bb-cc-dd
   75 	/mybootdir/pxelinux.cfg/C000025B
   76 	/mybootdir/pxelinux.cfg/C000025
   77 	/mybootdir/pxelinux.cfg/C00002
   78 	/mybootdir/pxelinux.cfg/C0000
   79 	/mybootdir/pxelinux.cfg/C000
   80 	/mybootdir/pxelinux.cfg/C00
   81 	/mybootdir/pxelinux.cfg/C0
   82 	/mybootdir/pxelinux.cfg/C
   83 	/mybootdir/pxelinux.cfg/default
   84 
   85   ... in that order.
   86 
   87 Note that all filename references are relative to the directory
   88 pxelinux.0 lives in.  PXELINUX generally requires that filenames
   89 (including any relative path) are 127 characters or shorter in length.
   90 
   91 Starting in release 3.20, PXELINUX will no longer apply a built-in
   92 default if it cannot find any configuration file at all; instead it
   93 will reboot after the timeout interval has expired.  This keeps a
   94 machine from getting stuck indefinitely due to a boot server failure.
   95 
   96 Starting in release 3.50, PXELINUX displays network information at
   97 the boot prompt pressing <Ctrl-N>.
   98 
   99 PXELINUX does not support MTFTP, and I have no plans of doing so, as
  100 MTFTP is inherently broken for files more than 65535 packets (about
  101 92 MB) in size.  It is of course possible to use MTFTP for the initial
  102 boot, if you have such a setup.  MTFTP server setup is beyond the
  103 scope of this document.
  104 
  105 
  106     ++++ HTTP AND FTP DOWNLOADS ++++
  107 
  108 Since version 5.10, native pxelinux.0 can support HTTP and FTP
  109 transfers, greatly increasing load speed and allowing for standard
  110 HTTP scripts to present PXELINUX's configuration file.  To use http or
  111 ftp, use standard URL syntax as filename; use the DHCP options below
  112 to transmit a suitable URL prefix to the client, or use the
  113 "pxelinux-options" tool provided in the utils directory to program it
  114 directly into the pxelinux.0 file.
  115 
  116 
  117     ++++ SETTING UP THE TFTP SERVER ++++
  118 
  119 For best results, use a TFTP server which supports the "tsize" TFTP
  120 option (RFC 1784/RFC 2349).  The "tftp-hpa" TFTP server, which support
  121 options, is available at:
  122 
  123 	http://www.kernel.org/pub/software/network/tftp/
  124 	ftp://www.kernel.org/pub/software/network/tftp/
  125 
  126 ... and on any kernel.org mirror (see http://www.kernel.org/mirrors/).
  127 
  128 Another TFTP server which supports this is atftp by Jean-Pierre
  129 Lefebvre:
  130 
  131 	ftp://ftp.mamalinux.com/pub/atftp/
  132 
  133 If your boot server is running Windows (and you can't fix that), try
  134 tftpd32 by Philippe Jounin (you need version 2.11 or later; previous
  135 versions had a bug which made it incompatible with PXELINUX):
  136 
  137 	http://tftpd32.jounin.net/
  138 
  139 
  140     ++++ SETTING UP THE DHCP SERVER ++++
  141 
  142 The PXE protocol uses a very complex set of extensions to DHCP or
  143 BOOTP.  However, most PXE implementations -- this includes all Intel
  144 ones version 0.99n and later -- seem to be able to boot in a
  145 "conventional" DHCP/TFTP configuration.  Assuming you don't have to
  146 support any very old or otherwise severely broken clients, this is
  147 probably the best configuration unless you already have a PXE boot
  148 server on your network.
  149 
  150 A sample DHCP setup, using the "conventional TFTP" configuration,
  151 would look something like the following, using ISC dhcp 2.0 dhcpd.conf
  152 syntax:
  153 
  154         allow booting;
  155         allow bootp;
  156 
  157 	# Standard configuration directives...
  158 
  159         option domain-name "<domain name>";
  160         option subnet-mask <subnet mask>;
  161         option broadcast-address <broadcast address>;
  162         option domain-name-servers <dns servers>;
  163         option routers <default router>;
  164 
  165 	# Group the PXE bootable hosts together
  166 	group {
  167 		# PXE-specific configuration directives...
  168 		next-server <TFTP server address>;
  169 		filename "/tftpboot/pxelinux.0";
  170 
  171 		# You need an entry like this for every host
  172 		# unless you're using dynamic addresses
  173 	        host <hostname> {
  174 		        hardware ethernet <ethernet address>;
  175 			fixed-address <hostname>;
  176 		}
  177 	}
  178 
  179 Note that if your particular TFTP daemon runs under chroot (tftp-hpa
  180 will do this if you specify the -s (secure) option; this is highly
  181 recommended), you almost certainly should not include the /tftpboot
  182 prefix in the filename statement.
  183 
  184 If this does not work for your configuration, you probably should set
  185 up a "PXE boot server" on port 4011 of your TFTP server; a free PXE
  186 boot server is available at:
  187 
  188 	http://www.kano.org.uk/projects/pxe/
  189 
  190 With such a boot server defined, your DHCP configuration should look
  191 the same except for an "option dhcp-class-identifier" ("option
  192 vendor-class-identifier" if you are using DHCP 3.0):
  193 
  194         allow booting;
  195         allow bootp;
  196 
  197 	# Standard configuration directives...
  198 
  199         option domain-name "<domain name>";
  200         option subnet-mask <subnet mask>;
  201         option broadcast-address <broadcast address>;
  202         option domain-name-servers <dns servers>;
  203         option routers <default router>;
  204 
  205 	# Group the PXE bootable hosts together
  206 	group {
  207 		# PXE-specific configuration directives...
  208 	        option dhcp-class-identifier "PXEClient";
  209 		next-server <pxe boot server address>;
  210 
  211 		# You need an entry like this for every host
  212 		# unless you're using dynamic addresses
  213 	        host <hostname> {
  214 		        hardware ethernet <ethernet address>;
  215 			fixed-address <hostname>;
  216 		}
  217 	}
  218 
  219 Here, the boot file name is obtained from the PXE server.
  220 
  221 If the "conventional TFTP" configuration doesn't work on your clients,
  222 and setting up a PXE boot server is not an option, you can attempt the
  223 following configuration.  It has been known to boot some
  224 configurations correctly; however, there are no guarantees:
  225 
  226         allow booting;
  227         allow bootp;
  228 
  229 	# Standard configuration directives...
  230 
  231         option domain-name "<domain name>";
  232         option subnet-mask <subnet mask>;
  233         option broadcast-address <broadcast address>;
  234         option domain-name-servers <dns servers>;
  235         option routers <default router>;
  236 
  237 	# Group the PXE bootable hosts together
  238 	group {
  239 		# PXE-specific configuration directives...
  240 	        option dhcp-class-identifier "PXEClient";
  241 		option vendor-encapsulated-options 09:0f:80:00:0c:4e:65:74:77:6f:72:6b:20:62:6f:6f:74:0a:07:00:50:72:6f:6d:70:74:06:01:02:08:03:80:00:00:47:04:80:00:00:00:ff;
  242 		next-server <TFTP server>;
  243 		filename "/tftpboot/pxelinux.0";
  244 
  245 		# You need an entry like this for every host
  246 		# unless you're using dynamic addresses
  247 	        host <hostname> {
  248 		        hardware ethernet <ethernet address>;
  249 			fixed-address <hostname>;
  250 		}
  251 	}
  252 
  253 Note that this *will not* boot some clients that *will* boot with the
  254 "conventional TFTP" configuration; Intel Boot Client 3.0 and later are
  255 known to fall into this category.
  256 
  257 
  258     ++++ SPECIAL DHCP OPTIONS ++++
  259 
  260 PXELINUX (starting with version 1.62) supports the following
  261 nonstandard DHCP options, which depending on your DHCP server you may
  262 be able to use to customize the specific behaviour of PXELINUX.  See
  263 RFC 5071 for some additional information about these options.
  264 
  265 Option 208	pxelinux.magic
  266 	- Earlier versions of PXELINUX required this to be set to
  267 	  F1:00:74:7E (241.0.116.126) for PXELINUX to
  268 	  recognize any special DHCP options whatsoever.  As of
  269 	  PXELINUX 3.55, this option is deprecated and is no longer
  270 	  required.
  271 
  272 Option 209	pxelinux.configfile
  273 	- Specifies the PXELINUX configuration file name.
  274 
  275 Option 210	pxelinux.pathprefix
  276 	- Specifies the PXELINUX common path prefix, instead of
  277 	  deriving it from the boot file name.  This almost certainly
  278 	  needs to end in whatever character the TFTP server OS uses
  279 	  as a pathname separator, e.g. slash (/) for Unix.
  280 
  281 Option 211	pxelinux.reboottime
  282 	- Specifies, in seconds, the time to wait before reboot in the
  283 	  event of TFTP failure.  0 means wait "forever" (in reality,
  284 	  it waits approximately 136 years.)
  285 
  286 ISC dhcp 3.0 supports a rather nice syntax for specifying custom
  287 options; you can use the following syntax in dhcpd.conf if you are
  288 running this version of dhcpd:
  289 
  290 	option space pxelinux;
  291 	option pxelinux.magic      code 208 = string;
  292 	option pxelinux.configfile code 209 = text;
  293 	option pxelinux.pathprefix code 210 = text;
  294 	option pxelinux.reboottime code 211 = unsigned integer 32;
  295 
  296     NOTE: In earlier versions of PXELINUX, this would only work as a
  297     "site-option-space".  Since PXELINUX 2.07, this will work both as a
  298     "site-option-space" (unencapsulated) and as a "vendor-option-space"
  299     (type 43 encapsulated.)  This may avoid messing with the
  300     dhcp-parameter-request-list, as detailed below.
  301 
  302 Then, inside your PXELINUX-booting group or class (whereever you have
  303 the PXELINUX-related options, such as the filename option), you can
  304 add, for example:
  305 
  306 	# Always include the following lines for all PXELINUX clients
  307 	site-option-space "pxelinux";
  308 	option pxelinux.magic f1:00:74:7e;
  309 	if exists dhcp-parameter-request-list {
  310 		# Always send the PXELINUX options (specified in hexadecimal)
  311 		option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
  312 	}
  313 	# These lines should be customized to your setup
  314 	option pxelinux.configfile "configs/common";
  315 	option pxelinux.pathprefix "/tftpboot/pxelinux/files/";
  316 	option pxelinux.reboottime 30;
  317 	filename "/tftpboot/pxelinux/pxelinux.bin";
  318 
  319 Note that the configfile is relative to the pathprefix: this will look
  320 for a config file called /tftpboot/pxelinux/files/configs/common on
  321 the TFTP server.
  322 
  323 The "option dhcp-parameter-request-list" statement forces the DHCP
  324 server to send the PXELINUX-specific options, even though they are not
  325 explicitly requested.  Since the DHCP request is done before PXELINUX
  326 is loaded, the PXE client won't know to request them.
  327 
  328 Using ISC dhcp 3.0 you can create a lot of these strings on the fly.
  329 For example, to use the hexadecimal form of the hardware address as
  330 the configuration file name, you could do something like:
  331 
  332 	site-option-space "pxelinux";
  333 	option pxelinux.magic f1:00:74:7e;
  334 	if exists dhcp-parameter-request-list {
  335 		# Always send the PXELINUX options (specified in hexadecimal)
  336 		option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3);
  337 	}
  338 	option pxelinux.configfile =
  339 		concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
  340 	filename "/tftpboot/pxelinux.bin";
  341 
  342 If you used this from a client whose Ethernet address was
  343 58:FA:84:CF:55:0E, this would look for a configuration file named
  344 "/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".
  345 
  346 
  347     ++++ HARDCODED OPTIONS ++++
  348 
  349 Since version 3.83, the program "pxelinux-options" can be used to
  350 hard-code DHCP options into the pxelinux.0 image file; this is
  351 sometimes useful when the DHCP server is under different
  352 administrative control.
  353 
  354 
  355     ++++ ALTERNATE TFTP SERVERS AND URL SYNTAX ++++
  356 
  357 PXELINUX supports the following special pathname conventions:
  358 
  359 ::filename
  360 
  361 	Suppresses the common filename prefix, i.e. passes the string
  362 	"filename" unmodified to the server.
  363 
  364 IP address::filename		(e.g. 192.0.2.1::filename)
  365 
  366 	Suppresses the common filename prefix, *and* sends a request
  367 	to an alternate TFTP server.  Instead of an IP address, a
  368 	DNS name can be used.  It will be assumed to be fully
  369 	qualified if it contains dots; otherwise the local domain as
  370 	reported by the DHCP server (option 15) will be added.
  371 
  372 :: was chosen because it is unlikely to conflict with operating system
  373 usage.  However, if you happen to have an environment for which the
  374 special treatment of :: is a problem, please contact the Syslinux
  375 mailing list.
  376 
  377 Since version 4.00, PXELINUX also supports standard URL syntax.
  378 
  379 
  380     ++++ SOME NOTES ++++
  381 
  382 If the boot fails, PXELINUX (unlike SYSLINUX) will not wait forever;
  383 rather, if it has not received any input for approximately five
  384 minutes after displaying an error message, it will reset the machine.
  385 This allows an unattended machine to recover in case it had bad enough
  386 luck of trying to boot at the same time the TFTP server goes down.
  387 
  388 Lots of PXE stacks, especially old ones, have various problems of
  389 varying degrees of severity.  Please see:
  390 
  391 	http://syslinux.zytor.com/hardware.php
  392 
  393 ... for a list of currently known hardware problems, with workarounds
  394 if known.
  395 
  396 
  397     ++++ KEEPING THE PXE STACK AROUND ++++
  398 
  399 Normally, PXELINUX will unload the PXE and UNDI stacks before invoking
  400 the kernel.  In special circumstances (for example, when using MEMDISK
  401 to boot an operating system with an UNDI network driver) it might be
  402 desirable to keep the PXE stack in memory.  If the option "keeppxe"
  403 is given on the kernel command line, PXELINUX will keep the PXE and
  404 UNDI stacks in memory.  (If you don't know what this means, you
  405 probably don't need it.)
  406 
  407 
  408     ++++ PROBLEMS WITH YOUR PXE STACK ++++
  409 
  410 There are a number of extremely broken PXE stacks in the field.  The
  411 gPXE project (formerly known as Etherboot) provides an open-source PXE
  412 stack that works with a number of cards, and which can be loaded from
  413 a CD-ROM, USB key, or floppy if desired.
  414 
  415 Information on gPXE is available from:
  416 
  417 	http://www.etherboot.org/
  418 
  419 ... and ready-to-use ROM or disk images from:
  420 
  421 	http://www.rom-o-matic.net/
  422 
  423 Some cards, like may systems with the SiS 900, has a PXE stack which
  424 works just barely well enough to load a single file, but doesn't
  425 handle the more advanced items required by PXELINUX.  If so, it is
  426 possible to use the built-in PXE stack to load gPXE, which can then
  427 load PXELINUX.  See:
  428 
  429 	http://www.etherboot.org/wiki/pxechaining
  430 
  431 
  432     ++++ CURRENTLY KNOWN PROBLEMS ++++
  433 
  434 The following problems are known with PXELINUX, so far:
  435 
  436 + The error recovery routine doesn't work quite right.  For right now,
  437   it just does a hard reset - seems good enough.
  438 + We should probably call the UDP receive function in the keyboard
  439   entry loop, so that we answer ARP requests.
  440 + Boot sectors/disk images are not supported yet.
  441 
  442 If you have additional problems, please contact the Syslinux mailing
  443 list (see syslinux.txt for the address.)