Serva PXE/BINL - AN04: Custom menu

Home

Page 1 of 8

Serva PXE/BINL - AN04: Custom menu

How to customize to your needs Serva's automatically created menu.

Application Notes
Advanced

The objective of this document is to show you a step-by-step guide on

how to edit the automatically created \pxeserva.cfg\menu.def including
examples of commonly needed customizations.

Troubleshooting
Procedures described in this document require Serva "Supporter"

Tools
References
Download
Contact

Serva PXE/BINL - Application Note Set

Serva PXE/BINL - AN01: Windows Install
Serva PXE/BINL - AN02: Windows Install Adv & WinPE Boot
Serva PXE/BINL - AN03: Non-Windows Boot/Install
Serva PXE/BINL - AN04: Custom menu

0 Index
1.
2.
3.
4.
5.
6.

Requirements
Introduction
Supported Commands
Customizations
Troubleshooting
Final Words

1 Requirements
1.1 Required Software
1.1.1 Microsoft Windows Serva 2.1 "Supporter" or higher.
1.2 Assumed knowledge
1.2.1 Serva PXE/BINL - AN01: Windows Install
1.2.2 PXESERVA/PXELINUX basics.

2 Introduction
Serva PXE boot/install menu system is based on Syslinux. A PXE booting station initially creates and
displays its root-level boot/install menu by parsing the commands and parameters contained within the
TFTP retrieved menu definition file located at \pxeserva.cfg\menu.def. On Servas side, BINL services,

http://www.vercot.com/~serva/an/MenuPXE4.html

12/20/2015

Serva PXE/BINL - AN04: Custom menu

Page 2 of 8

automatically create and maintain menu.def using the script language described in this document.
When required (i.e. when adding a new asset under Serva control, removing an existent one, etc.)
Serva Non-Supporter will automatically update menu.def by overwriting any existent previous
version of it. Serva Supporter on the other hand, since v2.1 includes a new menu editing engine that
is aware of and will keep user added menu entries, nested sub-menus, and other menu customizations.
2.1 File Format
Serva created menu.def is a case insensitive text file that can be divided in three clearly distinctive
consecutive sections:
1.
2.
3.

Global settings
Root-level menu container definition.
Root-level menu entry definition list.

Serva automation initially creates and arranges all the menu entries corresponding to Servas assets
within the root-level menu container. However, users can later on manually edit menu.def and not
only alter Servas default menu entry order but also i.e. build a hierarchic menu system by manually
interleaving and populating the required submenu containers. For those interested in customizing
Servas menu system it is highly recommended to initially analyze Servas created menu.def with this
Application Note and the PXESERVA Menu Definition Reference Guide in-hand.
2.2 Command Format
The Command Names have a simple format where up to 2 consecutive Command Identifiers can be
followed by the Command Payload when required.

[<space/Tab>]<CI_1>[<space/Tab><CI_2>][<space/Tab>Command Payload]<EOL>

Note
When the command payload is a text string for screen displaying it cannot contain TABs.

3 Supported Commands
Please see the PXESERVA Menu Definition Reference Guide

4 Customizations
4.1 Menu lay-out
Just alter the corresponding menu container definition variables taking the following diagram as
reference.

http://www.vercot.com/~serva/an/MenuPXE4.html

12/20/2015

Serva PXE/BINL - AN04: Custom menu

Page 3 of 8

Fig 1: Menu lay-out variables

i.e. reducing the password input box by increasing menu passwordmargin from default 3 to 10

menu.def
menu passwordmargin

10

4.2 Menu Title

Just alter the menu title variable.

menu.def
menu title

This is my custom title

4.3 Menu entry order

A typical automatically created menu entry is a sequence of commands beginning with LABEL.
Automatically created entries are separated by an empty line just for cosmetic reasons.

menu.def

http://www.vercot.com/~serva/an/MenuPXE4.html

12/20/2015

Serva PXE/BINL - AN04: Custom menu

Page 4 of 8

LABEL
WIA_WDS\w8_ent_64\
menu label
^ 1) Windows 8 Enterprise, AMD64
kernel
pxechain.cbt
append
::WIA_WDS\w8_ent_64\_SERVA_\pxeboot.n12
LABEL
WIA_WDS\w7_ult_32\
menu label
^ 2) Windows 7, x86
kernel
pxechain.cbt
append
::WIA_WDS\w7_ult_32\_SERVA_\pxeboot.n12

