TimothyYe / Godns

 ██████╗  ██████╗ ██████╗ ███╗   ██╗███████╗
██╔════╝ ██╔═══██╗██╔══██╗████╗  ██║██╔════╝
██║  ███╗██║   ██║██║  ██║██╔██╗ ██║███████╗
██║   ██║██║   ██║██║  ██║██║╚██╗██║╚════██║
╚██████╔╝╚██████╔╝██████╔╝██║ ╚████║███████║
 ╚═════╝  ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚══════╝

GoDNS is a dynamic DNS (DDNS) client tool. It is a rewrite in Go of my early DynDNS open source project.

Currently supports updating A records for subdomains. Doesn't support updating of root domains.

• Supported DNS Providers
• Supported Platforms
• Pre-conditions
• Installation
• Usage
• Configuration
  • Overview
  • Configuration properties
  • Configuration examples
    • Cloudflare
    • DNSPod
    • Dreamhost
    • Google Domains
    • AliDNS
    • DuckDNS
    • No-IP
    • HE.net
  • Notifications
    • Email
    • Telegram
    • Slack
  • Miscellaneous topics
    • IPv6 support
    • Network interface IP address
    • SOCKS5 proxy support
• Running GoDNS
  • As a manual daemon
  • As a managed daemon (with upstart)
  • As a managed daemon (with systemd)
  • As a Docker container
  • As a Windows service
• Special Thanks

Supported DNS Providers

Tip: You can follow this issue to view the current status of DDNS for root domains.

Supported Platforms

• Linux

• MacOS

• ARM Linux (Raspberry Pi, etc.)

• Windows

• MIPS32 platform

  To compile binaries for MIPS (mips or mipsle), run:

  GOOS=linux GOARCH=mips/mipsle GOMIPS=softfloat go build -a
  

  The binary can run on routers as well.

Pre-conditions

To use GoDNS, it is assumed:

• You registered (now own) a domain
• Domain was delegated to a supported DNS provider (i.e. it has nameserver NS records pointing at a supported provider)

Alternatively, you can sign in to DuckDNS (with a social account) and get a subdomain on the duckdns.org domain for free.

Installation

Build GoDNS by running (from the root of the repository):

cd cmd/godns  # go to the GoDNS directory
go get -v     # get dependencies
go build      # build

You can also download a compiled binary from the releases.

Usage

Print usage/help by running:

$ ./godns -h
Usage of ./godns:
  -c string
        Specify a config file (default "./config.json")
  -h    Show help

Configuration

Overview

• Make a copy of config_sample.json and name it config.json
• Configure your provider, domain/subdomain info, credentials, etc.
• Configure a notification medium (e.g. SMTP to receive emails) to get notified when your IP address changes
• Place the file in the same directory of GoDNS or use the -c=path/to/your/file.json option

Configuration properties

• provider — One of the supported provider to use: Cloudflare, Google, DNSPod, AliDNS, HE, DuckDNS or Dreamhost.
• email — Email or account name of the DNS provider.
• password — Password of the DNS provider.
• login_token — API token of the DNS provider.
• domains — Domains list, with your sub domains.
• ip_url — A URL for fetching one's public IPv4 address.
• ipv6_url — A URL for fetching one's public IPv6 address.
• ip_type — Switch deciding if IPv4 or IPv6 should be used (when supported). Available values: IPv4 or IPv6.
• interval — How often (in seconds) the public IP should be updated.
• socks5_proxy — Socks5 proxy server.
• resolver — Address of a public DNS server to use. For instance to use Google's public DNS, you can set 8.8.8.8 when using GoDNS in IPv4 mode or 2001:4860:4860::8888 in IPv6 mode.

Configuration examples

Cloudflare

For Cloudflare, you need to provide the email & Global API Key as password (or to use the API token) and config all the domains & subdomains.

{
  "provider": "Cloudflare",
  "email": "[email protected]",
  "password": "Global API Key",
  "domains": [{
      "domain_name": "example.com",
      "sub_domains": ["www","test"]
    },{
      "domain_name": "example2.com",
      "sub_domains": ["www","test"]
    }
  ],
  "resolver": "8.8.8.8",
  "ip_url": "https://myip.biturl.top",
  "ip_type": "IPv4",
  "interval": 300,
  "socks5_proxy": ""
}

