--- Begin Message ---
Package: pxe
Version: 1.4.2-7
Severity: wishlist
Please find attached an updated version of the pxe.8 manual page
and a new pxe.conf.5 manual page.
I would like to put these under a permissive licence, such as the
ISC licence, but I presume I can't do that for the parts of pxe.8
that were already in the Debian package. So if you prefer having
all files of the package under GPLv2-or-later, that is okay too.
I sent earlier versions of these manual pages upstream on
2009-11-23 and the maintainer was going to include them in the
next pxe release. I then sent these versions on 2009-11-28.
You may want to wait a few weeks in case there indeed is a new
release. Anyway, I'm posting these now in case they are useful
to someone.
The new BUGS section in pxe.8 mentions bug 558911 although not by
number.
.TH PXE 8 "2009-11-28" "1.4.2" "PXE daemon"
.SH NAME
pxe \- a free PXE daemon
.SH SYNOPSIS
.B pxe
[\fB-d\fP]
[\fB-c\fP \fIconfigfile\fP]
.SH DESCRIPTION
.B PXE
is a specification to boot PCs from the net. Apart from BOOTP or DHCP for
acquiring an IP address and TFTP for transferring files, it requires a PXE
daemon on the server which implements the boot loader selection.
.PP
This PXE daemon can operate as a PXE redirection server
(telling PXE clients which types of Boot Servers are available
and how to contact them) and as a PXE Boot Server
(telling PXE clients how to retrieve boot files over MTFTP).
It cannot operate as a DHCP server (assigning IP addresses to clients)
or as an MTFTP server (multicasting boot files to clients).
For those tasks, you need separate programs.
Note that MTFTP is different from the RFC 2090 TFTP multicast option.
.PP
It is also possible to boot a PXE client from the network
without any PXE-specific server features,
simply by making a DHCP server provide the address of a TFTP server
and the name of a file to be loaded from there.
DHCP servers such as \fBdnsmasq\fP(8) and the ISC \fBdhcpd\fP(8)
can even be configured to detect client system architectures
from DHCP options and send different file names for each.
Thus, you might not need the PXE daemon at all.
There are however a few advantages in having PXE servers:
.IP \(bu
The PXE redirection server can provide a boot menu
from which the user can choose the operating system to be booted.
.IP \(bu
The PXE clients can get their boot files using Multicast TFTP (MTFTP).
This saves network traffic if multiple clients are being booted
at the same time, as the server only needs to send the file once.
.IP \(bu
You can run redundant PXE Boot Servers for better reliability.
Each of those should then also have an MTFTP server on the same host.
.SH OPTIONS
.IP "\fB-c\fP \fIconfigfile\fP"
Read settings from \fIconfigfile\fP instead of the default.
.IP "\fB-d\fP"
Debug mode.
Write debug messages to stdout or stderr, and do not fork to the background.
.SH FILES
.IR /etc/pxe.conf ,
.IR /var/log/pxe.log ,
.IR /var/run/pxe/pxe.pid
.SH "CONFORMING TO"
Intel Preboot Execution Environment (PXE) Specification
Version 2.1 (September 20, 1999)
.SH BUGS
If two PXE clients request different files over MTFTP
at the same time, they can both receive the same file.
According to the PXE specification,
clients assume the MTFTP packet is for the correct file
if its destination IP multicast address, destination UDP port,
and source IP address match what the PXE servers reported;
but the PXE daemon sends the same settings for every file.
.PP
If a PXE client requests a Boot Integrity Services (BIS)
cryptographic signature for a boot file,
the PXE daemon instead tells it how to retrieve the file itself.
.PP
By default, the PXE daemon uses some multicast IP addresses and
UDP ports that have been registered at IANA for non-PXE purposes.
.SH AUTHOR
PXE was written by Tim Hurman <[email protected]>.
.PP
This manual page was written by Jens Schmalzing <[email protected]>, for the
Debian project (but may be used by others).
Updated by Kalle Olavi Niemitalo <[email protected]>.
.SH "SEE ALSO"
.BR pxe.conf (5),
.BR dnsmasq (8),
.BR dhcpd (8),
.BR atftpd (8)
.TH pxe.conf 5 "2009-11-28" "1.4.2" "PXE daemon"
.mso www.tmac
.SH NAME
pxe.conf \- configuration file for the PXE daemon
.SH DESCRIPTION
When the PXE daemon is starting,
it reads its settings from a configuration file,
\fI/etc/pxe.conf\fP by default.
.PP
In this configuration file, each setting must be defined in a separate line,
in \fIkey\fB=\fIvalue\fR format.
There must not be any whitespace at the beginning of the line
or around the equals sign.
Values can contain whitespace but not equals signs.
Do not put quotation marks around the values.
Generally, if the configuration file lists the same key
multiple times, only the last value takes effect;
but the \fBservice\fP setting is an exception.
.PP
The PXE daemon ignores comment lines beginning with \fB#\fP,
empty lines, and lines beginning with a space.
.SH USAGE
The PXE daemon recognizes the following settings.
They are listed here in approximately the same order
as they get used in the PXE protocol.
.IP \fBinterface=\fIname\fR
Listen for unicast and broadcast PXE requests
only on the network interface whose name is \fIname\fP.
If there is no such interface, the PXE daemon ignores the setting.
This setting does not affect listening to multicast PXE requests.
The PXE daemon detects from each request whether it should act
as a PXE redirection server or as a PXE Boot Server.
.IP
This setting does not affect any PXE options sent to clients,
except via the default value of the \fBdefault_address\fP setting.
.IP
Default: The PXE daemon listens for unicast PXE requests
on all interfaces that existed when the daemon started.
Likewise with broadcast, if enabled with the \fBuse_broadcast\fP setting.
.IP \fBlisten_port=\fIudp-port-number\fR
Listen for PXE requests sent to \fIudp-port-number\fP.
This applies to unicast, multicast, and broadcast.
The PXE daemon detects from each request whether it should act
as a PXE redirection server or as a PXE Boot Server.
.IP
This setting does not affect any PXE options sent to clients.
The value needs to match the port numbers in the PXE specification.
To contact a PXE redirection server,
PXE clients broadcast DHCPDISCOVER packets first to UDP port 67,
and then to UDP port 4011 if the DHCPOFFER from port 67
included DHCP option 60 (Class Id) with the value \%\*(lqPXEClient\*(rq
but neither DHCP option 43 (Vendor Specific) nor a boot file name.
To contact a PXE Boot Server,
PXE clients send DHCPREQUEST packets to UDP port 67 (broadcast)
or UDP port 4011 (multicast or unicast),
depending on the PXE option 6 (PXE_DISCOVERY_CONTROL)
they got from the PXE redirection server.
.IP
Default: \fBlisten_port=4011\fP
(as defined in the PXE specification, and registered at IANA)
.IP \fBuse_multicast=\fP(\fB0\fP|\fB1\fP)
Whether the PXE daemon should listen for multicast PXE requests
sent to the address given in the \fBmulticast_address\fP setting.
If this is 1, the daemon does so on all network interfaces,
regardless of the \fBinterface\fP setting.
.IP
This setting affects PXE option 6 (PXE_DISCOVERY_CONTROL):
the PXE redirection server tells clients
whether to discover PXE Boot Servers by multicasting.
.IP
Default: \fBuse_multicast=1\fP
.IP \fBmulticast_address=\fIIPv4-multicast-address\fR
The multicast address to which clients should send PXE Boot Server
discovery requests.
If the \fBuse_multicast\fP setting is 1,
the PXE daemon listens to this address as a PXE Boot Server.
(PXE clients never multicast requests to PXE redirection servers.)
.IP
The PXE daemon sends \fIIPv4-multicast-address\fP in PXE option 7
(DISCOVERY_MCAST_ADDR) when acting as a PXE redirection server.
If multicasting has been disabled by setting \fBuse_multicast=0\fP,
the PXE daemon sends this option anyway, but the clients ignore it.
.IP
Default: \fBmulticast_address=224.0.1.2\fP
(registered for a different purpose at IANA so should not be used)
.IP \fBdefault_address=\fIIPv4-unicast-address\fR
If a PXE Boot Server request comes in by multicast,
respond to it from the unicast address \fIIPv4-unicast-address\fP.
(PXE clients never multicast requests to PXE redirection servers.)
This setting is necessary because the PXE daemon does not automatically
detect the network interface whence multicast packets come.
.IP
When responding to multicast, the PXE Boot Server sends
\fIIPv4-unicast-address\fP in the \fBsiaddr\fP field of the DHCP response,
in DHCP option 54 (Server Identifier), and also in the source address
field of the IP header of the DHCP response if possible.
.IP
Default: The address of the network interface named in the
\fBinterface\fP setting, if any.
Otherwise, the PXE Boot Server does not choose a correct default,
so you should set \fBuse_multicast=0\fP.
.IP \fBuse_broadcast=\fP(\fB0\fP|\fB1\fP)
Whether the PXE daemon should listen for broadcast PXE requests.
See also the \fBinterface\fP setting.
Because the initial message from a PXE client to a PXE redirection
server is always by broadcast, you must set \fBuse_broadcast=1\fP
if you want to use the PXE daemon as such a server.
.IP
This setting affects PXE option 6 (PXE_DISCOVERY_CONTROL):
the PXE redirection server tells clients
whether to discover PXE Boot Servers by broadcasting.
.IP
Default: \fBuse_broadcast=1\fP
.IP \fBprompt=\fIstring\fR
Tell the PXE clients to display \fIstring\fP as a prompt.
The PXE specification does not say anything about charsets.
.IP
The PXE daemon sends \fIstring\fP in PXE option 10
(PXE_MENU_PROMPT) when acting as a PXE redirection server.
There is no way to configure the PXE daemon not to send this option,
but you can get a similar effect by setting a blank prompt
and specifying \fBprompt_timeout=255\fP.
.IP
Default: \fBprompt=Press F8 to view menu...\fP
.IP \fBprompt_timeout=\fInumber\fR
Tell the PXE clients to wait \fInumber\fP seconds
before automatically selecting the first menu item.
According to the PXE specification,
a timeout of 0 means select the first item immediately,
and a timeout of 255 means display the menu immediately with no timeout.
.IP
The PXE daemon sends \fInumber\fP in PXE option 10 (PXE_MENU_PROMPT)
when acting as a PXE redirection server.
.IP
Default: \fBprompt_timeout=10\fP
.IP
\fBservice=\fICSA\fR,\fImin-layer\fR,\fImax-layer\fR,\fIbasename\fR,\fIdescription\fR
A menu item for PXE clients to display.
To define multiple menu items, use multiple \fBservice=\fP
lines in the configuration file.
When acting as a PXE redirection server,
the PXE daemon sends the list of applicable menu items to the client.
The PXE client then chooses one of the items (the first one by default)
and asks the PXE Boot Servers how to retrieve the corresponding boot files.
.RS
.IP \fICSA
Client System Architecture to which the menu item is applicable.
This must be one of \fBX86PC\fP, \fBPC98\fP, \fBIA64PC\fP, \fBDEC\fP
(Alpha), \fBArcX86\fP, or \fBILC\fP (Intel Lean Client).
When acting as a PXE redirection server,
the PXE daemon sends the menu item to the PXE client
only if the client reports this as its system architecture
in DHCP option 93 (Client System; RFC 4578) or DHCP option 60
(Class Id; RFC 2132 but refined in the PXE specification).
.IP \fImin-layer\fP,\fImax-layer\fP
Each menu item has one or more boot files that the PXE client
should load in sequence.
The first boot file of the menu item is layer 0,
and the other boot files have their own layer numbers.
.IP
When acting as a PXE Boot Server, the PXE daemon responds only to
requests where the layer number is between \fImin-layer\fP and
\fImax-layer\fP, inclusive.
If the PXE client requests a layer not in this range, then the PXE
daemon ignores the request, and some other PXE Boot Server may perhaps
respond to it.
Thus, if you have no other PXE Boot Servers, \fImin-layer\fP must be 0
so that the PXE client can get its first boot file.
If there is only one boot file for the menu item, \fImax-layer\fP
should be 0 as well.
.IP
When acting as a PXE redirection server, the PXE daemon
sends the \fImin-layer\fP of the first menu item
in PXE option 71 (PXE_BOOT_ITEM).
This overrides any similar option sent by a PXE Boot Server.
.IP \fIbasename\fP
Basename of the boot file that the PXE client should load
from the MTFTP or TFTP server.
When acting as a PXE Boot Server,
the PXE daemon generates the actual file name from this
in the format \*(lq\fICSA\fB/\fIbasename\fB/\fIbasename\fB.\fIlayer\fR\*(rq
and sends the generated name to the PXE client,
which then requests the file from the MTFTP or TFTP server.
For example, \*(lqX86PC/pxelinux/pxelinux.0\*(rq.
.IP
The PXE daemon reserves the name \*(lqlocal\*(rq to mean
the PXE client should boot its local operating system.
Because the client will not request any boot files in that case,
\fImin-layer\fP and \fImax-layer\fP do not matter.
.IP
This parameter affects the Boot Server type numbers
that the PXE daemon sends in PXE option 9 (PXE_BOOT_MENU)
when acting as a PXE redirection server.
The menu item with \fIbasename\fP \*(lqlocal\*(rq,
if any, becomes Boot Server type 0.
The PXE daemon assigns integers starting from 1
as Boot Server types of other menu items.
This behaviour is contrary to the PXE specification,
which defines fixed meanings for the Boot Server types.
.IP \fIdescription\fP
The text that the client should display in the menu.
This can be at most 255 characters.
The PXE specification does not say anything about charsets.
.IP
The PXE daemon sends the description in PXE option 9
(PXE_BOOT_MENU) when acting as a PXE redirection server.
.RE
.IP \fBmtftp_address=\fIIPv4-multicast-address\fR
Tell the PXE clients that the Multicast Trivial File Transfer Protocol
(MTFTP) server will send boot files to the multicast address
\fIIPv4-multicast-address\fP, so the clients should join that
multicast group.
The \fBmtftp_client_port\fP setting is the corresponding UDP port number.
.IP
The PXE daemon sends \fIIPv4-multicast-address\fP in PXE option 1
(PXE_MTFTP_IP) when acting as a PXE redirection server.
This overrides any similar option sent by a PXE Boot Server.
There is no way to configure the PXE daemon not to send this option;
thus, if you have only a standard TFTP server rather than MTFTP,
the PXE clients may waste some time trying to use MTFTP
before they fall back to standard TFTP.
.IP
Default: \fBmtftp_address=224.1.5.1\fP
(in IANA Reserved space so should not be used)
.IP \fBmtftp_client_port=\fIudp-port-number\fR
Tell the PXE clients that the MTFTP server will send boot files
to \fIudp-port-number\fP, so the clients should listen to that port.
The \fBmtftp_address\fP setting is the corresponding IP address.
.IP
The PXE daemon sends \fIudp-port-number\fP in PXE option 2
(PXE_MTFTP_CPORT) when acting as a PXE redirection server.
This overrides any similar option sent by a PXE Boot Server.
.IP
Default: \fBmtftp_client_port=1758\fP
(registered for this purpose at IANA)
.IP \fBmtftp_server_port=\fIudp-port-number\fR
Tell the PXE clients to contact the MTFTP server at \fIudp-port-number\fP
if it is not already multicasting the correct boot file.
The MTFTP server must be run at the same IP address as the PXE Boot Server.
(That is only a recommendation in the PXE specification,
but when the PXE daemon is acting as a PXE Boot Server,
it assumes the recommendation has been followed,
and sets the \fBsiaddr\fP field of the DHCP response
and DHCP option 54 accordingly.)
.IP
The PXE daemon sends \fIudp-port-number\fP in PXE option 3
(PXE_MTFTP_SPORT) when acting as a PXE redirection server.
This overrides any similar option sent by a PXE Boot Server.
.IP
Default: \fBmtftp_server_port=1759\fP
(registered for a different purpose at IANA so should not be used)
.IP \fBdomain=\fIstring\fR
This setting has no effect.
.IP \fBtftpdbase=\fIdirectory\fR
This setting has no effect.
.SH FILES
.I /etc/pxe.conf
.SH "CONFORMING TO"
.URL http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf \
"Intel Preboot Execution Environment (PXE) Specification \
Version 2.1 (September 20, 1999)"
.SH "SEE ALSO"
.BR pxe (8),
RFC 2132,
RFC 4578
.SH AUTHOR
PXE was written by Tim Hurman <[email protected]>.
.PP
This manual page was written by Kalle Olavi Niemitalo <[email protected]>,
for the Debian project (but may be used by others).
-- System Information:
Debian Release: lenny/sid
APT prefers unstable
APT policy: (500, 'unstable'), (500, 'testing'), (500, 'stable'), (1,
'experimental')
Architecture: i386 (i686)
Shell: /bin/sh linked to /bin/dash
Kernel: Linux 2.6.30-1-686
Locale: LANG=fi_FI.UTF-8, LC_CTYPE=fi_FI.UTF-8 (charmap=UTF-8)
Versions of packages pxe depends on:
ii adduser 3.99 Add and remove users and groups
ii libc6 2.7-16 GNU C Library: Shared libraries
ii libgcc1 1:4.3.1-4 GCC support library
ii libstdc++6 4.3.1-4 The GNU Standard C++ Library v3
Versions of packages pxe recommends:
ii atftpd 0.7-9 advanced TFTP server
pn dhcp3-server | dnsmasq <none> (no description available)
pn syslinux <none> (no description available)
--- End Message ---
