refactor

ansible/tasks/global/utils/dynamic-dns-cf-setup.md

@@ -0,0 +1,124 @@
+# 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](https://dash.cloudflare.com/profile/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](https://t.me/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:
+
+```bash
+# 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
+
+```bash
+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`