MKNBI-DOS(8)

📦 version 0.10.2, in nixos 26.05, nixpkgs unstable

🌸 NAME 🌸

Okay bestie, meet mknbi-dos from section 8 — MaKe NetBoot Image for DOS. It’s literally the “turn a DOS boot disk image into something a diskless machine can load” program, and the vibes are very netboot main character. ✨

✨ SYNOPSIS ✨

mknbi-dos [OPTIONS] [<ramdisk> [<output file>]]

💖 DESCRIPTION 💖

Okay so mknbi-dos is a program that converts a DOS boot disk image into a file that diskless systems can load directly, using a bootrom that’s compliant with the netboot specification. No cap. 🫶

It supports several DOS variants: MS-DOS®, IBM-DOS (which has also been called PC-DOS®), PTS-DOS®, OpenDOS®, NovellDOS® and FreeDOS. Literally a whole DOS friend group. 💅

🎀 OPTIONS 🎀

  • -b, --batch-sys SYS — Puts mknbi-dos in batch mode. It looks up the given system name in a database and generates a netbootable image according to the parameters in that database entry. If this option is not given, mknbi-dos operates according to the other command line options. If you give any other options in addition to -b or --batch-sys, the parameters found in the database override the ones processed from the command line. Database said what it said, bestie. 👑
  • -c, --simulate-hard-disk — Lets the ramdisk get mounted as a virtual hard disk instead of a floppy drive. Only floppy drives can be removed lateron, but a hard disk image can have a user-selectable size. Choices, choices. 💅
  • -C, --config-file FILE — Specifies the pathname of the configuration file. If this option is not given, the value of the NETBOOT_CONFIG environment variable or a compiled-in default will be used. ✨
  • -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 is not given, the value of the NETBOOT_DATABASE environment variable or a compiled-in default will be used. See the netboot(5) man page for a further explanation of different ways to specify a database. 🗂️
  • -F, --logfile — Name of log file to write debugging output to. The default is to print all verbose output to stdout. Yes, this is the first -F on the page — there’s another one later, and that’s exactly what the manual says. Chaotic but iconic. 🫠
  • -h, --help — Prints short usage information. The “help me bestie” button. 🫶
  • -H, --home-dir — Specifies the home directory. If this command line option is not given, either the homedir configuration file parameter or the current user’s home directory will be used. 🏠
  • -i, --use-int-15 — The bootrom loads the ramdisk into high memory. After DOS has started, the ramdisk contents have to be protected against getting overwritten. To do this, the ramdisk driver tries to identify an XMS driver like HIMEM.SYS once it has been loaded, and tells it that the memory area used by the ramdisk is occupied. Unfortunately, sometimes this doesn’t work — the HIMEM.EXE of FreeDOS is known to not work properly. In these cases the ramdisk driver uses a different method of protecting the ramdisk contents called interrupt 15h protection. mknbi-dos tries to automatically identify those DOS versions which are known to not provide a properly working XMS driver. If this check doesn’t work correctly for your DOS version, or you are not loading an XMS driver at all on the diskless client, you should use this option to protect the ramdisk from getting overwritten by a program. 😭
⚠️ However, when using this option, the memory occupied by the ramdisk can’t get reclaimed lateron when the ramdisk is no longer needed. It then remains as unusable memory. So yes, it’s a whole tradeoff, and the manual is being very clear about it. 💀
  • -k, --keep STRING — After the boot image gets loaded, the bootrom will disable all its services and pass control to the DOS loader. This option controls how much of the bootrom PXE services interface will be removed before calling the loader. STRING can have the following values: 🎛️
    • none — Don’t keep anything in memory when DOS gets started. This is the default if this option has not been given.
    • undi — Only keep the UNDI interface in memory and remove all base code, which is responsible for all higher protocols like IP and UDP within the bootrom. With this option, DOS can access the basic network adapter functions using the UNDI interface as specified by the Preboot eXecution Environment (PXE) specification.
    • all — Keep all parts of the bootrom in memory when starting DOS. This keeps the base code in memory in addition to the UNDI interface. While it is possible to use the UDP and TFTP functions according to the PXE specification, it effectively prevents running your own TCP/IP stack on top of the UNDI interface.
