diff --git a/README.md b/README.md index 08561e6..e4e6f60 100644 --- a/README.md +++ b/README.md @@ -20,70 +20,103 @@ [15]: https://img.shields.io/badge/cover.run-88.2%25-green.svg [16]: https://cover.run/go/github.com/timothyye/godns -GoDNS is a dynamic DNS (DDNS) client tool, it is based on my early open source project: [DynDNS](https://github.com/TimothyYe/DynDNS). +[GoDNS](https://github.com/TimothyYe/godns) is a dynamic DNS (DDNS) client tool. It is a rewrite in [Go](https://golang.org) of my early [DynDNS](https://github.com/TimothyYe/DynDNS) open source project. -Now I rewrite [DynDNS](https://github.com/TimothyYe/DynDNS) by Golang and call it [GoDNS](https://github.com/TimothyYe/godns). +--- +- [Supported DNS Providers](#supported-dns-providers) +- [Supported Platforms](#supported-platforms) +- [Pre-conditions](#pre-conditions) +- [Installation](#installation) +- [Usage](#usage) +- [Configuration](#configuration) + - [Overview](#overview) + - [Configuration properties](#configuration-properties) + - [Configuration examples](#configuration-examples) + - [Cloudflare](#cloudflare) + - [DNSPod](#dnspod) + - [Dreamhost](#dreamhost) + - [Google Domains](#google-domains) + - [AliDNS](#alidns) + - [DuckDNS](#duckdns) + - [No-IP](#no-ip) + - [HE.net](#henet) + - [Notifications](#notifications) + - [Email](#email) + - [Telegram](#telegram) + - [Slack](#slack) + - [Miscellaneous topics](#miscellaneous-topics) + - [IPv6 support](#ipv6-support) + - [Network interface IP address](#network-interface-ip-address) + - [SOCKS5 proxy support](#socks5-proxy-support) +- [Running GoDNS](#running-godns) + - [As a manual daemon](#as-a-manual-daemon) + - [As a managed daemon (with upstart)](#as-a-managed-daemon-with-upstart) + - [As a managed daemon (with systemd)](#as-a-managed-daemon-with-systemd) + - [As a Docker container](#as-a-docker-container) + - [As a Windows service](#as-a-windows-service) +- [Special Thanks](#special-thanks) +--- ## Supported DNS Providers -* Cloudflare ([https://cloudflare.com](https://cloudflare.com)) -* Google Domains ([https://domains.google](https://domains.google)) -* DNSPod ([https://www.dnspod.cn/](https://www.dnspod.cn/)) -* HE.net (Hurricane Electric) ([https://dns.he.net/](https://dns.he.net/)) -* AliDNS ([https://help.aliyun.com/product/29697.html](https://help.aliyun.com/product/29697.html)) -* DuckDNS ([https://www.duckdns.org](https://www.duckdns.org)) -* Dreamhost ([https://www.dreamhost.com](https://www.dreamhost.com)) -* No-IP ([https://www.noip.com/](https://www.noip.com)) +| Provider | IPv4 support | IPv6 support | +| ------------------------------------- | :----------------: | :----------------: | +| [Cloudflare][cloudflare] | :white_check_mark: | :white_check_mark: | +| [Google Domains][google.domains] | :white_check_mark: | :white_check_mark: | +| [DNSPod][dnspod] | :white_check_mark: | :white_check_mark: | +| [HE.net (Hurricane Electric)][he.net] | :white_check_mark: | :white_check_mark: | +| [AliDNS][alidns] | :white_check_mark: | :x: | +| [DuckDNS][duckdns] | :white_check_mark: | :white_check_mark: | +| [Dreamhost][dreamhost] | :white_check_mark: | :white_check_mark: | +| [No-IP][no-ip] | :white_check_mark: | :white_check_mark: | + +[cloudflare]: https://cloudflare.com +[google.domains]: https://domains.google +[dnspod]: https://www.dnspod.cn +[he.net]: https://dns.he.net +[alidns]: https://help.aliyun.com/product/29697.html +[duckdns]: https://www.duckdns.org +[dreamhost]: https://www.dreamhost.com +[no-ip]: https://www.noip.com ## Supported Platforms * Linux * MacOS -* ARM Linux (Raspberry Pi, etc...) +* ARM Linux (Raspberry Pi, etc.) * Windows * MIPS32 platform -## MIPS32 platform + To compile binaries for MIPS (mips or mipsle), run: -To compile binaries for MIPS (mips or mipsle): + ```bash + 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](#supported-dns-providers) (i.e. it has nameserver `NS` records pointing at a supported provider) + +Alternatively, you can sign in to [DuckDNS](https://www.duckdns.org) (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): ```bash -GOOS=linux GOARCH=mips/mipsle GOMIPS=softfloat go build -a +cd cmd/godns # go to the GoDNS directory +go get -v # get dependencies +go build # build ``` -And the binary can run well on routers. +You can also download a compiled binary from the [releases](https://github.com/TimothyYe/godns/releases). +## Usage -## Pre-condition - -* Register and own a domain. - -* Domain's nameserver points to [DNSPod](https://www.dnspod.cn/) or [HE.net](https://dns.he.net/) or [Cloudflare](https://www.cloudflare.com/) or [Google Domains](https://domains.google) or [AliDNS](https://dc.console.aliyun.com). - -* Or just register an account from [DuckDNS](https://www.duckdns.org/). - -## Get it - -### Build it from source code - -* Get source code from Github: - -```bash -git clone https://github.com/timothyye/godns.git -``` - -* Go into the godns directory, get related library and then build it: - -```bash -cd cmd/godns -go get -v -go build -``` - -### Download from releases - -Download compiled binaries from [releases](https://github.com/TimothyYe/godns/releases) - -## Get help +Print usage/help by running: ```bash $ ./godns -h @@ -93,74 +126,37 @@ Usage of ./godns: -h Show help ``` -## Config it +## Configuration -* Get [config_sample.json](https://github.com/timothyye/godns/blob/master/config_sample.json) from Github. -* Rename it to **config.json**. -* Configure your provider, domain/subdomain 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. +### Overview -## Config fields +* Make a copy of [config_sample.json](./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: The providers that GoDNS supports, available values are: `Cloudflare`, `Google`, `DNSPod`, `AliDNS`, `HE`, `DuckDNS`, `Dreamhost`. -* email: Email or account name of your DNS provider. -* password: Password of your account. -* login_token: API token of your account. -* domains: Domains list, with your sub domains. -* ip_url: A site helps you to get your public IPv4 IP address. -* ipv6_url: A site helps you to get your public IPv6 address. -* ip_type: To configure GoDNS under IPv4 mode or IPv6 mode, available values are: `IPv4`, `IPv6`. -* interval: The interval `seconds` that GoDNS check your public IP. -* socks5_proxy: Socks5 proxy server. -* resolver: The address of the public DNS server. For example, to run GoDNS in `IPv4` mode, you can set resolver as `8.8.8.8`, to GoDNS in `IPv6` mode, you can set resolver as `2001:4860:4860::8888`. +### Configuration properties -## IPv6 support +* `provider` — One of the [supported provider to use](#supported-dns-providers): `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](#supported-dns-providers)). 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](https://developers.google.com/speed/public-dns/docs/using), you can set `8.8.8.8` when using GoDNS in IPv4 mode or `2001:4860:4860::8888` in IPv6 mode. -Supported provider(s): -* Cloudflare -* DNSPod -* Dreamhost -* DuckDNS -* Google Domains -* HE.net -* No-IP +### Configuration examples -To enable the `IPv6` support of GoDNS, there are 2 solutions you can choose: -* Get IPv6 address online -* Get IPv6 address from your network interface - -To get IPv6 address online: -* Set the `ip_type` as `IPv6`, and make sure the `ipv6_url` is configured. -* Add one `AAAA` record to your provider. - -For example: - -```json -{ - "domains": [ - { - "domain_name": "example.com", - "sub_domains": [ - "ipv6" - ] - } - ], - "resolver": "2001:4860:4860::8888", - "ipv6_url": "https://api-ipv6.ip.sb/ip", - "ip_type": "IPv6" -} -``` - -To get IPv6 address from your interface: - -It is quite simple, just left "ip_url" & "ipv6_url" as empty. Please note that an IPv6 address configured for your interface is the prerequisite for this feature. - -### Config example for Cloudflare +#### 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. -* Using email & Global API Key +
+Using email & Global API Key ```json { @@ -181,8 +177,10 @@ For Cloudflare, you need to provide the email & Global API Key as password (or t "socks5_proxy": "" } ``` +
-* Using the API Token +
+Using the API Token ```json { @@ -202,11 +200,15 @@ For Cloudflare, you need to provide the email & Global API Key as password (or t "socks5_proxy": "" } ``` +
-### Config example for DNSPod +#### DNSPod For DNSPod, you need to provide your API Token(you can create it [here](https://www.dnspod.cn/console/user/security)), and config all the domains & subdomains. +
+Example + ```json { "provider": "DNSPod", @@ -226,11 +228,15 @@ For DNSPod, you need to provide your API Token(you can create it [here](https:// "socks5_proxy": "" } ``` +
-### Config example for Dreamhost +#### Dreamhost For Dreamhost, you need to provide your API Token(you can create it [here](https://panel.dreamhost.com/?tree=home.api)), and config all the domains & subdomains. +
+Example + ```json { "provider": "Dreamhost", @@ -251,11 +257,15 @@ For Dreamhost, you need to provide your API Token(you can create it [here](https "socks5_proxy": "" } ``` +
-### Config example for Google Domains +#### Google Domains For Google Domains, you need to provide email & password, and config all the domains & subdomains. +
+Example + ```json { "provider": "Google", @@ -275,11 +285,15 @@ For Google Domains, you need to provide email & password, and config all the dom "socks5_proxy": "" } ``` +
-### Config example for AliDNS +#### AliDNS For AliDNS, you need to provide `AccessKeyID` & `AccessKeySecret` as `email` & `password`, and config all the domains & subdomains. +
+Example + ```json { "provider": "AliDNS", @@ -300,11 +314,15 @@ For AliDNS, you need to provide `AccessKeyID` & `AccessKeySecret` as `email` & ` "socks5_proxy": "" } ``` +
-### Config example for DuckDNS +#### DuckDNS For DuckDNS, only need to provide the `token`, config 1 default domain & subdomains. +
+Example + ```json { "provider": "DuckDNS", @@ -324,13 +342,17 @@ For DuckDNS, only need to provide the `token`, config 1 default domain & subdoma "socks5_proxy": "" } ``` +
-### Config example for No-IP +#### No-IP + +
+Example ```json { "provider": "NoIP", - "email": "mail@example.com", + "email": "mail@example.com", "password": "YourPassword", "domains": [ { @@ -345,11 +367,15 @@ For DuckDNS, only need to provide the `token`, config 1 default domain & subdoma "socks5_proxy": "" } ``` +
-### Config example for HE.net +#### HE.net For HE, email is not needed, just fill DDNS key to password, and config all the domains & subdomains. +
+Example + ```json { "provider": "HE", @@ -369,36 +395,31 @@ For HE, email is not needed, just fill DDNS key to password, and config all the "socks5_proxy": "" } ``` +
-### HE.net DDNS configuration +
+Provider configuration -Add a new "A record", make sure that "Enable entry for dynamic dns" is checked: +Add a new "A record" and 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": +Fill in 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. +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. +
-### Get an IP address from the interface +### Notifications -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: +GoDNS can send a notification each time the IP changes. -```json - "ip_url": "", - "ip_interface": "eth0", -``` +#### Email -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. - -### 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. +Emails are sent over [SMTP](https://en.wikipedia.org/wiki/Simple_Mail_Transfer_Protocol). Update your configuration with the following snippet: ```json "notify": { @@ -413,13 +434,13 @@ Update config file and provide your SMTP options, a notification mail will be se } ``` -Notification mail example: +Each time the IP changes, you will receive an email like that: - + -### Telegram notification support +#### Telegram -Update config file and provide your Telegram options, a notification message will be sent to your telegram channel once the IP is changed and updated. +To receive a [Telegram](https://telegram.org/) message each time the IP changes, update your configuration with the following snippet: ```json "notify": { @@ -432,11 +453,12 @@ Update config file and provide your Telegram options, a notification message wil }, } ``` -Markdown is supported in message template, and use `%0A` for newline. -### Slack notification support +The `message_template` property supports [markdown](https://www.markdownguide.org). New lines needs to be escaped with `%0A`. -Update config file and provide your Slack options, a notification message will be sent to your slack channel once the IP is changed and updated. +#### Slack + +To receive a [Slack](https://slack.com) message each time the IP changes, update your configuration with the following snippet: ```json "notify": { @@ -449,84 +471,145 @@ Update config file and provide your Slack options, a notification message will b }, } ``` -Markdown is supported in message template, and use `\n` for newline. + +The `message_template` property supports [markdown](https://www.markdownguide.org). New lines needs to be escaped with `\n`. + +### Miscellaneous topics + +#### IPv6 support + +Most of the [providers](#supported-dns-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 + + ```json + { + "domains": [ + { + "domain_name": "example.com", + "sub_domains": [ + "ipv6" + ] + } + ], + "resolver": "2001:4860:4860::8888", + "ipv6_url": "https://api-ipv6.ip.sb/ip", + "ip_type": "IPv6" + } + ``` +
-### SOCKS5 proxy support +2. Let GoDNS find the IPv6 of the network interface of the machine it is running on (more on that [later](#network-interface-ip-address)). -You can also use SOCKS5 proxy, just fill SOCKS5 address to the ```socks5_proxy``` item: + 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: ```json -"socks5_proxy": "127.0.0.1:7070" -"use_proxy": true +... + "ip_url": "", + "ip_interface": "interface-name", +... ``` -Now all the queries will go through the specified SOCKS5 proxy. +With `interface-name` replaced by the name of the network interface, e.g. `eth0` on Linux or `Local Area Connection` on Windows. -## Run it as a daemon manually +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](https://en.wikipedia.org/wiki/SOCKS#SOCKS5) by specifying it in the configuration file this way: + +```json +... +"socks5_proxy": "127.0.0.1:7070" +"use_proxy": true +... +``` + +## Running GoDNS + +There are few ways to run GoDNS. + +### As a manual daemon ```bash nohup ./godns & ``` -## Run it as a daemon, manage it via Upstart +Note: when the program stops, it will not be restarted. -* Install `upstart` first -* Copy `./upstart/godns.conf` to `/etc/init` -* Start it as a system service: +### 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: + + ```bash + 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: + + ```bash + sudo systemctl enable godns + sudo systemctl start godns + ``` + +### As a Docker container + +With `/path/to/config.json` your local configuration file, run: ```bash -sudo start godns +docker run \ +-d --name godns --restart=always \ +-v /path/to/config.json:/usr/local/godns/config.json \ +timothyye/godns:latest ``` -## Run it as a daemon, manage it via Systemd +### As a Windows service -* Modify `./systemd/godns.service` and config it. -* Copy `./systemd/godns.service` to `/lib/systemd/system` -* Start it as a systemd service: +1. Download the latest version of [NSSM](https://nssm.cc/download) -```bash -sudo systemctl enable godns -sudo systemctl start godns -``` +2. In an administrative prompt, from the folder where NSSM was downloaded, e.g. `C:\Downloads\nssm\` **win64**, run: -## Run it with docker + ``` + nssm install YOURSERVICENAME + ``` -Now godns supports to run in docker. +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. -* Get [config_sample.json](https://github.com/timothyye/godns/blob/master/config_sample.json) from Github. -* Rename it to **config.json**. -* Run GoDNS with docker: +4. The service will now start along Windows. -```bash -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 - -After creating your config.json file: - -* Get the latest [NSSM](https://nssm.cc/download) for create a windows service. -* Open the command prompt (as administrator) in the folder where you downloaded NSSM (e.g. C:\Downloads\nssm\ **win64**) and run: - -``` -nssm install YOURSERVICENAME -``` - -You will have an interface to configure your service, it is very simple in the "Application" tab just indicate where your `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 using the "Install service" button. -* Done. Now whenever windows start your service will be loaded. -* To uninstall: +Note: you can uninstall the service by running: ``` nssm remove YOURSERVICENAME ``` ## Special Thanks + -Thanks JetBrains for sponsoring this project with [free open source license](https://www.jetbrains.com/community/opensource/). +Thanks JetBrains for sponsoring this project with [free open source license](https://www.jetbrains.com/community/opensource/). > I like GoLand, it is an amazing and productive tool.