Cleanup README.md and fix path in systemd service file
This commit is contained in:
155
README.md
155
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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user