staticDHCPd is an all-Python, RFC 2131-compliant DHCP server, with support for most common DHCP extensions and extensive site-specific customisation.
staticDHCPd 2.0.0 is finally in rc1 status!
The 2.0.0 branch now needs to be tested; the running checklist follows (if you test a thing, send e-mail to Neil Tallim at the address in any source file or comment on the announcement post):
- staticDHCPd
- Long-term soak-test
- Stable memory usage settles after logs finish growing
- No processing errors stable in a home network for more than 24 hours
- E-mail logging facility
- Databases
- Postgres external validation required
- MySQL external validation required
- Oracle external validation required
- SQLite
- Long-term soak-test
- Extensions
- httpdb done
- statistics (with various config options)
- statistics (with pycha)
- dynamism
- feedservice done
- Documentation
- libpydhcpserver
- Sanity check
- Proofreading
- staticDHCPd
- Sanity check
- Proofreading
- libpydhcpserver
Since no major issues were reported (but also not much feedback), the code will migrate to GitHub in late April, 2015 and packages will be built at that time; anything not explicitly tested will be tracked as release errata.
At this point, no new features will be added until the system is stable (but please submit ideas to the issue-tracker anyway). Any non-bugfix commits will be things to prepare for the Debian/RPM packages or minor formatting tweaks.
staticDHCPd is appropriate for a very wide range of applications. In particular, it's an excellent choice for the following:
- Sites with a need to centrally manage a potentially vast number of clients, all of which are known
- staticDHCPd was originally developed to meet the needs of a growing ISP, with relays and multiple subnets
- LAN parties
- You can use the dynamic module to assign guest leases, have people connect log in to a registration page, which provisions a static assignment, and then let them plug into the real network; you can have staticDHCPd do the layer-2-to-layer-3 bridging for the website with just a few lines of code, so your users don't need to check any addresses on their own
- Research and testing labs
- Simple setup and configuration, even for network-based booting (PXE, TFTP), so you can focus on what matters, not esoteric syntax and troubleshooting
- Home or small office environments where you'll have an always-on server
- All of the important stuff can be static, so you can quickly spot irregularities with device auto-configuration, while still offering a dynamic network for guests
- This is especially helpful for laptops that provide services, where you need to be able to auto-configure when you're out somewhere, but want everything to "just work" when you get home, without needing to change from DHCP to static addressing
- Any situation in which you've ever thought "this would be so much easier if only I could control this one thing"
- staticDHCPd has extensive scripting support
- It also lets you customise pretty much everything that a client sees
- And you can tie it into any database imaginable
On the other hand, it's the wrong choice in the following cases:
- Your environment is entirely dynamic
- Consider the ISC's server for this
- Your environment is large and mostly dynamic, with need for only a few static assignments
- Again, the ISC's server is a good choice
- You already have a solution that works well for your needs
- Why are you considering alternatives?
- Your employer won't let you run anything without an SLA
- You're probably looking for solutions in the wrong place
- You actually want to have a hard time upgrading from one version to the next
- staticDHCPd will let you take your config file and custom code from version 1.0 and drop it into 2.0 with no changes required, even though the codebase running it is entirely different
- The concept of a feature-rich server running with a 4MB footprint scares you
If you think it might be a good match for your needs, take a look at its five-minute quick-start guide.
staticDHCPd was originally created for an ISP, which, as you can imagine, requires that its provisioning tools offer full control over which MACs are allowed to learn about and gain access to its network. It was also necessary that the database of authorised clients be updatable with no delay and that it could be easily linked to other systems to streamline the provisioning process, both of which were factors in excluding the ISC's server as a candidate.
Its name comes from these circumstances, in which the only thing required of the system was that it could serve static "leases" and do it well. That's no longer the case, though, since it's matured quite a bit and picked up enough scriptable flexibility that dropping in a module to handle dynamic allocation can be done with five lines of customisation code (which is given its own, out-of-the-core-codebase home), only one of which is truly site-dependent.
Internally, staticDHCPd makes use of a forked version of Mathieu Ignacio's pydhcplib (though few traces of its ancestry remain) and is developed against Debian-based GNU/Linux distributions and has been shown to operate on FreeBSD and Apple Mac OS X, for which it was originally created. It should run on any Unix variant without issue, but is not supported on Microsoft Windows, due to a lack of familiarity with permissions, sockets, and signals on that platform (a patch would be welcome, but must be accompanied by a commitment of maintenance).
A rich, fully customisable and extensible web-management console is included (and reasonably secure, through optional use of DIGEST authentication), intended to make life easy for NOC staff or curious administrators. It, a statistics engine, and a host of other features are all optional and lazily loaded, so your server will never be unnecessarily bloated.
Comprehensive logging and reporting systems are built-in, from standard things like self-rotating files, to in-memory web-dashboard reporting, to Atom feeds for keeping an eye on the server while you stay up to date with the news, to e-mail notification for emergencies.
All features are continuously and thoroughly tested against the ISC's dhclient and dhcrelay, to ensure compatibility with the DHCP protocol in realistic contexts. Furthermore, its developer uses it for practical purposes: a single home server manages multiple networks, containing various consumer electronics (phones, tablets, game consoles, printers), dedicated servers, laptops, desktops, and guest devices.
All documentation found outside of the following resources is pre-2.0.0 and should be considered deprecated.
libpydhcpserver: http://static.uguu.ca/projects/libpydhcpserver/doc/
staticDHCPd: http://static.uguu.ca/projects/staticDHCPd/doc/
Stable releases of staticDHCPd are available from the releases page.
Debian packages coming shortly after 2.0.0 is released.
The README, linked above, contains a quick-start guide. It will walk you through creating a simple configuration database and running staticDHCPd without making any changes to your server.
Just run sudo sh install.sh, or whatever equivalent is appropriate for your platform, and everything will be where it needs to go. You'll also receive some helpful (disclaimer: only as helpful as its users) text that will explain how to make the server run automatically on boot, specific to your platform.
You'll find a sample configuration file in /etc/staticDHCPd/; copy it to the same directory, without the .sample suffix, and you're ready for the next step. (If you're upgrading, just leave your old file alone; it'll work just fine)
While SQLite or INI-files are fine for home users and small labs, most environments will want to use a multi-client database service, to allow for runtime updates. Full details on how to configure staticDHCPd to speak with a server, and many more options, are described in the configuration guide in the doc directory.
For the server itself, specific schema-structuring is required, for which scripts and examples can be found in the samples directory.
Additionally, some database engines require additional packages:
- Postgres support requires installation of the psycopg library (python-psycopg2)
- Oracle support requires installation (and likely compilation) of the cx-oracle library
- MySQL support requires installation of the MySQLdb library (python-mysqlbd)
- Connection-pooling requires eventlet (python-eventlet)
While you're at it, you should also install python-scapy if you intend to use dynamic provisioning. It'll allow your network to serve as a living database for reconstructing leases after a server restart. scapy is also a pretty great library in general. And, if you want the snazzy load-graph in the web interface, also install python-pycha. These libraries aren't necessary, though: the associated components will function in a limited capacity if they're absent.
Once everything's configured, you can launch the daemon with sudo staticDHCPd. You'll need to start it with superuser permissions because it needs to bind to restricted ports, but it'll switch to whatever permissions you specified in the config file once setup is complete.
If you're using caching (or INI) with your database, you can send SIGHUP to the process to cause it to reinitialise, clearing the cache (or re-reading the file), and invoking the reinitialisation behaviour of any custom modules that subscribe to the event. You can also, if enabled, access this functionality from the web interface.
To kill the server, you can ^C it in non-daemon mode, or send SIGTERM otherwise. It'll go down gracefully.
staticDHCPd is available under the GPLv3. Accordingly, its full source code and all assets are available for use by anyone who wants to learn how something was done or to create a derivative work, as long as the terms of this license are upheld, which basically just amounts to not telling others they can't do the same with anything you publish. (Giving credit in anything you produce, while not strictly necessary, would be nice)
Lending a hand is easy: just write a patch against a current SVN checkout and send it in or, if coding's not your thing, tell us what's not working the way it should and provide clear steps that describe how to reproduce the problem. As soon as we've had an opportunity to review your submission and make sure that it doesn't break anything, the code will be updated and you'll be credited.
All code is meticulously commented, as per Puukusoft standards. If you find an under-documented section of code, please let us know.
For details on where the project is headed, check out the development feed at http://uguu.ca/tag/staticdhcpd/
If staticDHCPd has helped you, please let us know. Conversely, if it exploded in your face and, after consulting the FAQ, you need help to get things working, also let us know: our works may be free, but we still pride ourselves on making them do what we claim they can do.
Just don't contact Mathieu Ignacio with any complaints; he may have provided a crucial piece of this system, but he is not responsible for any mistakes we may have made.
- Architecture and implementation Mathieu Ignacio
- pydhcplib Matthew Boedicker
- Oracle support; sanity checking Andrew Xuan
- Lots of constructive feedback John Stowers
- Inspiration for making the database engine more flexible
- Ideas for several features that helped to define what 2.0 should be Aleksandr Chusov
- Lots of 2.0.0 dev-branch testing: stepping on glass so nobody else had to Ken Mitchell
- Identification and testing of the broadcast bit, meaning that every client should now be supported Anthony Woods
- Suggestions that led to enabling site-specific metadata to be stored and easily accessed in databases ("definition.extra") and unifying Definition across the codebase
flan {at} uguu {dot} ca