NextDNS IP Updater for Steam Deck

Automated deployment of the NextDNS IP updater as a systemd service on Steam Deck. This installer follows the Tailscale installation pattern, ensuring compatibility with Steam Deck's immutable filesystem and atomic updates.

The NextDNS IP updater keeps your NextDNS configuration automatically updated with your current WAN IP address, enabling DNS filtering and logging for dynamic IP addresses.

Quick Installation

For a one-command installation without cloning the repository:

# Download and run the installer directly
curl -fsSL https://raw.githubusercontent.com/nilbot/deck-nextdns-ip-update/main/quick-install.sh | sudo bash

Standard Installation

1. Clone this repository to your Deck:

   git clone https://github.com/nilbot/deck-nextdns-ip-update.git
   cd deck-nextdns-ip-update

2. Run the installation script:

   sudo bash install.sh

3. Configure your NextDNS endpoint:

   sudo nano /etc/default/nextdns-ip-updater

   Find your NextDNS endpoint URL in your NextDNS dashboard under "Dynamic DNS" and set it:

   NEXTDNS_ENDPOINT=https://link-ip.nextdns.io/your-unique-id/steam-deck

4. Start the service:

   sudo systemctl restart nextdns-ip-updater

5. Verify installation:

   bash test-service.sh

Configuration

The service is configured via /etc/default/nextdns-ip-updater:

Variable	Description	Default	Required
NEXTDNS_ENDPOINT	Your NextDNS dynamic DNS update URL	(empty)	✅ Yes
UPDATE_INTERVAL_SECONDS	IP check/update frequency	300 (5 min)	❌ No

Getting Your NextDNS Endpoint

