Debugging E2B

If you are having problems with E2B, here are a few tips on how to debug it and look for the cause. As E2B uses grub4dos, these techniques can be applied to most grub4dos systems.

Always update to the latest Beta version first!

Check for user ‘modifications’

You may have caused the problem by using a \_ISO\MyE2B.cfg file, or adding .txt, \_ISO\STRINGS.txt or \FASTLOAD.YES files (or perhaps other changes).

Temporarily rename or delete these files and test again. If possible, create a new E2B USB drive using the latest Beta version and test using that too.

If you are having trouble with a particular payload file, ensure that you have not specified a corresponding .txt file (e.g. ubuntu.iso and ubuntu.txt) – delete the .txt file in case it is causing problems.

If your payload is using a .mnu file, check the syntax carefully and ensure you have changed ALL occurrences of the payload filename, etc. Remember that grub4dos using / as a directory path separator and not \.

Avoid using spaces or other strange characters such as (){}&!, etc. in your payload file names. Just use a-z, A-Z, 0-9, and – or _ characters for initial testing.

Check for grub4dos bugs

Replace the \grldr file with a different version of grub4dos downloaded from here. You can also try copying the \_ISO\e2b\grub\grldr_046 file to \grldr. This version is usually an older, stable version. 

Tip: If you have trouble booting grub4dos, try pressing the S key just as it loads grub4dos – you should see a 5 seconds countdown and it will use ‘safe mode’. Disk accesses will be much slower however.

Remove the E2B grub4dos console password protection

The default E2B menu system has a grub4dos menu password preset. To remove the grub4dos menu password protection, boot to the Main menu (or any E2B menu) and press p (or SHIFT+p) – you should then be prompted for a password. The default E2B password is easy2boot.

Each menu is password protected, so you will need to re-enter the same password if you load another sub-menu page.

Tip: Use  set pwd=   in your \_ISO\MyE2B.cfg file to remove the menu password (no space after the = sign).

e.g.  \_ISO\MyE2B.cfg
!BAT
set pwd=

Menu editing and the console

Once password protection has been removed we can use some of the grub4dos menu and shell features:

Note: On later versions of grub4dos, hold down the SHIFT key before pressing the e, p, c or b key.

Use the Up\Down cursor keys to highlight a particular menu item and then press SHIFT+E (for edit) – grub4dos will then display the code that will be run by that menu item. You can edit any line or add or delete lines. Once you have finished editing press [ENTER] key to run it or press the B key – or press [ESC] key to abort the changes. Note that if you reload the same menu, your changes will be lost. Use O or o to insert a new line.

You can get to the grub4dos shell (console) by pressing SHIFT+C for the console (ESC will return you to the menu).

E2B stores each menu that it creates at (md)0x3000 in memory, you can therefore list the menu that was created by E2B by using the command:

cat (md)0x3000+2

to list the first 1024 bytes (2×512-byte sectors of memory). Increase the last number to display more of the menu. 

The Main menu is held in memory at (md)0xa000.

The command pager on and pager off will toggle the page-at-a-time display mode. Use the help command to list all commands or help pager to view the syntax of the pager command. e.g. to list the whole menu…

pager on
cat (md)0x3000+0xA0

E2B start-up

E2B v.1.78+ You can press the SPACEBAR as soon as E2B starts to load, and it will pause at certain points during start-up. Press the SPACEBAR twice quickly to proceed to the next point (this can be done when sub-menus are enumerated too). At the last point, you will be prompted to press ENTER and then the Main Menu will load.

This allows you to examine any E2B messages and check which files are being enumerated by E2B.

Single-Stepping

If you press the [INSERT] key just as grub4dos starts to boot, it will enter Single-Step mode. You then need to press [ENTER] key to execute one line at a time. 

You may need to hold down the ENTER key when multiple similar lines are executed until the E2B (blue) batch fie code is reached.

Once E2B code is executed, it may alter the debug mode so that the single-step mode no longer operates. However, you should see the .g4b batch files execute and the menu.lst code should single-step or be displayed one screen ‘page’ at a time. You will also see Warning and Error messages that are not normally displayed by E2B – these may help if you have a problem with a specific system or BIOS.

