Package: pybootd
OverviewPyBootd is a daemon supporting a subset of the BOOTP, DHCP, PXE and TFTP
protocols, with some handy extensions.One of its main goals is to provide a simple solution to boot up any
PXE-enabled personal computer, with no other tool required but a standard
Python installation.Pybootd can be used for any network boot up, or to install an OS without any
physical support such as a USB key or a CD/DVD.RequirementsPythonPython2.6 or above is required.Python3.x is not yet supported.NetifacesPython modulePermissionsDHCP protocol requires the daemon to listen on port 67.TFTP protocol requires the daemon to listen on port 69.As these ports are within the server’s range (<1024), the superuser privileges
are required on Unix hosts (Linux, Mac OS X, …) to start up these daemons.StatusThis project is in beta development stage.Supported featuresAccess control:None (any remote host can be served)MAC address ACLUUID based ACL - requires PXE protocolHTTP forwarding - authorization is delegated to a remote server using
simple HTTP GET requestsLocal or remote file serving:For example, it is possible to boot up a full Debian system directly from
the Internet, without storing any file on the pybootd host machineNetwork notification of client requests through UDP messagesFile name translationFiles requested from TFTP clients can be filtered and transformed into
local filenames using filtersIt is possible to use pybootd with only one of the services, either TFTP or
DHCPFAQCommon errorspybootd.pxed.BootpError: Unable to detect network configurationThis error is often triggered when thepool_startaddress is not part of
a valid network. Double check the network configuration and fix up the[bootp]section so that it matches the actual network.Configurationpybootdhas a few option switches. The server offers two services: bootp
(which supports Dhcp and PXE extensions) and tftp. It is possible to disable
either services.Usage: pybootd.py [options]PXE boot up server, a tiny BOOTP/DHCP/TFTP serverOptions:-h,--helpshow this help message and exit-cCONFIG,--config=CONFIGconfiguration file-p,--pxeenable BOOTP/DHCP/PXE server only-t,--tftpenable TFTP server onlypybootddaemon uses a configuration file, in.iniformat, for all other
options.Some options accept a boolean value. The following values are recognized:true values:on,true,enable,enabled,yes,high,ok,1false values:off,false,disable,disabled,no,low,ko,0The BOOTP daemon associates each MAC address to an assigned IP address. As long
as the BOOTP daemon is running, the same IP address is always assigned to the
same client. The address never gets back to the pool,i.e.it cannot be
re-assigned to another machine even when the lease expires.This is especially useful for a full network-based installation, where each
client requests at least an IP address twice:when BIOS kicks off, its PXE ROM code requests an IP address, then requests
an executable to run,when the executable runs, it usually boots up an OS (Linux, …), which in
turn requests an IP address to resume the installation.[logger]sectiontypeThe type of logger, if any.stderr,file,syslogornone.levelThe level of logger verbosity.critical,error,infoordebug.fileThe path to the output log file, iftypeis set tofile.[bootp]sectionaccessType of access control list. If this option is not defined, all BOOTP
requests are served, as long as the defined pool is not exhausted. It can be
one among the following options:mac: incoming BOOTP requests are filtered out based on the MAC address
of the requester.uuid: incoming PXE requests are filtered out based on the UUID of the
request. UUIDs are not emitted from simple BOOTP or DHCP clients, so this
option is only meaningful for PXE-enabled clients.http: incoming requests are forwarded to another host, through simple
HTTP GET requests. The MAC address and the UUID if it exists, are sent
to the HTTP server which replies to grant or deny access to the requester.A section named after the selected option should exist to define the access
list.addressSpecifies the network to listen to requesters for receiving incoming BOOTP
requests. On most hosts, the only valid address is0.0.0.0. Some hosts
accept subnetworks (such as192.168.1.0). It is recommended not to
define this option, and use an ACL to reject clients. Hosts will multiple
network interfaces, it might not be possible to listen to single network.
Implementing such as feature would require to use RAW sockets, which falls
out of scope for this simple server.allow_simple_dhcpThe default behaviour is to expect PXE requests. In order to serve simple
BOOTP or DHCP requests, this option should be enabled. This option accepts
a boolean value.boot_fileBoot filename to send back to the BOOTP client, which usually requests such
a file over TFTP to boot up after it has been assigned a network address.domainDomain part of the client FQDN, that is the network’s domain name.dnsIP address of the DNS server. The server only accepts a single address.lease_timeValidity in seconds of a DHCP lease. Please note that the BOOTP daemon does
not manage lease expiration; this value has therefore little meaning.pool_startFirst address to allocate for a BOOT client.pool_countThe maximum number of clients that can be served.notifyWhen defined, the IP address and port (using a column separator:a.b.c.d:p) to which a UDP notification message should be sent whenever
a client requests an IP address to the BOOTP daemon.portAlternative port for incoming BOOTP requests.timeoutTimeout in seconds for a response from a remote authentication host to be
received, when ACL is enabled and set to use the HTTP protocol. If no answer
is received from the remote host, the BOOTP daemon ignores the incoming
BOOTP/DHCP request.servernameName of the BOOTP server.[mac]sectionThe[mac]section contains one entry for each MAC address to allow or
block. The value for each entry is a boolean,i.e.:AA-BB-CC-DD-EE-FF = enable[uuid]sectionThe[uuid]section contains one entry for each UUID to allow or block.
The value for each entry is a boolean,i.e.:xxxxxxxx-aaaa-bbbb-cccc-yyyyyyyyyyyy = enable[http]sectionlocationThe URL prefix to contact the remote server for boot permission.pxeThe path to append to the URL prefix when the requester emits PXE
information. A regular PC with PXE capability emits a PXE boot request when
the BIOS kicks off. The remote HTTP server may therefore identify a BIOS
boot sequence upon receiving this kind of request from thepybootddaemon.dhcpThe path to append to the URL prefix when the requester emits simple DHCP
information. A regular OS emits a simple DHCP request at start up. The
remote HTTP server may therefore identify an OS boot sequence upon receiving
this kind of request from thepybootddaemon.Thepxe/dhcpoption pair enables the remote HTTP server to identify
the boot phase: either a BIOS initialization or an OS boot sequence. When such
differentiation is useless, both options may refer to the same path.[tftp]sectionaddressAddress to listen to incoming TFTP requests. When the BOOTP daemon is
enabled this option is better omitted, as the address is automatically
received from the BOOTP daemon.blocksizeSize of each exchanged data block. It is recommended to leave the default
value, as some clients may not accept other values.portAlternative port for incoming TFTP request.timeoutTimeout in seconds for an acknowledgment from the TFTP client to be
received. If the timeout expires the TFTP server retransmits the last
packet. It can be expressed as a real value.rootBase directory for the TFTP service. This path is automatically prepended
to the pathname issued from the TFTP client. It can either be:a relative path to the daemon directory, when therootoption starts
with./,an absolute path, when therootoption starts with/,a URL prefix, to access remote files.[filters]sectionThefilterssection allows on-the-fly pathnames transformation. When a TFTP
client requests some specific filenames, thetftpserver can translate them
to other ones.This option is useful to serve the very same configuration file (‘’e.g.’’pxelinux.cfg) whatever the remote client, thus speeding up the boot
process. This option also enables to access files that are not stored within
the currently configured path (see therootoption).Each option of thefilterssection represents a file pattern to match. It
accepts standard wildcard characters:*and?. The option’s value defines
the translated path.Thevaluepart can contain variables. Variables are written with enclosing
braces, such as{varname}.For now, the only supported variable isfilename, which is replaced with
the actual requested filename.Thevaluepart can also contain a special marker, that tells thetftpdaemon to read the replacement pattern from a file. This special marker should
be written with enclosing brackets, such as[file].ExamplesThe following filter:pxelinux.cfg/* = pybootd/etc/pxe.cfgtells thetftpserver that all client requests matching thepxelinux.cfg/*pattern should be served thepybootd/etc/pxe.cfgfile
instead. This prevents the client to perform the usual time-costing fallback
requests using UUID, MAC, and suffix addresses before eventually falling
back to the simplepxelinux.cfgfile.The following filter:startup = [dir/{filename}.cfg]tells thetftpserver that when thestartupfile is requested, it should
read out the actual filename from thedir/startup.cfgfile.HTTP-based authenticationThis option enabled the delegation of the BOOTP authorization to a remote web
server. Aspybootdemits standard HTTP GET requests and expects standard
HTTP reply codes, any web server may be used to manage authorizations.This web server receives HTTP GET requests with URLs formatted as follows:http://server/path?mac=AA-BB-CC-DD-EE-FF&uuid=xxxxxxxx-aaaa-bbbb-cccc-yyyyyyyyyyyywhere:http://servermatches thelocationoption,/pathmatches thepxeordhcpoptions of the[http]section.The web server should reply either with:200 Okresult if the requester is to be assigned an IP address, or401 Unauthorizedresult if it is to be ignored.Thepybootdpackage contains a minimalist HTTP server that demonstrates
this feature. It can be found within thetests/subdirectory. See theconfig.inifile for this test daemon. The test daemon expects thepxepath to be set to/bootand thedhcppath to/linux.Sample configurationsInstalling a Debian 6.0 machine from the official archiveAs thetftpdaemon is able to retrieve remote files using the HTTP protocol,
there is no need to manually download any file from a Debian mirror. The daemon
will forward all file requests to the mirror on behalf of the client being
installed.Thepybootd.iniwould contain:[logger]
; show requests on the standard error output of the daemon
type = stderr
; show informative and error messages only (disable verbose mode)
level = info

[bootp]
; do not force a full PXE boot-up cycle to accept the client
allow_simple_dhcp = enable
; First BOOTP/DHCP address to generate
pool_start = 192.168.1.100
; Google DNS
dns = 8.8.8.8
; boot-up executable the client should request through TFTP
boot_file = pxelinux.0

[tftp]
; URL to install a Debian 6.0 Intel/AMD 64-bit network installation
root = http://http.us.debian.org/debian/dists/squeeze/main/installer-amd64/current/images/netboot

[filters]
; serve a simple configuration file to the linux PXE helper
pxelinux.cfg/* = pybootd/etc/pxe.cfgThepool_startparameter should be a valid address on the host’s networks,
and therootURL may be changed to use alternative mirror and path.Please note that to complete the network installation, the client should be
able to access the remote resources on its own - as with a network ISO image
installation. There are two ways to achieve this:either enable IP forwarding on thepybootdhost (seeforward.shscript within thepybootdpackage), orbe sure to connect the network cable of the client to a LAN that has direct
access to the Internet, once the first installation stage is complete.