Crate leasehund 

Leasehund 🐶

A lightweight, embedded-friendly DHCP server implementation for Rust no_std environments.

Overview

Leasehund provides a minimal DHCP server implementation designed for embedded systems and resource-constrained environments. It supports the core DHCP functionality needed for automatic IP address assignment in local networks.

Protocol Compliance

Leasehund is compliant with RFC 2131 and RFC 2132, including strict checking and emission of the DHCP magic cookie (0x63825363) in all packets as required by the standard.

Features

• No-std compatible: Designed for embedded systems without heap allocation
• Embassy integration: Built on top of Embassy async runtime and networking stack
• Configurable IP pools: Define custom IP address ranges for client assignment
• Flexible lease management: Configurable lease times and automatic tracking
• Multiple DNS servers: Support for up to 4 DNS servers
• Optional router configuration: Router/gateway can be disabled if not needed
• Builder pattern: Fluent API for easy configuration
• Memory efficient: Uses heapless data structures with compile-time size limits

Usage

Basic Usage

use core::net::Ipv4Addr;
use leasehund::DhcpServer;
use embassy_net::Stack;
use leasehund::DhcpConfig;

let mut dhcp_server: DhcpServer<32, 4> = DhcpServer::new_with_dns(
    Ipv4Addr::new(192, 168, 1, 1),    // Server IP
    Ipv4Addr::new(255, 255, 255, 0),  // Subnet mask
    Ipv4Addr::new(192, 168, 1, 1),    // Router/Gateway
    Ipv4Addr::new(8, 8, 8, 8),        // DNS server
    Ipv4Addr::new(192, 168, 1, 100),  // IP pool start
    Ipv4Addr::new(192, 168, 1, 200),  // IP pool end
);

// Run the DHCP server (this will loop forever)
dhcp_server.run(stack).await;

Advanced Configuration

use core::net::Ipv4Addr;
use leasehund::{DhcpServer, DhcpConfigBuilder};
use embassy_net::Stack;
use leasehund::DhcpConfig;

let config: DhcpConfig<4> = DhcpConfigBuilder::new()
    .server_ip(Ipv4Addr::new(10, 0, 1, 1))
    .subnet_mask(Ipv4Addr::new(255, 255, 0, 0))
    .router(Ipv4Addr::new(10, 0, 1, 1))
    .add_dns_server(Ipv4Addr::new(1, 1, 1, 1))      // Cloudflare DNS
    .add_dns_server(Ipv4Addr::new(1, 0, 0, 1))      // Cloudflare backup
    .add_dns_server(Ipv4Addr::new(8, 8, 8, 8))      // Google DNS
    .ip_pool(
        Ipv4Addr::new(10, 0, 100, 1),
        Ipv4Addr::new(10, 0, 199, 254)
    )
    .lease_time(7200)    // 2 hours
    .build();

let mut dhcp_server: DhcpServer<32, 4> = DhcpServer::with_config(config);
dhcp_server.run(stack).await;

Supported DHCP Messages

• DHCP Discover: Client broadcast to find available DHCP servers
• DHCP Offer: Server response offering an IP address
• DHCP Request: Client request to lease a specific IP address
• DHCP ACK: Server acknowledgment of IP address lease
• DHCP Release: Client notification of IP address release

Limitations

• Maximum number of concurrent client leases is compile-time fixed via const generics (e.g., DhcpServer::<32, 4>, see examples)
• Lease time, buffer size, and DNS servers are configurable at runtime via DhcpConfig / DhcpConfigBuilder
• Support for multiple DNS servers (up to 4, set via const generics, e.g., DhcpConfig::<4>, see examples)
• Optional router/gateway configuration
• IPv4 only
• Fixed UDP buffer sizes (1024 bytes by default, configurable)

Network Configuration

The server listens on UDP port 67 (standard DHCP server port) and sends responses to port 68 (standard DHCP client port). All responses are sent as broadcast packets to ensure compatibility with clients that don’t yet have an IP address.

Memory Usage

The server uses a fixed-size hash map to store lease information, with a maximum number of entries set by the MAX_CLIENTS const generic parameter (e.g., DhcpServer::<32, 4>). Each lease entry contains:

• IPv4 address (4 bytes)
• MAC address (6 bytes)
• Lease expiration timestamp (8 bytes)

Structs

DhcpConfig

Configuration options for the DHCP server

DhcpConfigBuilder

Builder pattern for creating DHCP server configurations

DhcpServer

A lightweight DHCP server implementation for embedded systems