Ubuntu Manpage: mknbi - make network bootable image

NAME

       mknbi - make network bootable image

SYNOPSIS

       mknbi --version

       mknbi --format=format --target=target [--output=outputfile] target-specific-arguments

       mkelf-linux [--output=outputfile] kernelimage [ramdisk]

       mknbi-linux [--output=outputfile] kernelimage [ramdisk]

       mknbi-rom [--output=outputfile] .z?rom-file

       mkelf-img [--output=outputfile] .z?img-file

       mkelf-menu [--output=outputfile] [dataimage]

       mknbi-menu [--output=outputfile] [dataimage]

       mkelf-nfl [--output=outputfile] [dataimage]

       mknbi-nfl [--output=outputfile] [dataimage]

       mkelf-lua [--output=outputfile] luabin

       mknbi-fdos [--output=outputfile] kernel.sys floppyimage

       mknbi-dos [--output=outputfile] floppyimage

DESCRIPTION

       mknbi is a program that makes network bootable images for various operating systems
       suitable for network loading by Etherboot or Netboot, which are ROM boot loaders.  If you
       are looking to boot using PXE, look no further, mknbi is not what you want. You probably
       want something like PXELINUX which is part of the SYSLINUX package.

       mknbi --version prints the current version. Use this before reporting problems.

       mknbi can be invoked with the --format and --target options or links can be made to it
       under format and target specific names. E.g.  mkelf-linux is the same as mknbi
       --format=elf --target=linux.

       --format=format Specify the format of the output. Currently available are nbi and elf.
       ELF format only works with linux and menu.  Otherwise the invocation is the same as for
       mknbi. In discussions below, the mknbi form is used.

       --target=target Specify the target binary. Currently available are linux, menu, rom, fdos
       and dos. mknbi is not needed for booting FreeBSD.

       --output=outputfile Specify the output file, can be used with all variants.  Stdout is the
       default.

       The package must be installed in the destination location before the executables can be
       run, because it looks for library files.

       Each of the variants will be described separately.

MKELF-LINUX

       mkelf-linux and mknbi-linux makes a boot image from a Linux kernel image, either a zImage
       or a bzImage.

MKELF-LINUX OPTIONS

--param=string Replace the default parameter string with the specified one. This option
overrides all the following options so you should know what you are doing.

--append=string Appends the specified string to the existing parameter string. This option
operates after the other parameter options have been evaluated.

--rootdir=rootdir Define name of directory to mount via NFS from the boot server.

In the absence of this option, the default is to use the directory "/tftpboot/"%s, with
the %s representing the hostname or IP-address of the booting system, depending on whether
the hostname attribute is present in the BOOTP/DHCP reply.

If "rom" is given, and if the BOOTP/DHCP server is able to handle the RFC 1497 extensions,
the value of the rootpath option is used as the root directory.

If the name given to the option starts with "/dev/", the corresponding device is used as
the root device, and no NFS directory will be mounted.

--rootmode="ro|rw" Defines whether the root device will be mounted read-only or read-write
respectively. Without this parameter, the default is "rw".

--ip=string Define client and server IP addresses.

In the absence of this option no IP addresses are defined, and the kernel will determine
the IP addresses by itself, usually by using DHCP, BOOTP or RARP. Note that the kernel's
query is in addition to the query made by the bootrom, and requires the IP: kernel level
autoconfiguration (CONFIG_IP_PNP) feature to be included in the kernel.

Important note: In Linux kernels 2.2.x where x >= 18, and 2.4.x where x >= 5, it is
necessary to specify one of the enabling options in the next paragraph to cause the IP
autoconfiguration to be activated. Unlike in previous kernels, IP autoconfiguration does
not happen by default. Also note that IP autoconfiguration and NFSroot are likely to go
away in Linux 2.6 and that userspace IP configuration methods using ramdisk and userspace
DHCP daemons are preferred now.

If one of the following: "off, none, on, any, dhcp, bootp, rarp, both", is given, then the
option will be passed unmodified to the kernel and cause that autoconfig option to be
chosen.

If "rom" is given as the argument to this option, all necessary IP addresses for NFS root
mounting will be inherited from the BOOTP/DHCP answer the bootrom got from the server.

It's also possible to define the addresses during compilation of the boot image. Then, all
addresses must be separated by a colon, and ordered in the following way:

"--ip="client:server:gateway:netmask:hostname[:dev[:proto]]

Using this option mkelf-linux will automatically convert system names into decimal IP
addresses for the first three entries in this string. The hostname entry will be used by
the kernel to set the host name of the booted Linux diskless client. When more than one
network interface is installed in the diskless client, it is possible to specify the name
of the interface to use for mounting the root directory via NFS by giving the optional
value "dev". This entry has to start with the string "eth" followed by a number from 0 to
9. However, if only one interface is installed in the client, this dev entry including the
preceding semicolon can be left out. The proto argument is one of the IP autoconfiguration
enabling options listed above. (Author: it's not clear to me what the IP
autoconfiguration does when the parameters are already specified. Perhaps it's to obtain
parameters not specified, e.g. NIS domain.)

