Linux Remote-Boot mini-HOWTO: Configuring Remote-Boot Workstations with Linux, DOS, Windows 95/98 and Windows NT: Remote-Boot Tools Reference Manual

Next Previous Contents

## 5. Remote-Boot Tools Reference Manual

This section provides detailled informations on the use of the tools we developped at the CUI, University of Geneva for this remote-boot configuration.

## 5.1 BpBatch, MrBatch and MrZip

These three names stand for three variants of the same program, with the following characteristics:

- `BpBatch` is a special program that can be started from the BootProm before the operating system is loaded. It is made of two parts: `bpbatch.P`, the dynamic loader, and `bpbatch.ovl`, the program itself. `BpBatch` has full disk I/O capabilities through our own implementation of FAT16, FAT32 and Ext2fs, as well as remote network I/O capabilities through the BootProm TFTP API. `BpBatch` was compiled under DOS using Borland C 5.0 and Turbo Assembler 3.2.
- `MrBatch` is the DOS/Linux version of `BpBatch`. All commands recognized by `BpBatch` are recognized by `MrBatch` and vice versa. This is very usefull if you want to test your batch scripts from a DOS/Linux session. Under DOS, `MrBatch` emulates remote I/O by OS-based file access if the bootprom is not available. Under Linux, the bootprom cannot be seen anymore but `MrBatch` can emulate it using Linux IP support, or use OS-based file access. `MrBatch` was compiled under Linux using GCC 2.7.2.1 and under DOS using Borland C 5.0 and Turbo Assembler 3.2.
- `MrZip` is an interpreter that recognizes a superset of `MrBatch` language, and that serves to build disk images. In `MrZip`, the limited remote file I/O is replaced by a full-featured OS-based file access. `MrZip` does not include VESA support. `MrZip` was compiled under Linux using GCC 2.7.2.1 and under DOS using Borland C 5.0 and Turbo Assembler 3.2.

### Command Line Arguments

All programs accept the same syntax of arguments. `MrBatch` and `MrZip` take them from the command line, while `BpBatch` look for them in the BOOTP option 155 (decimal). Here is the syntax of the arguments:

            [-x] [-l] [-b] [-v] [-w] [-i] [script-basename]

where:

- `-x` disable the use of extended memory
- `-l` disable the use of ISO-latin-8859-1 as default character set
- `-b` cancel the bootprom detection (which cause a floppy seek under DOS)
- `-v` cancel the VESA detection (which cause a switch to full screen under Windows 95)
- `-w` enable direct disk write access (disabled by default under DOS and Linux)
- `-i` enable interactive mode even if a script name is provided

The `script-basename` is optional. If provided, `MrBatch` and `BpBatch` load the file with the `.bpb` extension, and `MrZip` loads the file with the `.mrz` extension. If not provided, `MrBatch` and `MrZip` run in interactive mode while `BpBatch` loads the file with the same basename as the BOOTP Boot file and a `.bpb` extension.

### Syntax rules

The following rules apply when `BpBatch` parses an input line.

- Commands are parsed line by line. Lines are separated by CR and/or LF.
- The maximal line length is currently 255 characters.
- Keywords and variable names are case-insensitive.
- " is interpreted as the special string delimiter
- When ${variable} or $variable is encountred, it is substituted by the value of the variable, or by an empty string if the variable is undefined. The substitution also occurs within a string. Moreover, the resulting substituted value must be explicitely enclosed between double quotes if used as a string value (ie. one should merely speak of macro expansion than of a variables).
- - `\a` is substituted by the audible-bell character (ASCII 7)
  - `\b` is substituted by the backspace character (ASCII 8)
  - `\n` is substituted by the newline character (ASCII 10)
  - `\r` is substituted by the return character (ASCII 13)
  - `\t` is substituted by the tabulation character (ASCII 9)
  - `\v` is substituted by the vertical-tab character (ASCII ...)
  - `\nnn` where n is a 3-digit octal number between 000 and 377 is substituted by the character with ascii code specified
  - `\X` where X is any other character not listed above is substituted by X itself. In particular,
    - `\"` is substituted by a regular double-quote (not a string-delimiter)
    - `\$` is substituted by a regular dollar sign (not variable substitution)
    - `\\` is substituted by a regular backslash (not a special character)
- The character "end of string" (ASCII code 0) CANNOT be used anywhere as it is used internally as end-of-string delimiter
- The character "floating diaeresis" (ASCII code dec 249, hex F9, octal 371) CANNOT be used in any string as it is used internally as string delimiter in the input parsing routine.
- The character "block space" (ASCII code dec 255, hex FF, octal 377) CANNOT be used in any variable value as it is used internally as variable delimiter.

Empty lines are ignored. Lines starting with a sharp (`#`) are treated as comments and are not interpreted. Lines starting with a column (`:`) are treated as labels and are not interpreted.

String expressions

  Strings are delimited by opening and closing double-quotes:

              "Hello world"

  To include double-quotes within a string, quote them using a backslash:

              "I said: \"Hello world\""

  Strings can be postfixed with a few operators.
  - The character substitution operator:

                "Hello world"/o=u/      ==      "Hellu wurld"
                "198.76.54.32"/.= /     ==      "198 76 54 32"

  - The word selection operator (zero-based):

                "Hello world"{0}        ==      "Hello"
                "198 76 54 32"{1-3}     ==      "76 54 32"

  - The substring selection operator (zero-based):

                "Hello world"[4]        ==      "o"
                "Hello world"[4-7]      ==      "o wo"

  Operators can be chained by postfixing one after the other. For informations about the string length and word count operators, see under "Numerical expressions".

