Sync Unifi Filters

A command-line tool to manage Unifi Network Controller content filtering rules. Fetch filter domains from your Unifi controller to stdout or files, and sync domain lists back to the controller.

Features

• Fetch filters: Download content filter domains from Unifi Controller
• Output to stdout: Easy piping and command composition
• File sync: Update Unifi filters from text files
• Generic: Works with any content filter name
• Flexible: Save to files or work with pipes

Requirements

• Python 3.6 or higher (uses f-strings and type hints)
• requests library (>=2.25.0)
• Unifi Network Controller with content filtering enabled

Installation

1. Clone this repository:

git clone https://github.com/yourusername/sync_unifi_filters.git
cd sync_unifi_filters

2. Install dependencies:

pip install -r requirements.txt

Or install manually:

pip install requests

Configuration

The script requires authentication credentials to connect to your Unifi Controller. You can provide these in two ways:

Method 1: Environment Variables (Recommended)

Set environment variables before running commands:

export UNIFI_HOST="https://192.168.1.1"      # Your Unifi Controller URL
export UNIFI_USERNAME="admin"                # Controller admin username
export UNIFI_PASSWORD="your_password"        # Controller password
export UNIFI_SITE="default"                  # Site name (optional, defaults to "default")

Then run commands normally:

./sync_unifi_filters.py fetch "Samsung Adblock"

Method 2: Inline Environment Variables

Provide credentials inline with each command:

UNIFI_HOST=https://192.168.1.1 \
UNIFI_USERNAME=admin \
UNIFI_PASSWORD=your_password \
./sync_unifi_filters.py fetch "Samsung Adblock"

Method 3: Edit the Script

Modify the default values in sync_unifi_filters.py (lines 13-16):

UNIFI_HOST = os.getenv("UNIFI_HOST", "https://192.168.1.1")
UNIFI_USERNAME = os.getenv("UNIFI_USERNAME", "admin")
UNIFI_PASSWORD = os.getenv("UNIFI_PASSWORD", "your_password")
SITE_NAME = os.getenv("UNIFI_SITE", "default")

Configuration Variables

