netboot(5)

okay so bestie, this is netboot(5) from the File Formats Manual — the page for the netboot package, aka the thing that gives you programs to generate bootroms and load image files using an IP network so an x86-based system can boot. 💅✨

💅 PROGRAMS 💅

The netboot package contains these 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 📁

okay, here’s the file roster, and every path is literally sacred — copy them exactly, no cap:

• /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 seperated 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 seperated 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 below for a required file, in this order:

1. /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/utils
2. /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot/utils
3. /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot/binaries
4. /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot/binaries

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.

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 the main configuration file is the one everybody reads. every netboot program reads it. if you don't name a config file on the command line of a netboot program and you don't set the NETBOOT_CONFIG environment variable, it just goes with the default:

/nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/etc/netboot.config

each program has its own lil section in there named [<progname>:general]. and then there's the [general] section, which is the shared one every single program uses. it can hold these parameters, bestie:

• datadir — tells netboot where all the shared files it needs actually live. super important detail: if a directory or file name in any of the config files starts with two leading slashes, that prefix gets swapped out for the value of this parameter. no datadir given? default is /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/share/netboot. every netboot program lets you override it with -N or --datadir. and if neither the config file nor the command line says anything, netboot checks the NETBOOT_DATA environment variable before it falls back to the default. layered queen behavior 💅
• libdir — basically datadir's sibling, except it points at the non-shared-data directory. default if you don't set it: /nix/store/bh9zrij5f8gc9m2p8902lxbw0y2s3r4v-netboot-0.10.2/lib/netboot. you can also set the name of that non-shared-data directory with the -L or --libdir command line options, or with the NETBOOT_LIB environment variable. so many doors, same room ✨
• homedir — this is the directory used to look up file names that aren't absolute and aren't relative to some other special directory. like, non-absolute database file names get looked up relative to homedir, iykyk. wanna override the config file on this one? hit it with -H or --home-dir. if no home directory value is specified anywhere, netboot uses the current user's home directory as given by the HOME environment variable or the /etc/passwd file. note: the home directory has to be writable, and if it doesn't exist, it gets created. it's giving "make yourself at home" fr fr 🏠
• tempdir — the directory where all the temporary files get stored. it has to exist and it has to be writable, no exceptions. there is no command line option to override this config parameter, and the default is system dependent. periodt.
• sysdb — names the database file used when a program is operating in batch mode, a.k.a. when you pass -b or --batch-sys on the command line. its default value is the contents of the NETBOOT_DATABASE environment variable, or //netboot.db if that environment variable isn't defined. plot twist: sysdb can also specify any number of predefined database specifications instead of just a plain file name. see below for how to write a database specification 👑

the parameters you can put in any other section of the config file are documented in the man pages of the netboot programs they belong to, so go read those, bestie.

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

---

🦋 DATABASES 🦋

two databases exist in netboot land:

1. the systems database — used by all programs
2. the network driver information database — used only by makerom

and yes you can specify more than one database for each purpose. all database specifications are separated by a colon character, and they get searched in the order they appear. so for example, this line in the main configuration file says "use two databases for the sysdb parameter":

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

every database name is preceded by a db@ string, which means that name refers to a separate database specification in the config file. if the db@ prefix is missing, the database name is assumed to be the name of a text database file. after the database name, in square brackets, you can put options. these are the recognized ones:

• ro — open the database read-only, no matter what mode the individual database specification defines. hands off 🚫
• add — use this database for adding new records. when a new record gets added to a list of databases, the last database that has the add option is the one used for writing. add can only be used on databases that aren't marked read-only. go write your lil heart out ✍️
• opt — when reading records, a database with the opt option is skipped if it doesn't exist. if opt is not specified, the database has to exist, and if it doesn't, you get an error printed. no chill, just facts.

these options work on a db@ database specification or on a text file name. flexible icon 💅

so here's the thing about accessing a database with the db@ prefix — it has to be specified separately in the main configuration file. to do that, you write a section literally named [db:<dbname>] into the config file. like, to define a database named systemsfile, the section should be named [db:systemsfile]. inside that section you describe the database more closely. the following parameters work there:

• dbtype — what kind of database is this? allowed values are:
  • text file — the database is made up of a text file with the same structure and syntax as the standard configuration file mentioned above. classic.
  • berkeley db — the database is accessed using the Berkeley DB library. binary file-based database, fancy.
  • 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 whether the required runtime libraries were available at compile time. wanna find out which database types a particular netboot program supports? run it with the --version command line option. vibe check via version flag 🔍

• dbmode — says whether writing into a database is allowed. the only allowed values are read-write and read-only. that's it, those are the two.
• filename — the name of the database file, for text and Berkeley DB databases.
• lockfile — the name of the lock file 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's ignored entirely. 🫶
• table — names the table used within a SQL database to look up and store netboot parameters.
• database — when specifying a SQL database, this names the ODBC data source name (DSN) used for the database access.
• server — the name of the LDAP server. obviously this one is only valid in an LDAP database specification. duh 💀
• basedn — the base DN value used when accessing the LDAP server.
• username — the user name used for authenticating access to a SQL or LDAP database.
• password — the password required for the user name mentioned in the username parameter. keep it secret, keep it safe 🙈

when reading a certain record, all the databases get searched in the order they appear in the database specification. and if a record name shows up more than once in any of the databases that make up a database specification, every record overwrites the parameter values defined by the previous record with the same name. last one wins, no cap 👑

the standard configuration file that ships with the netboot package defines 6 databases:

• systemsfile — a text-based systems database file in the netboot non-shared data directory named netboot.db. marked as read-only.
• usersysfile — a text-based systems database file in the user's home directory. the file name is $HOME/.netboot/systems.text. marked read-write.
• usersysdb — a Berkeley DB based systems database file in the user's home directory. its file name is $HOME/.netboot/systems.bdb. marked read-write.
• netdrvfile — a text-based network driver definition database in the netboot non-shared-data directory named netboot.drivers. marked read-only.
• userdrvfile — a text-based network driver definition database file in the user's home directory. it's named $HOME/.netboot/drivers.text and it's marked read-write.
• userdrvdb — a Berkeley DB based network driver definition database file in the user's home directory. the file name is $HOME/.netboot/drivers.bdb. marked read-write.

six whole databases, all living their best lives 🌈

💾 SYSTEMS DATABASE 💾

Okay bestie, so the systems database is where all the diskless-client definitions live for the netboot programs. Every section — or record, if you're in a non-text database — defines the params for one client and one program. No cap.

Record names are built like this: program name, then a colon, then the name of the diskless client. Example: [mknbi-dos:testclient] is the section mknbi-dos uses to generate a boot image file for system testclient. Iconic.

The client name can also have 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. Slay.

To 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. Periodt.

Each netboot program's own man page spills the tea on its parameters. When using 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: the database entry params are main character energy here — they override your command line options every time. So don't pile on extra flags, okay?

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

🧚 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. Cute.

🌈 ENVIRONMENT 🌈

These 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. Wild, but true.

👀 SEE ALSO 👀

• makerom(8)
• mknbi-linux(8)
• mknbi-dos(8)
• mknbi-mgl(8)

💅 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. Respect the icons.

---

xoxo, this was netboot(5) from netboot 0.10.2, dated 07 Dec 2004 💖✨