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.

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 library code. At the moment, only the library code has benchmarking. It uses criterion.

Note that Options make up the majority of a dhcp message, so how many, or which type, of options you have effect the results. Some libraries might lazily encode/decode which artificially improves their results.

Our benchmarks are split into few options (lower bound) and many options (upper bound) to give an idea of worst/best cases. The Message is fully processed (no part is lazily evaluated and thus excluded from the benchmark).

Here are the results as of June 14, 2025:

benchmark from_bytes (many options)
time: 332.27 nanoseconds

benchmark from_bytes (few options)
time: 103.35 nanoseconds

benchmark to_bytes (many options)
time: 165.52 nanoseconds

benchmark to_bytes (few options)
time: 66.779 nanoseconds

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 need to be expanded. A docker-compose example using dhclient is available.

Comparison

The last time I checked (two years ago), and I could very much be wrong, the only substantial dhcp rust projects are this one and dhcproto (which has a server implementation called dora). Massive shoutout Evan Cameron and the contributors of dhcproto for their excellent work!

I actually chose not to look at dhcproto very much in order to come up with my own solutions for toe-beans, so the projects are surprisingly different despite implementing the same core RFCs. Therefore, I apologize if I say anything wrong/outdated.

dhcproto was first published 2 years prior to toe-bean's first commit, and it shows in that dhcproto is further along in available options, ipv6 support, and multithreading. I'm not sure on how far along their server is. However, dora-dhcp, the crate for their server has not yet been published.

Ultimately, both projects have their merit, and I'm sure they'll both get better over time.

Shameless Plug

Check out these other projects on https://black-cat.us!

License

Distributed under the terms of the GNU GPL License (Version 3 or later)