Altering the entry positioning implies to move the menu entry corresponding command sequence to the
desired new location within the menu structure.
i.e. we invert the menu entry order here

menu.def
LABEL
WIA_WDS\w7_ult_32\
menu label
^ 2) Windows 7, x86
kernel
pxechain.cbt
append
::WIA_WDS\w7_ult_32\_SERVA_\pxeboot.n12
LABEL
WIA_WDS\w8_ent_64\
menu label
^ 1) Windows 8 Enterprise, AMD64
kernel
pxechain.cbt
append
::WIA_WDS\w8_ent_64\_SERVA_\pxeboot.n12

Note
Do not worry about the menu entry numbering; Serva will automatically correct it when restarted. If
for any reason you want to prevent Serva auto-numbering an specific entry, just make sure its
menu label command payload begins with "^ " i.e. ^ This label will not be auto-numbered

4.4 Menu entry separator

The command menu separator adds an empty line between two menu/sub-menu entries.
i.e. between two menu entries.

menu.def
LABEL
WIA_WDS\w8_ent_64\
menu label
^ 1) Windows 8 Enterprise, AMD64
kernel
pxechain.cbt
append
::WIA_WDS\w8_ent_64\_SERVA_\pxeboot.n12
menu separator
LABEL
WIA_WDS\w7_ult_32\
menu label
^ 2) Windows 7, x86
kernel
pxechain.cbt
append
::WIA_WDS\w7_ult_32\_SERVA_\pxeboot.n12

4.5 Menu entry Title

Just edit the corresponding variable menu label payload

menu.def

http://www.vercot.com/~serva/an/MenuPXE4.html

12/20/2015

Serva PXE/BINL - AN04: Custom menu

Page 5 of 8

LABEL
WIA_WDS\w8_ent_64\
menu label
"This is my menu entry custom title"
kernel
pxechain.cbt
append
::WIA_WDS\w8_ent_64\_SERVA_\pxeboot.n12

Note
For the sake of consistency this method should not be used on NWAs (non-Windows Assets) menu
entries; NWAs should edit their asset and platform variables on the corresponding ServaAsset.inf
instead.

4.6 Menu entry Help

Just add up to 3 lines of text surrounded by the command sequence text help / endtext

menu.def
LABEL
WIA_WDS\w8_ent_64\
menu label
"This is my entry custom label"
kernel
pxechain.cbt
append
::WIA_WDS\w8_ent_64\_SERVA_\pxeboot.n12
text help
Menu entry help text which can
span up to 3 lines on Serva's
default menu layout...
endtext

4.7 Sub-Menu
A sub-menu is easily created by framing the corresponding menu entries with the command sequence
MENU BEGIN / MENU END

menu.def
MENU BEGIN

My Sub-Menu Title

LABEL
WIA_WDS\w8_ent_64\
menu label
^ 1) Windows 8 Enterprise, AMD64
kernel
pxechain.cbt
append
::WIA_WDS\w8_ent_64\_SERVA_\pxeboot.n12
LABEL WIA_WDS\w7_ult_32\
menu label
^ 2) Windows 7, x86
kernel
pxechain.cbt
append
::WIA_WDS\w7_ult_32\_SERVA_\pxeboot.n12
MENU END

Notes
1.
2.
3.

Complex menu hierarchies can be created by nesting the MENU BEGIN / MENU END
sequence.
The menu entry indentation is not required.
Sub-Menu titles are automatically capitalized by Serva.

4.8 Sub-Menu custom Background

http://www.vercot.com/~serva/an/MenuPXE4.html

12/20/2015

Serva PXE/BINL - AN04: Custom menu

Page 6 of 8

Sub-menus can define custom backgrounds by adding the menu background command followed by
either a color definition or the path\filename of an image file (normally a 640x480 pixels PNG or JPG)