Numerical expressions

  Numerical expressions work on 32-bits integer numbers (from -2,147,483,646 to 2,147,483,647). Hexadecimal octal and binary numbers are not understood. Whenever a numerical expression is expected, the following are recognized:

  - A positive or negative integer number
  - An expression in the form (expr1 op expr2) where op can be either +, -, * (multiply), / (divide) or `%` (modulo) and `expr` is a numerical expression. Note that EACH operation MUST be enclosed between parenthesis :

                ((3 * 5)+2)             == 17

  - The string-length operator (@), followed by a string :

                @"Hello world"          == 11

  - The word-count operator (#) followed by a string :

                #"Hello world"          == 2

Durations

  A few commands expect durations as arguments. Durations are measured in seconds, with a precision of up to a tenth of second:

              Delay 3                 waits for 3 seconds
              Delay 0.3               waits for 3/10 seconds

Colors

  Whenever a color is expected, you can either use the numeric value of the color or its symbolic name (case-insensitive). The following colors are recognized

              Black           0
              Blue            1
              Green           2
              Cyan            3
              Red             4
              Magenta         5
              Brown           6
              LightGray       7
              DarkGray        8
              LightBlue       9
              LightGreen     10
              LightCyan      11
              LightRed       12
              LightMagenta   13
              Yellow         14
              White          15

File References

  File names are strings. They must therefore always be enclosed between double-quotes. File names are case-sensitive on case-sensitive filesystems, case-insensitive on case-insensitive filesystems. Slash and backslash can be freely used one in place of the other. Do not forget to double backslash since a single backslash is an escape character.

  There are two kinds of file references:

  - Direct disk files
  - Foreign files

  Direct disk files are referenced using the following notation:

              "{disk:partition}/absolute/filename"

  The disk number can be omitted and defaults to zero. For instance, `"{:1}/usr/bin"` points to `/usr/bin` assuming there is such a directory on the first partition. Direct file I/O is solely based on our own file access routines (we do not use the operating system).

  There are two special partitions. Partition zero corresponds to the hard disk master boot record (MBR) and has a pseudo file-system which let you access the boot code. Partition minus-one (-1) corresponds to the cache filesystem (see below).

  Under BpBatch/MrBatch, foreign files correspond to remote files on the TFTP server when the BootProm is available:

              "help.bpb"           is the file help.bpb in the /tftpboot directory
              "gifs/MyImage.gif"   is a file in /tftpboot/gifs

  Other TFTP servers can be referenced :

              "198.76.54.32:help.bpb"

  If the other server is behind a gateway :

              "198.70.0.1/198.76.54.31:help.bpb"

  One can also specify a specific port for the TFTP connection :

              "198.76.54.32@89:getpasswd/smith"

  There can be only one open remote file at a time. If the BootProm is not available, remote files are emulated using the operating system file I/O, but the same restriction apply.

  Under MrZip, foreign files correspond to files as seen by the operating system. There is no limitation, and foreign files can be used wherever direct disk files can be. Foreign files are usually faster than direct disk files, because the operating system has more buffers. Foreign files can refer to network files if supported by the operating system.

              "C:\\autoexec.bat"
              "C:/config.sys"
              "/mnt/net/usr"

### The Cache Filesystem

In order to reduce network load and to fasten the boot process, disk archives, linux kernels and possibly other files are cached on the hard disk. This disk cache is located at the end of the hard disk, between the last cylinder allocated in the partition table and the last physical cylinder of the disk (out of any allocated partition). There MUST be room between the last partition and the end of the disk if you want the cache filesystem to work. The cache filesystem MUST work if you want to restore a disk image.

The disk cache is organised in a volatile, CRC-validated filesystem : Each directory entry and each 32 KB data block is validated by a 32-bits CRC. Whenever a directory entry or a data block unexpectedly changes, the file is automatically removed from the cache and downloaded again upon the next request.

You can freely access the cache filesystem from within BpBatch, MrBatch and MrZip using direct disk access on the special partition `"{:-1}"`. To see the content of the cache, just type :

            logdir "{:-1}"

If the cache ever gets corrupted and is not automatically cleaned (which should never occurs), you can either type :

            clean -1

(in interactive mode) or hold both shifts down when BpBatch access the cache for the first time.

### Special variables

Some variable are initially set and/or have special meanings. Some of them exist within all programs, other are only available under MrZip and other are only available when a BOOTP/DHCP reply has been received.

General variables

  - `$Program` is set to "BpBatch" within BpBatch, "MrBatch" within MrBatch and "MrZip" within MrZip
  - `$Basename` is set to the basename of the script on which the batch interpreter was started
  - `$HelpFile` is the name of the file loaded when `Help` is invoked. Default: `"${Basename}.hlp"`
  - `$BOOTP-...` are variables set from the BOOTP/DHCP reply (see the paragraph on BOOTP/DHCP variables for more details)
  - `$DHCP-...` are variables set from the DHCP reply (see the paragraph on BOOTP/DHCP variables for more details)
  - `$Disks` is set to the space-separated list of sizes for each disk. That means, `#"$Disks"` represent the number of disks and `"$Disks"{0}` is the size of the first disk
  - `$Keypressed` is set to the next ready-to-read key available in the keyboard buffer (if available)
  - `$LBA` controls the use of LBA to access disks > 2Gb. Default: "ON"
  - `$FDA` controls the use of fast disk access (write accross cylinders). Default: "ON"
  - `$VESA` controls the use of VESA graphics. Default: "ON" if available
  - `$VESA-Modes` gives the list of all available VESA modes. The first entry of the list is the default mode, which is used when no parameter is given to InitGraph. Note: if VESA="OFF", this variable is blank
  - `$APM` is set to "ON" if your computer supports Avanced Power Management. If $APM is "ON", you can use the command PowerOff to turn your computer off. Default: depends on your hardware
  - `$Trace` controls the display of each command before execution. It also controls the display of file names when creating new archives. Default: "OFF"
  - `$AutoShowLog` controls the automatic switch to the text log whenever the ESC key is pressed. Default: "ON"
  - `$PauseLog` controls the pause between each page of log when the log is visible. Default: "ON"
  - `$CacheDisk` is set to the disk used for caching remote files. Default: empty == 0, the first hard disk
  - `$CacheAlways` controls the automatic caching of remote files copied, patched or drawn as GIF. Default: "OFF"
  - `$CacheNever` prevents any file from being cached. Turn this variable on for diskless Linux boot. Default: "OFF"
  - `$CacheReserve` controls the preventive allocation of 25 percent more space than necessary in the cache partition, to let the files grow. Turn this variable off if you are short of disk space. Default: "ON"
  - `$ExtMemory` controls the use of Extended Memory (or XMS). Once deactivated, extended memory cannot be reactivated. Default: "ON" if available
  - `$IsoLatin` controls the interpretation of upper ASCII codes in included and patched files. The IsoLatin settings are processed at the time the file is loaded, not at the time the file is processed. Default: "ON"
  - `$ProgressX` and `$ProgressY` controls the position of the progress window displayed in VESA graphics during archive download and decompression. Default: 200 200
  - `$EXT2-Backup` controls the update of superblock backups in Linux ext2 filesystem. Superblock backups take a few seconds to do and are never used by current kernels (only by e2fsck).
  - `$Security-Gateway` controls the gateway-server used for user authentication. Our special authentication gateway must be running on the target computer. Default: `"${BOOTP-Server-IP}@89"` (ie. the TFTP server, on port 89)
  - `$Security-Check` contains the answer of the security server for the last check performed, either PASSED or FAILED. Default: "FAILED"
  - `$Security-Passwd, $HelpTopic, $OnExit, $OnKey-...` are used internally.

  See also BOOTP variables and MrZip-specific variables.

MrZip-specific variables

  The following variables are only used within MrZip.

  - `$TempPath` controls the directory where temporary files will be stored. Default: <empty> == current directory
  - `$DumpFormat` controls the way archives are dumped to the log when requested. It is a string containing
    - "h"/"H" to display the archive header
    - "b"/"B" to summarize/dump boot sectors
    - "s"/"S" to display a short/long allocation summary
    - "d"/"D" to display a short/long directory listing
    - "f"/"F" to summarize/dump files
    Default: "hbD"
  - `$FragmentSize` controls the size of archive pieces. If you do not use InCom's extended TFTP server, you should set this to "30 MB". Default: "87 MB"
  - `$SourceArchive, $DestArchive, $Filter...` are used internally.

BOOTP variables

  The following BOOTP-... and DHCP-... variables are recognized, as long as a BOOTP/DHCP reply has been received (TCP/IP Bootprom must be reported as detected):

              $BOOTP-Client-ID
              $BOOTP-Your-IP
              $BOOTP-Server-IP
              $BOOTP-Gateway-IP
              $BOOTP-Bootfile
              $BOOTP-Server-Name
              $BOOTP-Subnet-Mask
              $BOOTP-Time-Offset
              $BOOTP-Routers
              $BOOTP-Time-Servers
              $BOOTP-Name-Servers
              $BOOTP-Domain-name-Servers
              $BOOTP-BOOTP-Log-Servers
              $BOOTP-Cookie-Servers
              $BOOTP-Lpr-Servers
              $BOOTP-Impress-Servers
              $BOOTP-Resource-Location-Servers
              $BOOTP-Host-Name
              $BOOTP-Boot-Size
              $BOOTP-Merit-Dump
              $BOOTP-Domain-Name
              $BOOTP-Swap-Servers
              $BOOTP-Root-Path
              $BOOTP-Extensions-Path
              $BOOTP-IP-Forwarding
              $BOOTP-Interface-MTU
              $BOOTP-All-Subnets-Are-Local
              $BOOTP-Broadcast-Address
              $BOOTP-NIS-Domain
              $BOOTP-NIS-Servers
              $BOOTP-NTP-Servers
              $BOOTP-Font-Servers
              $BOOTP-X-Display-Manager
              $DHCP-IP-Address-Lease-Time
              $DHCP-Message-Type
              $DHCP-Server-Identifier
              $DHCP-Message
              $DHCP-Renewal-Time
              $DHCP-Rebinding-Time
              $BOOTP-NIS+-Domain
              $BOOTP-NIS+-Servers
              $BOOTP-Server-Name
              $BOOTP-Bootfile
              $BOOTP-Mobile-IP-Agent
              $BOOTP-SMTP-Servers
              $BOOTP-POP3-Servers
              $BOOTP-NNTP-Servers
              $BOOTP-WWW-Servers
              $BOOTP-Finger-Servers
              $BOOTP-IRC-Servers
              $BOOTP-StreetTalk-Servers
              $BOOTP-STDA-Servers

  Other BOOTP/DHCP parameters can be used under the name

              $BOOTP-Option-n

  where n is the decimal representation of the BOOTP option number.

  Do not mix-up `BOOTP-Gateway-IP`, which is the gateway to use for TFTP and should be 0.0.0.0 if the TFTP server is in the same subnet, and `BOOTP-Routers`, which contains the default IP gateway(s). The TCP/IP Bootprom sometimes seems to set the value of `BOOTP-Gateway-IP` from the value in `BOOTP-Routers`, causing each TFTP ack packet to be sent to the router first. To avoid such behaviour, if your TFTP server is in the same subnet as the client, force `BOOTP-Gateway-IP` to `0.0.0.0` (thanks to Maciek Uhlig for having pointed out this problem).

### Monitoring commands

This section lists commands for monitoring the system state. Optional arguments are listed between parenthesis (I would have prefered square brackets, but LaTeX do not like them at this place...)

Interact

  Show the log and turn to interactive mode until QUIT or EXIT is entered. Type HideLog before quitting if you want to avoid disturbing log messages during batch execution.

Help (topic)

  Load the on-line help file (`bpbatch.hlp`) and display the description of the given topic. If no topic is provided, or if the topic is unknown, display the help index.

Log "text"

  Display the string on the log. No return/linefeed is implicitely added.

Echo "text"

  Display the string on the log and go to the next line. Equivalent to

              Log "text\r\n".

LogVars ("pattern")

  Log (ie. display on the log) all variables matching the given pattern. The pattern can contain wildcards (? and *).

      Example: LogVars "BOOTP-*"              list all BootP variables

LogDir "path/pattern"

  Log (ie. display on the log) all files from the given path that match the pattern. The pattern can contain wildcards (? and *).

      Example: LogDir "/usr/g*p"              list files names like g...p

LogTree "path"

  Log the directory tree starting with the given path as root.

LogFile "filename"

  Log the content of the file. The file must be no more than 64 KB big.

ShowLog

  Make the log visible if it was hidden. Automatically performed when ESC is pressed with "$AutoShowLog" == "ON" and when entering interactive mode.

HideLog

  Prevent log messages to appear on the screen. Default state when BpBatch, MrBatch and MrZip are started on a script file.

CaptureLog

  Record all log output to a 64 KB buffer until EndCapture is issued. Wrap around buffer if the log output is more than 64 KB big. This command can be used to create a text file with an arbitrary content. The EndCapture MUST occurs within the same batch file.

EndCapture ("filename")

  End up the capture of the log. If a filename is given, store the captured text to a file. Otherwise, discard it.

Beep

  Make a sound. This command is equivalent to Echo "\007".

### Control commands

This section lists commands that control the batch execution. Optional arguments are listed between parenthesis.

Include "filename"

  Load the given file and start up the parser on it. Go back to the current point when the include file processing is done. The interpretation of characters above ASCII 127 within the include file depends on the value of $IsoLatin at the time the file is included.

OnExit command

  Setup an exit-handler that will automatically be evaluated at the end of current batch file.

Goto label

  Move the execution cursor to the given label (ie. the line starting with :label)

Eval "command"

  Perform all substitutions on the "command" and run the parser on it.

If ...

        If (not) <expr1> (==|!=|<|>|>=|<=|=>|=<|<>) <expr2> <command>
        If (not) (ci) "str1" (==|!=|<|>|>=|<=|=>|=<|<>) "str2" <command>
        If (not) (ci) "str1" Match-Expr "pattern" <command>
        If (not) (ci) "str1" Match-Passwd "unix-passwd" <command>
        If (not) (ci) "str1" in "wordlist" <command>
        If (not) (ci) "str1" in-file "filename" <command>
        If (not) exist "filename" <command>
        If (not) valid <disk>:<partition> <command>

  These commands execute command; if the test succeeds. The 1st form compares two numerical expressions. The 2nd form compares two strings, optionally case-insensitive. The 3rd form tests if "str1" matches the given pattern (wildcards allowed). The 4th form tests if the clear password "str1" matches the Unix-crypted password. The 5th form tests if "str1" is included in the word list. The 6th form tests if "str1" is included in the word file. The 7th form tests if the given file exists. The 8th form tests if the given partition is valid (i.e. formatted). This form is only supported by BpBatch versions after February 1999.

Set ...

        Set variable = "string-value"
        Set variable = <expr>

  Setup a value for the given variable. If the given value is a numerical expresison, it will be implicitely converted to a string. A variable can be used anywhere by refering it as $variable or ${variable}. If the resulting reference is to be interpreted as a string, it should be enclosed between double quotes: "$variable" or "${variable}".

Delay duration

  Waits until the specified duration (expressed in seconds) expired. See also the paragraph on the format of durations.

GetTime variable, GetDate variable

  Get the CMOS time and store it into variablein the form HH:MM:SS. Get the CMOS date and store it into variablein the form YY/MM/DD. This can be used to customize the behavior of your boot scripts depending on the time of day or on the date.

SetTime "HH:MM:SS", SetDate "YY/MM/DD"

  Set the computer CMOS time or date to the given value. If you have a security gateway (our special TFTP server) running, you can automatically adjust the CMOS time and date of the client computers at each boot by evaluating the following command:

              include "$Security-Gateway:gettime"

  If you want to understand what this command does, just type:

              logfile "$Security-Gateway:gettime"

Poweroff

  Turn off the computer. This command only works if the computer is Advanced Power Management (APM) compatible.

### Keyboard-related commands

This section lists commands that let you monitor the keyboard input. Optional arguments are listed between parenthesis. See also under National Language Support.

GetKey (variable)

  Indefinitely wait until a key is pressed and store it in the variable.

WaitForKey duration (command)

  Wait until a key is pressed for no more than duration seconds. If no key has been pressed after the given time, evaluate the command. Otherwise, leave the key in the keyboard buffer. See also the paragraph on the format of durations.

Input (variable (max-length))

  Read a return-terminated string from the keyboard and store the result string in variable (without the terminating return). If max-length is given, do not allow the user to enter more than this number of characters.

  See also `GetPasswd` under Security-related commands.

OnKey "c" command

  Setup a key handler that will automatically evaluate the given command when the key "c" is pressed (except is explicitely waited by a GetChar or an Input command). If the string `"default"` is used instead of a single character, the command is executed if any other key is pressed.

### Text output commands

This section lists commands used to perform regular text output. All these commands can be used in graphic mode also, with the same behaviour (except that text mode provides 80x25 characters while graphic mode provides 100x37, because graphic mode characters are of size 8x16). Optional arguments are listed between parenthesis. See also under National Language Support.

Print "text"/expr

  Print the specified string/expression at current cursor position and using current text attributes, then move the cursor. Add "\r\n" to the end of the string to go to the next line.

TextAttr fg-color bg-color

  Setup the text attributes. One can also put a single numeric value representing both colors and defined as 16*bg-color+fg-color.

  If you need more fantasy, you can use `LoadFont`. See under National Language Support.

At line,col (command)

  Move the cursor position to the specified position and evaluate the command if provided.

      Example: At 10,20 Print "Gnats and rats !"

Clear (color (pattern-char (top,left,bottom,right)))

  Fill the given text area with the given pattern-char (either a string or the decimal ascii code). The area defaults to the full screen, the pattern char defaults to the full block (ASCII dec 219) and the color defaults to black (clear screen). Move the cursor to the upper left corner of the cleared area.

BpMenu backward compatibility commands

        .ATT (<attribute>)
        .CLS (<attribute>)
        .DEF <key> (<timeout_val>)
        .KEY <key> <filename>
        .POS ((<x>) <y>)
        .PWD <key> <cpasswd>
        .WLN (<text>)
        .WRT <text>

  See InCom's manual for more infos. We wrote some time ago a program program for editing menu files using this syntax, but it is preferable to make your menus using the new explicit syntax. Note that the .PWD command is not implemented because we do not now the password crypting algorithm used by InCom GmbH.

### Graphics output commands

This section lists commands used to perform graphic-mode output. For the functions listed in this section, coordinates are given in pixels. You can also use all text output commands (see above) in graphic mode. Optional arguments are listed between parenthesis.

Note that the graphic mode is automatically turned on whenever a graphic command is used, unless the variable `VESA` is set to `"OFF"`.

InitGraph ("mode")

  Turn on VESA graphics. The origin is on the upper-left corner of the screen (0 0). VESA graphics may hang some computers under Windows 95. Run MrBatch with the -v option to avoid such problems.

  You can request a specific video mode if you use the parameter "mode" This parameter is optional: if you do not specify any value, the video mode will be taken from the first field of the VESA-Modes variable.

  Valid modes are :

  - 640x480 => 640 by 480 pixels, 256 colors
  - 800x600 => 800 by 600 pixels, 256 colors (default mode)
  - 1024x768 => 1024 by 768 pixels, 256 colors
  - 1280x1024 => 1280 by 1024 pixels, 256 colors

  The VESA-Modes variable lists the video modes supported by your hardware.

  Example: `InitGraph "640x480"`

CloseGraph

  Close VESA graphic mode and go back to text mode.

DrawBar x-pos y-pos width height color

  VESA graphics. Draw a filled bar of the given size and colors.

DrawWindow x-pos y-pos width height (bg-color (bar-color)) ("title" (title-color))

  VESA graphics. Draw a window of the given size and colors. The background color defaults to LightGray and the title-bar color defaults to Blue. If you include a title string and a color, this text will be displayed in the title bar.

Drawtext x-pos y-pos "text" (fg-color)

  VESA graphics. Draw the text string at the given position with a transparent background. The color defaults to text foreground color.

DrawGif "gif-filename" (x-pos y-pos (color-strategy))

  VESA graphics. Load the given GIF-87a file and draw it on the screen. The file can be interlaced, but must be in GIF-87a (not GIF-89a). The image size should fit in the selected video mode. You cannot load a 1024x768 GIF file when you selected a 640x480 mode. The GIF position defaults to the top left corner of the screen (0 0).

  The color-strategy defines the allocation of colors in the palette when more than 256 colors are needed (for instance when two 256 colors GIF files are displayed simultaneously):

  - `Best-Colors` use best possible colors for the most recent GIF
  - `Spare-Colors` try to avoid allocating colors, change existing colors
  - `Share-Colors` try to avoid allocating colors, use existing colors
  - `Reuse-Colors` allocate no new color, only use existing colors
  The default strategy is `Best-Colors`.

### Security-related commands

This section lists commands that help you authenticate a user. Optional arguments are listed between parenthesis.

Some of these functions cooperate with a Security gateway, that you should first install. See the section on Special TFTP servers for more infos.

GetPasswd (variable (max-length))

  Same as Input, but echo stars instead of the typed characters.

Crypt "text" "salt" variable

  Apply the Unix crypt function to the given 8-chars text and store the resulting crypted string into variable. The "salt" is usually a two-character string that will be found as the first two characters of the crypted string.

  Note that Unix crypt is a one-way function. It is not possible to decode the crypted string. One can only try to crypt another string with the same salt and compre the resulting crypted string.

DESCrypt "text" "key" variable

  Crypt the given text using the given 8-chars key and store the result as an hexadecimal string in variable.

DESDecrypt "hexcode" "key" variable

  Decrypt the given hexadecimal string using the given 8-chars key and store the result in variable.

MD5 "text" variable

  Compute the MD5 checksum of the given text and store it as an hexadecimal string in variable. Can be used as an alternative to the Unix crypt function to check for passwords bigger than 8 characters.

CheckUser "user" "password" "domain"

  Connect to the $Security-Gateway and check if the given user exist in the given radius domain and uses the specified password. If the domain is `"Unix"`, use the Unix user/password definition on the security gateway. For any other domain, use the security gateway domain definition file to determine the real Radius or NT domain to check.

  Set the value of $Security-Check to "PASSED" or "FAILED". The password do not transit in clear on the network.

### Disk-related commands

This section lists commands for preparing the hard-disk. Optional arguments are listed between parenthesis.

GetPartitions variable (disk)

  Read the partition table(s) for the given disk and store it as a string into the given variable. The result string is a space-separated list of Type:Size, where

  - Type is FAT16, EXT, BIGDOS, NTFS, FAT32, FAT32-LBA, BIGDOS-LBA, EXT-LBA, LINUX-SWAP, LINUX-EXT2 or the decimal filesystem id for unknown types.
  - Size is the size of the partition in megabytes.
  See SetPartitions for more informations about partitions.

SetPartitions "partitions" (disk)

  Setup the partition table(s) to the content of the string. The format used is the same that for GetPartitions. This command also reset all boot flags (hint: use SetBootPart).

  The main partition table in the master boot record (MBR) has only four entries. Moreover, DOS and Windows accept only ONE FAT partition (called the Primary partition, C:) in the main partition table. Any supplemental FAT partition should be nested in an extended partition (and is thus called a Logical partition). If we give numbers 1-4 to the partitions described in the MBR partition table and numbers 5-8 to the partitions described in the first extended partition, the definition of two FAT partitions would work by defining partition 1 as FAT, partition 2 as EXT and partition 5 as FAT. Partitions 3,4,6,7 and 8 should be marked as UNUSED. The same scheme can be used recursively to define more than two FAT partitions: nesting another extended partition in partition 6 and adding a logical FAT partition in partition 9.

  In the most strict interpretation of DOS specifications, that means that entries 3 and 4 of the partition tables are never used. In practice, some versions of DOS and some other OS are able to use more than two partitions per partition table, but there is no clear rule. On this side, BpBatch is rather flexible in its interpretation of partition tables, it can often understands things that OSes cannot.

  One universal rule is that there should never be more than one extended partition per partition table, otherwise the partition numbering scheme breaks down.

  If you want to try funny configurations, make your own experiments, but don't complain if the OS does not recognize your partitions. The only way it is guarantee to work is to use the primary partition to store the OS boot partition, and to nest all other partitions, one at a time, in extended partitions.

  Example of extended partitions :

              SetPartitions "BIGDOS:100 EXT:400 EMPTY EMPTY BIGDOS:400"

GetBootPart variable (disk)

  Get the partition number with the boot flag turned on (DOS says: the activated primary partition) and store it to the variable. The first partition is numbered 1. If no partitions has the boot flag turned on, answers zero.

SetBootPart partition (disk)

  Set the boot flag to the given partition. The boot flag let the master boot record (MBR) choose which partition to boot on. The first partition is numbered 1.

Blank partition (disk)

  Fill the given partitions with zeroes. Can take quite a lot of time for big partitions. Do not format the partition for any operating system. See also `Clean`.

Clean partitions (disk) ("label")

  Fast-format the given partition(s) according to the type declared in the partition table. If a label is given and the filesystem supports it, setup the partition label. For a paranoiac full format, call `Blank` on the partition first.

  Clean is supported for (FAT16) BIGDOS, FAT32, EXT, LINUX-EXT2 and LINUX-SWAP partitions. To clean the master boot record (MBR), use `Clean 0`.

  Clean should be used on data partitions and on MBR/EXT partitions. It is totally useless to clean a partition before unzipping a filesystem on it using `FullUnzip`.

FullUnzip "full-archive" partition (disk)

  Decompress a full disk archive to the given partition, overwriting any existing file (clean-up on the fly).

  FullUnzip is supported for (FAT16) BIGDOS, FAT32 and LINUX-EXT2.

  This commands turn on VESA graphics to display a progress banner, unless `VESA` has been turned `OFF`.

IncrUnzip "incr-archive" "destpath"

  Decompress an incremental disk archive to the given path. Files in the archive replace those with the same name on the target path, but other files are not deleted.

  IncrUnzip is supported for (FAT16) BIGDOS, FAT32 and LINUX-EXT2. This command is far less efficient than FullUnzip since the existing filesystem structure must be preserved. However, it avoids multiplying the number of different disk images by storing the differences only.

FileUnzip "source-filename" "dest-filename"

  Uncompress a file previously compressed with `MrZip` FileZip command. The file is validated by a 32-bits CRC.

Copy "source-filename" "dest-filename"

  Copy the source file to the destinaton file, byte-to-byte. Can be used after a FullUnzip for instance to update configuration files from the server without rebuilding the image. Better to use `FileUnzip` for big and easy-to-compress files.

Append "src-filename-1" "src-filename-2" "dest-filename"

  Copy the first, then the second file to the destination file, byte-to-byte. Can be used on arbitrary large files. The destination file cannot be one of the two source files.

Patch "source-filename" "dest-filename" ("prefix" ("postfix"))

  Read the source file and perform variable substitution before writing it to the destination file. The interpretation of characters above ASCII 127 depends on the value of $IsoLatin.

  By default, variables are recognized when prefixed by "${" and postfixed by "}". This can be changed to any other non-empty string. remember that if you want to use a dollar sign within the prefix or suffix, you must escape it or it will get macro-evaluated. For instance, if you want to explicitely use the default prefix and postfix, use:

              Patch "source-file" "dest-file" "\${" "}"

MkDir "path"

  Recursively create directories from the root to the given full path. If the path already exists, this command has no effect.

Delete "filename", Del "filaname"

  Remove the given file. The file must exist.

DelTree "path"

  Recursively remove all files and directories under the given path, and remove the directory itself.

### Boot commands

This section lists commands for continuing the boot process. Optional arguments are listed between parenthesis.

HideBootProm

  Restore the memory and the interrupt vectors allocated by the bootprom. All attempts to make TFTP transfers will fail after calling this command. It is usually a good idea to call this command before HdBoot, or you might run short of memory under DOS/Windows. This command is implicitely called by FloppyBoot.

  Note that although this function restore all vectors "officially" rerouted by the BootProm, it does not seems to restore everything. But it works well enough for DOS and Windows.

LoadRamDisk "ramdisk-filename"

  Load a floppy disk image into the extended memory and redirect the BIOS Disk Services to make floppy disk calls use this image instead. This command implicitely calls `HideBootProm`. Call `FloppyBoot` to boot on the ramdisk you just loaded.

  This kind of ramdisk may not be as robust as what you get when you use the TFTPBoot command. The only advantage is that it only steals a few hundred bytes of conventional memory instead of the >64 KB reserved by the TCP/IP BootPROM. Warning, nothing secures the extended memory in which the ramdisk resides. There is no way to uninstall such a ramdisk.

LoadZRamDisk "ramdisk-filename"

  Do the same as `LoadRamDisk`, but for an image that has been compressed using `MrZip` FileZip command. Compressed ramdisks are protected against data corruption (and uncomplete download) by a byte count and a 32-bits CRC.

TFTPBoot "remote-bootfile"

  Chain to another boot file (for instance a floppy image made with InCom's BpShell program). See the file referencing conventions for accessing a file on another TFTP server.

FloppyBoot

  Hide the Boot ROM, load the floppy disk boot sector and boot on it.

HdBoot (disk)(:partition)

  Load the given boot sector and boot from it. The disk default to zero, the first hard disk, and the partition defaults to zero, ie. the master boot record. You can boot from any partition, but be warned that Windows 95 may not let you boot a partition that has not been set as the boot partition (hint: use SetBootPart).

  This command does not implicitely call HideBootProm, so you might want to call it before.

LinuxBoot "kernelfile" ("command-line" ("ramdisk-file"))

  Load the given kernel and ramdisk into the high memory, setup the command line and boot the kernel. It is a good idea to put at least a minimal command line with the location of the root filesystem (like `"root=`dev/hda1"/). If you are using a linux system that heavily relies on `lilo` (like RedHat Linux 5.1), it may be necessary to add to the command line something like `BOOT_IMAGE=linux`. Note that the kernel can be loaded by TFTP (automatically cached on the hard disk) or directly from the target root partition.

  This command works for small and big kernels (`zImage` and `bzImage`).

### National language support

This section lists commands related not national language support. Optional arguments are listed between parenthesis.

RemapKeys "original-keys" "remapped-keys"

  National keyboard support. Remap given keys to other characters. For instance, to swap the Y and Z keys, use

              Remapkeys "yzYZ" "zyZY"

  It is a good idea to use the quoted octal notation when using characters not included in the minimal ASCII character set, in order to avoid a dependency to the iso-latin modal settings.

  For international keyboards, there are two keys that produce a backslash in non-remapped (US) mode. Each of them can be independantly remapped, thanks to the fact that `BpBatch` sees one of them as a key answering ASCII code 252 (octal) or ASCII code 335 (octal) when shifted.

  If you send me a sample script that does keyboard mapping for your national keyboard, I will make it available under `http://cuiwww.unige.ch/info/pc/remote-boot/soft/sample-scripts` To help you make your own keyboard mapping, I suggest pressing all special keys without remapping the keyboard and writing down the character they produce. These will be the `original-keys`. The `remapped-keys` simply are the key you would have liked to see, in the same order. If some keys (either original or remapped) produce characters above ASCII dec 127, use the quoted octal notation. You can easily get the octal code for any given character by looking in the ASCII table of HelpPC for instance (HelpPC is a shareware hypertext on-line help program by David Jurgens).

RemapAltkeys "original-keys" "remapped-keys"

  National keyboard support. Remap the given keys when ALT is depressed For instance, to map Alt-2 to the ampersand sign, use

              RemapAltKeys "2" "@"

  Note that dead keys are not supported.

LoadCodePage "cpxxx.bin"

  Load and activate the given binary Codepage file. Codepages are used for the translation of Unicode characters (present on VFAT valumes for instance) into 8-bits characters. If you do not have the right Codepage loaded, you will get FAT warnings while accessing the filesystem when special characters are encountred.

  All binary codepage files are available at `http://cuiwww.unige.ch/info/pc/remote-boot/soft/codepage.zip`

  The default codepage is 850, a reordered superset of ISO-Latin-1. If you load a more exotic codepage, you should usually turn the variable `$IsoLatin` to `"off"` or you might get meaningless implicit conversions. Moreover, if you want to display exotic characters, you should also load the proper screen font (use `"LoadFont"`).

LoadFont "fontfile"

  Load and activate a VGA/VESA font, both in text and graphic mode. The font file must be a binary file of 16 bztes/characters (8x16 bitmap). This command can be used for National Language Support as well as for Fantasy support.

  An archive with several fantasy fonts is available at `http://cuiwww.unige.ch/info/pc/remote-boot/soft/fonts.zip`. This archive also contains a program to extract fonts for your codepage from the DOS `.CPI` file.

### Commands specific to MrZip

Source...

        Source (i)archive "filename"
        Source path "path"

  Set the source for the archive manipulation to the given (incremental) archive file or disk path.

Dest...

        Dest (i)archive "filename"
        Dest (i)dump
        Dest path "path"

  Set the destination for the archive manipulation to the given (incremental) archive file, dump or disk path. To control the quantity of data displayed during dump, use the $DumpFormat special variable.

FileZip "source-filename" "dest-filename"

  Compress a file for further decompression with FileUnzip or for using as ZRamDisk. The file is validated by a 32-bits CRC.

Filter...

        Filter -"pattern"
        Filter +"pattern"

  Avoid/allow files and directories matching the given pattern (wildcards allowed) to be included in the archive. The pattern is matched agains the full pathname. By default, all files are included in the image. You only need to explicitely allow files that where cancelled by a filter. Each negative filter has its own positive filter (allowed) sublist.

  For DOS/Windows images, you will typically use

              Filter -"*.swp"
              Filter -"temp/*"

  and for Unix images, you will typically use

              Filter -"var/log/*"
              Filter -"tmp/*"

CopyArchive

  Start the archive manipulation operation, according to source, destination and filter settings. Except in a few circumstances, you will probably use the shortcut below instead of explicitely calling `CopyArchive`. One circumstance in which you will use `CopyArchive` explicitely is when you want to change the fragmentation of an image, as follow:

              set FragmentSize="30 MB"
              Source archive "original.imz"
              Dest archive "refragmented.imz"
              CopyArchive

FullZip "path" "full-archive"

  Shortcut for

                      Source path "path"
                      Dest archive "full-archive"
                      CopyArchive

  You should usually first setup filters.

IncrZip "path" "incr-archive"

  Shortcut for

                      Source path "path"
                      Dest iarchive "incr-archive"
                      CopyArchive

FullDump "full-archive"

  Shortcut for

                      Source archive "full-archive"
                      Dest dump
                      CopyArchive

IncrDump "incr-archive"

  Shortcut for

                      Source iarchive "incr-archive"
                      Dest dump
                      CopyArchive

XCopy "srcpath" "dstpath"

  Shortcut for

                      Source path "srcpath"
                      Dest path "dstpath"
                      CopyArchive

## 5.2 NoBreak.sys

`Nobreak.sys` is a very small (about 350 bytes only) driver that you include at the beginning of your `config.sys`. Its goal is to secure the boot process, until the user is logged in. DOS provides a setting for this (namely `BREAK=OFF`), but it is not drastic enough, and has almost no effect in the `autoexec.bat`. Our driver works by modifying the scan-code of the key pressed when a break is requested, directly at the BIOS level. This way, no program at all can receive a break until break is enabled again.

The driver must be loaded from the `config.sys` (or using the `devlod` program from Undocumented DOS). Afterwards, break can be enabled by sending `Yes` to the `NOBRK` pseudo-device, and disabled again by sending `No` (in fact, only the first character, `Y` or `N` is significant).

As this driver relies on the BIOS, it does only work for DOS and Windows 3.1. Windows 95 has its own low-level keyboard handling routines.

Assembler source code is available.

Next Previous Contents