netboot(5)

📦

version 0.10.2 · 2 versions

0.10.2 · nixos 26.05 (latest)
0.10.2 · nixpkgs unstable

💻 netboot(5) — File Formats Manual 💻

okay bestie, this is netboot(5) from the File Formats Manual, and it's literally the lore drop for the netboot package's programs, files, and config-file energy. 🫶 no cap, we're keeping every detail.

🌸 PROGRAMS 🌸

The netboot package contains the following programs to generate bootroms and load image files using an IP network in order to boot a x86-based system:

makerom — generates a bootrom from various binary files. It can use many types of network drivers like standard DOS packet and NDIS driver binaries. 👑
mknbi-linux — generates a netbootable image to load the Linux operating system. 🐧
mknbi-dos — generates a netbootable image to load a DOS-like operating system, like MS-DOS® or OpenDOS®. 💾
mknbi-mgl — generates a netbootable image from a program written in the Pascal-like Menu Generation Language (MGL). With this program it is easily possible to write a custom boot menu. 🎛️

See the corresponding man page for a further explanation about any of the above mentioned programs.

🎀 FILES 🎀

/nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/etc/netboot.config — main netboot configuration file. 💖
/nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/config.local — local additions to the configuration file. While the master configuration file gets overwritten by installing a new netboot version, the config.local file never gets modified by the installation process. 🫶
/nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/netboot.db — systems database file. 🗂️
/nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot/netboot.drivers — network driver information database. This is a text file which contains the descriptions of individual network drivers. It gets replaced without asking everytime a new netboot version gets installed. 🔥
/nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/drivers.local — local additions to the network driver information database file. This file never gets modified by the installation process. ✨

These files control the operation of the various programs which are part of the netboot project. While the configuration file contains general definitions for the programs, the systems database contains specifications for client systems. Using this approach, it is for example possible to give a system name on the command line of mknbi-linux and then automatically have the boot image file created with the correct Linux kernel and NFS root parameters. This makes it easier to maintain a large base of diskless clients with different configurations.

The network driver information database contains specifications needed to find and use certain pre-known network drivers like packet or NDIS drivers.

All configuration files have a common format. Each file is divided into sections. Each section has to be preceded by a section name enclosed in square brackets, and reaches until the next section name or the end of the file. There are no blanks allowed between the square brackets and the section name. The name itself can contain any alphanumeric character, and may be split into different parts, which are separated by colons. For example, that section in the main configuration file which is used by makerom and contains its general definitions is named [makerom:general].

Each section contains a number of definitions, which start with a parameter name, followed by an equal sign and the parameter value. Depending on the type of parameter, the value can either be a string, a number, a boolean value or an enumeration value. In case of a number, the usual C conventions apply. For example, prepending the number with 0x identifies it as a hex number. Boolean parameters can either have a value of false or true. Enumeration parameters can have a value out of a list of allowed strings. In case of a string value, leading (between the equal sign and the first string character) and trailing (following the last string character) blanks are ignored. Blanks enclosed by some other string characters are copied into the string unmodified. If leading and/or trailing spaces, carriage-returns or # characters are required in a string argument, the whole string can be enclosed in double quotes. Also, if the string can be interpreted as some other type (like an integer number or a boolean value) it has to be enclosed in double quotes.

If a string value names a directory or file, it is possible to make these paths relative to either the non-shared-data directory /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot or the shared-data directory /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot by prepending the string with two slashes. All netboot programs then search for the corresponding file or directory in both paths. For example, specifying //utils gets expanded to /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/utils and /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot/utils when the configuration file is read. Also, many directory parameters can specify more than one directory. All directories in such a specification have to be separated by colons within the string, and are searched in turn for the required file. For example, specifying //utils://binaries as a directory name will let a program search the directories /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/utils, /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot/utils, /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/binaries and /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot/binaries for a required file, in this order. This is somewhat similar to specifying the PATH variable in the shell.

Everything including and following a # character up to the end of the line is ignored as a comment. Empty lines are also ignored, as well as leading and trailing blanks on a line. Therefore, tag names and parameter definitions can start anywhere on a line. Between the parameter name, the equal sign and the parameter value any number of spaces may be placed. Parsing of all configuration files is case significant. Especially, the boolean and enumeration values as well as parameter names have to be all lower case.

