Difference between revisions of "Pxechn.c32"

From Syslinux Wiki
Jump to: navigation, search
(Add Categories. Wiki formatting.)
m (Wiki formatting. Add (hidden) notes. Add anchors (for) linking specific command options.)
Line 2: Line 2:
 
[[Category:Examples]]
 
[[Category:Examples]]
 
[[Category:Modules]]
 
[[Category:Modules]]
<!-- Based on the respective asciidoc file, -->
+
<!--
<!-- so the resulting wiki format is slightly different -->
+
--><!-- Based on the respective asciidoc file,  
<!-- than other wiki pages for c32 modules. -->
+
--><!-- so the resulting wiki format is slightly different  
 +
--><!-- than other wiki pages for c32 modules.  
 +
--><!--
 +
--><!-- As of version 6.03-pre1, "pxechn.txt" is an asciidoc file located under
 +
--><!-- the "doc/" directory of the official Syslinux distribution archives:
 +
--><!--
 +
--><!-- https://repo.or.cz/syslinux.git/blob_plain/refs/tags/syslinux-6.04-pre1:/doc/pxechn.txt
 +
--><!-- https://repo.or.cz/syslinux.git/blob_plain/HEAD:/doc/pxechn.txt
 +
--><!--
 +
--><!-- Other (".txt") files within the same "doc/" directory are plain text,
 +
--><!-- _not_ asciidoc.
 +
--><!-- In the official Syslinux distribution archives,
 +
--><!-- there are other asciidoc files, located under the "txt/" directory:
 +
--><!--
 +
--><!-- https://repo.or.cz/syslinux.git/tree/refs/tags/syslinux-6.04-pre1:/txt
 +
--><!--
 +
--><!-- When building Syslinux, "txt/Makefile" contains a list of ".txt" files
 +
--><!-- that would be "translated"
 +
--><!-- from asciidoc into other formats (man pages, html, ...):
 +
--><!--
 +
--><!-- https://repo.or.cz/syslinux.git/blob/refs/tags/syslinux-6.04-pre1:/txt/Makefile
 +
--><!--
 +
--><!-- IOW, the "pxechn.txt" file should ideally be moved, from "doc/" to "txt/".
 +
--><!--
 +
-->
  
 
'''pxechn.c32''' - Chainboot to new Network Boot Program (NBP).<br />
 
'''pxechn.c32''' - Chainboot to new Network Boot Program (NBP).<br />
Line 14: Line 38:
 
  pxechn.c32 [-h | --help | -?]
 
  pxechn.c32 [-h | --help | -?]
 
  pxechn.c32 -r ''FILE''
 
  pxechn.c32 -r ''FILE''
  pxechn.c32 ''FILE'' [OPTIONS]
+
  pxechn.c32 ''FILE'' [''OPTIONS'']
  
 
== DESCRIPTION ==
 
== DESCRIPTION ==
Line 34: Line 58:
 
== OPTIONS ==
 
== OPTIONS ==
  
; '''-c''' ''CONFIG''
+
; {{S|1=-c}}<code id="-c">'''-c''' ''CONFIG''</code>
 
: ''config'' file for PXELINUX (DHCP Option 209).
 
: ''config'' file for PXELINUX (DHCP Option 209).
  
<!-- Options not to be displayed (as found in the asciidoc source) -->
+
<!--
<!--
+
--><!-- Options not to be displayed (as found in the asciidoc source)  
--><!-- ; '''-f''' ''MOD''
+
--><!--  
 +
--><!-- ; {{S|1=-f}}<code id="-f">'''-f''' ''MOD''</code>
 
--><!-- : ''Force'' behavior specified by modifier ''MOD''
 
--><!-- : ''Force'' behavior specified by modifier ''MOD''
 
--><!--  
 
--><!--  
--><!-- ; '''-g''' ''HOST''
+
--><!-- ; {{S|1=-g}}<code id="-g">'''-g''' ''HOST''</code>
--><!-- : Set ''gateway''/relay DHCP field to ''HOST''.  Parsed by <code>pxe_dns()</code> .
+
--><!-- : Set ''gateway''/relay DHCP field to ''HOST''.  Parsed by <code>pxe_dns()</code>.
 
-->
 
-->
  
; '''-h''', '''--help''', '''-?'''
+
; {{S|1=-h}}<code id="-h">'''-h''', '''--help''', '''-?'''</code>
: Print ''help''/usage information; invalid options will also cause this.
+
: Print help/usage information; invalid options will also cause this.
  
