Documentation

ZoneMesh is a DNS synchronization platform that enables you to keep DNS zones synchronized across multiple cloud providers and on-premises infrastructure. You deploy hub containers in your own infrastructure that pull zones from sources and push them to targets, giving you full control over your DNS data.

Key Features#

• Multi-provider DNS synchronization - Route 53, AXFR (GCP Cloud DNS and Azure DNS coming soon)
• Real-time status monitoring - Track sync history and hub health in real-time
• Secure credential management - All credentials encrypted at rest
• Automated zone synchronization - Hubs sync zones automatically on a schedule
• Hub health testing - Built-in diagnostics to verify hub functionality
• Bulk operations - Manage multiple resources efficiently
• Flexible plans - Free and Pro subscription options

How It Works#

ZoneMesh follows a simple workflow to keep your DNS zones synchronized:

1. Configure Credentials - Set up cloud provider credentials in the Integrations page (only needed for Route 53)
2. Create Zones - Define DNS zones and specify where to pull DNS records from (sources)
3. Deploy Hubs - Deploy hub containers in your infrastructure to handle synchronization
4. Attach Zones - Connect zones to hubs for synchronization
5. Configure Targets - Specify where to push DNS records to (targets)
6. Automatic Sync - Hubs automatically sync zones on a schedule and push changes to targets

Step 1: Set Up Cloud Credentials (If Needed)#

If you need cloud credentials for Route 53, configure them:

1. Navigate to Integrations in the sidebar
2. Click Add Credential
3. Select AWS Route 53 as your provider
4. Enter your AWS credentials:
   • Access Key ID: Your AWS Access Key ID
   • Secret Access Key: Your AWS Secret Access Key
5. Give your credential a descriptive name
6. Click Create

Step 2: Create a Zone#

Create a DNS zone that will be synchronized.

1. Navigate to Zones in the sidebar
2. Click Add Zone
3. Enter your zone name (e.g., example.com)
4. Select a source type:
   • Route 53: Pull from AWS Route 53 (currently supported) - Note that Route 53 doesn't support AXFR natively; ZoneMesh uses the Route 53 API instead. Learn about Route 53 zone transfer challenges.
   • AXFR: Pull via zone transfer from a master DNS server (currently supported)
   • GCP: Pull from Google Cloud DNS (coming soon)
   • Azure: Pull from Azure DNS (coming soon)
5. Configure source settings (hosted zone ID, project ID, master IP, etc.)
6. Click Create Zone

Step 3: Deploy a Hub#

Deploy a hub container to sync your zones. Hubs run in your infrastructure and pull zones from sources, serve them via NSD, and push them to targets.

1. Navigate to the Hubs page from the main navigation, or open your zone detail page
2. Click Create Hub
3. Enter a hub label (e.g., us-east-1-hub)
4. Click Create Hub
5. Copy the Docker command and hub token that appear

6. Run the Docker command on a server with Docker installed
7. The hub will automatically connect and start syncing zones
8. If created from the hubs page, attach the hub to zones from the zone detail page

Example Docker Command#

docker run -d \
--name dns-sync-hub-<your-hub-id> \
-e HUB_ID=your-hub-id \
-e HUB_TOKEN=your-hub-token \
-e CONTROL_PLANE_URL=https://your-saas.com \
-p 53:53/tcp -p 53:53/udp \
ghcr.io/rogerb831/zonemesh/dns-hub:latest

Step 4: Configure Targets#

Configure where your zones should be pushed to after being synced.

1. On your zone detail page, scroll to the Targets section
2. Click Add Target
3. Select target type:
   • Route 53: Push to AWS Route 53 (currently supported) - requires Hosted Zone ID and region
   • AXFR: Configure as AXFR secondary (currently supported) - requires secondary server IP, port, and optional TSIG key
   • GCP: Push to Google Cloud DNS (coming soon)
   • Azure: Push to Azure DNS (coming soon)
4. Configure target settings based on the selected type
5. Select the appropriate credential
6. Click Create Target

Zone Sources#

Zones can be pulled from various sources. Each source type requires different configuration.

Route 53#

Pull zones from AWS Route 53. Requires an AWS credential with Route 53 read permissions. Note that Route 53 doesn't support AXFR/IXFR natively—learn more about why Route 53 zone transfers are hard and how ZoneMesh enables zone transfers with Route 53.