--rdbase=top|asis|0xNNNNNNNN Set the ramdisk load address. "top" moves the ramdisk to the
top of memory before jumping to the kernel. This is the default if rdbase is not
specified. This option requires that first-linux's kernel sizing work correctly. "asis"
loads it at 0x100000 (1MB) if the kernel is loaded low; or leaves it just after the kernel
in memory, if the kernel is loaded high. For this option to work, the kernel must be able
to handle ramdisks at these addresses. 0xNNNNNNNN moves the ramdisk to the hex address
specified. The onus is on the user to specify a suitable address that is acceptable to the
kernel and doesn't overlap with any other segments. Etherboot will round address down to
multiple of 4k (last 3 digits to zero).

--rdnopad By default, etherboot pads (with nulls) the given initrd of any size to multiple
of 4k bytes (aligning to memory page boundary). Use this option to disable padding if it
causes problem.

--first32=program Override the default first stage setup program. It can be used to call
extensions to the Etherboot code, which paves the way for additional useful functionality
without enlarging the size of the Etherboot footprint. --first32 is implied by the ELF
format.

--progreturns This option is used in conjunction with and only valid with the --first32
option to indicate to the Etherboot loader that the called program will return to loader
and hence Etherboot should not disable the network device as is the case when the program
will never return to Etherboot.

--relocseg=segaddr This option is used to specify a relocation of the Linux first, boot,
setup, and parameter segments to another 64k band. Currently the only valid values are
0x9000 and 0x8000, corresponding to linear addresses of 0x90000 and 0x80000 upwards. The
default is 0x9000. Usually you use this option if you have relocated Etherboot to 0x84000
to avoid other code in the 0x90000 segment like DOC. The Linux kernel must support
relocation which implies a 2.4 kernel or later. --relocseg only works reliably with ELF or
--first32=.

mem=memsize This is not a command line option but a kernel parameter that is intercepted
by the first32 stage and used as the top of memory, to match Linux's interpretation.
memsize can be suffixed by "G" to indicate gibibytes (times 2^30), "M" to indicate
mebibytes (times 2^20) or "K" to indicate kibibytes (times 2^10). Note that the suffixes
are uppercase. This kernel parameter can be specified in --append= or option-129 of the
DHCP/BOOTP record.

Run the program thus:

mkelf-linux kernel-image [ramdisk-image] > linux.nb

Then move linux.nb to where the network booting process expects to find it.

MKELF-LINUX BOOTP/DHCP VENDOR TAGS

mkelf-linux includes a startup code at the beginning of the Linux kernel which is able to
detect certain DHCP vendor defined options. These can be used to modify the kernel
loading process at runtime. To use these options with ISC DHCPD v3, a popular DHCP daemon,
the syntax is as below. You will need to adjust the syntax for other DHCP or BOOTP
daemons.

option etherboot-signature code 128 = string;

option kernel-parameters code 129 = text;

...

option etherboot-signature E4:45:74:68:00:00;

option kernel-parameters "INITRD_DBG=6 NIC=3c509";

Option 128 is required to be the six byte signature above. See the vendortags appendix of
the Etherboot user manual for details.

The following option is presently supported by mkelf-linux:

129 The string value given with this option is appended verbatim to the end of the kernel
command line. It can be used to specify arguments like I/O addresses or DMA channels
required for special hardware like SCSI adapters, network cards etc. Please consult the
Linux kernel documentation about the syntax required by those options. It is the same as
the --append command line option to mkelf-linux, but works at boot time instead of image
build time.

130 With this option it is possible to the select the network adapter used for mounting
root via NFS on a multihomed diskless client. The syntax for the string value is the same
as for the "dev" entry used with the --ip= option as described above. However note that
the mkelf-linux runtime setup routine does not check the syntax of the string.

MKNBI-ROM

       mknbi-rom makes a boot image from an Etherboot ".rom" or ".zrom" boot ROM image.  This
       allows it to be netbooted using an existing ROM. This is useful for developing Etherboot
       drivers or to load a newer version of Etherboot with an older one.

       Run mknbi-rom like this:

       mknbi-rom nic.zrom > nic.nb

       Move nic.nb to where the network booting process expects to find it.  The boot ROM will
       load this as the operating system and execute the ROM image.