menu.def
MENU BEGIN
My Sub-Menu Title
menu background
pxeserva.cfg\myBkgnd.png
LABEL WIA_WDS\w8_ent_64\
menu label
^ 1) Windows 8 Enterprise, AMD64
kernel
pxechain.cbt
append
::WIA_WDS\w8_ent_64\_SERVA_\pxeboot.n12
LABEL
WIA_WDS\w7_ult_32\
menu label
^ 2) Windows 7, x86
kernel
pxechain.cbt
append
::WIA_WDS\w7_ult_32\_SERVA_\pxeboot.n12
MENU END

Note
The root level menu default background cannot be replaced.

4.9 Password Protection

Sub-menus and menu entries can be easily password protected by adding the command menu
passwd taking as argument the corresponding password hash.

menu.def
MENU BEGIN
menu passwd

My Sub-Menu Title
$4$KR4Oz7c5$iCbcWCHeCorBEC1nZ5oqBV5Z3sg$

LABEL
WIA_WDS\w8_ent_64\
menu label
^ 1) Windows 8 Enterprise, AMD64
menu passwd $4$O4N7ax23$SaXuu4J4LWDDop8kSMAIgpYjRsM$
kernel
pxechain.cbt
append
::WIA_WDS\w8_ent_64\_SERVA_\pxeboot.n12
LABEL
WIA_WDS\w7_ult_32\
menu label
^ 2) Windows 7, x86
menu passwd $4$Q7H2am1d$pnmznxy0wpbEf1/b/JCkxZ/jgZA$
kernel
pxechain.cbt
append
::WIA_WDS\w7_ult_32\_SERVA_\pxeboot.n12
MENU END

4.10 Non-Serva Menu Entries

There are situations when you might want to add a menu entry that does not correspond to a Serva
asset. On those cases remember the rules for the "LABEL MenuEntry_Id" command:
"User-created menu entries are free to use any MenuEntry_Id value as far as they are unique and
never a valid Serva_asset_path".
i.e. the typical entry that allows to boot from client's HDD.

menu.def

http://www.vercot.com/~serva/an/MenuPXE4.html

12/20/2015

Serva PXE/BINL - AN04: Custom menu

Page 7 of 8

LABEL
boot_hdd
menu label
Boot from local HDD
localboot
0
append
-

4.11 Serva RS232-Menu

There are several situations when you might need to install an OS on a head-less systems (nokeyboard/no-monitor), i.e. when probably installing some server OSs, Native Hypervisors, embedded
devices, batch unattended installations, etc. In those cases we can rely on Serva's ability to
simultaneously display its menu through a serial connection. This is done by adding a couple of
commands at the beginnings of the menu.def file.
i.e. commands for Serva displaying a text version of its menu on COM 1 at 115200 bps.

menu.def
############################################################################
# Serva v2.1.0 multi-OS PXE Boot/Install Menu definition
# by Patrick Masotta 2010-2013
############################################################################
SERIAL
CONSOLE

0 115200 0
1

Note
Interactively installing OSs on headless systems through RS-232 requires OS support

7 Troubleshooting
7.1 Serva will respect your custom entries, then there is always the risk of breaking things by
overwriting/deleting some of Serva's required menu parameters. If anything goes wrong just erase
menu.def; Serva will automatically create a new working copy for you. It is always a good idea editing
on small steps and testing if the small change works before to move ahead. Virtualized PXE clients are
very handy when polishing your custom made menu.def.
7.2 Menu displayed strings and TABs
Several menu commands take displayable strings as payload i.e.

menu label Boot from local HDD

In this case "Boot from local HDD" will be displayed in the screen as the corresponding menu entry
label. These kind of strings cannot contain TABS. If a TAB makes it to the screen it would break
menu's layout. In case you forget the rule Serva will automatically convert every TAB into a single
SPACE but is always better if you know/apply the rule.

8 Final words
Serva PXE/BINL custom menu provides endless alternatives and sure you will enjoy its capabilities.
If you find Serva useful please consider contributing to the project by purchasing Serva's "Supporter"
build. Supporter builds make possible Serva's maintenance and future development.

http://www.vercot.com/~serva/an/MenuPXE4.html

12/20/2015

Serva PXE/BINL - AN04: Custom menu

Page 8 of 8

Serva bugs, comments, or ideas on how to improve the information contained in this document please
contact me here.
Originally published

02/01/2013

Copyright 2010-2015 Patrick Masotta. All rights reserved.

http://www.vercot.com/~serva/an/MenuPXE4.html

12/20/2015