To add a Route 53 zone source:

1. Click Create Zone from the Zones page
2. Enter the zone name (e.g., example.com)
3. Select Route 53 as the source type
4. Select the AWS credential to use (must have Route 53 read permissions)
5. Enter the Hosted Zone ID from your AWS console (e.g., Z1234567890ABC)
6. Select the Region closest to your hub location
7. Click Create to save the zone

GCP Cloud DNS (Coming Soon)#

Azure DNS (Coming Soon)#

AXFR (Zone Transfer)#

Pull zones via AXFR from a master DNS server (BIND, NSD, PowerDNS, etc.). Supports TSIG (Transaction Signature) authentication for secure zone transfers.

To add an AXFR zone source:

1. Click Create Zone from the Zones page
2. Enter the zone name (e.g., example.com)
3. Select AXFR as the source type
4. Enter the Master IP address of your DNS server
5. Optionally configure TSIG authentication (see below)
6. Click Create to save the zone

Configuring TSIG Authentication#

TSIG (Transaction Signature) provides cryptographic authentication for DNS zone transfers, preventing unauthorized access to your zone data. When enabled, ZoneMesh authenticates to your master DNS server using a shared secret.

To enable TSIG when creating or editing an AXFR zone:

1. Toggle Enable TSIG Authentication to on
2. Enter the Key Name — a unique identifier that must match exactly on your master DNS server (e.g., transfer-key)
3. Enter the Secret — a base64-encoded shared secret (at least 32 bytes recommended)
4. Select the Algorithm — choose from hmac-sha256 (recommended), hmac-sha512, hmac-sha1, or hmac-md5

Zone Synchronization#

Zones are automatically synchronized by hubs on a schedule (every 10 minutes by default). You can also trigger manual syncs and monitor sync status in real-time.

• Automatic Sync: Hubs check for zone updates every 10 minutes
• Manual Sync: Click Sync Now on a hub to trigger immediate synchronization
• Config Refresh: Click Refresh Config to fetch the latest zone configuration from the control plane
• Status Monitoring: View sync status and history in the zone detail page
• Target Status: See per-target sync status (fully synced, partial sync, error, etc.)
• Push Retry Limit: Configure how many times a hub should retry pushing to a target if it fails (default: 10, range: 0-50)

Sync Status History#

The zone detail page displays sync status history for the last 24 hours. This helps you track sync events and troubleshoot issues.

• 24-Hour Window: Only sync events from the last 24 hours are displayed
• Scrollable List: Fixed-height scrollable table for easy navigation
• Clear History: Use the Clear button to remove all status history for a zone
• Automatic Cleanup: Status history older than 24 hours is automatically removed
• Real-Time Updates: Status updates appear in real-time as syncs complete
• Per-Hub History: View sync history for each hub attached to the zone

Editing and Deleting Zones#

You can edit zone source configuration or delete zones from the zones list or zone detail page.

• Edit Zone: Click the edit icon on a zone to update its source type and configuration
• Delete Zone: Use the delete action to permanently remove a zone and all its targets
• Bulk Delete: Select multiple zones and delete them at once from the zones list page

What is a Hub?#

A hub is a Docker container that runs in your infrastructure. It:

• Pulls DNS zones from configured sources
• Serves zones via NSD (authoritative DNS server)
• Pushes zones to configured targets
• Reports sync status to the control plane
• Supports AXFR/IXFR zone transfers

Hub Requirements#

• Docker: Docker or Docker Compose installed
• Network: Outbound HTTPS access to the control plane
• Ports: Port 53 TCP/UDP (for DNS queries and AXFR transfers)
• Resources: Minimal - 512MB RAM, 1 CPU core

Hub Status#

Hubs report their status in real-time. Status indicators:

Hub Management Page#

Access the dedicated hubs management page from the navigation menu to view and manage all your hubs in one place.

• View All Hubs: See all hubs across all zones with their status and attached zones
• Create Hub: Create new hubs without attaching to a zone first
• Hub Actions: Sync, refresh config, restart, test services, or delete hubs
• Zone Links: Click on zone names to navigate to zone detail pages

Hub Management Actions#

