A command-line tool to validate DNS CNAME records for HiveMQ Cloud custom domain setup. This script ensures your domain is properly configured to work with HiveMQ Cloud and SSL certificate provisioning.
- ✅ Validates main domain CNAME points to
*.hivemq.cloud - ✅ Validates ACME challenge CNAME for SSL certificate provisioning
- ✅ Validates CAA records authorize Let's Encrypt for SSL certificates
- ✅ Uses Google DNS servers (8.8.8.8) for consistent resolution
- ✅ Professional, customer-friendly output
- ✅ Cross-platform support (Linux, macOS, WSL)
- ✅ Proper exit codes for automation
digcommand must be available on your system- Internet connectivity to Google DNS (8.8.8.8)
Ubuntu/Debian:
sudo apt-get install dnsutilsCentOS/RHEL:
sudo yum install bind-utilsmacOS:
brew install bindMake the script executable and run it with your custom domain:
chmod +x hivemq-dns-validator.sh
./hivemq-dns-validator.sh your-domain.com./hivemq-dns-validator.sh mqtt.example.com
./hivemq-dns-validator.sh broker.mycompany.org./hivemq-dns-validator.sh --helpThe script checks three critical DNS configurations:
-
Main Domain CNAME: Your custom domain must resolve to a HiveMQ Cloud domain matching the pattern
*.hivemq.cloud -
ACME Challenge CNAME: The ACME challenge subdomain
_acme-challenge.<your-domain>must resolve to_acme-challenge.<same-hivemq-subdomain>.hivemq.cloud -
CAA Records: If Certificate Authority Authorization (CAA) records exist for your domain (or parent domains), they must authorize
letsencrypt.orgas a certificate issuer
Both CNAME records must point to the same HiveMQ Cloud subdomain, and CAA records (if present) must allow Let's Encrypt to issue certificates for proper SSL certificate provisioning.
==============================================
HiveMQ Cloud DNS Validation Tool
==============================================
Validating DNS configuration for: mqtt.example.com
Using DNS server: 8.8.8.8
Checking main domain CNAME record...
Domain: mqtt.example.com
Resolved CNAME: prod.12345.euc1.aws.hivemq.cloud
✓ Valid HiveMQ Cloud CNAME: prod.12345.euc1.aws.hivemq.cloud
Checking ACME challenge CNAME record...
ACME domain: _acme-challenge.mqtt.example.com
Resolved CNAME: _acme-challenge.prod.12345.euc1.aws.hivemq.cloud
✓ Valid ACME challenge CNAME: _acme-challenge.prod.12345.euc1.aws.hivemq.cloud
Checking CAA records for Let's Encrypt authorization...
✓ No CAA records found - Let's Encrypt is allowed
Domain checked: mqtt.example.com (and parent domains)
==============================================
VALIDATION SUMMARY
==============================================
✓ Main domain CNAME: PASSED
✓ ACME challenge CNAME: PASSED
✓ CAA records (Let's Encrypt): PASSED
🎉 All validations PASSED! Your domain is correctly configured for HiveMQ Cloud.
==============================================
HiveMQ Cloud DNS Validation Tool
==============================================
Validating DNS configuration for: mqtt.example.com
Using DNS server: 8.8.8.8
Checking main domain CNAME record...
Domain: mqtt.example.com
Resolved CNAME: prod.12345.euc1.aws.hivemq.cloud
✓ Valid HiveMQ Cloud CNAME: prod.12345.euc1.aws.hivemq.cloud
Checking ACME challenge CNAME record...
ACME domain: _acme-challenge.mqtt.example.com
✗ No CNAME record found for _acme-challenge.mqtt.example.com
Checking CAA records for Let's Encrypt authorization...
CAA records found on domain: example.com
CAA records:
0 issue "sectigo.com"
0 iodef "mailto:[email protected]"
✗ Let's Encrypt is NOT authorized in CAA records
Found CAA records but 'letsencrypt.org' is not listed as authorized issuer
Please add a CAA record: '0 issue "letsencrypt.org"' to allow Let's Encrypt
==============================================
VALIDATION SUMMARY
==============================================
✓ Main domain CNAME: PASSED
✗ ACME challenge CNAME: FAILED
✗ CAA records (Let's Encrypt): FAILED
❌ Validation FAILED. Please check your DNS configuration.
0- Validation successful1- Validation failed2- Usage error or missing prerequisites
To use a custom domain with HiveMQ Cloud, you need to configure these DNS records:
# Main domain CNAME
your-domain.com. IN CNAME <your-cluster>.hivemq.cloud.
# ACME challenge CNAME for SSL certificate provisioning
_acme-challenge.your-domain.com. IN CNAME _acme-challenge.<your-cluster>.hivemq.cloud.
Optional CAA Records: If you use CAA (Certificate Authority Authorization) records to control which certificate authorities can issue certificates for your domain, you must include Let's Encrypt:
# Allow Let's Encrypt to issue certificates (required if CAA records exist)
your-domain.com. IN CAA 0 issue "letsencrypt.org"
Replace <your-cluster> with the actual HiveMQ Cloud cluster identifier provided by HiveMQ support.
"dig command not found"
- Install the
digcommand using your system's package manager (see Prerequisites section)
"No CNAME record found"
- Verify your DNS records are properly configured
- DNS changes can take up to 48 hours to propagate globally
- Try using a different DNS server to check propagation
*"CNAME does not point to .hivemq.cloud"
- Ensure you're using the correct HiveMQ Cloud cluster identifier
- Contact HiveMQ support if you're unsure of the correct target domain
"ACME challenge CNAME mismatch"
- Both your main domain and ACME challenge must point to the same HiveMQ Cloud subdomain
- Double-check that both CNAME records use identical cluster identifiers
"Let's Encrypt is NOT authorized in CAA records"
- Your domain (or parent domain) has CAA records that don't authorize Let's Encrypt
- Add a CAA record:
your-domain.com. IN CAA 0 issue "letsencrypt.org" - CAA records are checked for the domain and all parent domains up to the TLD
- If no CAA records exist anywhere in the domain hierarchy, Let's Encrypt is allowed by default
Contributions are welcome! Please feel free to submit issues or pull requests.
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
For HiveMQ Cloud-specific questions or issues with your domain configuration, please contact HiveMQ Support.
For issues with this validation tool, please open an issue on GitHub.