# Core Components

Relevant source files

The following files were used as context for generating this wiki page: - [LICENSE](LICENSE) - [README.md](README.md) - [advanced/Scripts/utils.sh](advanced/Scripts/utils.sh) - [advanced/Templates/gravity.db.sql](advanced/Templates/gravity.db.sql) - [advanced/Templates/gravity_copy.sql](advanced/Templates/gravity_copy.sql) - [advanced/Templates/pihole-FTL-poststop.sh](advanced/Templates/pihole-FTL-poststop.sh) - [advanced/Templates/pihole-FTL-prestart.sh](advanced/Templates/pihole-FTL-prestart.sh) - [advanced/Templates/pihole-FTL.service](advanced/Templates/pihole-FTL.service) - [advanced/Templates/pihole-FTL.systemd](advanced/Templates/pihole-FTL.systemd) - [gravity.sh](gravity.sh) - [test/test_any_utils.py](test/test_any_utils.py)

This page provides an overview of the main functional components that make Pi-hole work as a network-wide ad blocker. It introduces the core architectural elements, their responsibilities, and how they interact to provide Pi-hole's DNS-sinkhole functionality. For information about the high-level architecture, see [System Architecture](#1.1). For detailed installation processes, see [Installation Process](#1.2). ## Component Overview Pi-hole's functionality is built upon several key components that work together to provide DNS-based ad blocking: 1. **Gravity System** - Manages ad blocking lists (downloading, processing, and maintaining blocklists) 2. **FTL DNS Service** - The DNS service that handles queries and implements blocking logic 3. **Database System** - Stores blocklists, settings, and statistics in an SQLite database 4. **Service Management** - Scripts and systemd services to manage Pi-hole operation 5. **Configuration System** - Manages Pi-hole settings and configuration files Each component is designed to be modular, with clear separation of responsibilities, which allows for easier maintenance and extensibility. ## Component Architecture The following diagram illustrates the core components of Pi-hole and their interactions: ```mermaid graph TB subgraph "Core Components" FTL["FTL DNS Service"] GravityDB["Gravity Database
(gravity.db)"] GravitySystem["Gravity System
(gravity.sh)"] Config["Configuration System
(utils.sh)"] Services["Service Management
(pihole-FTL.service)"] end subgraph "External Components" UserInterfaces["User Interfaces
(CLI & Web)"] Upstream["Upstream DNS
Servers"] AdLists["External Ad Lists"] end UserInterfaces -- "queries/settings" --> FTL UserInterfaces -- "manages lists" --> GravitySystem FTL -- "reads domains" --> GravityDB GravitySystem -- "updates" --> GravityDB GravitySystem -- "downloads" --> AdLists FTL -- "forwards allowed
queries" --> Upstream Services -- "starts/stops" --> FTL Config -- "provides settings" --> FTL Config -- "provides settings" --> GravitySystem ``` Sources: [gravity.sh:1-25](), [advanced/Templates/pihole-FTL.service:1-42](), [advanced/Scripts/utils.sh:1-20]() ## Gravity System The Gravity system is responsible for managing Pi-hole's blocklists. It downloads lists of domains to be blocked from various sources, processes them, and stores them in the Gravity database. Key features of the Gravity system include: - Downloading and processing blocklists from external sources - Managing domain lists (allow lists, deny lists, regex lists) - Updating the Gravity database with the latest blocklists - Supporting incremental updates using HTTP caching mechanisms - Providing backup and recovery mechanisms for the Gravity database The Gravity system is primarily implemented in the `gravity.sh` script and is executed when running `pihole -g` to update blocklists. For detailed information about the Gravity system, see [Gravity System](#2.1). Sources: [gravity.sh:1-50](), [gravity.sh:414-520]() ## FTL DNS Service FTL (Faster Than Light) is Pi-hole's DNS service component, which handles DNS queries and implements the blocking logic. It's a lightweight, high-performance daemon that provides both DNS resolution and statistical data. Key responsibilities of FTL include: - Receiving and processing DNS queries from client devices - Checking domain names against the Gravity database - Blocking requests to domains in blocklists - Forwarding allowed queries to upstream DNS servers - Collecting statistics for the dashboard - Providing an API for the web interface and command-line tools The FTL service runs as a system service and is managed by systemd (or other init systems on different platforms). For detailed information about the FTL DNS Service, see [FTL DNS Service](#2.2). Sources: [advanced/Templates/pihole-FTL.service:1-42](), [advanced/Templates/pihole-FTL.systemd:1-42](), [advanced/Templates/pihole-FTL-prestart.sh:1-31](), [advanced/Templates/pihole-FTL-poststop.sh:1-14]() ## Database Structure Pi-hole uses an SQLite database (gravity.db) to store its blocklists, configuration, and other data. This database is the central storage mechanism for Pi-hole's operation. The main tables in the Gravity database include: | Table | Purpose | |-------|---------| | `gravity` | Stores blocked domains from blocklists | | `antigravity` | Stores domains exempted from blocking | | `adlist` | Manages sources of blocklists | | `domainlist` | Stores manually configured allow/deny domains | | `group` | Manages domain/client groups for granular blocking | | `client` | Stores client configurations | | `info` | Stores metadata about the database | The database schema is defined in `gravity.db.sql` and provides a structured way to store and query Pi-hole's configuration and blocklists. For detailed information about the database structure, see [Database Structure](#2.3). Sources: [advanced/Templates/gravity.db.sql:1-205]() ## Service Management Pi-hole uses several system services and scripts to manage its components. The primary service is `pihole-FTL.service`, which manages the FTL DNS daemon. The service management components include: - **Service Initialization Scripts**: Handle starting, stopping, and restarting the FTL service - **Pre-start and Post-stop Scripts**: Set up required permissions and perform cleanup - **Process Management**: Monitor and control the FTL process Pi-hole supports different service managers including systemd and traditional SysV init scripts. ```mermaid graph TD subgraph "Service Management Flow" Start["Service Start
(pihole-FTL.service)"] PreStart["Pre-start
(pihole-FTL-prestart.sh)"] FTL["FTL Daemon
(pihole-FTL)"] PostStop["Post-stop
(pihole-FTL-poststop.sh)"] Stop["Service Stop"] end Start --> PreStart PreStart -- "set permissions" --> FTL FTL -- "service stopped" --> PostStop PostStop --> Stop subgraph "Files & Sockets" PIDFile["PID File
(pihole-FTL.pid)"] Socket["FTL Socket
(/run/pihole/FTL.sock)"] Logs["Log Files
(/var/log/pihole/)"] end PreStart -- "creates" --> PIDFile PreStart -- "sets permissions" --> Logs FTL -- "writes" --> PIDFile FTL -- "creates" --> Socket PostStop -- "removes" --> PIDFile PostStop -- "removes" --> Socket ``` Sources: [advanced/Templates/pihole-FTL.service:1-42](), [advanced/Templates/pihole-FTL-prestart.sh:1-31](), [advanced/Templates/pihole-FTL-poststop.sh:1-14]() ## Configuration System Pi-hole's configuration system manages settings and provides configuration values to other components. It uses a combination of configuration files and utilities to store and retrieve settings. Key aspects of the configuration system: - **Configuration Files**: Store settings in various formats - **Utils Library**: Provides functions for reading and writing configuration - **FTL Configuration**: Specific settings for the FTL DNS service The configuration system is primarily implemented in the `utils.sh` script, which provides functions for accessing and modifying configuration values. Examples of key utility functions: - `getFTLConfigValue`: Retrieves a configuration value from FTL - `setFTLConfigValue`: Sets a configuration value in FTL - `addOrEditKeyValPair`: Updates configuration files Sources: [advanced/Scripts/utils.sh:1-95](), [test/test_any_utils.py:1-59]() ## Component Interaction Flow The following diagram illustrates how the core components interact during a typical DNS query flow: ```mermaid sequenceDiagram participant Client as "Client Device" participant FTL as "FTL DNS Service" participant GravityDB as "Gravity Database" participant Upstream as "Upstream DNS" Client->>FTL: DNS Query (domain?) FTL->>GravityDB: Check domain against lists alt Domain is blocked GravityDB->>FTL: Domain in gravity table FTL->>Client: Blocked response (0.0.0.0) else Domain is explicitly allowed GravityDB->>FTL: Domain in whitelist/antigravity FTL->>Upstream: Forward query Upstream->>FTL: DNS response FTL->>Client: Forward response else Domain not in any list GravityDB->>FTL: Domain not in special lists FTL->>Upstream: Forward query Upstream->>FTL: DNS response FTL->>Client: Forward response end FTL->>FTL: Update statistics ``` This flow shows how Pi-hole's core components work together to process DNS queries, block unwanted domains, and allow legitimate traffic. Sources: [gravity.sh:52-174](), [README.md:13-24](), [README.md:117-131]() ## Database Backup and Recovery Pi-hole includes a robust backup and recovery system for its database to ensure data integrity and system reliability. The Gravity system automatically manages database backups during updates. Key aspects of the backup and recovery system: - **Automatic Backups**: Created during gravity updates - **Backup Rotation**: Maintains multiple backup versions (up to 10) - **Recovery Mechanism**: Automatically attempts to restore from backups if database corruption is detected ```mermaid graph TD subgraph "Gravity Database Backup & Recovery" Update["Gravity Update"] Check["Integrity Check"] Backup["Create Backup"] Rotate["Rotate Backups"] Restore["Restore from Backup"] end Update --> Check Check -- "OK" --> Backup Backup --> Rotate Check -- "Failed" --> Restore Restore -- "Success" --> Update Restore -- "Failed" -->|"Manual intervention
required"| Update ``` Sources: [gravity.sh:106-114](), [gravity.sh:366-411](), [gravity.sh:451-469]() ## Summary Pi-hole's core components work together as a cohesive system to provide network-wide ad blocking. The Gravity system manages blocklists, the FTL DNS service handles queries and implements blocking, the database stores configuration and blocklists, and the service management components ensure the system runs reliably. Each component is designed with modularity in mind, with clear interfaces between them. This approach allows for easier maintenance, troubleshooting, and extension of Pi-hole's functionality. For more detailed information about specific components, refer to the dedicated pages: - [Gravity System](#2.1) - [FTL DNS Service](#2.2) - [Database Structure](#2.3)