1. Log into your NextDNS dashboard
2. Go to your configuration
3. Navigate to "Settings" → "Dynamic DNS"
4. Copy the endpoint URL (format: https://link-ip.nextdns.io/abc123/device-name)

Example Configuration

# /etc/default/nextdns-ip-updater
NEXTDNS_ENDPOINT=https://link-ip.nextdns.io/abc123def456/steam-deck
UPDATE_INTERVAL_SECONDS=300

Updating NextDNS IP Updater

The installer automatically downloads the latest release when run:

1. Update the installer:

   cd deck-nextdns-ip-update
   git pull

2. Run the installer again:

   sudo bash install.sh

The updater will automatically upgrade to the latest version while preserving your configuration.

Service Management

Task	Command
Check status	sudo systemctl status nextdns-ip-updater
Start service	sudo systemctl start nextdns-ip-updater
Stop service	sudo systemctl stop nextdns-ip-updater
Restart service	sudo systemctl restart nextdns-ip-updater
View logs	sudo journalctl -u nextdns-ip-updater -f
Enable auto-start	sudo systemctl enable nextdns-ip-updater (automatic)
Disable auto-start	sudo systemctl disable nextdns-ip-updater
Test installation	bash test-service.sh

Uninstalling

To completely remove the NextDNS IP updater:

sudo bash uninstall.sh

This removes all files, stops the service, and cleans up the configuration.

How it Works

The NextDNS IP updater deployment follows Steam Deck best practices:

Installation Structure

• Binary: /opt/nextdns-ip-updater/nextdns-ip-updater (Go binary)
• Service: /etc/systemd/system/nextdns-ip-updater.service
• Override: /etc/systemd/system/nextdns-ip-updater.service.d/override.conf
• Configuration: /etc/default/nextdns-ip-updater
• PATH Integration: /etc/profile.d/nextdns-ip-updater.sh
• Atomic Updates: /etc/atomic-update.conf.d/nextdns-ip-updater.conf

Service Behavior

• Type: Simple long-running daemon
• User: Root (required for network operations)
• Restart Policy: Always restart on failure (10-second delay)
• Dependencies: Starts after network is available
• Signals: Graceful shutdown via SIGINT/SIGTERM
• Timeout: 90-second stop timeout

Download Source

Binaries are automatically downloaded from the latest GitHub release of the main updater project.

Troubleshooting

Service Won't Start

# Check service status and logs
sudo systemctl status nextdns-ip-updater
sudo journalctl -u nextdns-ip-updater -n 50

# Common issues:
# 1. NEXTDNS_ENDPOINT not configured
# 2. Invalid NextDNS endpoint URL
# 3. Network connectivity issues

Configuration Issues

Invalid NextDNS endpoint:

• Ensure the URL format is correct: https://link-ip.nextdns.io/id/name
• Verify the URL in your NextDNS dashboard
• Check for extra spaces or characters

Service keeps restarting:

# Monitor real-time logs
sudo journalctl -u nextdns-ip-updater -f

# Check configuration syntax
sudo systemctl status nextdns-ip-updater

Binary Issues

Command not found:

# Reload your shell environment
source /etc/profile.d/nextdns-ip-updater.sh

# Or restart your session

Installation corruption:

# Re-run the installer
sudo bash install.sh

# Or completely reinstall
sudo bash uninstall.sh
sudo bash install.sh

Network Issues

The service requires internet access to:

• Contact your NextDNS endpoint
• Detect your current WAN IP

Ensure your Steam Deck has internet connectivity and can reach NextDNS servers.

Steam Deck Compatibility

This installer is specifically designed for Steam Deck's immutable filesystem:

• Atomic Updates: Configuration files are registered with the atomic update system
• Persistent Installation: Survives Steam Deck system updates
• Immutable Compatibility: Follows Steam Deck installation patterns
• Override System: Uses systemd override files for customization
• Legacy Cleanup: Properly removes old installations

Technical Details

• Language: Go (compiled binary)
• Logging: Structured JSON logging via logrus
• Signals: Supports graceful shutdown (SIGINT/SIGTERM)
• Error Handling: Automatic restart on failure
• Resource Usage: Minimal CPU and memory footprint
• Dependencies: None (static binary)

The service runs perpetually, checking and updating your IP address at the configured interval, with automatic restart on any failures.

Support

• GitHub Issues: Report bugs
• Main Project: NextDNS IP Updater
• Documentation: Check both repositories for detailed documentation

Available Scripts

This repository provides several scripts for different purposes:

Script	Purpose	Usage
install.sh	Main installer (uses template files)	sudo bash install.sh
test-service.sh	Test installation and service status	bash test-service.sh
test-local.sh	Local validation of installation files	bash test-local.sh
test-steamdeck.sh	Live testing on Steam Deck via SSH	bash test-steamdeck.sh
rollback.sh	Complete rollback for testing	sudo bash rollback.sh
uninstall.sh	Complete removal of installation	sudo bash uninstall.sh

Available Scripts

This repository provides several scripts for different purposes:

Script	Purpose	Usage
install.sh	Main installer (uses template files)	sudo bash install.sh
test-service.sh	Test installation and service status	bash test-service.sh
test-local.sh	Local validation of installation files	bash test-local.sh
test-steamdeck.sh	Live testing on Steam Deck via SSH	bash test-steamdeck.sh
rollback.sh	Complete rollback for testing	sudo bash rollback.sh
uninstall.sh	Complete removal of installation	sudo bash uninstall.sh

Template Files:

• nextdns-ip-updater.service.example - Systemd service template
• nextdns-ip-updater.conf.example - Configuration template
• override.conf - Systemd override configuration

Development workflow (on macOS/Linux dev machine):

1. bash test-local.sh - Validate file syntax and structure only (no actual functionality testing)

Steam Deck installation workflow:

1. sudo bash install.sh - Install the service (run on Steam Deck)
2. sudo nano /etc/default/nextdns-ip-updater - Configure NextDNS endpoint
3. bash test-service.sh - Verify installation and service status
4. sudo journalctl -u nextdns-ip-updater -f - Monitor logs

Remote Steam Deck testing (via SSH):

1. bash test-steamdeck.sh - Deploy and test on Steam Deck remotely (ssh deck@manhood)