mknbi(1)

NAME

mknbi - make network bootable image

SYNOPSIS

mknbi --version
mknbi --format=format --target=target [--output=output_
file] target-specific-arguments
mkelf-linux [--output=outputfile] kernelimage [ramdisk]
mknbi-linux [--output=outputfile] kernelimage [ramdisk]
mknbi-rom [--output=outputfile] ROM-image
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. Cur rently 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 exist ing 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 ker
nel's query is in addition to the query made by the bootrom, and requires the IP: kernel level autoconfigura
tion (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 configura
tion 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 nec
essary IP addresses for NFS root mounting will be inher
ited 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:host_ name[: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 spec
ify 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 pre
ceding 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 autocon
figuration 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 jump
ing 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. It will have to
be aligned to a 4k byte boundary so you should ensure that
this is so. (The last three hex digits must be 0.)

--first32=program Override the default first stage setup program. It can be used to call extensions to the Ether
boot code, which paves the way for additional useful func
tionality 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 relo cation of the Linux first, boot, setup, and parameter seg
ments to another 64k band. Currently the only valid val
ues 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 BOOTP
vendor defined tags. These can be used to modify the ker
nel 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:

"T"number"=""string"""

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

"T130="eth1""

The following tags are presently supported by mkelf-linux:

129 The string value given with this tag is appended ver batim to the end of the kernel command line. It can be
used to specify arguments like I/O addresses or DMA chan
nels required for special hardware like SCSI adapters,
network cards etc. Please consult the Linux kernel docu
mentation about the syntax required by those options. It
is the same as the --append command line option to mkelflinux, 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 mkelf-linux runtime setup routine does not check the syntax of the string.

The same tags will work in DHCP with the appropriate syn
tax 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 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 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-MENU

mkelf-menu and mknbi-menu make a boot image from an auxil iary 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 specifica
tions of the DHCP tags required is in the vendortags docu
ment in the Etherboot documentation.

Typical usage is like this:

"mkelf-menu" > "menu.nb"

Then put menu.nb in the TFTP boot directory and edit your
DHCP tags 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".

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 environ
ment 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 ~/.mtool_ src:

"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 net work 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 work
ing 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 contain ing 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 distri
bution 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 cre ate 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

BUGS

Please report all bugs to the author.

COPYRIGHT

mknbi is under the GNU Public License

AUTHOR

Ken Yap ("ken_yap@users.sourceforge.net")

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.

docs.sk

komplexný repozitár dokumentácie

Najnavštevovanejšie