🧚 meta-commands, because ofc 🧚

All configuration files can make use of meta-commands, which modify parsing their contents. Text file meta-commands always start with a dollar sign, and have to be placed on a line by their own. They can appear anywhere in the text. The following meta-commands are implemented:

$if [not] <condition> — the $if meta-command allows processing of the following text according to certain conditions. If the condition is met, the text following the $if meta-command is processed until reaching a corresponding $else or $endif meta-command. If the word not is inserted in front of the condition code, the condition is inverted, e.g. the following text is processed if the condition is not met. These condition codes have been implemented:
- exists <filename> — the condition is met if the file <filename> exists and is readable. Normal preprocessing of the file name is used (e.g. substitution of two starting slashes as described above).
- defined <variable> — the condition is met if the variable named <variable> is defined. See the $set meta-command about setting a variable.
- equal [<string>|<variable>] , [<string>|<variable>] — the condition is met if both strings or variable contents are equal. Strings have to be enclosed in double-quotes.

Up to 16 levels of $if meta-commands can be nested into each other. 🌀

$else — this meta-command starts the else-branch of a $if meta-command. This means that the text following the $else is parsed if the corresponding $if condition is not met.
$endif — this meta-command ends the $if processing.
$include <filename> — the $include meta-command includes another file into the currently processed text file. Processing of the included file starts right at the position of the $include meta-command. Normal pre-processing of the file name (like double-slash substitutions) is done.
$set <variable> <string> — this meta-command sets a variable named <variable> to the value of the string <string>. Certain variables are already predefined: VERSION, PACKAGE, DEBUG, HAVE_BDB, HAVE_ODBC and HAVE_LDAP. Also, all environment variables are considered as predefined, so you can use any environment variable by just naming it in the configuration file.

