Allow the DHCP server to override PXELINUX default options;

PXELINUX documentation fixes.

4 files changed, 146 insertions, 16 deletions

diff --git a/NEWS b/NEWS
index 37e3f43c..1626a22b 100644
--- a/NEWS
+++ b/NEWS
@@ -1,6 +1,12 @@
 Starting with 1.47, changes marked with SYSLINUX/PXELINUX/ISOLINUX
 apply to that specific program only; other changes apply to both.
 
+Changes in 1.62:
+	* PXELINUX: Allow the DHCP server to override the
+	  configuration file name and pathname prefix, using
+	  "site-specific" DHCP options.
+	* PXELINUX: Documentation fixes.
+
 Changes in 1.61:
 	* ISOLINUX: Support full pathname searches.  Max length for a
 	  pathname is 255 characters.  As a result, only 64 "label"
diff --git a/pxelinux.asm b/pxelinux.asm
index 6c0c057b..c7f6d1c4 100644
--- a/pxelinux.asm
+++ b/pxelinux.asm
@@ -328,6 +328,7 @@ AppendBuf       resb max_cmd_len+1	; append=
 KbdMap		resb 256		; Keyboard map
 BootFile	resb 256		; Boot file from DHCP packet
 PathPrefix	resb 256		; Path prefix derived from the above
+ConfigName	resb 256		; Configuration file from DHCP option
 FKeyName	resb 10*FILENAME_MAX	; File names for F-key help
 NumBuf		resb 15			; Buffer to load number
 NumBufEnd	resb 1			; Last byte in NumBuf
@@ -775,10 +776,23 @@ mkkeymap:	stosb
 		inc al
 		loop mkkeymap
 
+
+;
+; Check to see if we got any PXELINUX-specific DHCP options
+;
+check_dhcp_magic:
+		test byte [DHCPMagic], 1	; If we didn't get the magic enable...
+		jnz .got_magic
+		mov byte [DHCPMagic], 0		; If not, kill all other options
+.got_magic:
+	
+
 ;
 ; Store standard filename prefix
 ;
-prefix:		mov si,BootFile
+prefix:		test byte [DHCPMagic], 04h	; Did we get a path prefix option
+		jnz .got_prefix
+		mov si,BootFile
 		mov di,PathPrefix
 		cld
 		call strcpy
@@ -803,6 +817,7 @@ prefix:		mov si,BootFile
 		dec si
 .notalnum:	mov byte [si+2],0		; Zero-terminate after delimiter
 		cld
+.got_prefix:
 		mov si,tftpprefix_msg
 		call writestr
 		mov si,PathPrefix
@@ -837,6 +852,21 @@ find_config:	mov di,trackbuf
 ; Begin looking for configuration file
 ;
 config_scan:
+		test byte [DHCPMagic], 02h
+		jz .no_option
+
+		; We got a DHCP option, try it first
+		mov si,trying_msg
+		call writestr
+		mov di,ConfigName
+		mov si,di
+		call writestr
+		call crlf
+		call open
+		jnz .success
+
+.no_option:		; Have to guess config file name
+
 		mov cx,9			; Up to 9 attempts
 
 .tryagain:	mov byte [di],0
@@ -4207,24 +4237,52 @@ parse_dhcp_options:
 		jmp short .opt_done
 
 .not_overload:
-		mov dl,67	; BOOTFILE NAME option
+		cmp dl,67	; BOOTFILE NAME option
 		jne .not_bootfile
-		push cx
 		mov di,BootFile
-		mov cx,ax
-		rep movsb
-		mov byte [di],0	; Null-terminate
-		pop cx
-		jmp short .opt_done_noskip
+		jmp short .copyoption
+
+.done:
+		ret		; This is here to make short jumps easier
 
 .not_bootfile:
+		cmp dl,176	; PXELINUX MAGIC option
+		jne .not_pl_magic
+		cmp al,4	; Must have length == 4
+		jne .opt_done
+		cmp dword [si], htonl(0xF100747E)	; Magic number
+		jne .opt_done
+		or byte [DHCPMagic], byte 1		; Found magic #
+		jmp short .opt_done
+
+.not_pl_magic:
+		cmp dl,177	; PXELINUX CONFIGFILE option
+		jne .not_pl_config
+		mov di,ConfigName
+		or byte [DHCPMagic], byte 2	; Got config file
+		jmp short .copyoption
+
+.not_pl_config:
+		cmp dl,178	; PXELINUX PATHPREFIX option
+		jne .not_pl_prefix
+		mov di,PathPrefix
+		or byte [DHCPMagic], byte 4	; Got path prefix
+		jmp short .copyoption
+	
+.not_pl_prefix:
 		; Unknown option.  Skip to the next one.
 .opt_done:
 		add si,ax
 .opt_done_noskip:
-		jmp short .loop
-.done:
-		ret
+		jmp .loop
+
+		; Common code for copying an option verbatim
+.copyoption:
+		xchg cx,ax
+		rep movsb
+		xchg cx,ax	; Now ax == 0
+		stosb		; Null-terminate
+		jmp short .opt_done_noskip
 
 ;
 ; genipopt
@@ -4767,6 +4825,8 @@ A20List		dw a20_dunno, a20_none, a20_bios, a20_kbc, a20_fast
 A20DList	dw a20d_dunno, a20d_none, a20d_bios, a20d_kbc, a20d_fast
 A20Type		dw A20_DUNNO		; A20 type unknown
 VGAFontSize	dw 16			; Defaults to 16 byte font
+ScrollAttribute	db 07h			; White on black (for text mode)
+
 ;
 ; TFTP commands
 ;
