Skip to content

Improve Cloudflare documentation with verified configuration approach #965

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Improve Cloudflare documentation with verified configuration approach #965

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
278 changes: 254 additions & 24 deletions docs/cloudflare.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,40 +1,270 @@
# Cloudflare
# Cloudflare DDNS-Updater Guide

## Configuration
This guide provides step-by-step instructions for setting up DDNS-Updater with Cloudflare. This solution will automatically update your Cloudflare DNS record when your public IP changes and provide a monitoring dashboard.

### Example
## Prerequisites

```json
- Server with Docker installed
- Sudo/root access to the server
- Cloudflare account with API token
- Domain managed by Cloudflare (e.g., example.com)

## Step 1: Create a Cloudflare API Token

1. Log in to your Cloudflare dashboard at https://dash.cloudflare.com
2. Go to "My Profile" > "API Tokens" > "Create Token"
3. Select "Create Custom Token"
4. Name it "DDNS Updater"
5. Under "Permissions":
- Zone - DNS - Edit
- Zone - Zone - Read
6. Under "Zone Resources":
- Include - Specific zone - your domain (e.g., example.com)
7. **Important**: Set "TTL" to "No expiration" (do not select a date range) or your token will expire and break your DDNS
8. Click "Continue to summary" then "Create Token"
9. Copy the generated token (you'll only see it once)

## Step 2: Prepare Your Docker Environment

```bash
# Create a directory for DDNS-Updater
mkdir -p ~/ddns-updater
cd ~/ddns-updater
```

This directory (`~/ddns-updater`) will be mounted into the container and will store your configuration file and update history. The important paths are:

- Host path: `~/ddns-updater/config.json` (expands to `/home/yourusername/ddns-updater/config.json`)
- Container path: `/updater/data/config.json`

## Step 3: Start the DDNS-Updater (Confirmed Working Method)

Based on extensive testing, this is the configuration that reliably works:

### Using a config.json file (CONFIRMED WORKING)

This method works with both the latest version and v2.5.0:

```bash
# Create directory for configuration
mkdir -p ~/ddns-updater

# Create the config.json file with your API token
cat > ~/ddns-updater/config.json << 'EOF'
{
"settings": [
{
"provider": "cloudflare",
"zone_identifier": "some id",
"domain": "domain.com",
"ttl": 600,
"token": "yourtoken",
"ip_version": "ipv4",
"ipv6_suffix": ""
"zone_identifier": "YOUR_ZONE_ID",
"domain": "example.com",
"host": "subdomain",
"token": "YOUR_API_TOKEN",
"ttl": 120
}
]
}
EOF

# Run the container with mounted volume
docker run -d \
--name ddns-updater \
--restart always \
-p 8000:8000/tcp \
-v ~/ddns-updater:/updater/data \
-e LOG_LEVEL=info \
qmcgaw/ddns-updater:latest
```

### Alternative Method (NOT TESTED)

While the container documentation suggests environment variables can also be used, this method has not been confirmed to work reliably in all situations:

```bash
docker run -d \
--name ddns-updater \
--restart always \
-p 8000:8000/tcp \
-e SETTINGS_1_PROVIDER=cloudflare \
-e SETTINGS_1_ZONE_IDENTIFIER=YOUR_ZONE_ID \
-e SETTINGS_1_DOMAIN=example.com \
-e SETTINGS_1_HOST=subdomain \
-e SETTINGS_1_TOKEN=YOUR_API_TOKEN \
-e SETTINGS_1_TTL=120 \
-e PERIOD=5m \
-e LOG_LEVEL=info \
qmcgaw/ddns-updater:latest
```

**Important Notes:**
- Only the config.json file method has been thoroughly tested and confirmed working in all environments
- Replace `YOUR_ZONE_ID` with your actual Cloudflare Zone ID
- Replace `YOUR_API_TOKEN` with your actual Cloudflare API token
- Splitting the domain into `domain` (example.com) and `host` (subdomain) is critical for proper functioning
- The `TTL` parameter is required (120 seconds is a good value for dynamic DNS)
- The mounted volume approach ensures configuration persistence across container restarts

## Step 4: Check Container Status

```bash
# Check if the container is running properly
docker ps | grep ddns-updater

# View initial logs
docker logs ddns-updater
```

## Step 5: Access the Web Dashboard

The web dashboard will be available at `http://YOUR_SERVER_IP:8000`

You can check this from your server to make sure it's responding:

```bash
# Test if the web UI is accessible locally
curl http://localhost:8000
```

### Compulsory parameters
## Troubleshooting

### Common Errors and Solutions

#### "Missing X-Auth-Key, X-Auth-Email or Authorization headers" Error (Code 9106)
- This is a Cloudflare authentication error that commonly occurs after ISP modem restarts
- **Quick fix**: Restart the container with `docker restart ddns-updater`
- If restart doesn't work, recreate the container using the recommended config.json approach in Step 3
- This error indicates one of these issues:
1. Using an incorrect authentication method (Global API Key instead of API Token)
2. The API Token has expired or been revoked
3. The domain and host are not correctly split in your configuration
4. The configuration wasn't properly applied after a network interruption
- **Solution**:
```bash
# First check logs for detailed error information
docker logs ddns-updater

# Recreate the container using the config.json method (most reliable)
docker rm -f ddns-updater

# Create a proper config.json file with split domain/host
mkdir -p ~/ddns-updater
cat > ~/ddns-updater/config.json << 'EOF'
{
"settings": [
{
"provider": "cloudflare",
"zone_identifier": "YOUR_ZONE_ID",
"domain": "example.com",
"host": "subdomain",
"token": "YOUR_API_TOKEN",
"ttl": 120
}
]
}
EOF

# Run with the mounted config.json
docker run -d \
--name ddns-updater \
--restart always \
-p 8000:8000/tcp \
-v ~/ddns-updater:/updater/data \
-e LOG_LEVEL=debug \
qmcgaw/ddns-updater:latest
```