<!-- Options not to be displayed (as found in the asciidoc source) -->
+
<!--
<!--
+
--><!-- Options not to be displayed (as found in the asciidoc source)  
--><!-- ; '''-n'''
+
--><!--  
 +
--><!-- ; {{S|1=-n}}<code id="-n">'''-n'''</code>
 
--><!-- : Use ''native'' methods, ignoring underlying gPXE/iPXE.
 
--><!-- : Use ''native'' methods, ignoring underlying gPXE/iPXE.
 
--><!--  
 
--><!--  
--><!-- ; '''-N'''
+
--><!-- ; {{S|1=-N}}<code id="-N">'''-N'''</code>
 
--><!-- : Use ''non-native'' methods to utilize gPXE/iPXE (if available).
 
--><!-- : Use ''non-native'' methods to utilize gPXE/iPXE (if available).
 
-->
 
-->
  
<!-- The following option's explanation might require better formatting, -->
+
<!--
<!-- and might benefit from a more adequate semantics/wording. -->
+
--><!-- The following option's explanation might require better formatting,  
<!--
+
--><!-- and might benefit from a more adequate semantics/wording.  
 
--><!--  
 
--><!--  
 
--><!-- <nowiki> Right curly curved single quotation mark character: </nowiki>  
 
--><!-- <nowiki> Right curly curved single quotation mark character: </nowiki>  
--><!-- <nowiki> unicode: 2019 </nowiki>  
+
--><!-- <nowiki> unicode   : 2019                                   </nowiki>  
--><!-- <nowiki> html: &rsquo; </nowiki>  
+
--><!-- <nowiki> html       : &rsquo;                               </nowiki>  
--><!-- <nowiki> xml / html: &#8217; </nowiki>  
+
--><!-- <nowiki> xml / html : &#8217;                               </nowiki>  
--><!-- <nowiki> Windows: alt+0146 </nowiki>  
+
--><!-- <nowiki> Windows   : alt+0146                               </nowiki>  
 
-->
 
-->
; '''-o''' ''OPT.TYPE=VALUE''
+
; {{S|1=-o}}<code id="-o">'''-o''' ''OPT.TYPE=VALUE''</code>
 
: Set ''option''.  <!--   
 
: Set ''option''.  <!--   
 
   --><p>  ''OPT'' is in [[#DECIMAL_INPUT|decimal input]] format (see below).  </p><!--   
 
   --><p>  ''OPT'' is in [[#DECIMAL_INPUT|decimal input]] format (see below).  </p><!--   
 
   --><p>  ''TYPE'' specifies the output type and input syntax  <!--   
 
   --><p>  ''TYPE'' specifies the output type and input syntax  <!--   
 
   -->    (listed here in between unpaired curved right single quotation marks <!--   
 
   -->    (listed here in between unpaired curved right single quotation marks <!--   
   -->    and {{nowrap|1-character-long)<nowiki>:</nowiki>}}  </p><!--   
+
   -->    and {{nowrap|1=1-character-long)<nowiki>:</nowiki>}}  </p><!--   
 
   --><p>  _ &rsquo;'''''b'''&rsquo;yte'',  </p><!--   
 
   --><p>  _ &rsquo;'''''b'''&rsquo;yte'',  </p><!--   
 
   --><p>  _ &rsquo;'''''w'''&rsquo;ord''(2B),  </p><!--   
 
   --><p>  _ &rsquo;'''''w'''&rsquo;ord''(2B),  </p><!--   
Line 85: Line 111:
 
   -->    meet the criteria for [[#DECIMAL_INPUT|decimal input]].</p>
 
   -->    meet the criteria for [[#DECIMAL_INPUT|decimal input]].</p>
  
; '''-p''' ''PATH''
+
; {{S|1=-p}}<code id="-p">'''-p''' ''PATH''</code>
 
: ''path'' option for PXELINUX (DHCP Option 210).
 
: ''path'' option for PXELINUX (DHCP Option 210).
; '''-r'''
+
 
 +
; {{S|1=-r}}<code id="-r">'''-r'''</code>
 
: ''restart''. Call the PXE stack with <code>PXENV_RESTART_TFTP</code>&nbsp;. <!--   
 
: ''restart''. Call the PXE stack with <code>PXENV_RESTART_TFTP</code>&nbsp;. <!--   
 
   -->    <u>Must</u> be the only option, and before ''FILE''.
 
   -->    <u>Must</u> be the only option, and before ''FILE''.
; '''-S'''
+
 
 +
; {{S|1=-S}}<code id="-S">'''-S'''</code>
 
: Set ''sip'' based on ''sname'' {{nowrap|field/option 66}}  <!--   
 
: Set ''sip'' based on ''sname'' {{nowrap|field/option 66}}  <!--   
   -->    (by direct IP if using a {{nowrap|period-delimited}} address, or otherwise by DNS).
+
   -->    (by direct IP if using a {{nowrap|period-delimited}} address, <!-- 
; '''-t''' ''SECONDS''
+
  -->    or otherwise by DNS).
 +
 
 +
; {{S|1=-t}}<code id="-t">'''-t''' ''SECONDS''</code>
 
: ''timeout'' option for PXELINUX (DHCP Option 211).
 
: ''timeout'' option for PXELINUX (DHCP Option 211).
  
<!-- Options not to be displayed (as found in the asciidoc source) -->
+
<!--
<!--
+
--><!-- Options not to be displayed (as found in the asciidoc source)  
--><!-- ; '''-u'''
+
--><!--  
 +
--><!-- ; {{S|1=-u}}<code id="-u">'''-u'''</code>
 
--><!-- : Copy ''UUID'' (Option 97) if found in packet #1
 
--><!-- : Copy ''UUID'' (Option 97) if found in packet #1
 
-->
 
-->
  
; '''-w'''
+
; {{S|1=-w}}<code id="-w">'''-w'''</code>
 
: After loading, ''wait'' for user input before booting.
 
: After loading, ''wait'' for user input before booting.
; '''-W'''
+
 
 +
; {{S|1=-W}}<code id="-W">'''-W'''</code>
 
: Enable specific options for ''WDS'' (Windows Deployment Services).  <!--   
 
: Enable specific options for ''WDS'' (Windows Deployment Services).  <!--   
 
   --><p>  ''FILE'' (or its overrides for DHCP fields ''siaddr'' and ''file'') <!--   
 
   --><p>  ''FILE'' (or its overrides for DHCP fields ''siaddr'' and ''file'') <!--   
 
   -->    must point at the WDS server.  </p><!--   
 
   -->    must point at the WDS server.  </p><!--   
 
   --><p>  <u>Note:</u> As of 2012-05-31, <!--   
 
   --><p>  <u>Note:</u> As of 2012-05-31, <!--   
   -->    there is a known issue with gPXE/iPXE, at least with <tt>undionly.kkpxe</tt>. <!--   
+
   -->    there is a known issue with gPXE/iPXE, <!-- 
 +
  -->    at least with <tt>undionly.kkpxe</tt>. <!--   
 
   --><!-- PXELINUX asks gPXE/iPXE to unload, reverting to an underlying stack. --></p>
 
   --><!-- PXELINUX asks gPXE/iPXE to unload, reverting to an underlying stack. --></p>
  
Line 116: Line 149:
 
All parameters that are defaulted to decimal format are processed by  
 
All parameters that are defaulted to decimal format are processed by  
 
<code>strtoul(3)</code> with a base of 0,  
 
<code>strtoul(3)</code> with a base of 0,  
which allows alternate formats and finds a suitable {{nowrap|non-space}} separating character.
+
which allows alternate formats and finds a  
 +
suitable {{nowrap|non-space}} separating character.
  
 
== EXAMPLES ==
 
== EXAMPLES ==
Line 124: Line 158:
 
{|
 
{|
 
|
 
|
<pre> pxechn.c32 http://myhost.dom.loc/path/nbp.0 -c myconfig </pre>
+
<pre>
 +
pxechn.c32 http://myhost.dom.loc/path/nbp.0 -c myconfig  
 +
</pre>
 
|}
 
|}
 
<br /></li>
 
<br /></li>
Line 134: Line 170:
 
{|
 
{|
 
|
 
|
<pre> pxechn.c32 gpxelinux.0 -p http://10.1.1.4/tftp/ -w -c myconfig -o 15.s=domain.loc -o 6.x=0A:01:01:02:ac:17:4D:Ec - </pre>
+
<pre>
 +
pxechn.c32 gpxelinux.0 -p http://10.1.1.4/tftp/ -w -c myconfig -o 15.s=domain.loc -o 6.x=0A:01:01:02:ac:17:4D:Ec -  
 +
</pre>
 
|}
 
|}
 
<br /></li>
 
<br /></li>
  
<li> Load ''gpxelinux.0'' (relative to the current directory and not altering {{nowrap|sname/option 66}}),  <!--   
+
<li> Load ''gpxelinux.0'' <!-- 
   -->  set the PXELINUX path prefix, wait after loading, set option <tt>160</tt> to  <!--   
+
  -->  (relative to the current directory and <!-- 
   -->  <tt>{{nowrap|0x12 0x34 0x56 0x78}}</tt>, and option <tt>197</tt> to <tt>{{nowrap|0x00 0xD0 0xDE 0x00}}</tt>.
+
  -->  not altering {{nowrap|sname/option 66}}),  <!--   
 +
   -->  set the PXELINUX path prefix, <!-- 
 +
  -->  wait after loading, <!-- 
 +
  -->  set option <tt>160</tt> to  <!--   
 +
   -->  <tt>{{nowrap|0x12 0x34 0x56 0x78}}</tt>, <!-- 
 +
  -->  and option <tt>197</tt> <!-- 
 +
  -->  to <tt>{{nowrap|0x00 0xD0 0xDE 0x00}}</tt>.
 
{|
 
{|
 
|
 
|
<pre> pxechn.c32 gpxelinux.0 -p http://10.1.1.4/tftp/ -w -o 0xA0.x=12:34:56:78 -x 197.x=00:d0:de:00 </pre>
+
<pre>
 +
pxechn.c32 gpxelinux.0 -p http://10.1.1.4/tftp/ -w -o 0xA0.x=12:34:56:78 -x 197.x=00:d0:de:00  
 +
</pre>
 
|}
 
|}
 
<br /></li>
 
<br /></li>
  
<li> Load ''wdsnbp.com'' from 10.1.1.8 and copy DHCP Option 66 to DHCP field ''sname'' if there is room.
+
<li> Load ''wdsnbp.com'' from 10.1.1.8 and <!-- 
 +
  -->  copy DHCP Option 66 to DHCP field ''sname'' if there is room.
 
{|
 
{|
 
|
 
|
<pre> pxechn.c32 10.1.1.8:boot\x86\wdsnbp.com -W </pre>
+
<pre>
 +
pxechn.c32 10.1.1.8:boot\x86\wdsnbp.com -W  
 +
</pre>
 
|}
 
|}
 
<br /></li>
 
<br /></li>
  
<li> Load ''wdsnbp.com'' from 10.1.1.4, point packets to 10.1.1.8 for use with WDS,  <!--   
+
<li> Load ''wdsnbp.com'' from 10.1.1.4, <!-- 
   -->  copy DHCP Option 66 to DHCP field ''sname'' if there is room and decode this to an IPv4 address.
+
  -->  point packets to 10.1.1.8 for use with WDS,  <!--   
 +
   -->  copy DHCP Option 66 to DHCP field ''sname'' if there is room <!-- 
 +
  -->  and decode this to an IPv4 address.
 
{|
 
{|
 
|
 
|
<pre> pxechn.c32 10.1.1.4:boot\x86\wdsnbp.com -W -o 66.x=0a:01:01:08 -S </pre>
+
<pre>
 +
pxechn.c32 10.1.1.4:boot\x86\wdsnbp.com -W -o 66.x=0a:01:01:08 -S  
 +
</pre>
 
|}
 
|}
 
<br /></li>
 
<br /></li>
Line 169: Line 222:
 
negating all DHCP field/option modifications by pxechn.c32,  
 
negating all DHCP field/option modifications by pxechn.c32,  
 
including Microsoft Windows Server 2008R2 WDS’s wdsnbp.com.  
 
including Microsoft Windows Server 2008R2 WDS’s wdsnbp.com.  
See also option ''-W''.
+
See also option [[#-W|''-W'']].
  
 
URL specifications in ''FILE'' that include user/password before the host  
 
URL specifications in ''FILE'' that include user/password before the host  
 
will currently cause the ''siaddr'' field to not be set properly.
 
will currently cause the ''siaddr'' field to not be set properly.
  
The non-space constraint is due to how Syslinux variants parse the command line as of 2012-09-16.
+
The non-space constraint is due to how Syslinux variants parse the command line  
 +
as of 2012-09-16.
 
<br />
 
<br />
  
 
As of version 6.03, pxechn.c32 has no use when booting with syslinux.efi.  
 
As of version 6.03, pxechn.c32 has no use when booting with syslinux.efi.  
 
Do not expect it to work in UEFI mode.
 
Do not expect it to work in UEFI mode.

Revision as of 15:29, 30 October 2020


pxechn.c32 - Chainboot to new Network Boot Program (NBP).


SYNOPSIS

pxechn.c32 [-h | --help | -?]
pxechn.c32 -r FILE
pxechn.c32 FILE [OPTIONS]

DESCRIPTION

Chainboot to a new Network Boot Program (NBP) FILE with options to adjust PXE packet #3 (PXENV_PACKET_TYPE_CACHED_REPLY) to alter end behavior.

FILE may be either:

  • a filename,
  • an IP::FN (192.168.1.1::path/to/file.0 ) ,
  • or a URL.

FILE is parsed to adjust the DHCP sname field/option 66 and file field/option 67.

OPTIONS

§ -c CONFIG
config file for PXELINUX (DHCP Option 209).


§ -h, --help, -?
Print help/usage information; invalid options will also cause this.


§ -o OPT.TYPE=VALUE
Set option.

OPT is in decimal input format (see below).

TYPE specifies the output type and input syntax (listed here in between unpaired curved right single quotation marks and 1-character-long):

_ ’b’yte,

_ ’w’ord(2B),

_ ’l’ong(4B),

_ ’q’uad(8B),

_ character ’s’tring, and

_ colon-separatedh’ex string

TYPE is case-insensitive; bytes must have 2 digits and each byte must be separated.

byte, word, long and quad input values must meet the criteria for decimal input.

§ -p PATH
path option for PXELINUX (DHCP Option 210).
§ -r
restart. Call the PXE stack with PXENV_RESTART_TFTP . Must be the only option, and before FILE.
§ -S
Set sip based on sname field/option 66 (by direct IP if using a period-delimited address, or otherwise by DNS).
§ -t SECONDS
timeout option for PXELINUX (DHCP Option 211).


§ -w
After loading, wait for user input before booting.
§ -W
Enable specific options for WDS (Windows Deployment Services).

FILE (or its overrides for DHCP fields siaddr and file) must point at the WDS server.

Note: As of 2012-05-31, there is a known issue with gPXE/iPXE, at least with undionly.kkpxe.

DECIMAL INPUT

All parameters that are defaulted to decimal format are processed by strtoul(3) with a base of 0, which allows alternate formats and finds a suitable non-space separating character.

EXAMPLES

  1. Load nbp.0 and set PXELINUX config (option 209).
     pxechn.c32 http://myhost.dom.loc/path/nbp.0 -c myconfig 
    

  2. Load gpxelinux.0 from the current directory, set prefix, wait to execute, set first config, set the domain name and 2 domain name servers (case mixed to show insensitivity; 10.1.1.2 and 172.23.77.236).
     pxechn.c32 gpxelinux.0 -p http://10.1.1.4/tftp/ -w -c myconfig -o 15.s=domain.loc -o 6.x=0A:01:01:02:ac:17:4D:Ec - 
    

  3. Load gpxelinux.0 (relative to the current directory and not altering sname/option 66), set the PXELINUX path prefix, wait after loading, set option 160 to 0x12 0x34 0x56 0x78, and option 197 to 0x00 0xD0 0xDE 0x00.
     pxechn.c32 gpxelinux.0 -p http://10.1.1.4/tftp/ -w -o 0xA0.x=12:34:56:78 -x 197.x=00:d0:de:00 
    

  4. Load wdsnbp.com from 10.1.1.8 and copy DHCP Option 66 to DHCP field sname if there is room.
     pxechn.c32 10.1.1.8:boot\x86\wdsnbp.com -W 
    

  5. Load wdsnbp.com from 10.1.1.4, point packets to 10.1.1.8 for use with WDS, copy DHCP Option 66 to DHCP field sname if there is room and decode this to an IPv4 address.
     pxechn.c32 10.1.1.4:boot\x86\wdsnbp.com -W -o 66.x=0a:01:01:08 -S 
    

NOTES

Please note that some NBPs may ignore packet #3 by either not examining it at all or by issuing its own DHCP DISCOVER/REQUEST, negating all DHCP field/option modifications by pxechn.c32, including Microsoft Windows Server 2008R2 WDS’s wdsnbp.com. See also option -W.

URL specifications in FILE that include user/password before the host will currently cause the siaddr field to not be set properly.

The non-space constraint is due to how Syslinux variants parse the command line as of 2012-09-16.

As of version 6.03, pxechn.c32 has no use when booting with syslinux.efi. Do not expect it to work in UEFI mode.