🚨 This option will only have an effect with bootroms which support PXE. With netboot bootroms older than version 0.9, specifying anything other than none may give unpredictable results. Not me being dramatic — it’s literally in the manual. 💀
  • -l, --no-rpl — In order to allow DOS to access the ramdisk, the primary boot loader has to permanently install a ramdisk driver before DOS gets started. This driver has to get protected from getting overwritten. To protect the driver, certain versions of MS-DOS®, PC-DOS® and OpenDOS® use a mechanism called RPL protection, which allows reclaiming the memory occupied by the ramdisk driver lateron when it’s no longer needed. However, older DOS versions or some other DOS brands (like FreeDOS) don’t support this RPL protection. mknbi-dos tries to identify the DOS version correctly, but this might not work with all different kinds of DOS. If your diskless client breaks after starting DOS, you should try to use this option. The primary loader will then use a different method of protecting the ramdisk driver. 💅
💀 If your diskless client breaks after starting DOS, this is the “try this, bestie” option. The manual said it, not me.
  • -n, --no-hard-disk — When the ramdisk is simulating a floppy disk drive, this switch disables 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. Network drive supremacy, no cap. 🌐
  • -N, --datadir DIR — Pathname of the shared-data directory. If this option is not 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 is not given, the value of the NETBOOT_LIB environment variable or a compiled-in default will be used. 📚
  • -o, --outfile FILE — Pathname of the output file, which is lateron loaded by the bootrom via TFTP. This is the file that gets the whole glow-up. ✨
  • -r, --ramdisk-image DIR | FILE — Pathname of the ramdisk image. This can either be a file, a block device or a directory. If the pathname is a file or block device, it is treated as a bootable DOS ramdisk image, and the boot sector defined in this image will be used. Otherwise, if the pathname is a directory, mknbi-dos will treat all files in that directory as MS-DOS files and will create a ramdisk image with a DOS filesystem and a simple boot sector in it. The directory has to contain at least the files IO.SYS, MSDOS.SYS and COMMAND.COM. Alternatively, it can also contain the corresponding files for PC-DOS®, OpenDOS® or FreeDOS. So many legacy files, so little time. 🦋
  • -s, --ramdisk-size SIZE — Size of the ramdisk in kB, which can not be smaller than that of the ramdisk image. If this option is missing, then for a hard disk simulation the default is to provide approximately 20% free space within the ramdisk. For a ramdisk simulating a floppy, the size defaults to 1.44 MB. This option can be used with or without the -c option. However, when it is used without -c then the specified ramdisk size has to be one of 320, 360, 720, 1200, 1440 or 2880. Otherwise, any arbitrary ramdisk size can be selected as long as it is large enough to hold the ramdisk contents. Size matters, but only within the manual’s rules. 💅
  • -S, --save-sys SYSTEM — This option lets you save the parameters for a netboot image into the systems database using the name SYSTEM. Lateron, it is no longer necessary to type all command line arguments to mknbi-linux again, but you can use the -b or --batch-sys option to generate a new netboot image. Yes, the page really says mknbi-linux here — iykyk 🙈
  • -F, --single-fat — Normally the ramdisk will be built with two File Allocation Tables (FAT) like with normal DOS disks. DOS uses two FATs in case one becomes unreadable on the disk. Since the ramdisk can’t fail, two FATs are not absolutely necessary, so mknbi can also create a filesystem with just one FAT using this command line option. This gives slightly more ramdisk space for user files. And yes — this is the other -F, same short flag as --logfile. The page said it, I’m just reporting. 🫠
  • -V, --volume-name STRING — Set the ramdisk volume name. The STRING argument should not exceed 11 characters. When this option is not given, no volume name will be set. Note that setting a volume name can cause problems on very old MS-/PC-DOS versions. In order for some DOS tools (like Windows-9x) to recognize the ramdisk, the volume name should be set to MS-RAMDRIVE. Name your drive wisely, bestie. 🏷️
  • -v, --version — Print version information. The “who am I” moment. 👑
  • -x, --verbose — Increase verbosity level. Let it yap. 🗣️

