.\" @(#)netboot.5
.\"
.\" Copyright (C) 1998-2007 Gero Kuhlmann   <gero@gkminix.han.de>
.\"
.\"  This program is free software; you can redistribute it and/or modify
.\"  it under the terms of the GNU General Public License as published by
.\"  the Free Software Foundation; either version 2 of the License, or
.\"  any later version.
.\"
.\"  This program is distributed in the hope that it will be useful,
.\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
.\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\"  GNU General Public License for more details.
.\"
.\"  You should have received a copy of the GNU General Public License
.\"  along with this program; if not, write to the Free Software
.\"  Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
.\"
.\" $Id: netboot.man.in,v 1.12 2007/02/01 12:09:23 gkminix Exp $
.TH netboot 5 "07 Dec 2004"
.SH PROGRAMS
The 
.B 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:
.TP
.B makerom
Generates a bootrom from various binary files. It can use many types
of network drivers like standard DOS packet and NDIS driver binaries.
.TP
.B mknbi-linux
Generates a netbootable image to load the Linux operating system.
.TP
.B mknbi-dos
Generates a netbootable image to load a DOS-like operating system, like
MS-DOS\*R or OpenDOS\*R.
.TP
.B 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.
.LP
See the corresponding man page for a further explanation about any of 
the above mentioned programs.

.SH FILES
.TP
.B %CONFIG%
Main netboot configuration file.
.TP
.B %LIBDIR%/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.
.TP
.B %LIBDIR%/netboot.db
Systems database file.
.TP
.B %DATADIR%/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.
.TP
.B %LIBDIR%/drivers.local
Local additions to the network driver information database file. This file
never gets modified by the installation process.
.LP
These files control the operation of the various programs which are 
part of the 
.B 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.
.LP
The network driver information database 
contains specifications needed to find and use certain pre-known network
drivers like packet or NDIS drivers.
.LP
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 it's general definitions is named
.BR [makerom:general] .
.LP
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 
.B false
or 
.BR 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.
.LP
If a string value names a directory or file, it is possible to make
these paths relative to either the non-shared-data directory
.I %LIBDIR%
or the shared-data directory
.I %DATADIR%
by prepending the string with two slashes. All
.B netboot
programs then search for the corresponding file or directory in both paths.
For example, specifying
.I //utils
gets expanded to 
.I %LIBDIR%/utils
and 
.I %DATADIR%/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
.I //utils://binaries
as a directory name will let a program search the directories 
.IR %LIBDIR%/utils ,
.IR %DATADIR%/utils ,
.I %LIBDIR%/binaries
and 
.I %DATADIR%/binaries
for a required file, in this order. This is somewhat similar to specifying
the PATH variable in the shell.
.LP
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.
.LP
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:
.TP
.B $if [not] <condition>
The 
.B $if
meta-command allows processing of the following text according to certain
conditions. If the condition is met, the text following the
.B $if
meta-command is processed until reaching a corresponding
.B $else
or 
.B $endif
meta-command. If the word
.B 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:
.RS
.TP
.B 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).
.TP
.B defined <variable>
The condition is met if the variable named <variable> is defined. See the
.B $set
meta-command about setting a variable.
.TP
.B 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.
.RE
.IP
Up to 16 levels of
.B $if
meta-commands can be nested into each other.
.TP
.B $else
This meta-command starts the else-branch of a
.B $if
meta-command. This means that the text following the
.B $else
is parsed if the corresponding 
.B $if
condition is not met.
.TP
.B $endif
This meta-commands ends the
.B $if
processing.
.TP
.B $include <filename>
The 
.B $include
meta-command includes another file into the currently processed text file.
Processing of the included file starts right at the position of the 
.B $include
meta-command. Normal pre-processing of the file name (like double-slash
substitutions) is done.
.TP
.B $set <variable> <string>
This meta-command sets a variable named <variable> to the value of the
string <string>. Certain
variables are already predefined:
.BR VERSION ,
.BR PACKAGE ,
.BR DEBUG ,
.BR HAVE_BDB ,
.B HAVE_ODBC
and 
.BR 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.
.LP
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 it's name enclosed into percent signs. For example,
specifying 
.I %HOME%
replaces this whole string with the value of the variable named 
.SM HOME.
Unless this variable has been set previously by using a 
.B $set
meta-command, it's value is looked up in the current environment (which
then corresponds to the current user's home directory name in this
example).
.LP
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 
.B netboot
program, it writes the whole database contents back into the text file
.B without
the meta-commands. They get lost in this case. See below for
a further explanation of databases.
.LP
The following sections contain some general comments on each configuration 
file. Configuration sections which are relevant to certain programs of the
.B netboot
package will be explained in greater detail in the man page of that program.