#### "zone identifier is not set" Error
- Make sure you're using the correct Zone ID from Cloudflare
- The parameter should be named `zone_identifier` (not `zone_id`)

#### "TTL is not set" Error
- Add the `ttl` parameter to your configuration (e.g., `"ttl":120`)

#### "Cannot unmarshal object into Go struct field" Error
- This occurs when using incorrect JSON structure
- Use the approach shown in Step 3

### File Locations

The configuration file is stored in these locations:

- **Host Machine**: `~/ddns-updater/config.json` (expands to `/home/yourusername/ddns-updater/config.json`)
- **Inside Container**: `/updater/data/config.json`

These locations are linked through the Docker volume mapping: `-v ~/ddns-updater:/updater/data`

To edit the configuration:
```bash
# Edit config with nano
nano ~/ddns-updater/config.json

# After editing, restart the container to apply changes
docker restart ddns-updater
```

### Version Compatibility Notes

- Both the latest version and v2.5.0 work correctly with the configuration shown above
- If you encounter issues with the latest version, you can try v2.5.0 which has been extensively tested:
```bash
docker run -d \
--name ddns-updater \
--restart always \
-p 8000:8000/tcp \
-v ~/ddns-updater:/updater/data \
qmcgaw/ddns-updater:v2.5.0
```

### Debugging Tips

If authentication issues persist:

1. Check container logs with `docker logs ddns-updater` for specific error messages
2. Try using the `-e LOG_LEVEL=debug` option to get more detailed logs
3. Verify that your Cloudflare API token is still valid by testing it with [Cloudflare's API documentation](https://api.cloudflare.com/)
4. Try recreating the API token in Cloudflare's dashboard

Remember that Cloudflare occasionally makes API changes that might require updates to your configuration.

## Conclusion and Key Learnings

Through extensive testing, we've definitively confirmed:

1. **The config.json file approach with mounted volume is VERIFIED WORKING**
2. **Both the latest container version and v2.5.0 work correctly** with the proper configuration
3. **Critical elements for success:**
- Using API Token authentication (not Global API Key)
- Splitting the domain into separate "domain" and "host" fields
- Mounting a persistent volume for the config.json file
- Setting appropriate TTL values

The web interface provides a convenient way to monitor your DDNS update status, and the detailed logs help with troubleshooting if any issues occur.

## Common Commands for Management

```bash
# Restart the container
docker restart ddns-updater

# Stop the container
docker stop ddns-updater

# Start the container
docker start ddns-updater

# Remove container and recreate it
docker rm -f ddns-updater
# Then run the docker run command from Step 3 again
```

- `"zone_identifier"` is the Zone ID of your site, from the domain overview page written as *Zone ID*
- `"domain"` is the domain to update. It can be `example.com` (root domain), `sub.example.com` (subdomain of `example.com`) or `*.example.com` for the wildcard.
See [this issue comment for context](https://github.com/qdm12/ddns-updater/issues/243#issuecomment-928313949). This is left as is for compatibility.
- `"ttl"` integer value for record TTL in seconds (specify 1 for automatic)
- One of the following ([how to find API keys](https://developers.cloudflare.com/fundamentals/api/get-started/)):
- Email `"email"` and Global API Key `"key"`
- User service key `"user_service_key"`
- API Token `"token"`, configured with DNS edit permissions for your DNS name's zone
## References

### Optional parameters
### Official Documentation
- [DDNS-Updater GitHub Repository](https://github.com/qdm12/ddns-updater) - Official project repository with comprehensive documentation
- [Docker Hub - qmcgaw/ddns-updater](https://hub.docker.com/r/qmcgaw/ddns-updater) - Official Docker image
- [DDNS-Updater Configuration Options](https://github.com/qdm12/ddns-updater/blob/master/docs/configuration.md) - All available configuration options

- `"proxied"` can be set to `true` to use the proxy services of Cloudflare
- `"ip_version"` can be `ipv4` (A records), or `ipv6` (AAAA records) or `ipv4 or ipv6` (update one of the two, depending on the public ip found). It defaults to `ipv4 or ipv6`.
- `"ipv6_suffix"` is the IPv6 interface identifier suffix to use. It can be for example `0:0:0:0:72ad:8fbb:a54e:bedd/64`. If left empty, it defaults to no suffix and the raw public IPv6 address obtained is used in the record updating.
### Cloudflare Resources
- [Cloudflare API Documentation](https://developers.cloudflare.com/api/tokens/) - Documentation for Cloudflare API tokens
- [Cloudflare DNS Documentation](https://developers.cloudflare.com/dns/) - General DNS configuration in Cloudflare
- [Cloudflare Zone ID Location](https://developers.cloudflare.com/fundamentals/setup/find-account-and-zone-ids/) - How to find your Zone ID

Special thanks to @Starttoaster for helping out with the [documentation](https://gist.github.com/Starttoaster/07d568c2a99ad7631dd776688c988326) and testing.