MKELF-IMG

       mkelf-img makes a boot image from an Etherboot ".img" or ".zimg" image.  This allows it to
       be netbooted using an existing ROM. This is useful for developing Etherboot drivers or to
       load a newer version of Etherboot with an older one.

       Run mkelf-img like this:

       mkelf-img nic.zimg > nic.nb

       Move nic.nb to where the network booting process expects to find it.  The boot ROM will
       load this as the operating system and execute the image.

       Note that this does not test the ROM loader portion that's in a ".z?rom" image, but not in
       a ".z?img".

MKELF-MENU

mkelf-menu and mknbi-menu make a boot image from an auxiliary menu program. Etherboot has
the ability to load an auxiliary program which can interact with the user, modify the DHCP
structure, and return a status. Based on the status, Etherboot can load another binary,
restart or exit. This makes it possible to have elaborate user interface programs without
having to modify Etherboot. The specification for auxiliary program is documented in the
Etherboot Developer's Manual.

mkelf-menu and mknbi-menu take a binary named "menu" from the library directory, which is
assumed to have an entry point of 0x60000. An optional argument is accepted, and this is
loaded at 0x80000. This can be a data file used by the menu program.

Currently, the menu binary provided duplicates the builtin menu facility of Etherboot with
the exception of a couple of small differences: no server or gateway specifications are
used and nested TFTP loads don't work. You should not have MOTD or IMAGE_MENU defined in
your Etherboot build to be able to use this external menu binary. The specifications of
the DHCP option required is in the vendortags document in the Etherboot user manual.

Typical usage is like this:

mkelf-menu > menu.nb

Then put menu.nb in the TFTP boot directory and edit your DHCP options according to the
documentation.

Alternate user interface programs are highly encouraged.

MKELF-NFL

       mkelf-nfl and mknbi-nfl make a boot image from the NFL menu program. This menu program
       takes the names of images from a menu-text-file file which just contains lines with the
       filenames (relative to the tftpd root directory) of images to load. The user-interface is
       a light-bar, similar to that used in GRUB.  There is a sample menu-text-file in
       "menu-nfl.eg". The special entry "Quit Etherboot" (without quotes, of course) can be used
       in menu-text-files as an entry that causes Etherboot to quit and return to the invoking
       environment, which is the BIOS in the case of ROMs.

       Typical usage is:

       mkelf-nfl menu-text-file > nfl.nb

       Then put nfl.nb in the TFTP boot directory and specify as the boot image. Chaining to
       other menus works.

       Enhancements to the menu format accepted to specify other features such as titles,
       timeout, colours, and so forth are highly encouraged.

MKELF-LUA

       mkelf-lua makes an ELF image from a precompiled Lua ("http://www.tecgraf.puc-rio.br/lua/")
       program.

       Typical usage is:

       mkelf-lua hello.lb > luaprog.nb

       where "hello.lb" was generated from a Lua program by:

       luac -o hello.lb hello.lua

       The functions available to Lua programs in this environment is described in a separate
       document.

MKNBI-FDOS

mknbi-fdos makes a boot image from a FreeDOS kernel file and a floppy image. Note that
the kernel image is not read from the floppy section of the boot image, but is a separate
section in the boot image. The bootloader has been adjusted to jump to it directly. This
means the space that would be taken up on the floppy by the kernel image file can now be
used for applications and data.

Obtain a distribution of FreeDOS with a recent kernel, probably at least 2006. It has been
tested with 2012 but nothing older. You can get the FreeDOS kernel here:

"http://freedos.sourceforge.net/"

Follow the instructions to make a bootable floppy. Then get an image of the floppy with:

dd if=/dev/fd0 of=/tmp/floppyimage

Also extract kernel.sys from the floppy. You can do this from the image using the mtools
package, by specifying a file as a drive with a declaration like this in ~/.mtoolsrc:

drive x: file="/tmp/floppyimage"

Then run:

mcopy x:kernel.sys .

Then run mknbi by:

mknbi-fdos kernel.sys /tmp/floppyimage > freedos.nb

where kernel.sys and /tmp/floppyimage are the files extracted above. Then move freedos.nb
to where the network booting process expects to find it.

If you have got it to netboot successfully, then you can go back and add your files to the
floppy image. You can delete kernel.sys in the floppy image to save space, that is not
needed. Note that you can create a floppy image of any size you desire with the mformat
program from mtools, you are not restricted to the actual size of the boot floppy.

