██████╗ ██████╗ ██████╗ ███╗ ██╗███████╗
██╔════╝ ██╔═══██╗██╔══██╗████╗ ██║██╔════╝
██║ ███╗██║ ██║██║ ██║██╔██╗ ██║███████╗
██║ ██║██║ ██║██║ ██║██║╚██╗██║╚════██║
╚██████╔╝╚██████╔╝██████╔╝██║ ╚████║███████║
╚═════╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═══╝╚══════╝
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
- Running GoDNS
- Special Thanks
Provider | IPv4 support | IPv6 support | Root Domain | Subdomains |
---|---|---|---|---|
Cloudflare | ✅ | ✅ | ✅ | ✅ |
Google Domains | ✅ | ✅ | ❌ | ✅ |
DNSPod | ✅ | ✅ | ✅ | ✅ |
HE.net (Hurricane Electric) | ✅ | ✅ | ✅ | ✅ |
AliDNS | ✅ | ✅ | ✅ | ✅ |
DuckDNS | ✅ | ✅ | ❌ | ✅ |
Dreamhost | ✅ | ✅ | ❌ | ✅ |
No-IP | ✅ | ✅ | ❌ | ✅ |
Scaleway | ✅ | ✅ | ✅ | ✅ |
Tip: You can follow this issue to view the current status of DDNS for root domains.
-
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.
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.
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.
Print usage/help by running:
$ ./godns -h
Usage of ./godns:
-c string
Specify a config file (default "./config.json")
-h Show help
- 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
provider
— One of the supported provider to use:Cloudflare
,Google
,DNSPod
,AliDNS
,HE
,DuckDNS
orDreamhost
.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
orIPv6
.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 set8.8.8.8
when using GoDNS in IPv4 mode or2001:4860:4860::8888
in IPv6 mode.
By simply putting @
into sub_domains
, for example:
"domains": [{
"domain_name": "example.com",
"sub_domains": ["@"]
}]
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.
Using email & Global API Key
{
"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"]
}
],
"resolver": "8.8.8.8",
"ip_url": "https://api.ip.sb/ip",
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
Using the API Token
{
"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://api.ip.sb/ip",
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
For DNSPod, you need to provide your API Token(you can create it here), and config all the domains & subdomains.
Example
{
"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://api.ip.sb/ip",
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
For Dreamhost, you need to provide your API Token(you can create it here), and config all the domains & subdomains.
Example
{
"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://api.ip.sb/ip",
"ip_type": "IPv4",
"interval": 300,
"resolver": "ns1.dreamhost.com",
"socks5_proxy": ""
}
For Google Domains, you need to provide email & password, and config all the domains & subdomains.
Example
{
"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://api.ip.sb/ip",
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
For AliDNS, you need to provide AccessKeyID
& AccessKeySecret
as email
& password
, and config all the domains & subdomains.
Example
{
"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://api.ip.sb/ip",
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
For DuckDNS, only need to provide the token
, config 1 default domain & subdomains.
Example
{
"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://api.ip.sb/ip",
"ip_type": "IPv4",
"interval": 300,
"socks5_proxy": ""
}
Example
{
"provider": "NoIP",
"email": "mail@example.com",
"password": "YourPassword",
"domains": [
{
"domain_name": "ddns.net",
"sub_domains": ["timothyye6"]
}
],
"ip_type": "IPv4",
"ip_url": "https://api.ip.sb/ip",
"resolver": "8.8.8.8",
"interval": 300,
"socks5_proxy": ""
}
For HE, email is not needed, just fill DDNS key to password, and config all the domains & subdomains.
Example
{
"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://api.ip.sb/ip",
"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:
![](https://raw.githubusercontent.com/zinete/godns/master/./snapshots/he1.png)
Fill in your own DDNS key or generate a random DDNS key for this new created "A record":
![](https://raw.githubusercontent.com/zinete/godns/master/./snapshots/he2.png)
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.
For Scaleway, you need to provide an API Secret Key as the login_token
(How to generate an API key), and configure the domains and subdomains. domain_name
should equal a DNS zone, or the root domain in Scaleway. TTL for the DNS records will be set to the interval
value. Make sure A
or AAAA
records exist for the relevant sub domains, these can be set up in the Scaleway console.
Example
{
"provider": "Scaleway",
"login_token": "API Secret Key",
"domains": [{
"domain_name": "example.com",
"sub_domains": ["www","@"]
},{
"domain_name": "samplednszone.example.com",
"sub_domains": ["www","test"]
}
],
"resolver": "8.8.8.8",
"ip_url": "https://api.ip.sb/ip",
"ip_type": "IPv4",
"interval": 300
}
GoDNS can send a notification each time the IP changes.
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": "my_mail@example.com"
}
}
Each time the IP changes, you will receive an email like that:
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
.
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
.
To receive a Discord message each time the IP changes, update your configuration with the following snippit:
"notify": {
"discord": {
"enabled": true,
"bot_api_token": "discord_bot_token",
"channel": "your_channel",
"message_template": "(Optional) Domain *{{ .Domain }}* is updated to \n{{ .CurrentIP }}",
}
}
Most of the providers support IPv6.
To enable the IPv6
support of GoDNS, there are two solutions to choose from:
-
Use an online service to lookup the external IPv6
For that:
- Set the
ip_type
asIPv6
, and make sure theipv6_url
is configured - Create an
AAAA
record instead of anA
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" }
- Set the
-
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
andipv6_url
empty.Note that the network interface must be configured with an IPv6 for this to work.
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.
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
...
To display debug info, set debug_info
as true
to enable this feature. By default, the debug info is disabled.
"debug_info": true,
There are a few ways to run GoDNS.
nohup ./godns &
Note: when the program stops, it will not be restarted.
-
Install
upstart
first (if not available already) -
Copy
./upstart/godns.conf
to/etc/init
(and tweak it to your needs) -
Start the service:
sudo start godns
-
Install
systemd
first (it not available already) -
Copy
./systemd/godns.service
to/lib/systemd/system
(and tweak it to your needs) -
Start the service:
sudo systemctl enable godns sudo systemctl start godns
Visit https://hub.docker.com/r/timothyye/godns to fetch the latest docker image.
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
-
Download the latest version of NSSM
-
In an administrative prompt, from the folder where NSSM was downloaded, e.g.
C:\Downloads\nssm\
win64, run:nssm install YOURSERVICENAME
-
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. -
The service will now start along Windows.
Note: you can uninstall the service by running:
nssm remove YOURSERVICENAME
Thanks JetBrains for sponsoring this project with free open source license.
I like GoLand, it is an amazing and productive tool.