NAME

mknbi - make network bootable image


SYNOPSIS

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

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

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

mknbi-rom [--output=outputfile] ROM-image

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.

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.


MKNBI-LINUX

mknbi-linux makes a tagged image from a Linux kernel image, either a zImage or a bzImage.


MKNBI-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.

--ip=string Define client and server IP addresses. --ipaddrs=string is a synonym for the same thing.

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. Note: In Linux kernels 2.2.x where x >= 18, 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 in the 2.2 series, IP autoconfiguration does not happen by default.

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 seperated by a colon, and ordered in the following way:

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

Using this option mknbi-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.)

--first16 Use old first stage setup program (first-linux.S). By default the new first stage setup program (first32.c) is used. The new setup program has some advantages, including being able to detect memory > 64 MB and in general being more maintainable. --first16 is only valid for tagged images, not ELF. It will be ignored if specified with ELF.

--first32pm[=program] Use a more efficient protected mode call protocol for the first stage setup program. This requires Etherboot ROMs version 5.0 and above and so is not enabled by default. It can also 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. When a program is not specified, the default is to use the standard first stage setup program suitable for booting a Linux kernel. --first32pm is implied by the ELF format and does not have to be specified in this case.

--progreturns This option is used in conjunction with and only valid with the --first32pm 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.

Run the program thus:

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

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


MKNBI-LINUX BOOTP/DHCP VENDOR TAGS

mknbi-linux includes a startup code at the beginning of the Linux kernel which is able to detect certain BOOTP vendor defined tags. These can be used to modify the kernel loading process at runtime. To use these tags with bootpd, a publicly available BOOTP server daemon, you can use the following syntax in the /etc/bootptab file:

Tnumber="string"

For example, to specify a different root NFS device, you can use:

T130="eth1"

The following tags are presently supported by mknbi-linux:

129 The string value given with this tag 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 mknbi-linux, but works at boot time instead of image build time.

130 With this tag 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 mknbi-linux runtime loader does not check the syntax of the string.

The same tags will work in DHCP with the appropriate syntax for your DHCP server configuration file.

Remember that you need to specify tag 128 in the correct format in order for the previous tags to be valid. See the documentation file vendortags.


MKNBI-ROM

mknbi-rom makes a tagged image from an Etherboot .rom or .lzrom boot ROM image. This allows it to be netbooted using an existing ROM. This is useful for developing Etherboot drivers.

Run mknbi like this:

mknbi-rom nic.lzrom > 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.


MKNBI-FDOS

mknbi-fdos makes a tagged image from a FreeDOS kernel file and a floppy image. Note that the kernel image is not read from the floppy section of the tagged image, but is a separate section in the tagged 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:

ftp://ftp.gcfl.net/freedos/kernel/

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.

--nosquash Do not try to chop unused sectors from the end of the floppy image. This increases the tagged 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.


MKNBI-DOS

mknbi-dos makes a tagged 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:

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):

mcopy a:ibmbio.com a:ibmdos.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 case a 2.88 MB floppy, at the same time writing the bootblock onto it:

mformat -C -t 160 -s 18 -h 2 -B bootblock x:

Finally, copy all your desired files onto the floppy:

mcopy ibmbio.com ibmdos.com config.sys autoexec.bat app.exe app.dat ... x:

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 tagged 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.

--nosquash Do not try to chop unused sectors from the end of the floppy image. This increases the tagged 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.


BUGS

Please report all bugs to the author.


SEE ALSO

Etherboot tutorial at http://etherboot.sourceforge.net/ Mtools package is at http://wauug.erols.com/pub/knaff/mtools/ Make sure you have a recent version, the ability to map a drive to a file is not present in old versions.


COPYRIGHT

mknbi is under the GNU Public License


AUTHOR

Ken Yap (ken_yap@users.sourceforge.net)


DATE

Version 1.1 December 2000