dotfiles/config/ansible/docs/dynamic-dns-setup.md

Dynamic DNS OnePassword Setup

This document explains how to set up the required OnePassword entries for the Dynamic DNS automation.

Overview

The Dynamic DNS task automatically retrieves credentials from OnePassword using the Ansible OnePassword lookup plugin. This eliminates the need for vault files and provides better security.

Required OnePassword Entries

1. CloudFlare API Token

Location: CloudFlare API Token in Dotfiles vault, field password

Setup Steps:

1. Go to CloudFlare API Tokens
2. Click "Create Token"
3. Use the "Edit zone DNS" template
4. Configure permissions:
   • Zone: DNS: Edit
   • Zone Resources: Include all zones (or specific zones for your domains)
5. Add IP address filtering if desired (optional but recommended)
6. Click "Continue to summary" and "Create Token"
7. Copy the token and save it in OnePassword:
   • Title: CloudFlare API Token
   • Vault: Dotfiles
   • Field: password (this should be the main password field)

2. Telegram Bot Credentials

Location: Telegram DynDNS Bot in Dotfiles vault, fields password and chat_id

Setup Steps:

Create Telegram Bot:

1. Message @BotFather on Telegram
2. Send /start then /newbot
3. Follow the prompts to create your bot
4. Save the bot token (format: 123456789:ABCdefGHijklMNopQRstUVwxyz)

Get Chat ID:

1. Send any message to your new bot
2. Visit: https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates
3. Look for "chat":{"id":YOUR_CHAT_ID} in the response
4. Save the chat ID (format: 987654321 or -987654321 for groups)

Save in OnePassword:

• Title: Telegram DynDNS Bot
• Vault: Dotfiles
• Fields:
  • password: Your bot token (123456789:ABCdefGHijklMNopQRstUVwxyz)
  • chat_id: Your chat ID (987654321)

Verification

You can test that the OnePassword lookups work by running:

# Test CloudFlare token lookup
ansible localhost -m debug -a "msg={{ lookup('community.general.onepassword', 'CloudFlare API Token', vault='Dotfiles', field='password') }}"

# Test Telegram bot token
ansible localhost -m debug -a "msg={{ lookup('community.general.onepassword', 'Telegram DynDNS Bot', vault='Dotfiles', field='password') }}"

# Test Telegram chat ID
ansible localhost -m debug -a "msg={{ lookup('community.general.onepassword', 'Telegram DynDNS Bot', vault='Dotfiles', field='chat_id') }}"

Security Notes

• Credentials are never stored in version control
• Environment file (~/.local/bin/dynamic-dns.env) has 600 permissions
• OnePassword CLI must be authenticated before running Ansible
• Make sure to run op signin before executing the playbook

Troubleshooting

OnePassword CLI Not Authenticated

op signin

Missing Fields in OnePassword

Ensure the exact field names match:

• CloudFlare: field must be named password
• Telegram: fields must be named password and chat_id

Invalid CloudFlare Token

• Check token has Zone:DNS:Edit permissions
• Verify token is active in CloudFlare dashboard
• Test with: curl -H "Authorization: Bearer YOUR_TOKEN" https://api.cloudflare.com/client/v4/user/tokens/verify

Telegram Not Working

• Ensure you've sent at least one message to your bot
• Verify chat ID format (numbers only, may start with -)
• Test with: go run dynamic-dns-cf.go --test-telegram

Usage

Once set up, the dynamic DNS will automatically:

• Update DNS records every 15 minutes
• Send Telegram notifications when IP changes
• Log all activity to system journal (journalctl -t dynamic-dns)

Domains Configured

The automation updates these domains:

• vleeuwen.me
• mvl.sh
• mennovanleeuwen.nl

To modify the domain list, edit the wrapper script at: ~/.local/bin/dynamic-dns-update.sh