@@ -4804,7 +4864,7 @@ ClustPerMoby	dw 65536/TFTP_BLOCKSIZE	; Clusters per 64K
 %error trackbufsize must be a multiple of TFTP_BLOCKSIZE
 %endif
 IPAppend	db 0			; Default IPAPPEND option
-ScrollAttribute	db 07h			; White on black (for text mode)
+DHCPMagic	db 0			; DHCP site-specific option info
 
 ;
 ; Stuff for the command line; we do some trickery here with equ to avoid
diff --git a/pxelinux.doc b/pxelinux.doc
index fd55baa4..9e1a7d26 100644
--- a/pxelinux.doc
+++ b/pxelinux.doc
@@ -52,6 +52,8 @@ search for its config file on the boot server in the following way:
   As an example, for 192.0.2.91, it will try C000025B, C000025,
   C00002, C0000, C000, C00, C0, C, and default, in that order.
 
+(See also the section on special DHCP options.)
+
 It should be noted that all filename references are relative to the
 directory pxelinux.0 lives in (usually /tftpboot).  PXELINUX
 generally requires that filenames (including any relative path) are 63
@@ -139,6 +141,7 @@ syntax:
 	group {
 		# PXE-specific configuration directives...
 		next-server <TFTP server address>;
+		filename "/tftpboot/pxelinux.0";
 
 		# You need an entry like this for every host
 		# unless you're using dynamic addresses
@@ -148,6 +151,11 @@ syntax:
         	}
 	}
 
+Note that if your particular TFTP daemon runs under chroot (tftp-hpa
+will do this if you specify the -s (secure) option; this is highly
+recommended), you almost certainly should not include the /tftpboot
+prefix in the filename statement.
+
 If this does not work for your configuration, you probably should set
 up a "PXE boot server" on port 4011 of your TFTP server; a free PXE
 boot server is available at:
@@ -182,6 +190,8 @@ the same except for an "option dhcp-class-identifier":
         	}
 	}
 
+Here, the boot file name is obtained from the PXE server.
+
 If the "conventional TFTP" configuration doesn't work on your clients,
 and setting up a PXE boot server is not an option, you can attempt the
 following configuration.  It has been known to boot some
@@ -204,6 +214,7 @@ configurations correctly; however, there are no guarantees:
 	        option dhcp-class-identifier "PXEClient";
 		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;
 		next-server <TFTP server>;
+		filename "/tftpboot/pxelinux.0";
 
 		# You need an entry like this for every host
 		# unless you're using dynamic addresses
@@ -217,9 +228,62 @@ Note that this *will not* boot some clients that *will* boot with the
 "conventional TFTP" configuration; Intel Boot Client 3.0 and later are
 known to fall into this category.
 
-Note that if your particular TFTP daemon runs under chroot (tftp-hpa
-will do this if you specify the -s (secure) option; this is
-recommended), you most likely should not include the /tftpboot prefix.
+
+    ++++ SPECIAL DHCP OPTIONS ++++
+
+PXELINUX (starting with version 1.62) supports the following
+nonstandard DHCP options, which depending on your DHCP server you may
+be able to use to customize the specific behaviour of PXELINUX:
+
+Option 176	pxelinux.magic
+	- Must be set to F1:00:74:7E (241.0.116.126) for PXELINUX to
+	  recognize any special DHCP options whatsoever.
+
+Option 177	pxelinux.configfile
+	- Specifies the PXELINUX configuration file name.
+
+Option 178	pxelinux.pathprefix
+	- Specifies the PXELINUX common path prefix, instead of
+	  deriving it from the boot file name.  This almost certainly
+	  needs to end in whatever character the TFTP server OS uses
+	  as a pathname separator, e.g. slash (/) for Unix.
+
+ISC dhcp 3.0 supports a rather nice syntax for specifying custom
+options; you can use the following syntax in dhcpd.conf if you are
+running this version of dhcpd:
+
+	option space pxelinux;
+	option pxelinux.magic code 176 = string;
+	option pxelinux.configfile code 177 = text;
+	option pxelinux.pathprefix code 178 = text;
+
+Then, inside your PXELINUX-booting group or class (whereever you have
+the PXELINUX-related options, such as the filename option), you can
+add, for example:
+
+	site-option-space pxelinux;
+	option pxelinux.magic f1:00:74:7e;
+	option pxelinux.configfile "configs/common";
+	option pxelinux.pathprefix "/tftpboot/pxelinux/files/";
+	filename "/tftpboot/pxelinux/pxelinux.bin";
+
+Note that the configfile is relative to the pathprefix: this will look
+for a config file called /tftpboot/pxelinux/files/configs/common on
+the TFTP server.
+
+Using ISC dhcp 3.0 you can create a lot of these strings on the fly.
+For example, to use the hexadecimal form of the hardware address as
+the configuration file name, you could do something like:
+
+	site-option-space pxelinux;
+	option pxelinux.magic f1:00:74:7e;
+	option pxelinux.configfile =
+		concat("pxelinux.cfg/", binary-to-ascii(16, 8, ":", hardware));
+	filename "/tftpboot/pxelinux.bin";
+
+If you used this from a client whose Ethernet address was
+58:FA:84:CF:55:0E, this would look for a configuration file named
+"/tftpboot/pxelinux.cfg/1:58:fa:84:cf:55:e".
 
 
     ++++ SOME NOTES ++++
diff --git a/version b/version
index 4213d88d..0a03ace4 100644
--- a/version
+++ b/version
@@ -1 +1 @@
-1.61
+1.62