dns_service_c/README.md

DNS Service

A lightweight DNS management service written in C with a web-based interface for configuring DNS settings and managing dnsmasq configuration.

Features

• Web Interface: Modern responsive web UI for DNS configuration
• DNS Settings Management: Configure upstream DNS servers, local domains, and cache settings
• DHCP Configuration: Enable/disable DHCP with range configuration
• File Management: Direct editing of configuration files
• SSL/TLS Support: Optional HTTPS with certificate configuration
• JSON Configuration: Easy-to-manage JSON-based configuration
• Cross-platform: Supports multiple build systems (Make, CMake, Meson)

Architecture

The service consists of:

• HTTP/HTTPS Server: Built on Mongoose web server
• REST API: JSON-based API for configuration management
• Web Interface: Bootstrap-based responsive UI
• Configuration Parser: Custom dnsmasq config parser
• File Operations: Safe file reading/writing utilities
• Settings Management: Direct manipulation of dnsmasq configuration files
  • Updates dnsmasq main configuration (/etc/dnsmasq.conf)
  • Manages hosts file (/etc/dnsmasq.conf.d/hosts)
  • Manages resolv.conf (/etc/dnsmasq.conf.d/resolv.conf)
  • Automatically restarts dnsmasq service after configuration changes

API Endpoints

Method	Endpoint	Description
GET	/api/settings	Get current DNS settings
POST	/api/settings	Update DNS settings (cache_size, resolv servers, hosts) and restart dnsmasq
GET	/api/settings/file	Get raw configuration file
POST	/api/settings/file	Update configuration file
GET	/#	Serve web interface

Requirements

Build Dependencies

• GCC compiler with C23 support
• OpenSSL development libraries
• pthread library

System Dependencies

• dnsmasq (for DNS service functionality)
• SSL certificates (for HTTPS support)
• System initialization service (systemd, openrc, rc, finit, or init)
• Appropriate privileges to restart system services

Installation

Using Make

make

Using CMake

mkdir build && cd build
cmake ..
make

Using Meson

meson setup builddir
meson compile -C builddir

Configuration

Edit config.json to configure the service:

{
    "address": "0.0.0.0:8321",
    "tls_address": "0.0.0.0:8322",
    "web": "./web",
    "tls_enabled": true,
    "tls_cert": "/path/to/certificate.crt",
    "tls_key": "/path/to/private.key",
    "system_initialization": "systemd",
    "dnsmasq_config": "/etc/dnsmasq.conf"
}

Configuration Parameters

• address: HTTP server bind address and port
• tls_address: HTTPS server bind address and port
• web: Path to web interface files
• tls_enabled: Enable/disable HTTPS support
• tls_cert: Path to SSL certificate file
• tls_key: Path to SSL private key file
• system_initialization: System initialization type for restarting dnsmasq service
  • "systemd": Uses systemctl restart dnsmasq
  • "rc" or "openrc": Uses rc restart dnsmasq
  • "finit": Uses initctl restart dnsmasq
  • "init": Uses /etc/init.d/dnsmasq restart
• dnsmasq_config: Path to dnsmasq configuration file

Usage

Starting the Service

./dns_service

The service will start HTTP server on the configured address (default: 0.0.0.0:8321) and optionally HTTPS server if TLS is enabled.

Web Interface

Navigate to http://localhost:8321 (or your configured address) to access the web interface where you can:

• Configure upstream DNS servers (resolv)
• Manage local domain mappings (hosts)
• Enable/disable DHCP with range settings
• Adjust DNS cache size
• Edit configuration files directly
• Save settings directly to dnsmasq configuration
• Automatic dnsmasq service restart after configuration changes

API Usage

Get Current Settings

curl -X GET http://localhost:8321/api/settings

Update Settings

curl -X POST http://localhost:8321/api/settings \
  -H "Content-Type: application/json" \
  -d '{
    "cache_size": 1000,
    "resolv": ["8.8.8.8", "8.8.4.4"],
    "hosts": {
      "192.168.1.1": "router.local",
      "192.168.1.100": ["server1.local", "server1"]
    }
  }'

The POST /api/settings endpoint accepts the following parameters:

• cache_size (integer): DNS cache size for dnsmasq
• resolv (array of strings): Upstream DNS servers
• hosts (object): Local DNS mappings where keys are IP addresses and values are either single hostnames (string) or arrays of hostnames

Note: After successfully updating the configuration files, the service automatically restarts dnsmasq to apply the changes. The restart method depends on the system_initialization setting in config.json.

