DDNS Connectors Documentation

Späť na zoznam

DDNS Connectors Documentation

This document describes the connector system in the DDNS application and provides specifications for proposed new connectors.

Overview

Connectors are components that execute actions when a hostname's IP address changes. They implement the TargetConnectorInterface and are automatically discovered by the ActionRunnerService through the DI container's targetConnector tag.

Current Connectors

1. CloudflareDnsConnector

Updates DNS A records in Cloudflare when IP addresses change.

2. HetznerFirewallConnector

Updates Hetzner cloud firewall rules by replacing placeholder IPs with the new dynamic IP.

3. MikroTikConnector

Updates MikroTik router firewall address lists and DNS static entries.

4. WebhookConnector

Sends HTTP requests to custom endpoints with configurable authentication and payload templates.

5. EmailNotificationConnector

Sends email notifications when IP addresses change.

6. SlackWebhookConnector

Sends notifications to Slack channels when IP changes occur.

7. AwsRoute53DnsConnector

Updates DNS records in Amazon Route53 when IP addresses change.

8. GoogleCloudDnsConnector

Updates DNS records in Google Cloud DNS when IP addresses change.

9. DigitalOceanDnsConnector

Updates DNS records in DigitalOcean when IP addresses change.

10. HomeAssistantConnector

Updates sensor entities in Home Assistant with current IP information.

11. PrometheusAlertingConnector

Sends alerts to Prometheus Alertmanager when IP changes occur.

12. WebhookNotificationConnector

Advanced webhook connector with authentication support for notifications.

13. PushoverConnector

Send push notifications to mobile devices when IP changes occur.

14. DatabaseConnector

Update database records with current IP information (MySQL/PostgreSQL).

15. RedisConnector

Update Redis cache entries with current IP information.

16. KubernetesConnector

Update Kubernetes services and ingresses with new IP addresses.

17. DockerConnector

Update Docker container environment variables or configurations.

Dynamic Connector Type Selection

Starting from version 1.0, the application now supports automatic detection of available connector types. Instead of hardcoded lists, the system dynamically discovers all registered connectors through the DI container.

CLI Tools for Connector Management

The platform includes comprehensive command-line tools for managing and testing connectors:

Connector Command

php bin/console connector <action> [connector_name] [options]

Available Actions:

  • list - Display all available connectors with their status
  • inspect - Show detailed information about a specific connector
  • test - Test a connector with provided credentials and parameters

Examples:

# List all connectors
php bin/console connector list

# Inspect Hetzner Firewall connector
php bin/console connector inspect HetznerFirewall

# Test a connector
php bin/console connector test HetznerFirewall \
  --credentials='{"api_token":"your_token"}' \
  --params='{"firewall_id":"123","placeholder_ip":"0.0.0.0/32"}'

Action Command

php bin/console action <action> [options] [arguments]

Available Actions:

  • list - List user actions with filtering options
  • inspect - Show detailed information about a specific action
  • test - Execute an action for testing (with real execution and logging)

Examples:

# List actions for a user
php bin/console action list --user=123

# Inspect an action
php bin/console action inspect 456

# Test an action (creates execution log)
php bin/console action test 456

Action Execution Logging

All action executions are automatically logged in the action_executions table with the following information:

  • Action ID and related hostname/target
  • Execution status (RUNNING, SUCCESS, FAILURE)
  • Start and completion timestamps
  • Log output and error messages
  • Triggering source (manual test, IP change, etc.)

Admin Interface for Monitoring

Administrators can monitor action executions through the web interface:

  1. Navigate to Admin → Actions → History
  2. View all execution logs with filtering and search
  3. Monitor success rates and identify failed actions
  4. Debug issues using detailed log output

CLI Testing Benefits

  • Safe Testing: Test actions without affecting production systems
  • Detailed Logging: All test executions are logged for review
  • Performance Monitoring: Measure execution times
  • Error Analysis: Detailed error messages for troubleshooting
  • Credential Validation: Verify connector credentials work correctly

Key Features:

  • Automatic Discovery: All connectors tagged with targetConnector are automatically detected
  • User-Friendly Names: Connector class names are automatically formatted for display
  • Extensible: Adding new connectors requires no code changes to the UI
  • Consistent: Same logic used in both admin and front-end interfaces

Implementation:

The TargetsFacade::getAvailableTargetTypes() method dynamically queries the DI container for all services tagged with targetConnector and formats their names for display.

