PyPXE

Pure Python PXE (DHCP-(Proxy)/TFTP/HTTP/NBD) Server

Showing:

Popularity

Downloads/wk

0

GitHub Stars

426

Maintenance

Last Commit

2mos ago

Contributors

19

Package

Dependencies

0

License

MIT

Categories

Readme

About

This repository contains code that provides a working PXE server (via HTTP, TFTP, DHCP, and/or iPXE) implemented purely in Python. Please read DOCUMENTATION.md for further explanation of the PyPXE project as well as recommended use. See the issues page for open issues, bugs, and enhancements/improvements.

DISCLAIMER: None of the implemented services are fully compliant with any standards or specifications. However, the true specifications and standards were followed when building PyPXE and while they work for PXE any other uses are purely coincidental. Use at your own risk.

Usage

Using PyPXE as a Library

PyPXE implements the following services for the purpose of creating a Python-based PXE environment: TFTP, HTTP, and DHCP. Each PyPXE service must be imported individually. For example, to import the TFTP service simply use:

from pypxe import tftp

or, if you prefer, you can use:

import pypxe.tftp

For more information on how each service works and how to manipulate them, see DOCUMENTATION.md.

QuickStart

pypxe.server uses all three services in combination with the option of enabling/disabling them individually while also setting some options. Run pypxe.server with --help or -h to see what command line arguments you can pass. Treat the provided netboot directory as tftpboot that you would typically see on a TFTP server, put all of your network-bootable files in there and setup your menu(s) in netboot/pxelinux.cfg/default.

Simply run the following command and you will have an out-of-the-box PXE-bootable server that runs TFTP and serves files out of the netboot directory!

$ sudo python -m pypxe.server

If you require the ability to handle DHCP PXE requests then you can either enable the built-in DHCP server (after configuring, of course)...

$ sudo python -m pypxe.server --dhcp

...or start pypxe.server in ProxyDHCP mode rather than a full DHCP server to prevent DHCP conflicts on your network...

$ sudo python -m pypxe.server --dhcp-proxy

PyPXE Server Arguments

The following are arguments that can be passed to pypxe.server when running from the command line:

Main Arguments
ArgumentDescriptionDefault
--ipxeEnable iPXE ROMFalse
--no-ipxeDisable iPXE ROMTrue
--httpEnable built-in HTTP serverFalse
--no-httpDisable built-in HTTP serverTrue
--dhcpEnable built-in DHCP serverFalse
--dhcp-proxyEnable built-in DHCP server in proxy mode (implies --dhcp)False
--tftpEnable built-in TFTP server which is enabled by defaultTrue
--no-tftpDisable built-in TFTP server which is enabled by defaultFalse
--debugEnable selected services in DEBUG mode; services are selected by passing the name in a comma separated list. Options are: http, tftp and dhcp; one can also prefix an option with - to prevent debugging of that service; for example, the following will enable debugging for all services except the DHCP service --debug all,-dhcp. This mode adds a level of verbosity so that you can see what's happening in the background.''
--verboseEnable selected services in verbose mode; services are selected by passing the name in a comma separated list. Follows the same syntax for selecting service as --debug._''
--configLoad configuration from JSON file. (see example_cfg.json)None
--static-configLoad DHCP lease configuration from JSON file. (see example-leases.json)None
--save-leasesSaves allocated leases on HUP, INT(^C), ALRM and TERM. Loads on start if the file exists alreadyNone
--syslogSpecify a syslog serverNone
--syslog-portSpecify a syslog server port514
DHCP Service Arguments
ArgumentDescriptionDefault
--dhcp-server-ip DHCP_SERVER_IPSpecify DHCP server IP address192.168.2.2
--dhcp-server-port DHCP_SERVER_PORTSpecify DHCP server port67
--dhcp-begin DHCP_OFFER_BEGINSpecify DHCP lease range start192.168.2.100
--dhcp-end DHCP_OFFER_ENDSpecify DHCP lease range end192.168.2.150
--dhcp-subnet DHCP_SUBNETSpecify DHCP subnet mask255.255.255.0
--dhcp-router DHCP_ROUTERSpecify DHCP lease router192.168.2.1
--dhcp-dns DHCP_DNSSpecify DHCP lease DNS server8.8.8.8
--dhcp-broadcast DHCP_BROADCASTSpecify DHCP broadcast address''
--dhcp-fileserver DHCP_FILESERVERSpecify DHCP file server IP address192.168.2.2
--dhcp-whitelistOnly serve clients specified in the static lease file (--static-config)False
TFTP Service Arguments
ArgumentDescriptionDefault
--tftp-server-ip TFTP_SERVER_IPSpecify TFTP server IP address0.0.0.0
HTTP Service Arguments
ArgumentDescriptionDefault
--http-server-ip HTTP_SERVER_IPSpecify HTTP server IP address0.0.0.0
--http-port HTTP_PORTSpecify HTTP server Port80
File Name/Directory Arguments
ArgumentDescriptionDefault
--netboot-dir NETBOOT_DIRSpecify the local directory where network boot files will be served'netboot'
--netboot-file NETBOOT_FILESpecify the PXE boot file nameautomatically set based on what services are enabled or disabled, see DOCUMENTATION.md for further explanation
Network Block Device Arguments
ArgumentDescriptionDefault
--nbd NBD_BLOCK_DEVICESpecify the block device to be served by NBD and enable NBD. This can be a disk image.''
--nbd-writeOpen the block device for write access. UNSAFE: Multiple clients can cause corruptionFalse
--nbd-cowWhen write is enabled, create a volatile file per client with their changes. Clients can write but changes are not shared or kept.True (Only applies if write is on)
--nbd-cow-in-memClient volatile changes are stored in RAM rather than on disk. WARNING: High RAM usage (up to sizeof(block device)*clients)False
--nbd-copy-to-ramDisk image is copied to RAM on start to speed up access. Changes are lost when write is used without cow.False
--nbd-serverThe NBD server IP address to bind to0.0.0.0
--nbd-portThe NBD server port to bind to10809

Notes

  • Core.iso located in netboot is from the TinyCore Project and is provided as an example to network boot from using PyPXE
  • chainload.kpxe located in netboot is the undionly.kpxe from the iPXE Project
  • ldlinux.c32, libutil.c32, pxelinux.0, menu.c32, and memdisk located in netboot are from the SYSLINUX Project version 6.02

Rate & Review

Great Documentation0
Easy to Use0
Performant0
Highly Customizable0
Bleeding Edge0
Responsive Maintainers0
Poor Documentation0
Hard to Use0
Slow0
Buggy0
Abandoned0
Unwelcoming Community0
100