# 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.
## 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](https://codeberg.org/black-cat/toe-beans/src/branch/main/src/bin) 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](https://codeberg.org/black-cat/antennas/src/branch/main/rust/src/toe_beans.rs) that uses the server binary.
## Documentation
All versions of this crate are on [docs.rs](https://docs.rs/toe-beans).
Or you may locally (offline):
- See the latest version's documentation with `cargo doc --open`
- Branch off any release tag with `git switch -C <branch-name> <release-tag>` then run `cargo doc --open`.
- Expore the DHCP RFC specifications downloaded to the `/rfcs` directory of this repo.
- Get a summary of historical changes by version from the `/CHANGELOG.md` file in this repo.
## Safety
The `unsafe_code` lint is set to `forbid` which means that unsafe code is not allowed (unless through a third-party crate).
## Stability
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](https://codeberg.org/black-cat/toe-beans/wiki/Performance), or run the benchmarks yourself with `cargo benches`.
## Testing
- Unit tests, doc tests, and integration tests can all be run through the `cargo tests` cargo alias. The integration tests check the server and client libraries.
- Docker is used to automate testing the server binary with both the client binary and third-party dhcp clients (currently `dhclient`). Run with `docker compose up --build`.
- All code changes are tested on a real [router](https://codeberg.org/black-cat/antennas) before being released.
## 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 [router](https://codeberg.org/black-cat/antennas).
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.
## 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.
- [dhcproto](https://crates.io/crates/dhcproto) has the most downloads (is a dhcp library only).
- [DHCPlayer](https://crates.io/crates/dhcplayer) let you pentest dhcp with various known attacks.
- [leasehund](https://github.com/rttfd/leasehund) has no_std/embedded support.
## You might also like...
Our other projects on <https://black-cat.us>.
## Releasing
0. If this is a hotfix, branch off the previous release (`git switch -C hotfix/v0.5.1 tags/v0.5.0`)
1. Update the version in `Cargo.toml`.
2. Check the `CHANGELOG.md`.
3. Commit/Push the changes.
4. 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`.
5. 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.