diff --git a/README.md b/README.md index 8893f8e..e014fc0 100644 --- a/README.md +++ b/README.md @@ -12,52 +12,57 @@ Dynamic DNS update service with CLI administration. Accepts HTTP(S) requests to - Rate limiting (separate limits for good/bad requests) - TTL-based automatic record expiration - Email notifications on expiry -- Syslog support with transaction IDs for request tracking -- Systemd integration -- Content negotiation (plain text / JSON responses) +- Syslog, file and stdout logging support +- Plain text / JSON responses according to Accept-Header (application/json) - IDN/punycode hostname support - -## Project Structure - -``` -ddns-service/ -├── ddns-service # Main executable -├── ddns_service/ # Python package -│ ├── __init__.py # Version info -│ ├── cleanup.py # TTL expiry cleanup -│ ├── cli.py # CLI commands -│ ├── config.py # Configuration loading -│ ├── dns.py # DNS operations -│ ├── email.py # Email notifications -│ ├── logging.py # Centralized logging -│ ├── models.py # Database models -│ ├── ratelimit.py # Rate limiting -│ ├── server.py # HTTP server -│ └── validation.py # Hostname validation -├── config.example.toml -├── ddns-service.service -├── requirements.txt -└── README.md -``` +- Proxy support ## Installation ```bash -pip install -r requirements.txt +pip install git+https://git.ccc-rheintal.ch/spacefreak/ddns-service.git + +# With MariaDB support: +pip install "ddns-service[mysql] @ git+https://git.ccc-rheintal.ch/spacefreak/ddns-service.git" ``` -### Dependencies +Requires Python 3.11+. Dependencies installed automatically: dnspython, peewee, argon2-cffi (+ pymysql for mysql extra). -- Python 3.11+ -- dnspython -- peewee -- argon2-cffi -- pymysql (for MariaDB support) +## Service setup + +1. Create system user and group: +```bash +useradd -r -s /sbin/nologin ddns +``` + +2. Create directories: +```bash +mkdir -p /etc/ddns-service /var/lib/ddns-service /var/log/ddns-service +chmod 750 /etc/ddns-service /var/lib/ddns-service +chown ddns:root /etc/ddns-service +chown ddns:ddns /var/lib/ddns-service /var/log/ddns-service +``` + +3. Service autostart +```bash +# Systemd setup +wget -O /etc/systemd/systemd/ddns-service.service https://git.ccc-rheintal.ch/spacefreak/ddns-service/raw/branch/master/files/ddns-service.service +systemctl daemon-reload +systemctl enable ddns-service + +# OpenRC setup +wget -O /etc/init.d/ddns-service https://git.ccc-rheintal.ch/spacefreak/ddns-service/raw/branch/master/files/ddns-service-openrc.init.d +wget -O /etc/conf.d/ddns-service https://git.ccc-rheintal.ch/spacefreak/ddns-service/raw/branch/master/files/ddns-service-openrc.conf.d +rc-update add ddns-service default +``` ## Configuration -Copy `config.example.toml` to `/etc/ddns-service/config.toml` or `./config.toml`: +```bash +wget -O /etc/ddns-service/config.toml https://git.ccc-rheintal.ch/spacefreak/ddns-service/raw/branch/master/files/config.example.toml +``` +Example: ```toml [daemon] # host = "localhost" # default: "localhost" (use reverse proxy for public access) @@ -235,6 +240,7 @@ password = ["password"] ### Manual Cleanup ```bash +# Manually cleanup expired hostnames (delete DNS records) ./ddns-service cleanup ``` @@ -247,15 +253,6 @@ password = ["password"] ./ddns-service --daemon --debug ``` -### Debug Mode - -Use `--debug` to enable debug logging for any command: - -```bash -./ddns-service --debug user list -./ddns-service --debug cleanup -``` - ## HTTP API ### Request @@ -272,7 +269,7 @@ GET /update?hostname=mypc.dyn.example.com&username=myuser&password=secret ### IP Detection -- If `myip` or `myip6` provided: use those values +- If `myip` and/or `myip6` provided: use those values - If neither provided: use client's source IP - IPv4 addresses create A records - IPv6 addresses create AAAA records @@ -312,41 +309,6 @@ wget -qO- --user=username --password=password \ "https://ddns.example.com/update?hostname=mypc.dyn.example.com" ``` -## Systemd Setup - -1. Create system user: -```bash -useradd -r -s /sbin/nologin ddns -``` - -2. Create directories: -```bash -mkdir -p /etc/ddns-service /var/lib/ddns-service -chown ddns:ddns /var/lib/ddns-service -``` - -3. Install files: -```bash -cp -r ddns_service /opt/ddns-service/ -cp ddns-service /opt/ddns-service/ -cp config.example.toml /etc/ddns-service/config.toml -cp ddns-service.service /etc/systemd/system/ -``` - -4. Configure and start: -```bash -# Edit config -vi /etc/ddns-service/config.toml - -# Initialize database -/opt/ddns-service/ddns-service --init-db - -# Enable and start -systemctl daemon-reload -systemctl enable ddns-service -systemctl start ddns-service -``` - ## Security Considerations - **Do not expose directly to the internet** - run behind a reverse proxy (e.g. nginx, caddy, apache) that handles TLS termination @@ -372,38 +334,17 @@ When a hostname expires: ## Logging -The daemon supports stdout and syslog logging targets. +The daemon supports stdout, syslog, and file logging targets. ### Configuration Options | Option | Default | Description | |--------|---------|-------------| | `log_level` | INFO | DEBUG, INFO, WARNING, ERROR | -| `log_target` | stdout | stdout or syslog | -| `syslog_socket` | /dev/log | Path to syslog socket | -| `syslog_facility` | daemon | daemon, user, local0-7 | +| `log_target` | stdout | stdout, syslog, or file | +| `syslog_socket` | /dev/log | Path to syslog socket (syslog only) | +| `syslog_facility` | daemon | daemon, user, local0-7 (syslog only) | +| `log_file` | /var/log/ddns-service/ddns-service.log | Log file path (file only) | +| `log_file_size` | 52428800 | Max file size before rotation in bytes (file only) | +| `log_versions` | 5 | Number of backup files to keep (file only) | | `log_requests` | false | Log HTTP request lines at INFO level | - -### Transaction IDs - -Each HTTP request is assigned a random 8-character transaction ID for log correlation. All log messages during request processing include this ID: - -``` -2025-01-17 12:34:56 [INFO] [a1b2c3d4] Updated: hostname=mypc.dyn.example.com ipv4=1.2.3.4 ipv6=N/A -``` - -### Syslog Format - -When using syslog, timestamps are omitted (syslog provides them): - -``` -ddns-service[12345]: [INFO] [a1b2c3d4] Updated: hostname=mypc.dyn.example.com ipv4=1.2.3.4 ipv6=N/A -``` - -### CLI Logging - -CLI commands run silently by default. Use `--debug` to enable logging output. - -## License - -GPL-3.0 diff --git a/files/ddns-service.service b/files/ddns-service.service index 980b74f..3f1bc91 100644 --- a/files/ddns-service.service +++ b/files/ddns-service.service @@ -6,7 +6,7 @@ After=network.target Type=simple User=ddns Group=ddns -WorkingDirectory=/opt/ddns-service +WorkingDirectory=/var/lib/ddns-service ExecStart=/usr/bin/ddns-service --daemon ExecReload=/bin/kill -HUP $MAINPID Restart=on-failure