# networkconfiguration/dhcpcd architecture

> Architecture diagram of the GitHub repository networkconfiguration/dhcpcd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/networkconfiguration/dhcpcd
- Repository: https://github.com/networkconfiguration/dhcpcd

## Overview

##### Project Type and Purpose
- dhcpcd is a system‐level C daemon that implements a DHCPv4, DHCPv6, and IPv4LL (ZeroConf) client for UNIX‐like operating systems. It runs in the background, configures network interfaces, manages IP leases, and invokes scripts/hooks on state changes. It also exposes a control socket for external tools (e.g., dhcpcd-ui) and co‐exists with other resolvers via openresolv.

##### Core Directory Analysis
- src/: the principal C source files. Contains:
- common.c/.h – shared utilities
- eloop.c/.h – the event‐loop core
- dhcp*.c/.h – DHCPv4 client logic
- dhcp6.c/.h – DHCPv6 client logic
- ipv4*.c/.h, ipv6*.c/.h – IP address management, SLAAC, IPv4LL
- privsep-*.c/.h – privilege separation modules
- control.c/.h – control socket interface
- script.c/.h & hooks/ – hook script runner and shipped hook templates
- bpf.c/.h, route.c/.h, arp.c/.h – low‐level kernel interface (netlink/BPF)
- config parsing, logging, DUID, lease database, etc.
- compat/: portability shims for various OS functions (arc4random, crypt, strlcpy, etc.).
- hooks/: packaged hook scripts (DNS config, hostname, DHCP‐specific tasks).
- tests/: unit and integration tests for cryptographic primitives, event loop, etc.
- Build files (Makefile, configure, BUILDING.md): standard autotools/Makefile.inc integration.

##### Key Architectural Components
a. Core Daemon Process ("dhcpcd")
- Initialization & Configuration Loader
- Event Loop (eloop)
- Interface Manager
- DHCPv4 & DHCPv6 Protocol Engines
- IPv4LL (ZeroConf) & SLAAC Engine
- Privilege Separation Daemon (child process)
- Control Socket Server (UNIX domain socket)
- Script/Hook Executor
- Lease Database & DUID Storage
- Logging/Error Handling
b. Compat Layer
- Provides uniform APIs for cryptography, random, string, and other OS‐specific calls.
c. Hooks Subsystem
- External shell/perl scripts triggered on interface events.
d. openresolv Integration
- Invoked by hooks to update /etc/resolv.conf, coexisting with other daemons.
e. External Clients
- GUI or CLI clients (e.g., dhcpcd-ui) connecting over the control socket.

##### Interactions & Data Flows
- Daemon starts, reads /etc/dhcpcd.conf → initializes eloop → enumerates network interfaces.
- For each interface:
- Binds raw sockets or netlink/BPF
- Launches DHCPv4/DHCPv6 or IPv4LL state machine
- Receives packets → processes leases → updates OS interface via netlink/ioctl
- On state transitions (bound, deconfigured, renewed):
- Event loop triggers hook scripts → hooks call openresolv or modify system files
- Control socket:
- External client → sends commands (status, renew, release) → daemon responds.
- Privilege Separation:
- Sensitive operations (raw sockets, file writes) handled in a less‐privileged child.

##### Architectural Patterns & Principles
- Modular C code organized by protocol and functionality.
- Event‐driven design (single‐threaded eloop).
- Privilege separation to minimize attack surface.
- Clear separation between core logic and external scripts (hooks).
- Portability layer (compat/) insulating OS differences.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Kernel Layer
    Kernel["Kernel / Network Stack"]:::kernel

    %% Filesystem
    Config["/etc/dhcpcd.conf"]:::storage
    LeaseDB["Lease DB & DUID"]:::storage

    %% External Clients
    subgraph "External Clients"
        CLI["CLI / dhcpcd-ui"]:::external
    end

    %% Hooks & openresolv
    subgraph "Hooks & openresolv" 
        Hooks["Hook Scripts"]:::hooks
        OpenResolv["openresolv Integration"]:::hooks
    end

    %% Portability Layer
    Compat["Compat Layer"]:::compat

    %% Developer Tools
    subgraph "Developer Tools"
        Tests["Tests"]:::devtools
    end

    %% Core Daemon Process
    subgraph "dhcpcd Daemon"
        direction TB
        CFG["Initialization & Config Loader"]:::core
        Eloop["Event Loop (eloop)"]:::core
        IfMgr["Interface Manager"]:::core
        DHCP4["DHCPv4 Engine"]:::core
        DHCP6["DHCPv6 Engine"]:::core
        IPv4LL["IPv4LL & SLAAC Engine"]:::core
        Script["Script/Hook Executor"]:::core
        Control["Control Socket Server"]:::core
        Log["Logging / Error Handling"]:::core
        DUID["DUID Storage"]:::core
        LowLevel["Low-Level Kernel Interfaces"]:::core

        subgraph "Privilege Separation" 
            Privsep["Privsep Daemon"]:::privsep
        end
    end

    %% Flows
    Kernel -->|netlink/BPF| LowLevel
    LowLevel -->|events| Eloop
    CFG --> Eloop
    Config --> CFG
    LeaseDB -->|read/write| DUID
    DUID --> CFG
    Eloop --> IfMgr
    IfMgr -->|packet I/O| DHCP4
    IfMgr -->|packet I/O| DHCP6
    IfMgr -->|packet I/O| IPv4LL
    DHCP4 -->|state events| Eloop
    DHCP6 -->|state events| Eloop
    IPv4LL -->|state events| Eloop
    Eloop -->|trigger| Script
    Script -.->|execute hook| Hooks
    Hooks -->|update resolv.conf| OpenResolv
    CLI ---|control socket| Control
    Control -->|commands| CFG
    Privsep -->|secure ops| LowLevel
    Eloop -->|privileged| Privsep

    Compat --> CFG
    Compat --> DHCP4
    Compat --> DHCP6
    Compat --> IPv4LL
    Compat --> Script

    Tests --> CFG
    Tests --> Eloop
    Tests --> DHCP4

    %% Click Events
    click CFG "https://github.com/networkconfiguration/dhcpcd/blob/master/src/dhcpcd.c"
    click Eloop "https://github.com/networkconfiguration/dhcpcd/blob/master/src/eloop.c"
    click IfMgr "https://github.com/networkconfiguration/dhcpcd/blob/master/src/dev.c"
    click DHCP4 "https://github.com/networkconfiguration/dhcpcd/blob/master/src/dhcp.c"
    click DHCP6 "https://github.com/networkconfiguration/dhcpcd/blob/master/src/dhcp6.c"
    click IPv4LL "https://github.com/networkconfiguration/dhcpcd/blob/master/src/ipv4ll.c"
    click Privsep "https://github.com/networkconfiguration/dhcpcd/blob/master/src/privsep.c"
    click Control "https://github.com/networkconfiguration/dhcpcd/blob/master/src/control.c"
    click Script "https://github.com/networkconfiguration/dhcpcd/blob/master/src/script.c"
    click DUID "https://github.com/networkconfiguration/dhcpcd/blob/master/src/duid.c"
    click Log "https://github.com/networkconfiguration/dhcpcd/blob/master/src/logerr.c"
    click LowLevel "https://github.com/networkconfiguration/dhcpcd/blob/master/src/bpf.c"
    click Compat "https://github.com/networkconfiguration/dhcpcd/tree/master/compat/"
    click Hooks "https://github.com/networkconfiguration/dhcpcd/tree/master/hooks/"
    click OpenResolv "https://github.com/networkconfiguration/dhcpcd/blob/master/hooks/20-resolv.conf"
    click Tests "https://github.com/networkconfiguration/dhcpcd/tree/master/tests/"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef privsep fill:#B0E0E6,stroke:#000,stroke-width:1px
    classDef compat fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef hooks fill:#98FB98,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef kernel fill:#E0FFFF,stroke:#000,stroke-width:1px
    classDef storage fill:#FFFFE0,stroke:#000,stroke-width:1px
    classDef devtools fill:#DDA0DD,stroke:#000,stroke-width:1px
```
