[syslinux:lwip] Add documentation about the new features

Tue Apr 26 22:51:03 PDT 2011

Commit-ID:  7dfe5f27a0fc56ba3da0e300043731af0bdf13de
Gitweb:     http://syslinux.zytor.com/commit/7dfe5f27a0fc56ba3da0e300043731af0bdf13de
Author:     H. Peter Anvin <hpa at zytor.com>
AuthorDate: Tue, 26 Apr 2011 22:49:00 -0700
Committer:  H. Peter Anvin <hpa at zytor.com>
CommitDate: Tue, 26 Apr 2011 22:49:00 -0700

Add documentation about the new features



---
 NEWS             |    7 +++++++
 doc/pxelinux.txt |   41 ++++++++++++++++++++++++++---------------
 doc/syslinux.txt |   41 +++++++++++++++++++++++++++++++++++++++--
 3 files changed, 72 insertions(+), 17 deletions(-)

diff --git a/NEWS b/NEWS
index 02963db..5c8b3d8 100644
--- a/NEWS
+++ b/NEWS
@@ -6,6 +6,13 @@ Changes in 4.10:
 	* PXELINUX: An entirely new network implementation based on
 	  the lwIP embedded TCP/IP stack.  As a result, plain PXELINUX
 	  can now support HTTP and FTP without gPXE/iPXE.
+	* Rename the "ipappend" option to "sysappend" ("ipappend" is
+	  still accepted as an alias) and make it available for all
+	  derivatives.  Add additional strings derived from the system
+	  DMI/SMBIOS information if available.
+	* "sysappend" strings are also sent as http cookies, with the
+	  prefix _Syslinux_ added, on all http transfers.  This can be
+	  overridden with the SENDCOOKIES configuration file command.
 
 Changes in 4.05:
 	* HDT updated, and now supports uploading data to a TFTP
diff --git a/doc/pxelinux.txt b/doc/pxelinux.txt
index 69c1a64..f7d2da5 100644
--- a/doc/pxelinux.txt
+++ b/doc/pxelinux.txt
@@ -3,12 +3,16 @@
     A bootloader for Linux using the PXE network booting protocol
 
        Copyright 1994-2008 H. Peter Anvin - All Rights Reserved
+       Copyright 2009-2011 Intel Corporation; author: H. Peter Anvin
 
 This program is provided under the terms of the GNU General Public
 License, version 2 or, at your option, any later version.  There is no
 warranty, neither expressed nor implied, to the function of this
 program.  Please see the included file COPYING for details.
 
+This documentation file is slightly out of date; please check the NEWS
+file for changes.
+
 ----------------------------------------------------------------------
 
 PXELINUX is a Syslinux derivative, for booting Linux off a network
@@ -99,25 +103,22 @@ boot, if you have such a setup.  MTFTP server setup is beyond the
 scope of this document.
 
 
-    ++++ gPXE-ENHANCED VARIANTS ++++
+    ++++ HTTP AND FTP DOWNLOADS ++++
 
-gPXE can be used to enhance PXELINUX's functionality to also include
-HTTP transfers, greatly increasing load speed and allowing for standard
-HTTP scripts to present PXELINUX's configuration file.  pxelinux.0 is
-the plain variant.  gpxelinux.0 (included as of 3.70) is gPXE's
-undionly.kkpxe, pxelinux.0 and a script to run pxelinux.0.  gpxelinuxk.0
-(included as of 4.04) is gPXE's undionly.kpxe, pxelinux.0 and a script
-to run pxelinux.0.  gpxelinuxk.0 should only be used with systems that
-are incompatible with gpxelinux.0 as it prevents certain functionality
-from working (LOCALBOOT with a type not equal to -1) and is incompatible
-with certain hardware, PXE stacks and network setups.
+Since version 4.10, native pxelinux.0 can support HTTP and FTP
+transfers, greatly increasing load speed and allowing for standard
+HTTP scripts to present PXELINUX's configuration file.  To use http or
+ftp, use standard URL syntax as filename; use the DHCP options below
+to transmit a suitable URL prefix to the client, or use the
+"pxelinux-options" tool provided in the utils directory to program it
+directly into the pxelinux.0 file.
 
 
     ++++ SETTING UP THE TFTP SERVER ++++
 
