From 4473b90a2aec8a1dc8d1295529a21dba8abec3c1 Mon Sep 17 00:00:00 2001 From: TolaMironcenko Date: Tue, 9 Sep 2025 13:31:58 +0700 Subject: [PATCH] added LICENSE and README.md --- LICENSE | 21 ++++++ README.md | 216 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 237 insertions(+) create mode 100644 LICENSE create mode 100644 README.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2a20de9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 DNS Service Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md new file mode 100644 index 0000000..818d5a8 --- /dev/null +++ b/README.md @@ -0,0 +1,216 @@ +# DNS Service + +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) + +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 + +## API Endpoints + +| Method | Endpoint | Description | +|--------|----------|-------------| +| GET | `/api/settings` | Get current DNS settings | +| POST | `/api/settings` | Update DNS settings | +| 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) + +## Installation + +### Using Make +```bash +make +``` + +### Using CMake +```bash +mkdir build && cd build +cmake .. +make +``` + +### Using Meson +```bash +meson setup builddir +meson compile -C builddir +``` + +## Configuration + +Edit `config.json` to configure the service: + +```json +{ + "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": "rc", + "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 +- `dnsmasq_config`: Path to dnsmasq configuration file + +## Usage + +### Starting the Service +```bash +./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 +- Manage local domain mappings +- Enable/disable DHCP with range settings +- Adjust DNS cache size +- Edit configuration files directly + +### API Usage + +#### Get Current Settings +```bash +curl -X GET http://localhost:8321/api/settings +``` + +#### Update Settings +```bash +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"]}' +``` + +## 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 +│ └── ... +├── web/ # Web interface files +│ ├── index.html +│ ├── css/ +│ └── js/ +├── config.json # Service configuration +└── README.md +``` + +### Building for Development +```bash +# 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: +```bash +clang-format -i src/*.c src/*.h +``` + +## Security Considerations + +- The service runs with system privileges to modify DNS configuration +- HTTPS is strongly recommended for production deployments +- Ensure proper file permissions on certificate files +- Consider firewall rules to restrict access to management interface + +## 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 + +2. **SSL/TLS certificate errors** + - Verify certificate and key file paths in `config.json` + - Ensure certificate files have correct permissions + - Check certificate validity and format + +3. **Port binding errors** + - Verify ports are not already in use + - Check firewall settings + - Ensure proper privileges for binding to privileged ports + +### 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](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. \ No newline at end of file