🦋 RAMDISK SIZE 🦋

The actual size of the ramdisk is determined by several parameters. When the ramdisk is going to simulate a floppy drive, only the standard floppy sizes are available: 320, 360, 720, 1200, 1440 or 2880 kB. If the -s or --ramdisk-size options are not used, the default ramdisk size will be 1440 kB. 💾

When the ramdisk is going to simulate a hard drive by using the -c or --simulate-hard-disk switch, the default ramdisk size is determined so that the ramdisk will have approximately 20% free space. If using the -s or --ramdisk-size options, the ramdisk size will be determined by the option argument. It can have any value larger than 360 and is not restricted to the standard floppy values mentioned above. The maximum value is 262144. So yes, you can go big — but not infinite. ✨

🧠 MEMORY MANAGEMENT 🧠

okay so here's the situation, bestie. The bootrom loads the image file that mknbi-dos made, so that the ramdisk image sits at the start of extended memory on the client. Cute, right? Except… when DOS starts, that memory area is not protected in any way against being clobbered by client programs. 💀 So like, anything can just wander in and ruin it.

But! If the ramdisk driver notices that a XMS driver like HIMEM.SYS got loaded, it'll use it to allocate a XMS memory block and protect the ramdisk. Iconic behavior honestly. 🫶

Unfortunately — and this is the messy part — HIMEM.SYS, starting with version 3.10, does a check of extended memory which destroys the ramdisk image. 😭 So your options are:

  • use a version of HIMEM.SYS prior to 3.10, or
  • use the command line option /TESTMEM:OFF.

When you're booting OpenDOS® you have to load HIMEM.SYS before starting EMM386.EXE, even though the documentation and the screen messages say that the HIMEM.SYS functionality is incorporated within EMM386.EXE. Like, they say one thing and reality says another, no cap. Unfortunately, when loading EMM386.EXE alone the ramdisk image gets corrupted for some reason. The only way to prevent that is explicitly using HIMEM.SYS with OpenDOS®.

So if you choose not to use an XMS driver, or when you don't have a driver which works correctly (like HIMEM.EXE provided by FreeDOS), you should use the -i or --use-int-15 command line option to protect the ramdisk contents. ✨

mknbi-dos tries to automatically determine when this interrupt 15h memory protection should be used, but ng l this test is not very reliable, because there are so many different versions and brands of DOS floating around. It's giving chaos out here. 🌈

Wanna remove a ramdisk? Use the program rmrd.com — it not only restores access to the physical drive which has been replaced by the ramdisk, but also frees all memory (including extended memory) used by the ramdisk image. Obsessed. But heads up: a ramdisk can only be removed if it is simulating a floppy disk drive (see option -c above). In a standard installation rmrd.com lives in the directory /usr/local/share/netboot/misc.

💾 DOS RAMDISK DRIVER 💾

When mknbi-dos gets installed on the host system, an additional file nbramdrv.sys gets installed too — usually into the directory /usr/local/share/netboot/misc. This file contains a DOS ramdisk driver which replaces the ramdisk driver installed on the diskless client by the primary netboot loader. 🎀

Note that the file nbramdrv.sys can only be executed on a DOS netboot client.

You can copy it into the ramdisk image of your diskless client and modify the file config.sys to contain a line which looks like:

devicehigh=nbramdrv.sys /verbose

It should appear AFTER calling the XMS driver. ⭐