Variables are a means of modifying the contents of a file based on certain runtime states. In order to use a variable value somewhere in the text file, specify its name enclosed into percent signs. For example, specifying %HOME% replaces this whole string with the value of the variable named HOME. Unless this variable has been set previously by using a $set meta-command, its value is looked up in the current environment (which then corresponds to the current user's home directory name in this example).

With these meta-commands it is possible to write rather elaborative configuration files. However note that using meta-commands in database files (like the systems database file or the network driver definition file) is not recommended, unless those files are marked read-only. This is because when the contents of a database file gets modified by some netboot program, it writes the whole database contents back into the text file without the meta-commands. They get lost in this case. See below for a further explanation of databases.

The following sections contain some general comments on each configuration file. Configuration sections which are relevant to certain programs of the netboot package will be explained in greater detail in the man page of that program.

💖 CONFIGURATION FILE 💖

okay so bestie, every single netboot program reads the main configuration file. if no configuration file name is specified either on the command line of a netboot program or in the environment variable NETBOOT_CONFIG, the default /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/etc/netboot.config gets used. that's the fallback, no cap.

each program has its own configuration section named [<progname>:general]. plus there's the shared <purple>[general]</purple> section, and literally every program uses it. it can contain these parameters:

datadir — tells netboot where to look for all the shared files it needs to actually function. specifically, two leading slashes in a directory or file name specified in any of the configuration files get replaced by the value of this parameter. if you don't set it, the default is /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot. you can override it with the -N or --datadir command line options on all netboot programs. and if neither the config file nor the command line sets it, netboot checks the environment variable NETBOOT_DATA before falling back to the default. she's thorough 💅
libdir — same energy as datadir, but for the non-shared-data directory. default is /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot. you can also set the name of the non-shared-data directory with the -L or --libdir command line options, or with the NETBOOT_LIB environment variable. pick your fighter.
homedir — this directory is used to look up file names that are not absolute, and that are not relative to some other special directory. like, non-absolute database file names get looked up relative to homedir. to override this config file parameter, use the -H or --home-dir command line options. if the home directory value hasn't been specified, netboot uses the home directory for the current user as specified in the HOME environment variable or the /etc/passwd file. note: the home directory has to be writable. if it does not exist, it will be created. she will simply materialize it, okay? ✨
tempdir — name of the directory where all temporary files go. this directory has to exist, and it has to be writable. there is no command line option to override this configuration file parameter, and the default is system dependent. so like, respect her space.
sysdb — specifies the name of the database file used when operating in batch mode, i.e. when the -b or --batch-sys command line options are given to a program. its default value is the contents of the NETBOOT_DATABASE environment variable, or //netboot.db if the environment variable is not defined. sysdb can also specify any number of predefined database specifications instead of a simple file name. see below for how to write a database specification. yes, there's lore.

the possible parameters in any other section of the configuration file are described in the man pages of the corresponding netboot programs. not gonna steal their spotlight.

also! the standard configuration file as distributed with the netboot package includes the file $HOME/.netboot/config at its very end. it also defines $HOME/.netboot as the home directory for every user. cute, consistent, iconic.

🗄️ DATABASES 🗄️

two databases are used by netboot programs: the systems database (used by all programs), and the network driver information database (used only by makerom). and yes, you can specify more than one database for each purpose. because one database is never enough when you're that girl.

all database specifications are separated by a colon character, and they're searched in the order they appear. for example, this line in the main configuration file tells netboot to use two databases for the sysdb parameter:

sysdb = db@systemsfile[ro,opt]:db@usersysfile[add,opt]

each database name is preceded by a "db@" string, which means that the database name refers to a separate database specification in the configuration file. if the "db@" prefix is missing, the database name is assumed to be the name of a text database file. following the database name, in square brackets, options can be specified. these options are recognized:

ro — opens the database read-only regardless of the mode defined in the individual database specification. she's just here to read, not to be messy.
add — use this database for adding new records. when a new record gets added to a list of databases, the last database which has the add option is used for writing. the add option can only be used for databases which are not marked read-only. so don't try it, bestie.
opt — when reading records, a database with the opt option is skipped if it does not exist. if opt is not specified, the database has to exist. otherwise an error gets printed. no silent ghosting allowed.

these options can be used with a "db@" database specification, or a text file name. either way, the vibe is the same.

in order to access a database using the "db@" prefix, the database has to be specified separately in the main configuration file. to do this, write a section with the name [db:<dbname>] into the configuration file. for example, to define a database named systemsfile, the section should be named [db:systemsfile]. in this section, the particular database is specified more closely. the following parameters can be used in such a section:

dbtype — specifies the type of the database. allowed values are:
- text file — the database is made up of a text file, which has the same structure and syntax as the standard configuration file as mentioned above. old reliable.
- berkeley db — the database is accessed using the Berkeley DB library. this is a binary file-based database.
- sql — the database is based on an SQL server using the ODBC interface.
- ldap — the Lightweight Directory Access Protocol (LDAP) is used to access the database.

text-file databases are always supported, but support for any of the other types depends on the availability of the required runtime libraries at compile time. to find out about the types of databases supported by a particular netboot program, run it with the --version command line option. very "check the label before you commit" of you.

dbmode — specifies if it is allowed to write into a database. the only allowed values are read-write and read-only. that's it. that's the whole menu.
filename — specifies the name of the database file for text and Berkeley DB databases. straightforward, slay.
lockfile — the name of the lock file to be used for a text database. a lock file only has to be specified for a database with mode read-write. for a read-only database it is ignored. so if you're just reading, don't stress about it.
table — names the table used within a SQL database to look up and store netboot parameters. yes, SQL girlies get their own table.
database — when specifying a SQL database, this parameter names the ODBC data source name (DSN) to be used for the database access. not the file, the DSN. keep up 💅
server — the name of the LDAP server. of course this parameter is only valid in an LDAP database specification. we love a specialized queen.
basedn — the base DN value to be used when accessing the LDAP server. LDAP-only, naturally.
username — the user name used for authenticating access to a SQL or LDAP database. identity check.
password — the password required for the user name mentioned in the username parameter. protect it like your phone passcode, bestie.

when reading a certain record, all databases are searched in the order as they appear in the database specification. if a record name appears more than once in any of the databases which make up a database specification, every record overwrites the parameter values defined by the previous record with the same name. so like, last one to the group chat wins. periodt.

the standard configuration file as distributed with the netboot package defines 6 databases:

systemsfile — a text-based systems database file in the netboot non-shared data directory named netboot.db. it is marked as read-only. she's giving reference material.
usersysfile — a text-based systems database file in the user's home directory. the name of the file is $HOME/.netboot/systems.text. this database is marked as read-write. your own personal little systems corner.
usersysdb — a Berkeley DB based systems database file in the user's home directory. its file name is $HOME/.netboot/systems.bdb. this database is marked as read-write. binary and ready.
netdrvfile — a text-based network driver definition database in the netboot non-shared-data directory named netboot.drivers. it is marked as read-only. only makerom is in this lane, but she's still iconic.
userdrvfile — a text-based network driver definition database file in the user's home directory. it is named $HOME/.netboot/drivers.text and is marked read-write. driver notes, but make it personal.
userdrvdb — a Berkeley DB based network driver definition database file in the user's home directory. the name of the file is $HOME/.netboot/drivers.bdb. it is marked as read-write. and that's the standard six, no cap.

🗄️ SYSTEMS DATABASE 🗄️

Okay bestie, so the systems database is where the diskless-client definitions live for all the different netboot programs. Each section — or each record, if you’re dealing with a non-text database — defines the parameters for one client and one program. The record names are built like this: program name, then a colon, then the diskless client’s name.

Example time: [mknbi-dos:testclient] means the section that mknbi-dos uses to generate a boot image file for the system testclient. And because the client name can have several colon-separated parts, you can specify different configurations for the same operating system. Using the example above, [mknbi-dos:testclient:msdos] could specify an MS-DOS® setup, while [mknbi-dos:testclient:opendos] might be used for an OpenDOS® environment. Iconic naming system, honestly.

To actually use a record in the systems database, you have to give either the -b or --batch-sys command-line option to the corresponding program. The argument to these options specifies the client’s system name. When you use different configurations for the same system, you have to give the full name including the colon and the configuration name. With the example above, it would be necessary to use --batch-sys=testclient:opendos on the command line to mknbi-dos to use the [mknbi-dos:testclient:opendos] record.

The parameters available for each netboot program are discussed in the individual man pages of the programs. When you use a system definition from the systems database, all parameters specified in the database entry always override any command-line options. Therefore, you should not use any other command-line option besides -b or --batch-sys.

🚨 Bestie, warning warning: database parameters win. Do not load up extra command-line options when you’re using -b or --batch-sys.

The default name for the database file is /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/netboot.db. You can specify a different name by either using the sysdb parameter in the general section of the main configuration file, or by using the command-line options -D or --database-file. If none of these has been specified, the value of the NETBOOT_DATABASE environment variable will be looked up before using the default.

🧚 NETWORK DRIVER INFORMATION DATABASE 🧚

The network driver information database is only used by the makerom program. Its structure is therefore explained in the makerom man page. The default name of this database file is /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/netboot.drivers. It can be changed by using the -d or --drivers command-line options to makerom. Alternatively, it can also be specified in the main configuration file with the driverdb parameter within the [makerom:general] section.

🌈 ENVIRONMENT 🌈

The following environment variables are used by all netboot programs:

NETBOOT_CONFIG — Specifies the name of the configuration file. This environment variable setting can be overridden by the -c or --config-file command-line options.
NETBOOT_DATA — Specifies the main netboot shared-data directory. This environment variable setting can be overridden by the -N or --datadir command-line options.
NETBOOT_LIB — Specifies the netboot non-shared-data directory. This environment variable setting can be overridden by the -L or --libdir command-line options.
NETBOOT_DATABASE — Specifies the name of the systems database to be used with the -b or --batch-sys command-line options. This environment variable setting can be overridden by the -D or --database-file command-line options.

Only the NETBOOT_CONFIG environment variable gets read independently of the configuration file. All other environment variables are used in the main configuration file, and modify parsing it. For example, setting NETBOOT_LIB modifies the value of the libdir parameter in the [general] section of the configuration file. Subtle but important, iykyk.

👑 AUTHOR 👑

The netboot package was written by Gero Kuhlmann <gero@gkminix.han.de> with some parts written by other authors, who are mentioned in the man pages of those programs which they helped writing.

That’s the whole vibe, bestie — this is netboot(5), dated 07 Dec 2004, and yes, the source/version footer is getting its flowers too 💖🎀✨

📦 where this page comes from

nixos 26.05: netboot 0.10.2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms