Booting custom entries in 2PXE menu

This page explains hot the CustomMenuItems item in the .config file works to allow custom actions in the 2PXE menu.

Note: Please use 2.9.18.0 or later with 2PXE when experimenting with this.

The CustomMenuItems section provides the following capabilities;

• Provide a way to link custom iPXE scripting language with an entry in the menu provided by 2PXE.

• Using the custom script entry, a call to the iPXE Anywhere Web Service can be made to create custom scripting scenarios from the 2PXE boot menu.

How does it work?

Define one or many entries in the CustomMenuItems using the key/value format, where;

• The "key" value links to an entry under CustomItems which is just below in the same .config file.

• The "value" value is the display text shown in the menu itself on the machine you are booting.

The below scenario is linking a single entry as per below, in this case, we create a single entry with the "key" set to "myShell", and the display text will then be "iPXE Shell" in the menu:

  <CustomMenuItems>
    <add key="myShell" value="iPXE Shell"/>
  </CustomMenuItems>

So then we need a matching entry with iPXE code in the "CustomItems" sections. In this case, it's simple, create a key with "myShell" identifier, linking with above, then the iPXE code snippet to start a shell, is "shell". Simple!

  <CustomItems>
    <add key="myShell" value="shell"/>
  </CustomItems>

After the snippet returns, it will run the "goto keypressed" label, which is an internal label to return to the menu. You can call this yourself in your custom script if you want to exit out early.

Multiple items

You can have multiple items in here, as long as you match the keys as per below:

  <CustomMenuItems>
    <add key="myShell" value="iPXE Shell"/>
    <add key="vaccine" value="Book Corona vaccination"/>
    <add key="bootToiPXWS" value="Reset device"/>
  </CustomMenuItems>

<CustomItems>
    <add key="myShell" value="shell"/>
    <add key="vaccine" value="echo Sorry not available here! &amp;&amp; prompt Press any key to return to menu"/>
    <add key="bootToiPXWS" value="chain https://server.fqnd...."/>
</CustomItems>

XML and advanced syntax

Keep in mind that the .config file is XML based, so using & and other XML syntax language, you need to escape them correctly so that the XML parsing is not broken. So an iPXE && would in the config file be && etc.

If you want a line break, you can do this two ways;

1. Create an actual line break in the .config file

2. Don't use the \r\n line feed character inline. Its important that there is no \r\n characters in the script piece as the .Net parser will double escape this which break. Instead use the following syntax:

echo line 1
echo line2

Booting a custom WinPE image

Its certainly possible to boot against a custom boot image, you just have to issue the right commands, and make sure you have the right files available.

Please see the following link to the iPXE web site for some inspiration: https://ipxe.org/howto/winpe

The syntax would be something like this in the .config section:

Linking up against the iPXE Web Service

One great feature is to use the 2PXE menu items to integrate with the iPXE Anywhere Web Service. Please reach out to us if you have custom scripting scenarios you would like to discuss. You can use this issue to automate a "ticket" etc for machine refusing to boot, or reset PXE flags etc. There is really no end to the possibilities.