Toe Beans
This crate provides:
- A library for:
- Serializing and deserializing DHCP messages.
- Client and server logic.
- A client and server binary that wraps the library.
This crate is heavily documented on docs.rs.
Usage
Library
cargo add toe-beans to install it as a dependency.
You may disable either of the default feature flags (v4_client/v4_server) if you don't need the other.
Check out the binaries' code and the docs.rs link above for examples of how to use the library.
Binary
cargo install toe-beans will install both the server and client binaries.
You may use the --bin cli arg to install only one of the binaries.
Check out this wifi router that uses the server binary.
Safety
The unsafe_code lint is set to forbid which means that unsafe code is not allowed (unless through a third-party crate).
Nearly all of the code within the listen loop of the server is panic free to prevent the server from crashing from a bad request.
Performance
A significant amount of work has been put into optimizing the code. Learn more and see benchmark results on our wiki, or run the benchmarks yourself with cargo benches.
Status
Currently, only dhcpv4/ipv4 is handled. Ipv6 support will be added in the future.
The standard RFCs are closely followed, but its hard to promise 100% compatibility with them. Subtle differences may exist.
The message library code is complete with the exception of needing to implement more options.
The server library/binary have successfully assigned/validated an ip address on a live router. The server is currently single threaded, configured through a toml file, and leases are stored in another toml file.
The client binary is still a work in progress, but the client library code is more complete.
Unit and integration tests exist but more should be written. Docker is used to automate testing the server with third-party dhcp clients (currently dhclient).
Alternatives
Warning: I have neither used, nor vetted the safety of any of these alternatives. There might be better options that I'm not aware of.
There were not a lot of dhcp libraries available when I started writing toe-beans. Nowadays there are more options, but to varying degrees of completeness.
The most complete is dhcproto by Evan Cameron and others.
If you want to pen test dhcp, DHCPlayer let you use various known attacks.
You might also like...
Our other projects on https://black-cat.us.
Releasing
- Update the version in
Cargo.toml. - Check the
CHANGELOG.md. - Commit/Push the changes.
- Create/Push an annotated tag (with the SHA of the last commit):
git tag -a v0.2.1 aa15cb8473 -m "v0.2.1" && git push --tags origin. - Publish to crates.io:
cargo publish.
License
Distributed under the terms of the GNU Library General Public License (Version 2.0). See LICENSE file for more information.