MKNBI-FDOS OPTIONS

       --harddisk Make the boot ramdisk the first hard disk, i.e. C:. One reason you might want
       to do this is because you want to use the real floppy. The limit on "disk size" in the
       boot image is not raised by this option so that is not a reason to use this option. This
       option is incompatible with --disableharddisk.

       --disableharddisk When the ramdisk is simulating a floppy disk drive, this switch will
       disable hard disk accesses.  This is necessary if the client should use a network file
       system as drive C:, which is only possible if there are no hard disks found by DOS. This
       option is incompatible with --harddisk.

       --nosquash Do not try to chop unused sectors from the end of the floppy image. This
       increases the boot image size and hence loading time if the FAT filesystem on the floppy
       is mostly empty but you may wish to use this option if you have doubts as to whether the
       squashing algorithm is working correctly.

       --rdbase=0xNNNNNNNN Set the ramdisk load address. The default load address for the ramdisk
       is 0x110000. It can be moved higher (lower will not work) if for some reason you need to
       load other stuff at the address it currently occupies. As this is a linear address and not
       a segment address, the last 4 bits are not used and should be 0.

MKNBI-DOS

mknbi-dos makes a boot image from a floppy image containing a bootable DOS filesystem. It
is not necessary to build the filesystem on a physical floppy if you have the mtools
package, but you need a bootable floppy of any size to start with. First extract the boot
block from the floppy, this boot block must match the DOS kernel files you will copy in
the next step:

dd if=/dev/fd0 of=bootblock bs=512 count=1

Then get the DOS kernel files (this is correct for DR-DOS, the names are different in MS-
DOS, IO.SYS and MSDOS.SYS):

mcopy a:IBMBIO.COM a:IBMDOS.COM a:COMMAND.COM .

Next make an entry in ~/.mtoolsrc to declare a floppy to be mapped to a file:

drive x: file="/tmp/floppyimage"

Now format a floppy of the desired size, in this example a 2.88 MB floppy, at the same
time writing the bootblock onto it:

mformat -C -t 80 -s 36 -h 2 -B bootblock x:

The size of the "floppy" is only limited by the limits on the number of cylinders, sectors
and heads, which are 1023, 63 and 255 respectively, and the amount of RAM you are willing
to allocate to the "floppy" in memory. As RAM is precious, choose a size slightly bigger
than what is needed to hold your "floppy" files.

Finally, copy all your desired files onto the floppy:

mcopy IBMBIO.COM x:

mcopy IBMDOS.COM x:

mcopy COMMAND.COM x:

mcopy CONFIG.SYS AUTOEXEC.BAT APP.EXE APP.DAT ... x:

For MS-DOS substitute IO.SYS for IBMIO.COM, and MSDOS.SYS for IBMDOS.COM. The case of the
files must be preserved, it may not work if VFAT lower case names are generated in the
floppy image. Pay attention to the order of copying as the boot block may expect the
first two entries on a newly formatted disk to be IO.SYS, MSDOS.SYS. Possibly too
COMMAND.COM has to be the third entry so we play safe. Thanks to Phil Davey and Phillip
Roa for these tips.

I have reports that the bootblock of MS-DOS 6.22 sometimes fails to boot the ramdisk. You
could try using the boot block from Netboot instead of getting the boot block off the
floppy. I have provided this boot block in the distribution as altboot.bin, and in source
form as altboot.S and boot.inc. One essential thing is to make IO.SYS the first file on
the disk, or this bootblock will not work.

If you happen to have a media of the same size you could test if the image is bootable by
copying it onto the media, and then booting it:

dd if=/tmp/floppyimage of=/dev/fd0

Then run mknbi-dos over the image /tmp/floppyimage to create a boot image:

mknbi-dos /tmp/floppyimage > dos.nb

Move dos.nb to where the network booting process expects to find it.

MKNBI-DOS OPTIONS

       --harddisk Make the boot ramdisk the first hard disk, i.e. C:. One reason you might want
       to do this is because you want to use the real floppy. The limit on "disk size" in the
       boot image is not raised by this option so that is not a reason to use this option. This
       option is incompatible with --disableharddisk.

       --disableharddisk When the ramdisk is simulating a floppy disk drive, this switch will
       disable hard disk accesses.  This is necessary if the client should use a network file
       system as drive C:, which is only possible if there are no hard disks found by DOS. This
       option is incompatible with --harddisk.

       --nosquash Do not try to chop unused sectors from the end of the floppy image. This
       increases the boot image size and hence loading time if the FAT filesystem on the floppy
       is mostly empty but you may wish to use this option if you have doubts as to whether the
       squashing algorithm is working correctly.

       --rdbase=0xNNNNNNNN Set the ramdisk load address. The default load address for the ramdisk
       is 0x110000. It can be moved higher (lower will not work) if for some reason you need to
       load other stuff at the address it currently occupies. As this is a linear address and not
       a segment address, the last 4 bits are not used and should be 0.

BUGS

       Please report all bugs to Etherboot users mailing list:
       <https://sourceforge.net/mail/?group_id=4233>

COPYRIGHT

       mknbi is under the GNU Public License

AUTHOR

       Ken Yap

       mk{elf,nbi}-nfl was contributed by Robb Main of Genedyne.

DATE

       See man page footer for date and version. Sorry, not available in the HTML version.