{
  "provider": "Cloudflare",
  "login_token": "API Token",
  "domains": [{
      "domain_name": "example.com",
      "sub_domains": ["www","test"]
    },{
      "domain_name": "example2.com",
      "sub_domains": ["www","test"]
    }
  ],
  "resolver": "8.8.8.8",
  "ip_url": "https://myip.biturl.top",
  "ip_type": "IPv4",
  "interval": 300,
  "socks5_proxy": ""
}

DNSPod

For DNSPod, you need to provide your API Token(you can create it here), and config all the domains & subdomains.

{
  "provider": "DNSPod",
  "login_token": "your_id,your_token",
  "domains": [{
      "domain_name": "example.com",
      "sub_domains": ["www","test"]
    },{
      "domain_name": "example2.com",
      "sub_domains": ["www","test"]
    }
  ],
  "resolver": "8.8.8.8",
  "ip_url": "https://myip.biturl.top",
  "ip_type": "IPv4",
  "interval": 300,
  "socks5_proxy": ""
}

Dreamhost

For Dreamhost, you need to provide your API Token(you can create it here), and config all the domains & subdomains.

{
  "provider": "Dreamhost",
  "login_token": "your_api_key",
  "domains": [{
      "domain_name": "example.com",
      "sub_domains": ["www","test"]
    },{
      "domain_name": "example2.com",
      "sub_domains": ["www","test"]
    }
  ],
  "resolver": "8.8.8.8",
  "ip_url": "https://myip.biturl.top",
  "ip_type": "IPv4",
  "interval": 300,
  "resolver": "ns1.dreamhost.com",
  "socks5_proxy": ""
}

Google Domains

For Google Domains, you need to provide email & password, and config all the domains & subdomains.

{
  "provider": "Google",
  "email": "Your_Username",
  "password": "Your_Password",
  "domains": [{
      "domain_name": "example.com",
      "sub_domains": ["www","test"]
    },{
      "domain_name": "example2.com",
      "sub_domains": ["www","test"]
    }
  ],
  "resolver": "8.8.8.8",
  "ip_url": "https://myip.biturl.top",
  "ip_type": "IPv4",
  "interval": 300,
  "socks5_proxy": ""
}

AliDNS

For AliDNS, you need to provide AccessKeyID & AccessKeySecret as email & password, and config all the domains & subdomains.

{
  "provider": "AliDNS",
  "email": "AccessKeyID",
  "password": "AccessKeySecret",
  "login_token": "",
  "domains": [{
      "domain_name": "example.com",
      "sub_domains": ["www","test"]
    },{
      "domain_name": "example2.com",
      "sub_domains": ["www","test"]
    }
  ],
  "resolver": "8.8.8.8",
  "ip_url": "https://myip.biturl.top",
  "ip_type": "IPv4",
  "interval": 300,
  "socks5_proxy": ""
}

DuckDNS

For DuckDNS, only need to provide the token, config 1 default domain & subdomains.

{
  "provider": "DuckDNS",
  "password": "",
  "login_token": "3aaaaaaaa-f411-4198-a5dc-8381cac61b87",
  "domains": [
    {
      "domain_name": "www.duckdns.org",
      "sub_domains": [
        "myname"
      ]
    }
  ],
  "resolver": "8.8.8.8",
  "ip_url": "https://myip.biturl.top",
  "ip_type": "IPv4",
  "interval": 300,
  "socks5_proxy": ""
}

No-IP

{
  "provider": "NoIP",
  "email": "[email protected]",
  "password": "YourPassword",
  "domains": [
    {
      "domain_name": "ddns.net",
      "sub_domains": ["timothyye6"]
    }
  ],
  "ip_type": "IPv4",
  "ip_url": "https://myip.biturl.top",
  "resolver": "8.8.8.8",
  "interval": 300,
  "socks5_proxy": ""
}

HE.net

For HE, email is not needed, just fill DDNS key to password, and config all the domains & subdomains.

{
  "provider": "HE",
  "password": "YourPassword",
  "login_token": "",
  "domains": [{
      "domain_name": "example.com",
      "sub_domains": ["www","test"]
    },{
      "domain_name": "example2.com",
      "sub_domains": ["www","test"]
    }
  ],
  "resolver": "8.8.8.8",
  "ip_url": "https://myip.biturl.top",
  "ip_type": "IPv4",
  "interval": 300,
  "socks5_proxy": ""
}

Provider configuration

Add a new "A record" and make sure that "Enable entry for dynamic dns" is checked:

Fill in your own DDNS key or generate a random DDNS key for this new created "A record":

