UniFi Bulk DNS Records Creator

A Python script to bulk create static DNS records in UniFi Network using the API. Works with UDM, UDM Pro, and UDM SE running UniFi OS.

Features

• 🚀 Bulk create DNS records from CSV file
• 🔒 Secure API token authentication (no password storage)
• ✅ Support for A and CNAME records
• 🎯 Configurable TTL and enable/disable status
• 🐛 Optional debug mode for troubleshooting
• 💯 Rate limiting to avoid API throttling

Use Cases

This script updates the DNS Records policy in UniFi Network, allowing you to:

• Add records for external networks: Create DNS entries for clients not managed by your UniFi console (e.g., devices on external networks, VPN clients, remote sites)
• Create aliases: Add CNAME records to create easy-to-remember aliases for existing hosts
• Bulk management: Import dozens or hundreds of DNS records at once instead of adding them manually one by one through the UI

View your DNS records in the UniFi Console at: https://<your-unifi-controller-ip>/network/default/settings/policy-table?preset=dns-records

(Replace <your-unifi-controller-ip> with your controller's IP address)

Requirements

• Python 3.6+
• UniFi Dream Machine (UDM), UDM Pro, or UDM SE with UniFi OS
• API Token from UniFi Console

Installation

1. Clone this repository:

git clone https://github.com/denisvinciguerra/unifi-bulk-dns.git
cd unifi-bulk-dns

2. Install dependencies:

pip install -r requirements.txt

Creating an API Token

1. Log in to your UniFi OS Console
2. Navigate to Settings → Admins
3. Click Create API Token
4. Copy the generated token (you'll need it when running the script)

⚠️ Important: Keep your API token secure and never commit it to version control!

Usage

Basic Usage

python unifi_bulk_create_dns_records.py dns_records.csv

The script will prompt you for your API token securely (input won't be displayed).

Advanced Options

# Custom UDM IP address
python unifi_bulk_create_dns_records.py dns_records.csv --udm-ip 192.168.1.254

# Custom site name
python unifi_bulk_create_dns_records.py dns_records.csv --site custom_site

# Enable debug output
python unifi_bulk_create_dns_records.py dns_records.csv --debug

CSV File Format

Create a CSV file with the following columns:

key,value,record_type,ttl,enabled
nas.home.lan,192.168.1.10,A,3600,true
plex.home.lan,nas.home.lan,CNAME,0,true
backup.home.lan,192.168.1.20,A,3600,true
media.home.lan,192.168.1.30,A,3600,false

Columns:

• key: DNS hostname (FQDN)
• value: IP address (for A records) or target hostname (for CNAME records)
• record_type: Record type (A or CNAME)
• ttl: Time to live in seconds (use 0 for default)
• enabled: true or false to enable/disable the record

See example.csv for a complete example.

Troubleshooting

403 Forbidden Error

If you get a 403 error, make sure:

• Your API token is valid and hasn't expired
• Your account has admin permissions
• You're using an API token (not username/password authentication)

Connection Errors

• Verify your UDM IP address is correct
• Ensure you can access the UniFi Console from your computer
• Check that port 443 is accessible

Debug Mode

Run with --debug flag to see detailed information:

python unifi_bulk_create_dns_records.py dns_records.csv --debug

API Endpoints

This script uses the UniFi Network v2 API:

• Endpoint: /proxy/network/v2/api/site/{site}/static-dns
• Authentication: API Token via X-API-Key header
• Method: POST for creating records

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - See LICENSE file for details

Disclaimer

This script is not officially supported by Ubiquiti Networks. Use at your own risk.

Development

This project was developed with assistance from Claude (Anthropic AI). The initial concept, requirements, and testing were done by the maintainer, with AI assistance for code structure, error handling, and documentation.

Author

Created by @denisvinciguerra