.SH CONFIGURATION FILE
The main configuration file is read by all 
.B netboot
programs. If no
configuration file name is specified either on the command line of a 
.B netboot
program or in the environment variable 
.SM NETBOOT_CONFIG,
the default 
.I %CONFIG%
will be used. Each program has it's own configuration section named
.BR [<progname>:general] .
In addition, the section
.B [general]
is used by all programs. It can contain the following parameters:
.TP
.B datadir
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
.I %DATADIR%
will be used. This parameter can be overriden by the
.B -N
or 
.B --datadir
command line options with all 
.B netboot
programs. Also, if neither the
configuration file or the command line is used to specify the directory,
the environment variable 
.SM NETBOOT_DATA
will be looked up before using the default value.
.TP
.B libdir
This parameter is similar to the 
.B datadir
parameter. It specifies the path to the non-shared-data directory. If not
specified, the default
.I %LIBDIR%
will be used. Alternatively, it is also possible to set the name of the
non-shared-data directory using the
.B -L
or 
.B --libdir
 command line options or using the
.SM NETBOOT_LIB
environment variable.
.TP
.B 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 
.B homedir
directory. To override this configuration file parameter, it is possible
to use the 
.B -H
or 
.B --home-dir
command line options. If the home directory value has not been specified,
.B netboot
will use the home directory for the current user as specified in the 
.SM 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.
.TP
.B 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.
.TP
.B sysdb
Specifies the name of the database file to be used when operating in 
batch mode, i.e. when the
.B -b
or 
.B --batch-sys
command line options are given to a program. It's default value is the
contents of the 
.SM NETBOOT_DATABASE
environment variable, or
.I //netboot.db
if the environment variable is not defined. The
.B 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.
.LP
The possible parameters in any other section of the configuration file are 
described in the man pages of the corresponding 
.B netboot
programs.
.LP
In addition, the standard configuration file as distributed with the
.B netboot
package includes the file 
.I $HOME/.netboot/config
at it's very end.
It also defines 
.I $HOME/.netboot
as the home directory for every user.

.SH DATABASES
Two databases are used by 
.B 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 
.B sysdb
parameter:
.LP
sysdb = db@systemsfile[ro,opt]:db@usersysfile[add,opt]
.LP
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:
.TP
.B ro
Open the database read-only regardless of the mode defined in
the individual database specification.
.TP
.B 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
.B add
option is used for writing. The
.B add
option can only be used for databases which are not marked read-only.
.TP
.B opt
When reading records, a database with the
.B opt
option is skipped if it does not exist. If
.B opt
is not specified, the database has to exist. Otherwise an error gets
printed.
.LP
These options can be used with a "db@" database specification, or a text
file name.
.LP
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
.I systemsfile
the section should be named 
.BR [db:systemsfile] .
In this section, the
particular database is specified more closely. The following parameters
can be used in such a section:
.TP
.B dbtype
This parameter specifies the type of the database. Allowed values are:
.RS
.TP
.B 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.
.TP
.B berkeley db
The database is accessed using the Berkeley DB library. This is a binary
file-based database.
.TP
.B sql
The database is based on an SQL server using the ODBC interface.
.TP
.B ldap
The Lightweight Directory Access Protocol (LDAP) is used to access the
database.
.RE
.IP
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 
.B netboot
program, run it with the
.B --version
command line option.
.TP
.B dbmode
This parameter specifies if it is allowed to write into a database. The
only allowed values are 
.B read-write
and 
.BR read-only .
.TP
.B filename
Specifies the name of the database file for text and Berkeley DB databases.
.TP
.B 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 
.BR read-write .
For a 
.B read-only
database it is ignored.
.TP
.B table
This names the table used within a SQL database to lookup and store 
.B netboot
parameters.
.TP
.B database
When specifying a SQL database, this parameter names the ODBC data
source name (DSN) to be used for the database access.
.TP
.B server
The name of the LDAP server. Of course this parameter is only valid
in a LDAP database sepcification.
.TP
.B basedn
The base DN value to be used when accessing the LDAP server.
.TP
.B username
This is the user name to be used for authenticating access to a SQL 
or LDAP database.
.TP
.B password
The password required for the user name mentioned in the 
.B username
parameter.
.LP
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.
.LP
The standard configuration file as distributed with the 
.B netboot
package defines 6 databases:
.TP
.B systemsfile
A text-based systems database file in the netboot non-shared data directory
named 
.IR netboot.db .
It is marked as read-only.
.TP
.B usersysfile
A text-based systems database file in the user's home directory. The name of
the file is 
.IR $HOME/.netboot/systems.text .
This database is marked as read-write.
.TP
.B usersysdb
A Berkeley DB based systems database file in the user's home directory. It's
file name is 
.IR $HOME/.netboot/systems.bdb .
This database is marked as read-write.
.TP
.B netdrvfile
A text-based network driver definition database in the netboot non-shared-data
directory named 
.IR netboot.drivers .
It is marked as read-only.
.TP
.B userdrvfile
A text-based network driver definition database file in the user's home
directory. It is named
.I $HOME/.netboot/drivers.text
and is marked read-write.
.TP
.B userdrvdb
A Berkeley DB based network driver definition database file in the user's
home directory.  The name of the file is
.IR $HOME/.netboot/drivers.bdb .
It is marked as read-write.

