mirror of
https://github.com/eblot/pybootd.git
synced 2024-09-11 14:06:57 +03:00
Fix English grammar
This commit is contained in:
parent
d67e96da08
commit
d1f0bfcbf7
253
README.rst
253
README.rst
@ -5,15 +5,15 @@ PyBootd
|
||||
Overview
|
||||
~~~~~~~~
|
||||
|
||||
PyBootd is a daemon that supports a subset of the BOOTP, DHCP, PXE and TFTP
|
||||
PyBootd 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, without requiring any other tools but a standard
|
||||
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 CD/DVD.
|
||||
physical support such as a USB key or a CD/DVD.
|
||||
|
||||
Requirements
|
||||
~~~~~~~~~~~~
|
||||
@ -33,8 +33,8 @@ Permissions
|
||||
- DHCP 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 range (<1024), the superuser privileges
|
||||
are required on Unix hosts (Linux, Mac OS X, ...) to start up these daemons.
|
||||
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.
|
||||
|
||||
Status
|
||||
~~~~~~
|
||||
@ -63,8 +63,8 @@ Supported features
|
||||
- Files requested from TFTP clients can be filtered and transformed into
|
||||
local filenames using filters
|
||||
|
||||
- It is possible to use pybootd with only one of the offered services, either
|
||||
TFTP or DHCP
|
||||
- It is possible to use pybootd with only one of the services, either TFTP or
|
||||
DHCP
|
||||
|
||||
FAQ
|
||||
~~~
|
||||
@ -75,13 +75,13 @@ Common errors
|
||||
``pybootd.pxed.BootpError: Unable to detect network configuration``
|
||||
This error is often triggered when the ``pool_start`` address is not part of
|
||||
a valid network. Double check the network configuration and fix up the
|
||||
``[bootp]`` section so that it match the actual network.
|
||||
``[bootp]`` section so that it matches the actual network.
|
||||
|
||||
Configuration
|
||||
-------------
|
||||
|
||||
``pybootd`` as a few option switches. The daemon offers two services: Bootp
|
||||
(which supports Dhcp and PXE extensions) and Tftp. It is possible to disable
|
||||
``pybootd`` has 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]
|
||||
@ -94,7 +94,7 @@ Options:
|
||||
-p, --pxe enable BOOTP/DHCP/PXE server only
|
||||
-t, --tftp enable TFTP server only
|
||||
|
||||
``pybootd`` daemon uses a configuration file, in .ini format, for all other
|
||||
``pybootd`` daemon uses a configuration file, in ``.ini`` format, for all other
|
||||
options.
|
||||
|
||||
Some options accept a boolean value. The following values are recognized:
|
||||
@ -104,30 +104,31 @@ Some options accept a boolean value. The following values are recognized:
|
||||
- false values: ``off``, ``false``, ``disable``, ``disabled``, ``no``, ``low``,
|
||||
``ko``, ``0``
|
||||
|
||||
The BOOTP daemon associates each MAC address to an assigned IP address, so 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 if the lease expires.
|
||||
The 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 installation, where each client
|
||||
request at least an IP address twice:
|
||||
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 for an IP address, then
|
||||
requests for an executable to run,
|
||||
- when the executable runs, it usually boots up an OS (Linux, ...) which in
|
||||
turns requests for an IP address to resume the installation.
|
||||
- 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]`` section
|
||||
....................
|
||||
|
||||
``type``
|
||||
The type of logger, if any. ``stderr``, ``file``, ``syslog`` or ``none``
|
||||
The type of logger, if any. ``stderr``, ``file``, ``syslog`` or ``none``.
|
||||
|
||||
``level``
|
||||
The level of logger verbosity. ``critical``, ``error``, ``info`` or ``debug``
|
||||
The level of logger verbosity. ``critical``, ``error``, ``info`` or
|
||||
``debug``.
|
||||
|
||||
``file``
|
||||
The path to the output log file, if ``type`` is set to ``file``
|
||||
The path to the output log file, if ``type`` is set to ``file``.
|
||||
|
||||
``[bootp]`` section
|
||||
...................
|
||||
@ -135,83 +136,87 @@ request at least an IP address twice:
|
||||
``access``
|
||||
Type 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:
|
||||
one among the following options:
|
||||
|
||||
- ``mac``: incoming BOOTP requests are filtered out based on the MAC address
|
||||
of the requester
|
||||
of the requester.
|
||||
- ``uuid``: incoming PXE requests are filtered out based on the UUID of the
|
||||
request. UUID are not emitted from simple BOOTP or DHCP clients, so this
|
||||
option is only meaningful for PXE-enabled clients
|
||||
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 the access to the
|
||||
BOOTP client.
|
||||
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 with the same name should exist to define the access list.
|
||||
A section named after the selected option should exist to define the access
|
||||
list.
|
||||
|
||||
``address``
|
||||
Which network to listen to on the host for receiving incoming BOOTP
|
||||
Specifies the network to listen to requesters for receiving incoming BOOTP
|
||||
requests. On most hosts, the only valid address is ``0.0.0.0``. Some hosts
|
||||
accepts subnetworks (such as ``192.168.1.0``). It is recommended not to
|
||||
define this option, and use an ACL to reject clients. On hosts that have
|
||||
more than one network cards, it might not be possible to listen on a
|
||||
single network interface. It would require a much more complex
|
||||
implementation, using RAW sockets.
|
||||
accept subnetworks (such as ``192.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_dhcp``
|
||||
The default behaviour of the daemon 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.
|
||||
The 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_file``
|
||||
Boot filename to send back to a BOOTP client, so that it can request it
|
||||
over TFTP to boot up after being assigned a network address.
|
||||
Boot 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.
|
||||
|
||||
``domain``
|
||||
Domain part of the client FQDN, that is the domain name of the network.
|
||||
Domain part of the client FQDN, that is the network's domain name.
|
||||
|
||||
``dns``
|
||||
IP address of the DNS server.
|
||||
IP address of the DNS server. The server only accepts a single address.
|
||||
|
||||
``lease_time``
|
||||
Validity, in seconds, of a DHCP lease. Note that the BOOTP daemon does not
|
||||
managed lease expiration, this value has therefore little meaning.
|
||||
Validity in seconds of a DHCP lease. Please note that the BOOTP daemon does
|
||||
not manage lease expiration; this value has therefore little meaning.
|
||||
|
||||
``pool_start``
|
||||
First address to allocate for a BOOT client.
|
||||
|
||||
``pool_count``
|
||||
How many clients can be served
|
||||
The maximum number of clients that can be served.
|
||||
|
||||
``notify``
|
||||
If 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.
|
||||
When 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.
|
||||
|
||||
``port``
|
||||
Alternative port for incoming BOOTP requests
|
||||
Alternative port for incoming BOOTP requests.
|
||||
|
||||
``timeout``
|
||||
Timeout in seconds to receive a response from a remote authentication host,
|
||||
when ACL are enabled using the HTTP protocol. IF no answer is received from
|
||||
the remote host, the BOOTP daemon ignores the incoming BOOTP/DHCP request.
|
||||
Timeout 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.
|
||||
|
||||
``servername``
|
||||
Name of the BOOT server, which some clients might expect.
|
||||
Name of the BOOTP server.
|
||||
|
||||
``[mac]`` section
|
||||
.................
|
||||
|
||||
``AA-BB-CC-DD-EE-FF``
|
||||
The ``[mac]`` section contains one entry for each MAC address to allow or
|
||||
block. The value for each entry is a boolean.
|
||||
block. The value for each entry is a boolean, *i.e.*::
|
||||
|
||||
AA-BB-CC-DD-EE-FF = enable
|
||||
|
||||
|
||||
``[uuid]`` section
|
||||
..................
|
||||
|
||||
``xxxxxxxx-aaaa-bbbb-cccc-yyyyyyyyyyyy``
|
||||
The ``[uuid]`` section contains one entry for each UUID to allow or block.
|
||||
The value for each entry is a boolean.
|
||||
The value for each entry is a boolean, *i.e.*::
|
||||
|
||||
xxxxxxxx-aaaa-bbbb-cccc-yyyyyyyyyyyy = enable
|
||||
|
||||
``[http]`` section
|
||||
..................
|
||||
@ -220,19 +225,19 @@ request at least an IP address twice:
|
||||
The URL prefix to contact the remote server for boot permission.
|
||||
|
||||
``pxe``
|
||||
The path to append to the URL prefix when the BOOTP client emits PXE
|
||||
The 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 when it receives this kind of request from the *pybootd* daemon.
|
||||
boot sequence upon receiving this kind of request from the *pybootd* daemon.
|
||||
|
||||
``dhcp``
|
||||
The path to append to the URL prefix when the BOOTP client emits simple DHCP
|
||||
The 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 when it receives this
|
||||
kind of request from the *pybootd* daemon.
|
||||
remote HTTP server may therefore identify an OS boot sequence upon receiving
|
||||
this kind of request from the *pybootd* daemon.
|
||||
|
||||
The dual ``pxe``/``dhcp`` options allow to distinguish the boot phase on the
|
||||
remote HTTP server: either a BIOS initialization or an OS boot. When such
|
||||
The ``pxe``/``dhcp`` option 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]`` section
|
||||
@ -240,53 +245,53 @@ differentiation is useless, both options may refer to the same path.
|
||||
|
||||
``address``
|
||||
Address to listen to incoming TFTP requests. When the BOOTP daemon is
|
||||
enabled, this option is better omitted, as the address is automatically
|
||||
enabled this option is better omitted, as the address is automatically
|
||||
received from the BOOTP daemon.
|
||||
|
||||
``blocksize``
|
||||
Size of each data block exchange with the client. It is recommend to
|
||||
leave the default value, as some clients may not accept other values
|
||||
Size of each exchanged data block. It is recommended to leave the default
|
||||
value, as some clients may not accept other values.
|
||||
|
||||
``port``
|
||||
Alternative port for incoming TFTP request
|
||||
Alternative port for incoming TFTP request.
|
||||
|
||||
``timeout``
|
||||
Timeout in seconds to receive an acknowledgment from the TFTP client. If
|
||||
the timeout expires, the TFTP server retransmits the last packet. If can
|
||||
be expressed as a real value.
|
||||
Timeout 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.
|
||||
|
||||
``root``
|
||||
Base 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, if the ``root`` option starts
|
||||
with ``./``
|
||||
- an absolute path, if the ``root`` option starts with ``/``
|
||||
- a URL prefix, to accces remote files
|
||||
- a relative path to the daemon directory, when the ``root`` option starts
|
||||
with ``./``,
|
||||
- an absolute path, when the ``root`` option starts with ``/``,
|
||||
- a URL prefix, to access remote files.
|
||||
|
||||
``[filters]`` section
|
||||
.....................
|
||||
|
||||
The ``filters`` option allows on-the-fly pathnames transformation. When a TFTP
|
||||
request for some specific filenames, the TFTP daemon can translate then to
|
||||
other ones.
|
||||
The ``filters`` section allows on-the-fly pathnames transformation. When a TFTP
|
||||
client requests some specific filenames, the *tftp* server can translate them
|
||||
to other ones.
|
||||
|
||||
This option can be useful to serve the very same configuration file
|
||||
(``pxelinux.cfg`` for example) whatever the remote client, hence speeding up
|
||||
the boot process. This option also enable to access files that are not stored
|
||||
within the currently configured path (see the ``root`` option).
|
||||
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 the ``root`` option).
|
||||
|
||||
Each option of the ``filters`` section represents a file pattern to match. It
|
||||
accepts standard wildcard characters, `*` and `?`. The value defines the
|
||||
translated path.
|
||||
accepts standard wildcard characters: `*` and `?`. The option's value defines
|
||||
the translated path.
|
||||
|
||||
The *value* part can contain variables, which are replaced in-place.
|
||||
Variables are written with enclosing braces, such as ``{varname}``.
|
||||
The *value* part can contain variables. Variables are written with enclosing
|
||||
braces, such as ``{varname}``.
|
||||
|
||||
For now, the only supported variable is ``filename``, which is replaced with
|
||||
the actual requested filename.
|
||||
|
||||
The *value* part can also contains a special marker, that tells the *tftp*
|
||||
The *value* part can also contain a special marker, that tells the *tftp*
|
||||
daemon to read the replacement pattern from a file. This special marker should
|
||||
be written with enclosing brackets, such as ``[file]``.
|
||||
|
||||
@ -297,53 +302,54 @@ The following filter::
|
||||
|
||||
pxelinux.cfg/* = pybootd/etc/pxe.cfg
|
||||
|
||||
tells the *tftp* daemon that all client requests that matches the
|
||||
``pxelinux.cfg/*`` pattern should be server the ``pybootd/etc/pxe.cfg`` file
|
||||
instead. This avoids the client to perform the usual time-costing fallback
|
||||
requests using UUID, then MAC, then suffix address before eventually falling
|
||||
tells the *tftp* server that all client requests matching the
|
||||
``pxelinux.cfg/*`` pattern should be served the ``pybootd/etc/pxe.cfg`` file
|
||||
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 simple ``pxelinux.cfg`` file.
|
||||
|
||||
The following filter::
|
||||
|
||||
startup = [dir/{filename}.cfg]
|
||||
|
||||
tells the *tftp* daemon that when requested the ``startup`` file, the tftp
|
||||
daemon should look for the actual name within the ``dir/startup.cfg`` file.
|
||||
tells the *tftp* server that when the ``startup`` file is requested, it should
|
||||
read out the actual filename from the ``dir/startup.cfg`` file.
|
||||
|
||||
HTTP-based authentication
|
||||
-------------------------
|
||||
|
||||
This option allows to delegate the BOOTP authorization to a remote web server.
|
||||
Any web server may be used as pybootd emits standard HTTP GET requets and
|
||||
expects standard HTTP reply codes.
|
||||
This option enabled the delegation of the BOOTP authorization to a remote web
|
||||
server. As *pybootd* emits standard HTTP GET requests and expects standard
|
||||
HTTP reply codes, any web server may be used to manage authorizations.
|
||||
|
||||
This server receives HTTP GET requests with URLs such as::
|
||||
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-yyyyyyyyyyyy
|
||||
|
||||
where ``http://server`` matches the ``location`` option and ``/path`` matches
|
||||
the ``pxe`` or ``dhcp`` options of the ``[http]`` section.
|
||||
where:
|
||||
|
||||
- ``http://server`` matches the ``location`` option,
|
||||
- ``/path`` matches the ``pxe`` or ``dhcp`` options of the ``[http]`` section.
|
||||
|
||||
The web server should reply either with:
|
||||
|
||||
- ``200 Ok`` result if the bootp client should be assigned an IP address, or
|
||||
- ``401 Unauthorized`` result if the bootp client should be ignored.
|
||||
|
||||
The ``pybootd`` package contains in the ``tests/`` subdirectory a minimalist
|
||||
HTTP server that demonstrates this feature. See the ``config.ini`` file for
|
||||
this test daemon. The test daemon expects the ``pxe`` path to be set to
|
||||
``/boot`` and the ``dhcp`` path set to ``/linux``.
|
||||
- ``200 Ok`` result if the requester is to be assigned an IP address, or
|
||||
- ``401 Unauthorized`` result if it is to be ignored.
|
||||
|
||||
The ``pybootd`` package contains a minimalist HTTP server that demonstrates
|
||||
this feature. It can be found within the ``tests/`` subdirectory. See the
|
||||
``config.ini`` file for this test daemon. The test daemon expects the ``pxe``
|
||||
path to be set to ``/boot`` and the ``dhcp`` path to ``/linux``.
|
||||
|
||||
Sample configurations
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Installing a Debian 6.0 machine from the official archive
|
||||
---------------------------------------------------------
|
||||
As the TFTP daemon is able to retrieve remote file, using the HTTP protol,
|
||||
there is no need to manually download any file from a Debian mirror. The TFTP
|
||||
daemon will forward all file requests to the mirror on behalf of the client
|
||||
being installed.
|
||||
As the *tftp* daemon 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.
|
||||
|
||||
The ``pybootd.ini`` would contain::
|
||||
|
||||
@ -354,13 +360,13 @@ The ``pybootd.ini`` would contain::
|
||||
level = info
|
||||
|
||||
[bootp]
|
||||
; to not force a full PXE boot up cycle to accept the client
|
||||
; 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-up executable the client should request through TFTP
|
||||
boot_file = pxelinux.0
|
||||
|
||||
[tftp]
|
||||
@ -368,18 +374,17 @@ The ``pybootd.ini`` would contain::
|
||||
root = http://http.us.debian.org/debian/dists/squeeze/main/installer-amd64/current/images/netboot
|
||||
|
||||
[filters]
|
||||
; serves a simple configuration file to the linux PXE helper
|
||||
; serve a simple configuration file to the linux PXE helper
|
||||
pxelinux.cfg/* = pybootd/etc/pxe.cfg
|
||||
|
||||
The ``pool_start`` parameter should be a on an existing network on the host,
|
||||
and the ``root`` URL may be changed to use an alternative mirror and path.
|
||||
The ``pool_start`` parameter should be a valid address on the host's networks,
|
||||
and the ``root`` URL may be changed to use alternative mirror and path.
|
||||
|
||||
Note that to complete the network installation, the client should be able to
|
||||
access the remote file on its own - as with a network ISO image. There are two
|
||||
ways to achieve this:
|
||||
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 the *pybootd* host (see ``forward.sh``
|
||||
script within the ``pybootd`` package), or
|
||||
- be sure to connect the network cable of the client to a LAN that have
|
||||
direct access to the Internet, once the first installation stage is
|
||||
complete.
|
||||
- be 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.
|
||||
|
Loading…
Reference in New Issue
Block a user