Variable	Required	Description	Example
UNIFI_HOST	Yes	Full URL to your Unifi Controller (including https://)	https://192.168.1.1 or https://unifi.local
UNIFI_USERNAME	Yes	Admin username for the controller	admin
UNIFI_PASSWORD	Yes	Password for the admin account	your_password
UNIFI_SITE	No	Site name in multi-site setups	default (default), office, home, etc.

Security Note: Avoid storing passwords in shell history. Consider using exported environment variables in your shell profile or a .env file (not committed to git).

Usage

Fetch Filters

Fetch filter domains and output to stdout:

./sync_unifi_filters.py fetch "Samsung Adblock"

Fetch and save to a file:

./sync_unifi_filters.py fetch "Samsung Adblock" -o filters.txt

Sync Filters

Update a Unifi filter from a text file:

./sync_unifi_filters.py sync "Samsung Adblock" filters.txt

Advanced Examples

Count domains in a filter:

./sync_unifi_filters.py fetch "My Filter" | wc -l

Search for specific domains:

./sync_unifi_filters.py fetch "My Filter" | grep example.com

Backup all filters:

./sync_unifi_filters.py fetch "Ad Blocker" -o backup_ads.txt
./sync_unifi_filters.py fetch "Tracking Blocker" -o backup_tracking.txt

Combine multiple filter lists:

cat list1.txt list2.txt | sort -u > combined.txt
./sync_unifi_filters.py sync "Combined Filter" combined.txt

Example: Blocking Samsung TV Ads

This repository includes a curated list of Samsung TV advertising and telemetry domains in example_samsung_adblock_filters.txt. Use this to block ads and tracking on Samsung Smart TVs connected to your network.

Quick Start

1. Create a content filter in your Unifi Controller UI (Settings → Security → Content Filtering):

   • Name: Samsung Adblock
   • Categories: Basic
   • Sources: Select your IoT network or specific Samsung TV devices

2. Sync the filter list to your Unifi Controller:

# Set your credentials
export UNIFI_HOST="https://192.168.1.1"
export UNIFI_USERNAME="admin"
export UNIFI_PASSWORD="your_password"

# Sync the Samsung blocklist
./sync_unifi_filters.py sync "Samsung Adblock" example_samsung_adblock_filters.txt

3. Verify the sync by fetching the filter:

./sync_unifi_filters.py fetch "Samsung Adblock"

What Gets Blocked

The Samsung filter list (71 domains) blocks:

• Advertising: Samsung ad hubs, ad servers, and tracking domains
• Telemetry: Usage analytics, error reporting, and metrics collection
• Content promotion: App recommendations, game promotions, and premium content ads

See example_samsung_adblock_filters.txt for the complete list of blocked domains.

Updating the Filter

You can edit example_samsung_adblock_filters.txt to add or remove domains, then sync again:

# Edit the file
nano example_samsung_adblock_filters.txt

# Sync your changes
./sync_unifi_filters.py sync "Samsung Adblock" example_samsung_adblock_filters.txt

Filter File Format

Filter files are simple text files with one domain per line:

# Comments start with #
example.com
ads.example.net
tracking.example.org

Important Notes

Prerequisites: Creating a Content Filter

Before using this tool, you must create a content filter in the Unifi Controller UI first. The script can only update existing filters, not create new ones.

Setting Up a Content Filter in Unifi

1. Navigate to: Settings → Security → Content Filtering
2. Click: "Create New Content Filtering Rule"
3. Configure the filter:
   • Name: Choose a descriptive name (e.g., "Samsung Adblock")
   • Categories: Select "Basic" filtering (you do NOT need CyberSecure Enhanced subscription)
   • Ad Block: NOT required - you can leave this disabled
   • Sources: Important - Define which networks or client devices this filter applies to
     • Select specific networks (e.g., IoT network, Guest network)
     • Or select specific client devices by MAC address
   • Block List: You can leave this empty or add a few sample domains - the script will overwrite it
4. Save the filter

Important: The filter name in the Unifi UI must exactly match the name you use in the script commands (case-sensitive).

Reference: For more information about Unifi Content Filtering, see the official Unifi documentation.

Subscription Requirements

• No CyberSecure Enhanced subscription required
• Basic content filtering is available in all Unifi Network Controller installations
• You only need "Basic" category filtering enabled
• Ad Block features are NOT required for this tool to work

Undocumented API

This tool uses undocumented Unifi Network Controller APIs (/proxy/network/v2/api/site/{site}/content-filtering). These endpoints are not part of the official API specification and may:

• Change without notice in future controller updates
• Behave differently across controller versions
• Be removed or modified in future releases

Tested with: Unifi Network Controller 10.1.68

SSL Verification

The script disables SSL verification for self-signed certificates by default. If you have a valid certificate, you may want to modify this behavior in the code.

Troubleshooting

Filter not found:

• Ensure the filter exists in your Unifi Controller UI (Settings → Security → Content Filtering)
• The filter name must match exactly (case-sensitive)
• See "Prerequisites: Creating a Content Filter" above for setup instructions

Authentication errors:

• Verify your UNIFI_USERNAME and UNIFI_PASSWORD are correct
• Ensure your user has admin permissions on the controller

Connection errors:

• Check that your Unifi Controller is accessible at the configured UNIFI_HOST URL
• Verify the URL includes https:// (e.g., https://192.168.1.1)
• If using a hostname, ensure it resolves correctly

403 Forbidden errors:

• This typically indicates CSRF token issues (should be fixed in current version)
• Try logging out and back in to the Unifi UI
• Ensure you're using an admin account with full permissions

Contributing

Contributions are welcome! Here's how you can help:

Reporting Issues

Found a bug or have a feature request?

• Bug Reports: Open an issue with details about the problem

  • Include your Unifi Controller version
  • Provide error messages and command output
  • Describe steps to reproduce the issue

• Feature Requests: Open an issue to suggest new features

  • Describe the feature and its use case
  • Explain how it would benefit users
  • Consider including example usage

General Discussion

Have questions or want to share how you're using this tool?

• Discussions: Use GitHub Discussions for:
  • General questions and help
  • Sharing filter lists and use cases
  • Tips and tricks
  • Community support

Pull Requests

Code contributions are appreciated! Please:

• Fork the repository
• Create a feature branch
• Follow the existing code style
• Test your changes
• Submit a pull request with a clear description

License

MIT License - See LICENSE file for details

Disclaimer

This is an unofficial tool that uses undocumented APIs. Use at your own risk. Always backup your Unifi configuration before making changes.