• Sync Now: Trigger immediate zone synchronization for all zones attached to the hub
• Refresh Config: Fetch latest zone configuration from control plane
• Restart Hub: Send restart command to hub container (reloads DNS server configuration)
• Services Test: Test hub services to verify DNS server and DNS resolution are working correctly
• Detach: Remove hub from a zone (hub container continues running and can be attached to other zones)
• Delete Hub: Permanently delete a hub (only available if the hub is not attached to any zones)
• Bulk Delete: Select multiple hubs and delete them at once from the hubs list page
• Update Software: Update hub container software to the latest version (bulk update available)

Services Test#

The Services Test feature allows you to verify that your hub is functioning correctly by testing two key services:

• DNS Server Test: Verifies that the hub's DNS server is running and responding
• DNS Resolution Test: Verifies that the hub can resolve DNS queries correctly

To run a services test, navigate to a hub detail page or use the "Test Services" button in the hub actions menu. Test results will appear showing whether each service passed or failed, along with any error messages.

Hub Detail Page#

Each hub has a dedicated detail page where you can view and manage all zones attached to the hub, monitor hub status, and view sync history.

• Attached Zones: View all zones currently attached to the hub
• Attach Zone: Add zones to the hub from the hub detail page
• Detach Zone: Remove zones from the hub
• Status History: View sync history for all zones on this hub (last 24 hours)
• Hub Information: View hub ID, status, last seen time, and creation date

Target Types#

Zones can be pushed to various DNS providers. Each target type requires different configuration.

Route 53 Target#

Push zones to AWS Route 53. Requires an AWS credential with Route 53 write permissions. While Route 53 doesn't support AXFR/IXFR as a protocol, ZoneMesh enables zone synchronization via the Route 53 API. Learn about Route 53 zone transfer limitations and how ZoneMesh works around them.

To add a Route 53 target:

1. Navigate to the zone detail page
2. Click Add Target
3. Select Route 53 as the target type
4. Select the AWS credential to use (must have Route 53 write permissions)
5. Enter the Hosted Zone ID from your AWS console (e.g., Z1234567890ABC)
6. Select the Region closest to your hub location
7. Click Create to save the target

GCP Cloud DNS Target (Coming Soon)#

Azure DNS Target (Coming Soon)#

AXFR Secondary Server#

Configure the hub's NSD server to allow zone transfers to secondary DNS servers. The secondary servers will pull zones via AXFR/IXFR from the hub. Supports TSIG (Transaction Signature) authentication for secure zone transfers.

To add an AXFR secondary target:

1. Navigate to the zone detail page
2. Click Add Target
3. Select AXFR Secondary as the target type
4. Enter the IP Address of your secondary DNS server
5. Optionally configure TSIG authentication (see below)
6. Click Create to save the target

Configuring TSIG Authentication#

TSIG (Transaction Signature) ensures only authorized secondary servers can pull zones from your hub. When enabled, the hub's NSD server requires TSIG authentication for zone transfers.

To enable TSIG when creating or editing an AXFR target:

1. Toggle Enable TSIG Authentication to on
2. Enter the Key Name — a unique identifier that must match exactly on your secondary server (e.g., transfer-key)
3. Enter the Secret — click Generate to create a secure base64-encoded secret, or enter your own
4. Select the Algorithm — choose from hmac-sha256 (recommended), hmac-sha512, hmac-sha1, or hmac-md5

Editing and Deleting Targets#

You can edit target configuration or delete targets from the zone detail page or the targets list page.

• Edit Target: Click the edit icon on a target to update its configuration and credentials
• Delete Target: Use the delete action to remove a target from a zone
• Bulk Delete: Select multiple targets and delete them at once from the targets list page
• Target Status: View real-time sync status for each target (fully synced, partial sync, error, etc.)

When Are Credentials Needed?#

• Route 53 source/target: Requires AWS credentials (currently supported)
• AXFR source/target: No cloud credentials needed (uses zone transfer protocol, currently supported)
• GCP Cloud DNS source/target: Coming soon - will require GCP service account credentials
• Azure DNS source/target: Coming soon - will require Azure service principal credentials

Credential Security#

AWS Route 53 Credentials#

To use Route 53 as a source or target, you need AWS Access Keys. Follow these steps to create and configure them. Understanding why Route 53 zone transfers are hard can help you better configure ZoneMesh for Route 53 synchronization.

Step 1: Create AWS IAM User and Access Keys#

