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 the netboot(5) file formats manual, and it's giving "netboot package lore, but make it make sense" ✨. Everything here is about the files and config magic that control the netboot programs — and yes, we're keeping every single path, flag, and meta-command. No cap. 💖

✨ PROGRAMS ✨

The netboot package contains these programs to generate bootroms and load image files using an IP network so an x86-based system can boot:

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 🎀

💖 the actual 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.

🧚 config files: the common format 🧚

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.

📁 path expansion, but make it cute 📁

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.

💬 comments, whitespace, and case 💬

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: the plot twists ✨

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).

⚠️ careful, bestie — 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 bestie, this is the main configuration file, and literally all netboot programs read it. 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 will be used. Each program has its own configuration section named [<progname>:general]. In addition, the section [general] is used by all programs. It can contain the following parameters:

datadir — bestie, this specifies the directory where to look for all shared files required for proper operation. Especially, two leading slashes in a directory or file name specified in any of the configuration files gets replaced by the value of this parameter. If not specified, the default /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot will be used. This parameter can be overriden by the -N or --datadir command line options with all netboot programs. Also, if neither the configuration file or the command line is used to specify the directory, the environment variable NETBOOT_DATA will be looked up before using the default value.
libdir — this parameter is similar to the datadir parameter. It specifies the path to the non-shared-data directory. If not specified, the default /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot will be used. Alternatively, it is also possible to set the name of the non-shared-data directory using the -L or --libdir command line options or using the NETBOOT_LIB environment variable.
homedir — the directory specified by this parameter is used to look up file names which are not absolute, and which are not relative to some other special directory. For example, non-absolute database file names are looked up relative to the homedir directory. To override this configuration file parameter, it is possible to use the -H or --home-dir command line options. If the home directory value has not been specified, netboot will use the home directory for the current user as specified in the HOME environment variable or the /etc/passwd file. Note that the home directory has to be writable. If it does not exist, it will be created.
tempdir — name of the directory where to store all temporary files. This directory has to exist, and has to be writable. There is no command line option to override this configuration file parameter, and the default is system dependent.
sysdb — specifies the name of the database file to be 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. The sysdb parameter can also specify any number of predefined database specifications instead of a simple file name. See below about how to write a database specification.

The possible parameters in any other section of the configuration file are described in the man pages of the corresponding netboot programs.

In addition, 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.

🌈 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). It is possible to specify more than one database for each purpose. All database specifications are seperated by a colon character, and are searched in the order they appear. For example, the following line in the main configuration file specifies 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 seperate 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. The following options are recognized:

ro — open the database read-only regardless of the mode defined in the individual database specification.
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.
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.

These options can be used with a db@ database specification, or a text file name.

In order to access a database using the db@ prefix, the database has to be specified seperately in the main configuration file. To do this it is necessary to 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 — this parameter 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.
- 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.

dbmode — this parameter specifies if it is allowed to write into a database. The only allowed values are read-write and read-only.
filename — specifies the name of the database file for text and Berkeley DB databases.
lockfile — the name of the lock file to be used for a text database. A lock file has only to be specified for a database with mode read-write. For a read-only database it is ignored.
table — this names the table used within a SQL database to lookup and store netboot parameters.
database — when specifying a SQL database, this parameter names the ODBC data source name (DSN) to be used for the database access.
server — the name of the LDAP server. Of course this parameter is only valid in a LDAP database sepcification.
basedn — the base DN value to be used when accessing the LDAP server.
username — this is the user name to be used for authenticating access to a SQL or LDAP database.
password — the password required for the user name mentioned in the username parameter.

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.

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.
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.
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.
netdrvfile — a text-based network driver definition database in the netboot non-shared-data directory named netboot.drivers. It is marked as read-only.
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.
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.

🗂️ SYSTEMS DATABASE 🗂️

okay bestie, this database is where the diskless clients get their whole identity 💅. It contains the definition of diskless clients used by the various netboot programs. Each section (or record, if we're talking non-text databases) defines the parameters for one client and one program. The names of the records are built using the program name, then a colon, then the name of the diskless client. So like, [mknbi-dos:testclient] specifies the section used by the mknbi-dos program to generate a boot image file for system testclient. iconic naming system, no cap ✨.

The client name can also contain several colon-separated parts to specify different configurations for the same operating system. Using the example above, [mknbi-dos:testclient:msdos] could be used to specify an MS-DOS® setup, while [mknbi-dos:testclient:opendos] might be used for an OpenDOS® environment. the range? impeccable 🫶.

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. yes, bestie, include the colon, don't get cute and shorten it 😭.

The parameters available for each netboot program are discussed in the individual man pages of the programs. When you're using a system definition from the systems database, all parameters specified in the database entry always override any command line options. So do not use any other command line option besides -b or --batch-sys. like, the database said what it said, and it's the main character now 👑.

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. look at precedence doing its lil runway walk 💃.

🚗 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. very "one program only, but make it slay" energy 🎀.

🌱 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, bestie — it's giving "the config file is doing a group project with your shell" 😭💖.

👀 SEE ALSO 👀

go read those too, they're literally the extended universe 🌈✨.

💖 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. we love a collaborative queen 🫶👑.

okay that's the whole netboot(5) moment, dated 07 Dec 2004 — netboot page, final bow, mwah 💋💅✨

📦 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