.SH SYSTEMS DATABASE
The systems database contains the definition of diskless clients used 
by the various 
.B netboot
programs. Each section (or record in the case of non-text databases)
of the systems database defines the 
parameters for one client and one program. The names of the records
are constructed using the program name, followed by a colon and followed
by the name of the diskless client.
For example,
.B [mknbi-dos:testclient]
specifies the section used by the mknbi-dos program to generate a
boot image file for system 
.IR testclient .
The client name can also contain several colon separated parts to specify 
different configurations for the same operating system. Using the example
above,
.B [mknbi-dos:testclient:msdos]
could be used to specify an MS-DOS\*R
setup, while
.B [mknbi-dos:testclient:opendos]
might be used for an OpenDOS\*R environment.
.LP
To use a record in the systems database you have to give either the 
.B -b
or 
.B --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 
.I --batch-sys=testclient:opendos
on the command line to mknbi-dos to use the
.B [mknbi-dos:testclient:opendos]
record.
.LP
The parameters available for each netboot 
program are discussed in the individual man pages of the programs. 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 -b
or 
.BR --batch-sys .
.LP
The default name for the database file is 
.IR %LIBDIR%/netboot.db .
You can specify a different name by either using the 
.B sysdb
parameter in the general section of the main configuration file, or
by using the command line options 
.B -D
or 
.BR --database-file .
If none of these has been specified, the value of the
.SM NETBOOT_DATABASE
environment variable will be looked up before using the default.

.SH NETWORK DRIVER INFORMATION DATABASE
The network driver information database is only used by the makerom 
program. It's structure is therefore explained in the makerom
man page. The default name of this database file is
.IR %LIBDIR%/netboot.drivers .
It can be changed by using the 
.B -d
or 
.B --drivers
command line options to makerom.  Alternatively, it can also be
specified in the main configuration file with the 
.B driverdb
parameter within the 
.B [makerom:general]
section.

.SH ENVIRONMENT
The following environment variables are used by all 
.B netboot
programs:
.TP
.B NETBOOT_CONFIG
Specifies the name of the configuration file. This environment variable
setting can be overriden by the 
.B -c
or 
.B --config-file
command line options.
.TP
.B NETBOOT_DATA
Specifies the main 
.B netboot
shared-data directory. This environment variable setting can be overriden by the
.B -N
or 
.B --datadir
command line options.
.TP
.B NETBOOT_LIB
Specifies the 
.B netboot
non-shared-data directory. This environment variable setting can be overridden
by the 
.B -L
or 
.B --libdir
command line options.
.TP
.B NETBOOT_DATABASE
Specifies the name of the systems database to be used with the 
.B -b
or 
.B --batch-sys
command line options. This environment variable setting can be
overriden by the 
.B -D
or 
.B --database-file
command line options.
.LP
Only the 
.SM 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
.SM NETBOOT_LIB
modifies the value of the 
.B libdir
parameter in the 
.B [general]
section of the configuration file.

.SH SEE ALSO
makerom(8), mknbi-linux(8), mknbi-dos(8), mknbi-mgl(8)

.SH AUTHOR
The 
.B netboot
package was written by 
.SM 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.