-PXELINUX currently requires that the boot server has a TFTP server
-which supports the "tsize" TFTP option (RFC 1784/RFC 2349).  The
-"tftp-hpa" TFTP server, which support options, is available at:
+For best results, use a TFTP server which supports the "tsize" TFTP
+option (RFC 1784/RFC 2349).  The "tftp-hpa" TFTP server, which support
+options, is available at:
 
 	http://www.kernel.org/pub/software/network/tftp/
 	ftp://www.kernel.org/pub/software/network/tftp/
@@ -343,7 +344,15 @@ If you used this from a client whose Ethernet address was
 "/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".
 
 
-    ++++ ALTERNATE TFTP SERVERS ++++
+    ++++ HARDCODED OPTIONS ++++
+
+Since version 3.83, the program "pxelinux-options" can be used to
+hard-code DHCP options into the pxelinux.0 image file; this is
+sometimes useful when the DHCP server is under different
+administrative control.
+
+
+    ++++ ALTERNATE TFTP SERVERS AND URL SYNTAX ++++
 
 PXELINUX supports the following special pathname conventions:
 
@@ -365,6 +374,8 @@ usage.  However, if you happen to have an environment for which the
 special treatment of :: is a problem, please contact the Syslinux
 mailing list.
 
+Since version 4.00, PXELINUX also supports standard URL syntax.
+
 
     ++++ SOME NOTES ++++
 
diff --git a/doc/syslinux.txt b/doc/syslinux.txt
index 32f8dc4..67740f6 100644
--- a/doc/syslinux.txt
+++ b/doc/syslinux.txt
@@ -153,8 +153,8 @@ APPEND options...
         usually permitting explicitly entered kernel options to override
         them.  This is the equivalent of the LILO "append" option.
 
-SYSAPPEND flag_val
-IPAPPEND flag_val
+SYSAPPEND bitmask
+IPAPPEND bitmask
 
 	The SYSAPPEND option was introduced in Syslinux 4.10; it is an
 	enhancement of a previous option IPAPPEND which was only
@@ -194,6 +194,40 @@ IPAPPEND flag_val
 
 	... in lower case hexadecimal in the format normally used for
 	UUIDs (same as for the configuration file; see pxelinux.txt.)
+	This may not be available if no valid UUID is found on the
+	system.
+
+	The following strings are derived from DMI/SMBIOS information
+	if available; these are all new in version 4.10:
+	
+	Bit	String		Significance
+	-------------------------------------------------------------
+	0x0008	SYSVENDOR=	System vendor name
+	0x0010	SYSPRODUCT=	System product name
+	0x0020	SYSVERSION=	System version
+	0x0040	SYSSERIAL=	System serial number
+	0x0080	SYSSKU=		System SKU
+	0x0100	SYSFAMILY=	System family
+	0x0200	MBVENDOR=	Motherboard vendor name
+	0x0400	MBVERSION=	Motherboard version
+	0x0800	MBSERIAL=	Motherboard serial number
+	0x1000	MBASSET=	Motherboard asset tag
+
+	If these strings contain whitespace they it is replaced with
+	underscores (_).
+
+SENDCOOKIES bitmask			[PXELINUX only]
+
+	When downloading files over http, the SYSAPPEND strings are
+	prepended with _Syslinux_ and sent to the server as cookies.
+	The cookies are URL-encoded; whitespace is *not* replaced with
+	underscores.
+
+	This command limits the cookies send; 0 means no cookies.  The
+	default is -1, meaning send all cookies.
+
+	This option is "sticky" and is not automatically reset when
+	loading a new configuration file with the CONFIG command.
 
 LABEL label
     KERNEL image
@@ -379,6 +413,9 @@ SERIAL port [[baudrate] flowcontrol]
 	responsiveness without setting the NOHALT option, but could
 	potentially cause problems with buggy BIOSes.
 
+	This option is "sticky" and is not automatically reset when
+	loading a new configuration file with the CONFIG command.
+
 NOHALT flag_val
 	If flag_val is 1, don't halt the processor while idle.
 	Halting the processor while idle significantly reduces the

