mknbi-linux(8)

NAME

mknbi-linux - MaKe NetBoot Image for Linux

SYNOPSIS

mknbi-linux [OPTIONS] [<kernel image> [<output file>]]

DESCRIPTION

mknbi-linux is a program to convert a Linux kernel image into a file suitable for loading by diskless systems using a Bootrom.

OPTIONS

-a, --append STRING: String to append to the end of the kernel command line.

-b, --batch-sys SYS: Lets mknbi-linux operate in batch mode. It will look up the given system name in a database file and generate a netbootable image according to the parameters given in the database entry. If this option is not given, mknbi-linux will operate according to the other command line options. If giving any other options in addition to -b or --batch-sys, the parameters found in the database will override those processed from the command line.

-C, --config-file FILE: Specifies a configuration file.

-d, --root-dir STRING: Define name of directory to mount via NFS from the boot server. If rom is given, that directory is used as root in which the loaded netboot image file is located. This is determined by the Bootrom at run time, usually by using the BOOTP-Protocol. If the BOOTP Server is able to handle the RFC 1497 extensions, it is possible to define a different root directory. With kernel the directory name is the default name used by the kernel. Giving ram the kernel will use a ramdisk for booting, and no NFS directory will be mounted. Also if the name given to the -d or --root-dir option starts with "/dev/", the corresponding device is used as the root device, and no NFS directory will be mounted. The default for this option is /tftpboot/%s, with the %s representing the IP-Number of the booting system.

-h, --help: Print short usage information.

-i, --ip-addrs STRING: Define client and server IP addresses. If rom is given as the argument to this option, all necessary IP addresses for NFS root mounting will be determined at runtime using the BOOTP answer the Bootrom got from the server. This is the prefered value when using mknbi-linux together with a Bootrom.

With kernel no IP addresses are defined, and the kernel should determine them by itself, usually by using RARP or BOOTP. If the -i or --ip-addrs option is missing this is the default.

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:

client:server:gateway:netmask:hostname[:dev]

Using this option mknbi-linux will automatically convert system names into decimal IP addresses for the first four 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 are 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.

-k, --kernel FILE: Pathname of kernel image file. The default is /vmlinuz.

-l, --ramdisk-mode

The startup code that will be include in the netboot image, can usually take care of moving the ramdisk image to a valid location in memory. But depending on the version of your BIOS, the kind of Bootrom you use, and the fact that you might have more than 16MB of memory, there could be difficulties. In this case, you will have to provide further information:

auto: This is the default behavior. The Bootrom will load the ramdisk image at address 0x100000 (if the kernel is already loaded there, the ramdisk image will be moved right behind the kernel image). The startup code will then try to determine the last legal address in the lower 16MB and subsequently move the ramdisk image there. This technique will work in most cases and provides the highest degree of compatibility and portability among different machines.

eom: If auto does not work for you, you should check if your Bootrom is capable of loading the ramdisk image to the end of the physical memory. This might work fine, but it is slightly less compatible than auto.

<address>: If everything else fails, you can resort to explicitly specifying the load address. Although beware that this is likely to cause problems, when trying to use the same image on machines with different amounts of memory. You should try to specify an address that is both below 16MB and below the physical end of memory; you will have to leave enough room for the entire (compressed) ramdisk image. If you move the image too low, it will collide with the uncompressed kernel image and the kernel will ignore the contents of the ramdisk; you will notice a warning message, when booting. If you have at least 16MB of main memory, you should try to load the image to 0xD30000, as this leaves enough room for an uncompressed 2.88MB ramdisk image, but is unlikely to conflict with the uncompressed kernel image. If you want to see if there is a conflict between the ramdisk image and other parts of the compiled netboot image, you can increase the verbosity level until detailed load record information is printed.

-N, --netboot-dir DIR: Specifies the path of the main netboot directory.

-o, --outfile FILE: Pathname of output file, which is lateron loaded by the Bootrom via tftp.

-r, --ramdisk-image DIR|FILE: Preloaded ramdisk image; for further information look into linux/Documentation/initrd.txt in the Linux source tree. This requires Linux V1.3.73 or above.

-s, --cmdl-size SIZE: Maximum size of command line. This parameter specifies how much memory the boot loader should reserve for assembling the kernel command line. It is useful if you have a very long kernel command line, for example by using the -a option. If the kernel command line is longer then the number of bytes specified, it gets truncated automatically. The lowest usable value for this parameter is 2048, which is also the default. Use -s or --cmdl-size only if you know what you are doing because it can scramble the memory layout of the boot loader.

-v, --version: Print version information.

-x, --verbose: Verbose output to let you know what mknbi-linux is doing. Each -x increases the verbosity level.

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

T<number>="<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 -a or --append command line option to mknbi-linux, but works at runtime instead of compile 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 -i option as described above. However note that the mknbi-linux runtime loader does not check the syntax of the string.

DATABASE FILE

mknbi-linux does not use any sections in the configuration file except the [general] section. However, for easier maintenance of different client configurations the database file can be used. The entries have to be preceded by a [<system name>:mknbi-linux] tag and can contain the following parameters:

outfile: Specifies the name of the output file

ramdisk-image: Specifies the name of the ramdisk image file or directory

ramdisk-size: Specifies the size of the ramdisk. This parameter works like the -s or --ramdisk-size command line arguments. The ramdisk size gets therefore determined in the same way as described above.

append: Adds a string verbatim at the end of the Linux kernel command line.

skip-check: This boolean parameter specifies wether to skip certain compatibility checks.

no-hard-disk: Boolean parameter which specifies if to allow hard disk accesses in the client or not.

simulate-hd: This boolean parameter allows the ramdisk to simulate a hard disk in the client.

BUGS

None known yet

AUTHOR

mknbi-linux was written by Gero Kuhlmann <[email protected]>. Support for preloaded ramdisks and loading into extended memory has been added by Markus Gutschke <[email protected]>.