  VendorTag extensions
  Markus Gutschke, gutschk@math.uni-muenster.de
  1 July 1997

  This document describes the format and semantics of the VendorTags


  This documentation has been   written  and is copyrighted  1996,97 by
  Markus  Gutschke  <gutschk@math.uni-muenster.de>.   You   are free to
  distribute this  file as long as  you do not  change  its contents.  I
  appreciate comments and  will consider them  in  future revisions.  If
  you   have any questions, comments,  or  suggestions, please also send
  carbon   copies    of  your   e-mail  message    to both    Ken   Yap
  <ken.yap@acm.org> and Gero Kuhlmann <gero@gkminix.han.de>. I will
  happily include any of your extensions, but I would  like to avoid the
  proliferation of different incompatible revisions of this document. If
  these conditions are a problem to you, then feel free to contact me.



  RFC1533  allows   for   vendor-specific   extensions   to the    BOOTP
  protocol. It defines that all tags in  the range 128  thru 254 are set
  aside for site-specific extensions. Common implementations of "bootpd"
  daemons  can  assign arbitrary null-terminated  character  strings  to
  these tags.



  This is a list of the tags  that are currently  used by the BOOT-Prom;
  as a general  rule, you should  never  fill out any  of these entries,
  unless you positively know that  your BOOT-Prom supports the extension
  or ignores this particular tag:





     TTAAGG 112288
        this  is  a six-byte hexadezimal  entry.  The first four bytes
        have to be the magic number  E4 45 74 68; if this magic cannot
        be found, then  none of the  other vendor  tags are valid! The
        fifth byte is  the major version  number and the sixth byte is
        the  minor version number    of this protocol extension.   The
        current  version is  0.0;    the BOOT-Prom  can assume    that
        incompatible changes  increase the major  version number. Mere
        extensions  to  the  existing  protocol,  increase  the  minor
        version number. If  the BOOT-Prom code  has been  written in a
        way that anticipates future extensions,  then it is acceptable
        to honor the vendor tags even though, the minor version number
        does not match exactly. Before  making a change, that requires
        updating the major version number,  you should contact all  of
        the persons that are listed at the top of this document.


     TTAAGG 112299
        the  BOOT-Prom  uses   this tag for   passing  a user-provided
        command  line to the loaded  operating system.  As this tag is
        used internally, the "bootpd" daemon must not assign any value
        to it!


     TTAAGG 116600
        a   string   that   contains  a   colon   separated list    of
        "parameter=value" pairs.  Currently, these parameters are only
        used to  control   the behavior  of an  interactive  menu  for
        selecting  different boot images;  future extensions are quite
        likely:


        ttiimmeeoouutt
           after this many seconds, the default image will be loaded. If
           no  'timeout'  has been set,  then  the program will wait
           indefinitly.

        ddeeffaauulltt
           either an  integer 'n' in the  range 0 thru  15 or 192 thru
           207, selecting  the default image. If 'n' is in the first
           range, it refers to the 'n'th menu entry; if it is in  the
           later range, it refers  to the    entry  with the   tag
           number  'n'.   This distinction  is  important, if the  list
           of images contains gaps. If no  value has been set, then the
           image  with  the  lowest tag  number  will  be the default
           image.


     TTAAGGSS 116611 tthhrruu 117755
        these tags are currently unused,  but they should be allocated
        for purposes that resemble the function of tag 160.


     TTAAGG 117766
        the BOOT-Prom  uses this tag  for telling the loaded operating
        system,  which of  the entries  in  tags  192 to  207 has been
        selected  by  the user.  As this   tag  is used interally, the
        "bootpd" daemon must not assign any value to it!


     TTAAGGSS 117777 tthhrruu 118833
        these  tags  are reserved  for  passing  information  from the
        BOOT-Prom to the boot image. Under no circumstances should the
        "bootpd" daemon assign any of   these entries.  The format  of
        these parameters is yet to be discussed.


     TTAAGGSS 118844 tthhrruu 119911
        up to eight zero-terminated  character strings can be used for
        displaying a "message of the day". If you need to display more
        than eight lines, you can embed  suitable CR/LF pairs.  If you
        fully exploit  that feature, you can  display a complete 80x24
        screen of information, but you should be aware that subsequent
        output might scroll part of a long message.



        The  BOOT-Prom can optionally be  configured to interpret some
        ANSI escape  sequences.   There  also  is  an   extension  for
        including  extra  data  via TFTP;    this  overcomes the  size
        limitation of the tags 184-191.



        The ANSI emulation currently knows about these commands:










        ________________________________________________________________
                  Display attributes

                    Code          Effect
                    <esc>[0m      normal text
                    <esc>[1m      high-intensity on
                    <esc>[21m     high-intensity off
                    <esc>[5m      blinking on
                    <esc>[25m     blinking off
                    <esc>[7m      reverse video on
                    <esc>[27m     reverse video off
                    <esc>[3xm     set foreground color:
                    <esc>[4xm     set background color. x can be:
                                   0 - black                   4 - blue
                                   1 - red                     5 - magenta
                                   2 - green                   6 - cyan
                                   3 - yellow                  7 - white
                    <esc>[=xh     set video mode
                                   0 - 40x25 mono     (text)  13 - 40x25 16colors (gfx)
                                   1 - 40x25 16colors (text)  14 - 80x25 16colors (gfx)
                                   2 - 80x25 mono     (text)  15 - 80x25 mono     (gfx)
                                   3 - 80x25 16colors (text)  16 - 80x25 16colors (gfx)
                                   4 - 40x25 4colors  (gfx)   17 - 80x30 mono     (gfx)
                                   5 - 40x25 mono     (gfx)   18 - 80x30 16colors (gfx)
                                   6 - 80x25 mono     (gfx)   19 - 40x25 256colors(gfx)


                  Cursor control

                    Code          Effect
                    <esc>[r;cH    move cursor to row r and column c
                    <esc>[r;cf    move cursor to row r and column c
                    <esc>[rA      move cursor up r rows
                    <esc>[rB      move cursor down r rows
                    <esc>[cC      move cursor right c columns
                    <esc>[cD      move cursor left c columns
                    <esc>[?7l     turn off line wrap
                    <esc>[?7h     turn on line wrap
                    <esc>[J       clear screen and home cursor
                    <esc>[K       clear to end of line
                    <esc>[s       save the cursor position
                    <esc>[u       return cursor to saved position


                  Extended features

                    Code          Effect
                    <esc>['filename'#
                                  load include file with TFTP. Nested includes
                                  are  not   allowed  and   will   silently be
                                  ignored.
                    <esc>[a;b;c;d+<data>
                                  draw pixel data.  Use  one byte  per  pixel.
                                  Colors are encoded as  shown above.  In text
                                  mode, graphics is approximated by outputting
                                  suitable    characters.  Parameters   differ
                                  depending    on  the number    of parameters
                                  passed:
                                    cnt
                                      "cnt"  data  bytes follow. They  will be
                                      drawn to  the right of the last graphics
                                      position.
                                    rle;col
                                      the next  "rle"  pixels  have the  value
                                      "col". They will  be drawn to  the right
                                      of the last  graphics position.  No data
                                      bytes follow.
                                    x;y;cnt
                                      "cnt" data  bytes  follow. They  will be
                                      drawn relative to the top left corner of
                                      the text cursor with an offset of (x/y).
                                    x;y;rle;col
                                      the next "rle"   pixels have  the  value
                                      "col".  They will  be drawn  relative to
                                      the top  left corner of the  text cursor
                                      with an offset  of (x/y).  No data bytes
                                      follow
                                  you usually   do not  have   to enter  these
                                  values manually, but you  should use  a tool
                                  such as  "ppmtoansi" which  is  shipped with
                                  your BOOT-Prom or available from the contrib
                                  directory of the "etherboot" package.
                    <esc>[a;b;c;d-<data>
                                  same as above,   but pack pixels into  three
                                  bits. The first pixel is stored in the three
                                  most  significant  bits  of the  first  data
                                  byte.
        ________________________________________________________________



     Note that you usually  have to specify any control  characters
     directly (rather than in hex form) in your bootptab file.


     TTAAGGSS 119922 tthhrruu 220077
        these tags  define all of  the valid boot images  and override
        any settings  that are given  with the "bf" bootfile option in
        your "bootptab".  It is  allowed to leave   gaps in the  list.
        This has an    impact on  how the   `default'  image will   be
        selected.

        All entries are of the form

        ________________________________________________________________
                    label:server:gateway:filename:passwd:flags:cmdline
        ________________________________________________________________


     For   future extensibility,  it   is  permitted  to  append an
     arbitrary amount of  other colon seperated  entries as long as the
     limit  of    255 characters   per  tag  is  not  exceeded.  Non-
     existant entries can be   left empty. This means  that the default
     value for this particular entry will be used. Trailing colons can
     be omitted.


        llaabbeell
           this is the text string  that is  displayed to the user.  It
           can contain arbitrary characters, except for  a   colon.
           Embedding  arbitrary     control characters  is  not
           recommended, but  you might be able to include  ANSI escape
           sequences (if enabled in the ROM) for  changing text
           attributes as  long as you restore the  attributes  at the
           end of  the string.  It probably does not make very much
           sense to leave this entry empty.

        sseerrvveerr
           IP  number of the TFTP server, where the image can be found.
           This  data has to   be in decimal form (e.g. 192.168.0.1); it
           is not permitted to use  a hostname. It is the responsibility
           of the "bootpd" to look up  hostnames.  If this entry is
           omitted, then the BOOTP server  will  be used for the  TFTP
           download.

        ggaatteewwaayy
           use this IP gateway, when accessing the boot image by TFTP.
           If no  value is given, the BOOTP  gateway or alternatively
           the  first  entry in the  list of gateways "gw" is used.

        ffiilleennaammee
           name of the boot image  that  has to be  loaded by TFTP.  If
           this entry  is omitted, then the machine boots  locally  from
           disk.   If   enabled in  the BOOT-Prom, you  can specify
           pseudo-filenames   for booting   from   a   local
           blockdevice   (floppy, harddisk, ...);  these filenames have
           to match the pattern "/dev/[fh]d*".   If the BOOT-Prom does
           not have support for  these  pseudo-filenames, you can still
           boot from blockdevices   by storing an boot image as
           generated by mknbi-blkdev under the name of  the  desired
           blockdevice  (symbolic links will do).

        ppaasssswwdd
           MD5 message digest of the password.  If this entry is
           omitted, then no    password is  required for loading  this
           image.   Support  for  passwords is optional and might  not
           be compiled into the  ROM image. For generating the  MD5
           message digest, you can  use   freely    available  tools
           such   as "md5sum".  C.f.  the  flags entry  for controlling
           the behavior of passwords.

        ffllaaggss
           flags are used for controlling some aspects of how the BOOT-
           Prom code behaves. All flags are a string of decimal  digits
           followed by  a letter; multiple flags can  be   concatenated.
           If this  entry   is omitted,  then  a  default   value  of
           "1i1p"   is assumed. Currently, these flags are defined:


           00ii booting  this  image  does  not  require  a password;  the
              contents of   the password entry is ignored  unless some
              other feature (such as the flag "2p") requires it.

           11ii booting this image requires a password.  If the  password
              entry    is omitted,  or  no password   support   is
              available in    the BOOT-Prom, then this flag is ignored.

           00pp the  user cannot enter   a command line for passing
              parameters  to  the loaded  image, even if this feature
              has been enabled when compiling the BOOT-Prom. N.B. this
              does not affect  the cmdline  entry  as    described
              below!

           11pp the user  does not get prompted for passing parameters to
              the loaded  image, but he can explicitly  request the
              prompt (e.g.   by pressing a modifier  key while selecting
              an image from  the   menu).  If the   password entry is
              not omitted, then the password has to be entered.   Both
              parameter passing and password validation   can be
              disabled when compiling the BOOT-Prom.

           22pp the  user always gets prompted  for passing parameters
              to the  loaded   image. If the password  entry  is
              present and  password support  has been enabled in the
              BOOT-Prom, then the password has to be entered.

           33pp the  user always gets  prompted for passing parameters to
              the loaded image. No password is required.
        ccmmddlliinnee
           the contents of this  entry is appended to the end of the
           command line that gets passed to the loaded image.  This
           feature   is unaffected  by the  "p" flags.  Passing
           parameters currently does not make sense for any  operating
           system other than  Linux and  is  silently   ignored for
           other   operating systems.  As it is  not legal  to enter
           colons  as part   of an entry, you    have to escape them  by
           writing  ' c' instead.  This  also means, that all tilde
           characters have to   be escaped by   writing entering a
           backslash  in  a character string,  the escape   sequence
           ' b'    inserts  a  backslash character.   Currently, all
           other escape sequences are undefined.




  For demonstration purposes,  I attached an  annotated  excerpt from my
  "bootptab" illustrating some of these techniques. In the following the
  character sequence ESC should be replaced by the ASCII escape
  character.













































  ______________________________________________________________________
  #
  # The MOTD (message of the day) can contain arbitrary characters, that
  # the PC  is capable of displaying.   Here we use  8bit characters for
  # drawing  a border around the  message; also we change the foreground
  # color to  red (this assumes that the  BOOT Prom has support for ANSI
  # escape sequences):
  #
  .motd:\
          :T184="ESC[31m":\
          :T185="":\
          :T186=" This is an experimental release of the new BOOT-Prom ":\
          :T187=" code.  It supports a couple of  non-standard  vendor ":\
          :T188=" extensions.                                          ":\
          :T189="":\
          :T190="ESC[37m":

  #
  # Alternatively,  the MOTD can be  stored  in an  external file;  this
  # requires that you  enabled ANSI support  in the BOOT Prom!  For more
  # advanced configurability,  you  should  explore the  feature of  the
  # patched   tftpd daemon (as available  in  the  contrib directory) to
  # execute shell scripts and use the output as the file contents.
  #
  # .motd:\
  #       :T184="ESC[31mLoading message of the day...ESC[37mESC['/etc/motd'#":
  #

  #
  # We use the "template" feature of modern versions of "bootp" in order
  # to group common entries. Unfortunatly, you  cannot use more than one
  # "tc" entry per (pseudo-) host.  Pseudo hostnames should begin with a
  # leading period character.
  #
  # All entries are kept as generic as possible.  This ensures that they
  # will keep working even when the network topology is changed. Leaving
  # the server  IP address  and  the gateway  IP  address  empty, should
  # ensure that booting works even when we go thru "bootpgw" gateways.
  #
  # "Technicolor"   special  effects   are   achieved  by  changing  the
  # foreground text color of the individual labels. You could even embed
  # small icons after switching to graphics mode. C.f. "linux-logo.ansi"
  # for an example; this will not work, if your BOOT  Prom does not have
  # support for ANSI escape sequences.
  #
  # Passing  boot-time parameters  to  the  Linux kernel, requires   the
  # password "Penguin".
  #
  # Booting from  the local disk requires  the password "Joshua". If the
  # BOOT-Prom does not have support for booting from local block devices
  # (floppy, harddrive,  ...),  then you can  either  omit  the filename
  # (c.f. README.Security for  potential security problems) or your TFTP
  # server has   to provide  a  boot  image that  has been  generated by
  # mknbi-blkdev.
  #
  .imagemenu:\
          :tc=.motd:\
          :T128=E44574680000:\
          :T160="timeout=30:default=207:":\
          :T192="ESC[32mLinux 2.0.27ESC[37m:::/tftpboot/image-linux:99625fa1cac27bb6a2b33b7638afe47:0i1p":\
          :T193="ESC[33mDOS 6.2ESC[37m:::/tftpboot/image-dos":\
          :T207="ESC[34mLocal DiskESC[37m:::/dev/hda:85b103482a20682da703aa388933a6d8":

  #
  # When using  more than  a handful of   vendor parameters, we  have to
  # specify an extension file "ef". If you are  very careful, then it is
  # possible to  use one extension  file for several hosts. Don't forget
  # to run  "bootpef" after editing the  "bootptab", and  make sure that
  # you "chroot" into the proper directory, if applicable.
  #
  .default:\
          :tc=.imagemenu:\
          :bf=tftpboot/image-rom:\
          :hd=:\
          :ht=ethernet:\
          :sm=255.255.255.0:\
          :vm=auto:\
          :ef=extension.bootp:

  #
  # Ideally, hosts  differ only with  respect to their ethernet hardware
  # ID and IP number. We let the "bootpd" look up the correct IP number.
  #
  thalamus:tc=.default:ha=00400529C11B:ip=thalamus:
  cortex: :tc=.default:ha=0000C0531A24:ip=cortex:
  ______________________________________________________________________





  If  you only   have  old BOOT-Proms  and want   to use these  advanced
  features without  having  to burn  new BOOT-Proms,  there  is a little
  trick.



  You  may have noticed  that old BOOT-Proms  ignore all of these vendor
  extensions and unconditionally load the file that is given in the "bf"
  bootfile  entry.  On the  other hand, new BOOT-Proms completely ignore
  the "bf" entry when they find a list of images in the vendor extension
  tags.



  Therefore,  you create a boot   image that contains the new  BOOT-Prom
  code and specify the filename in the "bf" entry. This results in a two
  step bootloading process.  First the old BOOT-Prom  loads the new code
  and then the new  code displays the message  of the day, processes the
  image list, asks  the  user for his prefered  image  (and possibly for
  parameters and a password) and then proceeds booting.



  There  are different  techniques for  building  a boot  image from   a
  BOOT-Prom file. I will only list the one, that I  use, but I guess you
  can come up with others:



  Follow  the instructions  of your   BOOT-Prom  package for creating  a
  ".com" file   from your BOOT-Prom.   If  you use "etherboot",  then by
  default it  will always build  an "all.com"  file  and several ".rom"
  files  for all  of  the  available NICs; you    can probably use   the
  "all.com" file,  but if you  want to make  a ".com" file that contains
  just one device driver, enter  "make <nic>.com" replacing "<nic>" with
  the  name of  your network interface  card.  Next  get a  copy  of the
  "masq" utility  which is distributed in the  contrib directory of the
  the  "etherboot"  package.  Modify  the  "Makefile" according to your
  needs and  create a "netImage" file by  running "make"; this has to be
  done  on a Linux    machine and the   kernel source  tree has  to  be
  accessible. You can now use "mknbi-linux" to convert this file into a
  regular boot image.

































































