MKNBI-LINUX(8)

📦 version 0.10.2, in nixos 26.05, nixpkgs unstable

💅 mknbi-linux — MaKe NetBoot Image for Linux

okay so bestie, welcome to the mknbi-linux(8) page — yes it's section 8, System Manager's Manual, very official, very demure. This is the tool that takes your Linux kernel and turns it into something your diskless babies can actually boot. Buckle up 🎀

✨ SYNOPSIS ✨

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

that's it. that's the whole vibe. options go in, kernel goes in, output file goes out. slay 💅

🌸 DESCRIPTION 🌸

so mknbi-linux is literally the program that converts a Linux kernel image into a file which is directly loadable by diskless systems using a bootrom that's compliant with the netboot specification. that's the whole job. it eats kernels and spits out netbootable images. iconic behavior, honestly 🦋

👑 OPTIONS 👑

okay this is the long part, stay with me, we're getting through all of them together fr fr 🫶

  • -a, --append STRING — string to append to the end of the kernel command line. so by default the kernel command line starts with auto rw, which tells the kernel to automatically check and mount all file systems and to mount the root file system read-write. but bestie, if you want your root file system mounted read-only, use the word ro with the -a option instead of rw. likewise, if you want to remove the word auto from the command line, use noauto with the -a option. and yes, you can also drop any other command line options here that the kernel needs. go off 💖
  • -b, --batch-sys SYSTEM — puts mknbi-linux into batch mode. it looks up the given system name in a database file and generates a netbootable image according to the parameters specified in that database entry. if this option is not given, mknbi-linux operates according to the other command line options instead. and heads up: if you give any other options in addition to -b or --batch-sys, the parameters found in the database override those processed from the command line. database said what it said 💀
  • -C, --config-file FILE — specifies the pathname of the configuration file. if you don't pass this option, the value of the NETBOOT_CONFIG environment variable gets used, or a compiled-in default. no cap 🧚
  • -d, --root-dir STRING — defines the name of a directory to mount via NFS on the boot server. STRING can have the following values, and each one is a whole mood:
    • rom — 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 BOOTP or DHCP. and if the boot server is able to handle RFC 1497 extensions, it's possible to define a different root directory than the one where the image file is located. flexible, we love to see it ✨
    • kernel — the root directory is the one used by the loaded kernel as its compiled-in default. simple, no drama.
    • ram[0-9] — tells the kernel to use a ramdisk for booting. no NFS directory will be mounted in that case. if a number is given, that numbered ram disk will be used for the root directory. otherwise, if no number is given, the initial ram disk of the kernel is used. numbered ramdisks are so main character 🔥
    • initrd — this uses the initial ramdisk as the root directory, so it's therefore the same as ram0. however (and this is the important part), with the initrd root device specification the boot loader will not pass any IP autoconfiguration option to the kernel, and the initial ramdisk has to set up the network interface itself if necessary. also the kernel command line will be built so that /linuxrc will be started by the kernel as the first process — see the initrd documentation for further info iykyk 🌈
    • <directory name> — compiles the directory name directly into the boot image. it will be used by the kernel for its root directory, and there is no way later on to change it at run time. 😭 this is the default when this option isn't given, and the default directory name is /tftpboot/%s, with the %s representing the IP address of the booting system. and hey — if the directory name starts with /dev/, that named device is used as the root device, and no NFS directory will be mounted. periodt.
  • -D, --database FILE|DBSPEC — pathname of the database file (or database specification) to be used together with the -b or --batch-sys options. if this option isn't given, the value of the NETBOOT_DATABASE environment variable or a compiled-in default will be used. check the netboot(5) man page for a further explanation of the different ways to specify a database 🦋
  • -F, --logfile — name of the log file to write debugging output to. the default is to print all verbose output to stdout. very "we're doing it live" of it 💅
  • -h, --help — prints short usage information. the classic. the icon. when in doubt, -h it out 🎀
  • -H, --home-dir — specifies the home directory. if this command line option isn't given, either the homedir configuration file parameter or the current user's home directory will be used. home sweet home 🏠
  • -i, --ip-addrs STRING — defines client and server IP addresses. STRING can have the following values:
    • rom — all necessary IP addresses for NFS root mounting will be determined at run time using the BOOTP or DHCP answer the bootrom received from the server. this is the preferred value when using mknbi-linux together with a netboot bootrom. bestie this is the good one ⭐
    • kernel — no IP addresses are defined, and the kernel should determine them by itself, usually by using RARP, BOOTP or DHCP. letting the kernel handle it, bold of you, respect 🙈
    • <client:server:gateway:netmask:hostname[:dev[:proto]]> — define the necessary boot addresses during compilation of the boot image. all addresses must be separated by a colon. 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 and shouldn't contain any domain name part. when more than one network interface is installed in the diskless client, it's possible to specify the name of the interface to use for mounting the root directory via NFS by giving the optional dev value. 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 colon) can be left out, or remain empty. the proto entry is only usable with kernel version 2.2.x or newer and can be used to specify the protocol with which the kernel should detect any missing addresses. it can have one of the following values: off, none, on, any, dhcp, bootp, rarp or both. that's a lot of colons but you got this 🫶
  • -k, --kernel FILE — pathname of the kernel image file. the default is /vmlinuz. your classic, your default, your girl 💜
  • -l, --ramdisk-mode — okay so the startup code that gets included with 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 that case, you'll have to provide further information:
    • auto — this is the default behavior. the bootrom will load the ramdisk image 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 works in most cases and provides the highest degree of compatibility and portability among different machines. the reliable friend of the group ✨
    • eom — if auto doesn't 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's slightly less compatible than auto. proceed with awareness 💀
    • <address> — if everything else fails, you can resort to explicitly specifying the load address. although, beware: 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 — and you'll 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'll notice a warning message when booting. if you have at least 16MB of main memory, you should try to load the image to 0xD30000, since 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 whether there's 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. detective mode 🔍