Note that all iftitle lines in a menu are executed first and the result of the ‘test’ is displayed as ‘rp’ in the debug text – if rp=0 then the iftitle menu will not be shown (false), if rp is not 0 then the iftitle menu will be shown to the user (true).

Batch files

Most batch files in E2B have a .g4b file extension (by convention). These can be run from the grub4dos console too.

All grub4dos batch files must start with !BAT on the first line.

Note that some batch files require extra command line parameters – e.g.  to clear all environment variables (using set *), run a batch file to count the number of .iso files in \_ISO\MAINMENU and view the variables returned, use:

set *
/_ISO/e2b/grub/LstFExt.g4b /_ISO/MAINMENU .iso
set

Tip: To display all variables beginning with s, for example, you can use the set s command (case sensitive – set S lists variables beginning with capital S).

Many of my batch files output more information if you set the DD variable before running them:

set DD=1

Debug

To debug and single-step through a .g4b batch file, use the command line   debug batchfile  param1  param2 param3 – for instance…

debug /_ISO/e2b/grub/QRUN.g4b /_ISO/MAINMENU/linux.iso

or, because E2B sets the default batch file extension as .g4b and the default path as \_ISO\e2b\grub, we can use…

debug qrun /_ISO/MAINMENU/linux.iso

Press ENTER to execute the next line of code in the batch file.

Editing E2B files

E2B files are just plain text files (some are in UTF-8 format so be careful if using an editor such as NotePad++ which may lose any special UTF-8 characters!) – I suggest Windows NotePad for editing E2B files.

Many E2B batch files alter the debug level using the debug command. Useful values are:

• debug 0  = minimum help\warning\error messages = debug off
• debug 1 = normal help\warning\error messages = debug normal
• debug 2 = extra verbose help\warning\error messages  = debug on
• debug 3 = extra messages
• debug -1 = similar to 0 but no timeout countdown is displayed on pause –wait=x commands.
• debug msg=n  (n=0=no messages, 1=normal messages to stdout, 2=messages and error messages to stdout, 3=verbose) – e.g. debug msg=3 (0.4.6a only)

Warning: Some E2B files may set debug 1 because the grub4dos messages are required to be output. Reducing the debug level number to 0 may therefore cause errors or unwanted side-effects.

A useful technique for debugging menus or batch files is to add lots of pause statements and you can display variables within special characters so you can see any spaces – for instance, to display the values of the variables fred and doris, you can add the line:

pause fred=*%fred%* doris=*%doris%*

If fred and doris are not defined, you will see  fred=** doris=**, if fred contains the string ‘here is a space ‘ then you will see fred=*here is a space * doris=**   Note that the space at the end of the string in fred can clearly be seen, which is why we add the * characters. You need to be careful of  invisible spaces because code such as if “%fred%”==”1” will not work if fred contains the number 1 followed by a space!

For lots more information on grub4dos see my grub4dos eBook

For super-geeks!

Most of the grub4dos batch files (*.g4b) I have written will print debug information if the DD variable is set to 1, e.g.

set DD=1
/_ISO/e2b/grub/LstFExt.g4b  /_ISO/MAINMENU  .iso 

If you need to debug the \_ISO\e2b\grub\menu.lst file then

1. Delete or rename \menu.lst so it is not found by grub4dos

2. Add

!BAT

as the top line in the file \_ISO\e2b\grub\menu.lst

3. Boot to grub4dos and in the command console type (to get a bigger display)…

graphicsmode -1 1024
debug /_ISO/e2b/grub/menu.lst

to debug the main E2B batch file.

E2B grub4dos batch files

If you are looking at some of the code in the E2B batch files, you may think that in some cases, there are ‘better’ ways of coding it by using some of the newer features in the more recent versions of grub4dos.

However, I have deliberately used ‘old’ ways (and often more complicated ways) because this allows me to test E2B using older versions of grub4dos where I have to use a work-around to avoid some bugs which were fixed in later versions.

It is sometimes the case that a new version of grub4dos will introduce a subtle bug which stops a certain feature of E2B from working (e.g. booting XP ISOs or modifying the menu). In this case, it is useful to be able to simply use older versions of grub4dos to find out in which version a bug was introduced.

You must also take into account that the E2B code has been tested on FAT16, FAT32, NTFS, exFAT and ext2/3/4 USB drives, so you must test any of your own code on each of these filesystems to check that your new code still works correctly in all cases.