The effect? A ramdisk driver gets installed into DOS which represents an ordinary DOS device driver, and does not simulate a fake disk drive like the one installed by the primary netboot loader. After nbramdrv.sys has been loaded, the initial ramdisk driver will be removed from memory (just like it's done with rmrd.com), but the ramdisk will remain accessible using the same drive letter as before. Slay. 💅

Another way of operation is by giving the /newdrive command line option to nbramdrv.sys. In this case nbramdrv.sys does not remove the old ramdisk driver, but will install the ramdisk as a new drive — for example drive C: (if no hard disk is installed) or drive D: (with a one-DOS-partition hard disk installed). Since after calling nbramdrv.sys this way there are two ramdisk drivers installed (the old one and the new one), in order to avoid problems the new drive will be automatically set to read-only initially. Lateron you can remove the old driver with rmrd.com when it's no longer needed, and then the new ramdisk drive becomes writable. 🔥

Without nbramdrv.sys the ramdisk appears to DOS and any other program like a physical disk connected to a physical controller. Some programs like Windows therefore try to directly access the controller to which the ramdisk is supposed to be connected to — but will obviously fail. 🙈 nbramdrv.sys makes the ramdisk appear as a logical drive without a physical controller, which is a lot closer to reality. Main character energy.

⚠️ Note that after installing nbramdrv.sys from the config.sys file there is no way of removing the ramdisk lateron. When using the /newdrive command line option the old ramdisk driver can be removed using rmrd.com, but in any case, once nbramdrv.sys has been loaded the newly installed driver can't be removed anymore. Fr fr, be sure before you commit.

nbramdrv.sys supports the following command line options:

  • /VERBOSE — print out some more or less useful information. 😌
  • /READONLY — make the ramdisk readonly.
  • /NEWDRIVE — install the ramdisk as a new drive instead of replacing the old initial ramdisk driver. When the old driver is no longer needed it should be removed with the rmrd.com command.
  • /SIMPLE — only provide a smaller subset of device driver commands to DOS. This option might be necessary for some DOS variants which can't cope with MS-DOS 7.x extensions to the device driver interface.
  • /DHCP=[ON|OFF] — save the DHCP/BOOTP information record provided by the bootrom into some XMS memory. Presently there is no application available which can make use of this information. The default is ON.

🗂️ DATABASE FILE 🗂️

mknbi-dos 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-dos:<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-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.
  • 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.
  • no-rpl — boolean parameter which specifies to not use the RPL method of protecting the initial ramdisk driver, but use an alternative way.
  • use-int-15 — this boolean parameter tells the diskless client to not use an XMS driver to protect the ramdisk contents.
  • single-fat — this boolean parameter specifies to install just one FAT into the ramdisk file system. Without this parameter or when it's value is FALSE two FATs will be installed.
  • volume-name — specifies the volume name of the ramdisk image. This name should not be longer than 11 characters.
  • keep — specifies which parts of the bootrom should be kept in memory when DOS gets started. It works exactly like the -k or --keep command line options, and therefore has to have one of these values: none, undi, all.

🌱 ENVIRONMENT VARIABLES 🌱

See the netboot(5) man page for a description of all environment variables used by mknbi-dos. Go read that one too, bestie, it's got the lore. 📖

™️ TRADEMARKS ™️

The names Windows®, MS-DOS®, PC-DOS®, PTS-DOS®, NovellDOS®, OpenDOS® and DR-DOS® are registered trademarks of their respective owners. Respect the paperwork, periodt. 💅

🐛 BUGS 🐛

None known yet. ✨ (iconic, honestly — we love a clean slate 🎀)

👀 SEE ALSO 👀

netboot(5), netboot.config(5)

👑 AUTHOR 👑

mknbi-dos was written by Gero Kuhlmann <gero@gkminix.han.de>. Thank you Gero, you ate. 🫶

and that's the whole page, bestie — brought to you by the 15 Nov 2002 build of MKNBI-DOS(8), which is literally vintage at this point 💜✨ go forth and boot responsibly 🦋

📦 where this page comes from