1. Log in to the AWS Console
2. Navigate to IAM → Users → Create User
3. Enter a username (e.g., dns-sync-route53)
4. Click Next to set permissions
5. Attach policies with Route 53 permissions:
   • AmazonRoute53ReadOnlyAccess (for pulling zones as a source)
   • AmazonRoute53FullAccess (for pushing zones as a target)
   • Or create a custom policy with only the permissions you need (see below)
6. Click Next and then Create User
7. Open the user → Security credentials tab
8. Click Create access key
9. Select Application running outside AWS
10. Click Next and then Create access key
11. Important: Copy the Access Key ID and Secret Access Key immediately

Step 2: Add Credentials to the Application#

1. Navigate to Integrations in the sidebar (or go to /dashboard/integrations)
2. Click Add Credential
3. Fill in the form:
   • Credential Name: A descriptive name (e.g., "Production Route 53")
   • Provider: Select "AWS Route 53"
   • Access Key ID: Your AWS Access Key ID
   • Secret Access Key: Your AWS Secret Access Key
   • Region: AWS region (e.g., us-east-1)
4. Click Create Credential

Note: Route 53 is a global service, but API calls require a region. Use us-east-1 as the default.

Required AWS Permissions#

For Route 53 operations, the IAM user needs the following permissions:

{
"Version": "2012-10-17",
"Statement": [
  {
    "Effect": "Allow",
    "Action": [
      "route53:ListHostedZones",
      "route53:GetHostedZone",
      "route53:ListResourceRecordSets",
      "route53:ChangeResourceRecordSets",
      "route53:GetChange"
    ],
    "Resource": "*"
  }
]
}

Or use the managed AWS policies:

• AmazonRoute53ReadOnlyAccess - For read-only operations (pulling zones)
• AmazonRoute53FullAccess - For read/write operations (pulling and pushing zones)

Using Credentials#

Once created, credentials are available when:

• Creating a zone with Route 53 as the source
• Adding a Route 53 target to push zones to

GCP Credentials (Coming Soon)#

GCP Cloud DNS support will be available in the near future. When available, you'll need to create a service account in your GCP project with the appropriate DNS roles.

Azure Credentials (Coming Soon)#

Azure DNS support will be available in the near future. When available, you'll need to create an Azure AD application (service principal) with the appropriate DNS zone permissions.

Editing and Deleting Credentials#

You can edit credential configuration or delete credentials from the integrations page.

• Edit Credential: Click the edit icon on a credential to update its configuration
• Delete Credential: Use the delete action to remove a credential (only if not in use by any zones or targets)

General Guidelines#

• Most resources can be edited by clicking the edit icon (pencil) next to the resource
• Delete actions are available in dropdown menus or action buttons
• Bulk operations (delete multiple items) are available on list pages by selecting items with checkboxes
• Some resources cannot be deleted if they are in use (e.g., credentials used by zones/targets, hubs attached to zones)

Zones#

• Edit: Update zone name, source type, and source configuration
• Delete: Permanently removes the zone and all its targets (hubs remain available)
• Bulk Delete: Select multiple zones from the zones list page and delete them at once

Hubs#

• Edit: Hub labels can be updated (though this is typically not necessary)
• Delete: Only available if the hub is not attached to any zones
• Detach: Remove hub from zones without deleting the hub itself
• Bulk Delete: Select multiple hubs from the hubs list page and delete them at once

Targets#

• Edit: Update target type, configuration, and credentials
• Delete: Remove target from a zone
• Bulk Delete: Select multiple targets from the targets list page and delete them at once

Credentials#

• Edit: Update credential name and configuration (e.g., access keys, service account JSON)
• Delete: Only available if the credential is not used by any zones or targets

Plans#

ZoneMesh offers two subscription plans:

Free Tier#

• Limited number of zones, hubs, and targets
• Basic DNS synchronization features
• Perfect for testing and small deployments

Pro Plan#

• Higher limits for zones, hubs, and targets
• Access to all current features (Route 53 and AXFR support)
• Early access to GCP and Azure DNS support when available
• Priority support
• Monthly or annual billing options

Managing Your Subscription#

Access billing and subscription management from Settings → Billing in the navigation menu.

• View Current Plan: See your current plan, usage, and limits
• Upgrade to Pro: Upgrade from Free tier to Pro plan
• Update Payment Method: Change your payment method for Pro subscriptions
• Unsubscribe: Cancel your Pro subscription (access continues until the end of the billing period)
• Resubscribe: Reactivate a canceled subscription
• View Invoices: Access upcoming invoice previews