ngl this one is giving "please read the numbers twice" energy. 0xD30000, 16MB, 2.88MB. don't come for me, that's what the page says 💅
  • -m, --vga-mode MODE — specifies the mode into which to set the graphics card when the Linux kernel starts. MODE can be any of these values:
    • normal — use normal VGA mode, which is what the BIOS has selected when the bootrom started.
    • extended — switch to a larger screen size. bigger screen, bigger vibes 🦋
    • ask — ask the user which mode to use when the Linux kernel starts. the user gets presented with a menu of possible video modes. very "you decide, bestie" of it 🎀
    • default — use the VGA mode value defined in the Linux kernel and don't allow mknbi-linux to change it. this is the default behaviour if the --vga-mode option is missing. leave it alone, it knows what it's doing.
    • <number> — directly specify the video mode. raw. unhinged. iconic. 🔥
  • -N, --datadir DIR — pathname of the shared-data directory. if this option isn't given, the value of the NETBOOT_DATA environment variable or a compiled-in default will be used 🌸
  • -L, --libdir DIR — pathname of the non-shared-data directory. if this option isn't given, the value of the NETBOOT_LIB environment variable or a compiled-in default will be used. note the difference from -N, they're siblings not twins 💜
  • -o, --outfile FILE — pathname of the output file, which is later on loaded by the bootrom via TFTP. this is your product, your masterpiece, your little creation 👑
  • -r, --ramdisk-image FILE — preloaded ramdisk image. for further information, look into linux/Documentation/initrd.txt in the Linux source tree. this requires Linux version 1.3.73 or above. yes i said the number out loud, it's old, we respect the elders 🫶
  • -S, --save-sys SYSTEM — okay so this one saves your netboot image parameters into the systems database under the name SYSTEM 🫶. After that, you don’t have to retype all the command line arguments to mknbi-linux again — just use the -b or --batch-sys option to generate a new netboot image. Iconic lazy-girl win 💅.
  • -v, --version — prints version information, periodt ✨.
  • -x, --verbose — verbose output so you actually know what mknbi-linux is doing 👀. Each -x increases the verbosity level — stack ’em if you’re nosy.

✨ BOOTP VENDOR TAGS ✨

mknbi-linux includes a startup code at the beginning of the Linux kernel which is able to detect certain BOOTP or DHCP 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 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 [mknbi-linux:<system name>] 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-mode — specifies the mode of the ramdisk like the -l or --ramdisk-mode command line options.
  • vga-mode — specifies the mode to set the graphics card into when starting the Linux kernel like the -m or --vga-mode command line options.
  • append — adds a string verbatim at the end of the Linux kernel command line.
  • root-dir — specifies the name of the client root directory like the -d or --root-dir command line options.
  • ip-addrs — specifies the Linux kernel IP address option like the -i or --ip-addrs command line options.
  • debug — Boolean value which specifies if the debugging version of the kernel loader should be used on the client or not.

🌱 ENVIRONMENT VARIABLES 🌱

See the netboot(5) man page for a description of all environment variables used by mknbi-linux. 👑

💀 BUGS 💀

None known yet 😭✨.

🫶 SEE ALSO 🫶

👑 AUTHOR 👑

mknbi-linux was written by Gero Kuhlmann <gero@gkminix.han.de>. Support for preloaded ramdisks and loading into extended memory has been added by Markus Gutschke <gutschk@uni-muenster.de>. 💖

okay bestie, that’s the whole tea ☕ — this page is MKNBI-LINUX(8), dated 25 Jul 2002 🌈💅. Catch you in the next man page! 🫶✨

📦 where this page comes from