Settings Configuration Details

Cache Size (cache_size)

• Configures the DNS cache size in dnsmasq
• Updates the cache-size parameter in /etc/dnsmasq.conf
• Accepts integer values (recommended: 150-10000 depending on system resources)

Upstream DNS Servers (resolv)

• Array of DNS server IP addresses to use for upstream resolution
• Creates/updates /etc/dnsmasq.conf.d/resolv.conf with nameserver entries
• Example: ["8.8.8.8", "1.1.1.1", "8.8.4.4"]

Local Hosts (hosts)

• Object mapping IP addresses to hostnames for local DNS resolution
• Creates/updates /etc/dnsmasq.conf.d/hosts file
• Supports both single hostnames and multiple hostnames per IP
• Format:
  • Single hostname: "192.168.1.1": "router.local"
  • Multiple hostnames: "192.168.1.100": ["server1.local", "server1"]

Development

Project Structure

dns_service_c/
├── src/
│   ├── lib/                        # Third-party libraries
│   │   ├── mongoose.c              # HTTP server
│   │   ├── cJSON.c                 # JSON parser
│   │   └── ...
│   ├── main.c                      # Application entry point
│   ├── config.c                    # Configuration management
│   ├── settings.c                  # DNS settings handlers (GET)
│   ├── set_settings.c              # DNS settings handlers (POST)
│   ├── set_dnsmasq_settings_field.c # Update dnsmasq config fields
│   ├── set_hosts.c                 # Manage hosts file
│   ├── set_resolvs.c               # Manage resolv.conf
│   ├── restart_dnsmasq.c           # Restart dnsmasq service
│   ├── settings.h                  # Settings function declarations
│   ├── restart_dnsmasq.h           # Restart function declarations
│   └── ...
├── web/               # Web interface files
│   ├── index.html
│   ├── css/
│   └── js/
├── config.json        # Service configuration
└── README.md

Building for Development

# With debug symbols
make CFLAGS="-Wall -g -std=gnu2x -DDEBUG"

# Clean build
make clean && make

Code Style

The project uses .clang-format for consistent code formatting:

clang-format -i src/*.c src/*.h

Security Considerations

• The service runs with system privileges to modify DNS configuration files
• HTTPS is strongly recommended for production deployments
• Ensure proper file permissions on certificate files
• The service directly modifies system files (/etc/dnsmasq.conf, /etc/dnsmasq.conf.d/hosts, /etc/dnsmasq.conf.d/resolv.conf)
• Consider firewall rules to restrict access to management interface
• Validate all input data to prevent configuration file corruption
• Backup configuration files before making changes
• Ensure the service has appropriate write permissions to dnsmasq configuration directories
• The service requires privileges to restart the dnsmasq service via system commands

Troubleshooting

Common Issues

1. Permission denied when accessing dnsmasq config

   • Ensure the service has read/write permissions to the dnsmasq configuration file
   • Run with appropriate privileges or adjust file permissions
   • Check permissions for /etc/dnsmasq.conf.d/ directory

2. Failed to write settings

   • Verify write permissions to /etc/dnsmasq.conf, /etc/dnsmasq.conf.d/hosts, and /etc/dnsmasq.conf.d/resolv.conf
   • Ensure the /etc/dnsmasq.conf.d/ directory exists
   • Check disk space availability

3. Failed to restart dnsmasq

   • Ensure the service has appropriate privileges to restart system services
   • Verify the system_initialization parameter in config.json matches your system
   • Supported initialization systems: rc, openrc, systemd, finit, init
   • Check that dnsmasq service is properly installed and configured on the system

4. SSL/TLS certificate errors

   • Verify certificate and key file paths in config.json
   • Ensure certificate files have correct permissions
   • Check certificate validity and format

5. Port binding errors

   • Verify ports are not already in use
   • Check firewall settings
   • Ensure proper privileges for binding to privileged ports

6. Settings not persisting after dnsmasq restart

   • Ensure dnsmasq is configured to read from /etc/dnsmasq.conf.d/ directory
   • Verify the main dnsmasq configuration includes the conf-dir directive
   • Check that temporary files are properly cleaned up after configuration updates

Logging

The service uses Mongoose's built-in logging. Set log level in code or use debug build for verbose output.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes following the existing code style
4. Test your changes thoroughly
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-party Libraries

This project includes the following third-party libraries:

• Mongoose: HTTP/WebSocket server library
• cJSON: JSON parser library

Please refer to their respective licenses for usage terms.

Support

For issues and questions, please check the project's issue tracker or documentation.