Usage Limits#

Your current usage is displayed on the billing page, showing how many zones, hubs, and targets you're using compared to your plan limits.

• Usage Tracking: Real-time usage counts for zones, hubs, and targets
• Limit Warnings: Notifications when approaching plan limits
• Upgrade Prompts: Suggestions to upgrade when limits are reached
• Unsubscription Blocking: If you're using more than free tier limits, you must reduce usage before unsubscribing

Organization Settings#

Manage your organization settings from Settings → General in the navigation menu.

• Display Name: Update your organization's display name
• Delete Organization: Permanently delete your organization and all associated data

Hub Connection Issues#

Hub shows as "offline"#

• Check if the Docker container is running on your server
• Check container logs for error messages
• Verify the hub ID and token are correct in your Docker command
• Ensure the control plane URL is accessible from your hub's network
• Check firewall rules allow outbound HTTPS connections
• Use the "Services Test" feature to diagnose hub issues

Hub connects but immediately disconnects#

• Verify the hub token is correct and hasn't been regenerated
• Check network connectivity to the control plane
• Review hub container logs for authentication errors
• Ensure the hub token matches the one shown when you created the hub

SSL certificate verification error#

If you see SSL certificate errors in your hub logs:

• This typically occurs in development/test environments with self-signed certificates
• Add -e SSL_VERIFY=false to your Docker run command

Zone Sync Failures#

Zone sync fails with credential error#

• Verify credentials are correctly configured in Integrations
• Check credential permissions match requirements
• For AWS Route 53: Verify IAM user has Route 53 permissions
• For AXFR: Verify master DNS server allows zone transfers from your hub's IP address

Zone sync fails with "zone not found"#

• Verify zone name matches exactly (case-sensitive)
• Check source configuration (hosted zone ID, project ID, etc.)
• Ensure the zone exists in the source DNS provider

AXFR transfer fails#

• Verify master DNS server IP address is correct
• Check if TSIG key is required and correctly configured
• Ensure port 53 TCP is accessible from the hub
• Verify the master DNS server allows zone transfers from your hub's IP address
• Check hub logs for specific AXFR error messages

Target Push Failures#

Target push fails#

• Verify target configuration (hosted zone ID, project ID, etc.)
• Check credential has write permissions
• Ensure target zone exists in the DNS provider
• Review hub logs for detailed error messages

AXFR secondary cannot pull zone#

• Verify AXFR target is configured in the zone
• Use the "Services Test" feature to verify the hub's DNS server is running
• Verify port 53 TCP/UDP is accessible from the secondary server
• Check that the hub's IP address is allowed to transfer zones to the secondary
• Review hub logs for zone transfer attempts and errors

Getting Help#

If you're still experiencing issues:

• Check hub container logs for detailed error messages
• Review sync status history in the zone detail page (shows last 24 hours)
• Use the "Services Test" feature to verify hub functionality
• Check target status indicators to see which targets are failing
• Verify credentials have the correct permissions for your DNS providers
• Contact support with hub logs, zone configuration, and error details

Security#

• Use IAM roles/service accounts with minimal required permissions (read-only for sources, write for targets)
• Rotate credentials regularly for better security
• Use TSIG keys for AXFR transfers when possible to secure zone transfers
• Restrict hub container network access to necessary endpoints only
• Keep hub containers updated using the "Update Software" feature
• Never share hub tokens or credentials
• Use proper SSL certificates in production (never disable SSL verification)

High Availability#

• Deploy multiple hubs in different regions/availability zones
• Attach zones to multiple hubs for redundancy
• Configure Docker restart policies: --restart unless-stopped
• Monitor hub status regularly

docker run -d \
--restart unless-stopped \
--name dns-sync-hub-<your-hub-id> \
-e HUB_ID=your-hub-id \
-e HUB_TOKEN=your-hub-token \
-e CONTROL_PLANE_URL=https://your-saas.com \
-p 53:53/tcp -p 53:53/udp \
ghcr.io/rogerb831/zonemesh/dns-hub:latest

Performance#

• Place hubs close to your DNS sources for faster sync times
• Use multiple hubs in different regions to distribute load and improve redundancy
• Monitor sync times in the status history and adjust if needed
• Configure appropriate push retry limits based on your network reliability
• Attach zones to multiple hubs for redundancy and faster synchronization