Remember the DDNS key and set it in the password property in the configuration file.

NOTICE: If you have multiple domains or subdomains, make sure their DDNS key are the same.

Notifications

GoDNS can send a notification each time the IP changes.

Email

Emails are sent over SMTP. Update your configuration with the following snippet:

  "notify": {
    "mail": {
      "enabled": true,
      "smtp_server": "smtp.example.com",
      "smtp_username": "user",
      "smtp_password": "password",
      "smtp_port": 25,
      "send_to": "[email protected]"
    }
  }

Each time the IP changes, you will receive an email like that:

Telegram

To receive a Telegram message each time the IP changes, update your configuration with the following snippet:

  "notify": {
    "telegram": {
      "enabled": true,
      "bot_api_key": "11111:aaaa-bbbb",
      "chat_id": "-123456",
      "message_template": "Domain *{{ .Domain }}* is updated to %0A{{ .CurrentIP }}",
      "use_proxy": false
    },
  }

The message_template property supports markdown. New lines needs to be escaped with %0A.

Slack

To receive a Slack message each time the IP changes, update your configuration with the following snippet:

  "notify": {
    "slack": {
      "enabled": true,
      "bot_api_token": "xoxb-xxx",
      "channel": "your_channel",
      "message_template": "Domain *{{ .Domain }}* is updated to \n{{ .CurrentIP }}",
      "use_proxy": false
    },
  }

The message_template property supports markdown. New lines needs to be escaped with \n.

Miscellaneous topics

IPv6 support

Most of the providers support IPv6.

To enable the IPv6 support of GoDNS, there are two solutions to choose from:

1. Use an online service to lookup the external IPv6

   For that:

   • Set the ip_type as IPv6, and make sure the ipv6_url is configured
   • Create an AAAA record instead of an A record in your DNS provider
   Configuration example

   {
     "domains": [
       {
         "domain_name": "example.com",
         "sub_domains": [
           "ipv6"
         ]
       }
     ],
     "resolver": "2001:4860:4860::8888",
     "ipv6_url": "https://api-ipv6.ip.sb/ip",
     "ip_type": "IPv6"
   }
   

2. Let GoDNS find the IPv6 of the network interface of the machine it is running on (more on that later).

   For this to happen, just leave ip_url and ipv6_url empty.

   Note that the network interface must be configured with an IPv6 for this to work.

Network interface IP address

For some reasons if you want to get the IP address associated to a network interface (instead of performing an online lookup), you can specify it in the configuration file this way:

...
  "ip_url": "",
  "ip_interface": "interface-name",
...

With interface-name replaced by the name of the network interface, e.g. eth0 on Linux or Local Area Connection on Windows.

Note: If ip_url is also specified, it will be used to perform an online lookup first and the network interface IP will be used as a fallback in case of failure.

SOCKS5 proxy support

You can make all remote calls go through a SOCKS5 proxy by specifying it in the configuration file this way:

...
"socks5_proxy": "127.0.0.1:7070"
"use_proxy": true
...

Running GoDNS

There are few ways to run GoDNS.

As a manual daemon

nohup ./godns &

Note: when the program stops, it will not be restarted.

As a managed daemon (with upstart)

1. Install upstart first (if not available already)

2. Copy ./upstart/godns.conf to /etc/init (and tweak it to your needs)

3. Start the service:

   sudo start godns
   

As a managed daemon (with systemd)

1. Install systemd first (it not available already)

2. Copy ./systemd/godns.service to /lib/systemd/system (and tweak it to your needs)

3. Start the service:

   sudo systemctl enable godns
   sudo systemctl start godns
   

As a Docker container

With /path/to/config.json your local configuration file, run:

docker run \
-d --name godns --restart=always \
-v /path/to/config.json:/config.json \
timothyye/godns:latest

As a Windows service

1. Download the latest version of NSSM

2. In an administrative prompt, from the folder where NSSM was downloaded, e.g. C:\Downloads\nssm\ win64, run:

   nssm install YOURSERVICENAME
   

3. Follow the interface to configure the service. In the "Application" tab just indicate where the godns.exe file is. Optionally you can also define a description on the "Details" tab and define a log file on the "I/O" tab. Finish by clicking on the "Install service" button.

4. The service will now start along Windows.

Note: you can uninstall the service by running:

nssm remove YOURSERVICENAME

Special Thanks

Thanks JetBrains for sponsoring this project with free open source license.

I like GoLand, it is an amazing and productive tool.