Proposed New Connectors

1. AwsRoute53Connector

Purpose: Updates DNS records in Amazon Route53.

Use Cases:

  • Enterprise DDNS solutions
  • AWS-hosted applications requiring dynamic IPs
  • Multi-region DNS updates

Required Credentials:

{
  "access_key_id": "aws_access_key",
  "secret_access_key": "aws_secret_key",
  "region": "us-east-1"
}

Parameters:

{
  "hosted_zone_id": "Z123456789",
  "record_name": "dynamic.example.com",
  "record_type": "A",
  "ttl": 300
}

Implementation Notes:

  • Uses AWS SDK for PHP
  • Supports all Route53 record types
  • Handles record sets with multiple values
  • Includes proper IAM permissions validation

3. DigitalOceanFirewallConnector

Purpose: Updates DigitalOcean cloud firewall rules.

Use Cases:

  • Dynamic firewall management for DO droplets
  • Security automation for cloud infrastructure
  • Automated access control for remote workers

Required Credentials:

{
  "api_token": "do_api_token"
}

Parameters:

{
  "firewall_id": "firewall_uuid",
  "rule_type": "inbound",
  "protocol": "tcp",
  "ports": "22,80,443",
  "placeholder_ip": "0.0.0.0/0"
}

Implementation Notes:

  • Uses DigitalOcean API v2
  • Supports inbound and outbound rules
  • Handles multiple ports and port ranges
  • Manages rule ordering and priorities

4. EmailNotificationConnector

Purpose: Sends email notifications when IP addresses change.

Use Cases:

  • IP change alerts for administrators
  • User notifications for dynamic DNS updates
  • Security monitoring and logging

Required Credentials:

{
  "smtp_host": "smtp.gmail.com",
  "smtp_port": 587,
  "smtp_username": "user@gmail.com",
  "smtp_password": "app_password",
  "smtp_encryption": "tls"
}

Parameters:

{
  "to_email": "admin@example.com",
  "from_email": "noreply@example.com",
  "subject_template": "IP Changed: {{hostname}}",
  "body_template": "The IP address for {{hostname}} has changed to {{ip}}",
  "cc_emails": ["backup@example.com"]
}

Implementation Notes:

  • Uses Symfony Mailer component
  • Supports template variables (hostname, ip, timestamp)
  • Handles multiple recipients and CC
  • Includes proper email validation

5. SlackWebhookConnector

Purpose: Sends notifications to Slack channels when IP changes occur.

Use Cases:

  • Team notifications for infrastructure changes
  • Integration with DevOps monitoring tools
  • Real-time alerts for security teams

Required Credentials:

{
  "webhook_url": "https://hooks.slack.com/services/...",
  "channel": "#ddns-updates",
  "username": "DDNS Bot"
}

Parameters:

{
  "message_template": "🚨 IP Change Alert\n• Hostname: {{hostname}}\n• New IP: {{ip}}\n• Time: {{timestamp}}",
  "color": "warning",
  "include_fields": ["hostname", "ip", "timestamp", "user"],
  "mention_users": ["@admin"]
}

Implementation Notes:

  • Uses Slack Webhook API
  • Supports rich message formatting
  • Includes user mentions and channel targeting
  • Handles rate limiting gracefully

Implementation Guidelines

Interface Compliance

All connectors must implement TargetConnectorInterface:

interface TargetConnectorInterface
{
    public function execute(array $credentials, array $params, string $newIp): bool;
}

Error Handling

  • Throw \Exception for critical errors
  • Return true for success, false for soft failures
  • Log detailed error information
  • Handle API rate limits and temporary failures

DI Container Registration

Add new connectors to config/services.neon:

-
    class: App\Model\Action\Connector\NewConnector
    tags: [targetConnector]

Testing

  • Unit tests for each connector
  • Integration tests with actual APIs (using test accounts)
  • Mock external services for CI/CD
  • Validate credentials and parameters

Usage Examples

Existing Connectors

Hetzner Firewall Connector

Use Case: Update Hetzner cloud firewall rules to allow access from your dynamic IP.

Target Configuration:

{
  "target_type": "hetzner_firewall",
  "credentials": {
    "api_token": "your_hetzner_api_token"
  }
}

Action Configuration:

{
  "name": "Update Hetzner Firewall",
  "params": {
    "firewall_id": "your_firewall_id",
    "placeholder_ip": "0.0.0.0/32"
  }
}

MikroTik Router Connector

Use Case: Update MikroTik firewall address list for remote access.

Target Configuration:

{
  "target_type": "mikrotik",
  "credentials": {
    "host": "192.168.1.1",
    "username": "api_user",
    "password": "your_password",
    "port": 8728,
    "use_ssl": true
  }
}

Action Configuration for Firewall:

{
  "name": "Update MikroTik Firewall",
  "params": {
    "action_type": "update_firewall_address_list",
    "list_name": "allowed_ips",
    "comment": "DDNS Update"
  }
}

Action Configuration for DNS:

{
  "name": "Update MikroTik DNS",
  "params": {
    "action_type": "update_dns_static",
    "name": "dynamic.example.com",
    "type": "A"
  }
}

Original Webhook Connector

Use Case: Send simple notifications to any HTTP endpoint.

Target Configuration:

{
  "target_type": "webhook",
  "credentials": {
    "url": "https://api.example.com/notify",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer your_token",
      "X-API-Key": "your_api_key"
    }
  }
}

Action Configuration:

{
  "name": "Simple Webhook Notification",
  "params": {
    "body_template": "{\"hostname\":\"{{hostname}}\",\"ip\":\"{{ip}}\"}",
    "content_type": "application/json"
  }
}

New Connectors

Cloudflare DNS Connector

Use Case: Update DNS records for a home server when IP changes.

Target Configuration:

{
  "target_type": "cloudflare_dns",
  "credentials": {
    "api_token": "your_cloudflare_api_token_here",
    "zone_id": "your_zone_id_here"
  }
}

Action Configuration:

{
  "name": "Update Home Server DNS",
  "params": {
    "record_name": "home.example.com",
    "record_type": "A",
    "ttl": 300,
    "proxied": false
  }
}

Email Notification Connector

Use Case: Send email alerts when IP changes occur.

Target Configuration:

{
  "target_type": "email_notification",
  "credentials": {
    "smtp_host": "smtp.gmail.com",
    "smtp_port": 587,
    "smtp_username": "alerts@example.com",
    "smtp_password": "your_app_password",
    "smtp_encryption": "tls"
  }
}

Action Configuration:

{
  "name": "IP Change Alert",
  "params": {
    "to_email": "admin@example.com",
    "from_email": "noreply@example.com",
    "subject_template": "🚨 IP Changed: {{hostname}}",
    "body_template": "The IP address for {{hostname}} has changed from {{old_ip}} to {{ip}} at {{timestamp}}.",
    "cc_emails": ["backup@example.com"]
  }
}

Slack Webhook Connector

Use Case: Post notifications to a Slack channel for team monitoring.

Target Configuration:

{
  "target_type": "slack_webhook",
  "credentials": {
    "webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
    "channel": "#infrastructure",
    "username": "DDNS Monitor",
    "icon_emoji": ":globe_with_meridians:"
  }
}

Action Configuration:

{
  "name": "Slack Infrastructure Alert",
  "params": {
    "message_template": ":warning: *IP Address Changed*\n• Hostname: `{{hostname}}`\n• New IP: `{{ip}}`\n• Old IP: `{{old_ip}}`\n• Time: {{timestamp}}",
    "include_fields": ["hostname", "ip", "timestamp", "user_id"],
    "attachment_color": "warning"
  }
}

Universal Webhook Connector

Use Case 1: Send data to n8n workflow automation.

Target Configuration:

{
  "target_type": "webhook",
  "credentials": {
    "url": "https://your-n8n-instance.com/webhook/ddns-update",
    "method": "POST",
    "auth_type": "bearer",
    "auth_data": {
      "token": "your_n8n_webhook_token"
    }
  }
}

Action Configuration:

{
  "name": "n8n Workflow Trigger",
  "params": {
    "body_template": "{\"event\":\"ip_changed\",\"hostname\":\"{{hostname}}\",\"new_ip\":\"{{ip}}\",\"old_ip\":\"{{old_ip}}\",\"timestamp\":\"{{timestamp}}\",\"user_id\":{{user_id}}}",
    "content_type": "application/json"
  }
}

Use Case 2: Update external monitoring system.

Target Configuration:

{
  "target_type": "webhook",
  "credentials": {
    "url": "https://api.monitoring-service.com/v1/hosts",
    "method": "PATCH",
    "auth_type": "basic",
    "auth_data": {
      "username": "api_user",
      "password": "api_password"
    }
  }
}

Action Configuration:

{
  "name": "Update Monitoring System",
  "params": {
    "url_template": "https://api.monitoring-service.com/v1/hosts/{{hostname}}",
    "body_template": "{\"ip_address\":\"{{ip}}\",\"last_updated\":\"{{timestamp}}\"}",
    "content_type": "application/json",
    "success_status_codes": [200, 204]
  }
}

Use Case 3: Send SMS via Twilio (using webhook to external service).

Target Configuration:

{
  "target_type": "webhook",
  "credentials": {
    "url": "https://api.twilio.com/2010-04-01/Accounts/YOUR_ACCOUNT_SID/Messages.json",
    "method": "POST",
    "auth_type": "basic",
    "auth_data": {
      "username": "YOUR_ACCOUNT_SID",
      "password": "YOUR_AUTH_TOKEN"
    }
  }
}

Action Configuration:

{
  "name": "SMS Alert",
  "params": {
    "content_type": "application/x-www-form-urlencoded",
    "body_template": "To=%2B421123456789&From=%2B421987654321&Body=IP%20changed%20for%20{{hostname}}:%20{{ip}}"
  }
}

AWS Route53 Connector (Proposed)

Use Case: Update DNS records in Amazon Route53 for enterprise environments.

Target Configuration:

{
  "target_type": "aws_route53",
  "credentials": {
    "access_key_id": "AKIAIOSFODNN7EXAMPLE",
    "secret_access_key": "wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY",
    "region": "us-east-1"
  }
}

Action Configuration:

{
  "name": "Update Route53 DNS",
  "params": {
    "hosted_zone_id": "Z1D633PJN98FT9",
    "record_name": "dynamic.example.com",
    "record_type": "A",
    "ttl": 300
  }
}

DigitalOcean Firewall Connector (Proposed)

Use Case: Update cloud firewall rules when IP changes.

Target Configuration:

{
  "target_type": "digitalocean_firewall",
  "credentials": {
    "api_token": "your_digitalocean_token"
  }
}

Action Configuration:

{
  "name": "Update DO Firewall",
  "params": {
    "firewall_id": "firewall_uuid_here",
    "rule_type": "inbound",
    "protocol": "tcp",
    "ports": "22,80,443",
    "placeholder_ip": "0.0.0.0/0"
  }
}

Configuration in Admin Interface

Creating a Target

  1. Navigate to Admin → Targets → Create
  2. Select Target Type from dropdown (now includes new connectors)
  3. Enter Credentials based on the connector type
  4. Save Target

Creating an Action

  1. Navigate to Admin → Actions → Create
  2. Select Target from your saved targets
  3. Configure Parameters based on the connector documentation
  4. Set Action Name and enable it
  5. Save Action

Linking Actions to Hostnames

Actions are automatically triggered when a hostname's IP address changes, based on the hostname's associated actions in the database.

Template Variables Reference

All connectors support these template variables:

  • {{ip}} - The new IP address
  • {{hostname}} - The hostname that changed
  • {{timestamp}} - Current timestamp (ISO 8601)
  • {{old_ip}} - The previous IP address (if available)
  • {{user_id}} - ID of the user who owns the hostname
  • {{domain}} - The domain part of the hostname

Future Enhancements

Additional Connectors to Consider

  • Discord Webhook Connector
  • Telegram Bot Connector
  • Microsoft Teams Connector
  • Pushover Notifications
  • SMS Notifications (Twilio)
  • Database Connectors (MySQL, PostgreSQL)
  • Redis Cache Updates
  • Kubernetes Service Updates
  • Docker Container Updates

Advanced Features

  • Batch operations for multiple records
  • Rollback capabilities
  • Health checks and monitoring
  • Custom validation rules
  • Template engine integration
  • Queue-based processing for high-volume updates

Security Considerations

  • Store API credentials encrypted
  • Use least-privilege API tokens
  • Implement rate limiting
  • Log all connector activities
  • Validate all input parameters
  • Handle sensitive data appropriately
  • Regular credential rotation

Monitoring and Maintenance

  • Track success/failure rates
  • Monitor API usage and limits
  • Alert on connector failures
  • Regular dependency updates
  • Performance optimization
  • Documentation updates