godns

README

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

GoDNS is a dynamic DNS (DDNS) client tool, it is based on my early open source project: DynDNS.

Now I rewrite DynDNS by Golang and call it GoDNS.

Supported DNS Provider

• Cloudflare (https://cloudflare.com)
• DNSPod (https://www.dnspod.cn/)
• HE.net (Hurricane Electric) (https://dns.he.net/)

Supported Platforms

• Linux
• MacOS
• ARM Linux (Raspberry Pi, etc...)
• Windows
• MIPS32 platform

MIPS32 platform

To compile binaries for MIPS (mips or mipsle):

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

And the binary can run well on routers.

Pre-condition

• Register and own a domain.

• Domain's nameserver points to DNSPod or HE.net or Cloudflare.

Get it

Build it from source code

• Get source code from Github:

git clone https://github.com/timothyye/godns.git

• Go into the godns directory, get related library and then build it:

cd cmd/godns
go get -v
go build

Download from releases

Download compiled binaries from releases

Get help

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

Config it

• Get config_sample.json from Github.
• Rename it to config.json.
• Configure your provider, domain/sub-domain info, username and password, etc.
• Configure the SMTP options if you want, a mail notification will sent to your mailbox once the IP is changed.
• Save it in the same directory of GoDNS, or use -c=your_conf_path command.

Config example for Cloudflare

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

{
  "provider": "Cloudflare",
  "email": "you@example.com"
  "password": "Global API Key",
  "domains": [{
      "domain_name": "example.com",
      "sub_domains": ["www","test"]
    },{
      "domain_name": "example2.com",
      "sub_domains": ["www","test"]
    }
  ],
  "ip_url": "https://ifconfig.co/ip",
  "socks5_proxy": ""
}

Config example for DNSPod

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

{
  "provider": "DNSPod",
  "password": "",
  "login_token": "your_id,your_token",
  "domains": [{
      "domain_name": "example.com",
      "sub_domains": ["www","test"]
    },{
      "domain_name": "example2.com",
      "sub_domains": ["www","test"]
    }
  ],
  "ip_url": "http://members.3322.org/dyndns/getip",
  "socks5_proxy": ""
}

Config example for 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"]
    }
  ],
  "ip_url": "http://members.3322.org/dyndns/getip",
  "socks5_proxy": ""
}

HE.net DDNS configuration

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

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

Remember the DDNS key and fill it as password to the config.json.

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

Get an IP address from the interface

For some reasons if you want to get an IP directly from the interface, say eth0 for Linux or Local Area Connection for Windows, update config file like this:

  "ip_url": "",
  "ip_interface": "eth0",

If you set both ip_url and ip_interface, it first tries to get an IP address online, and if not succeed, gets an IP address from the interface as a fallback.

Note that IPv6 address will be ignored currently.

Email notification support

Update config file and provide your SMTP options, a notification mail will be sent to your mailbox once the IP is changed and updated.

  "notify": {
    "enabled": true,
    "smtp_server": "smtp.example.com",
    "smtp_username": "user",
    "smtp_password": "password",
    "smtp_port": 25,
    "send_to": "my_mail@example.com"
  }

Notification mail example:

SOCKS5 proxy support

You can also use SOCKS5 proxy, just fill SOCKS5 address to the socks5_proxy item:

"socks5_proxy": "127.0.0.1:7070"

Now all the queries will go through the specified SOCKS5 proxy.

Run it as a daemon manually

nohup ./godns &

Run it as a daemon, manage it via Upstart

• Install upstart first
• Copy ./upstart/godns.conf to /etc/init
• Start it as a system service:

sudo start godns

Run it as a daemon, manage it via Systemd

• Modify ./systemd/godns.service and config it.
• Copy ./systemd/godns.service to /lib/systemd/system
• Start it as a systemd service:

sudo systemctl enable godns
sudo systemctl start godns

Run it with docker

Now godns supports to run in docker.

• Get config_sample.json from Github.
• Rename it to config.json.
• Run GoDNS with docker:

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

Run it as a Windows service

• Get birkett/srvany-ng from Github.
• Uncompress and place the executable srvany-ng.exe to the same directory where godns.exe in.
• Create a service and add registry keys according to the guide here.

Enjoy it!

Documentation

Index

• Constants
• Variables
• func CheckSettings(config *Settings) error
• func GetCurrentIP(configuration *Settings) (string, error)
• func GetIPFromInterface(configuration *Settings) (string, error)
• func GetIPOnline(configuration *Settings) (string, error)
• func LoadSettings(configPath string, settings *Settings) error
• func SendNotify(configuration *Settings, domain, currentIP string) error
• type Domain
• type Notify
• type Settings

Constants

const (
	// PanicMax is the max allowed panic times
	PanicMax = 5
	// INTERVAL is minute
	INTERVAL = 5
	// DNSPOD for dnspod.cn
	DNSPOD = "DNSPod"
	// HE for he.net
	HE = "HE"
	// CLOUDFLARE for cloudflare.com
	CLOUDFLARE = "Cloudflare"
)

Variables

var (
	// Logo for GoDNS
	Logo = `` /* 775-byte string literal not displayed */

)

Functions

func CheckSettings

func CheckSettings(config *Settings) error

CheckSettings check the format of settings

func GetCurrentIP

func GetCurrentIP(configuration *Settings) (string, error)

GetCurrentIP gets an IP from either internet or specific interface, depending on configuration

func GetIPFromInterface

func GetIPFromInterface(configuration *Settings) (string, error)

GetIPFromInterface gets IP address from the specific interface

func GetIPOnline

func GetIPOnline(configuration *Settings) (string, error)

GetIPOnline gets public IP from internet

func LoadSettings

func LoadSettings(configPath string, settings *Settings) error

LoadSettings -- Load settings from config file

func SendNotify

func SendNotify(configuration *Settings, domain, currentIP string) error

SendNotify sends mail notify if IP is changed

Types

type Domain

type Domain struct {
	DomainName string   `json:"domain_name"`
	SubDomains []string `json:"sub_domains"`
}

Domain struct

type Notify

type Notify struct {
	Enabled      bool   `json:"enabled"`
	SMTPServer   string `json:"smtp_server"`
	SMTPUsername string `json:"smtp_username"`
	SMTPPassword string `json:"smtp_password"`
	SMTPPort     int    `json:"smtp_port"`
	SendTo       string `json:"send_to"`
}

Notify struct for SMTP notification

type Settings

type Settings struct {
	Provider    string   `json:"provider"`
	Email       string   `json:"email"`
	Password    string   `json:"password"`
	LoginToken  string   `json:"login_token"`
	Domains     []Domain `json:"domains"`
	IPUrl       string   `json:"ip_url"`
	LogPath     string   `json:"log_path"`
	Socks5Proxy string   `json:"socks5_proxy"`
	Notify      Notify   `json:"notify"`
	IPInterface string   `json:"ip_interface"`
}

Settings struct