From 4bb918bb6e62ef7d4001c4b507e6f9c43af9158e Mon Sep 17 00:00:00 2001 From: lurchi Date: Mon, 5 Nov 2018 12:20:35 +0100 Subject: [PATCH] add documentation --- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++ homeserverdns.cfg | 2 +- 2 files changed, 66 insertions(+), 1 deletion(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..fa76e58 --- /dev/null +++ b/README.md @@ -0,0 +1,65 @@ +# homeserverdns: Dynamic DNS updater for home servers +homeserverdns monitors the IPv6 addresses (using the ip tool from [iproute2](https://wiki.linuxfoundation.org/networking/iproute2)). When it detects a change, it updates the A and AAAA records for a set of domains (and subdomains). + +So far it has modules for these domain provider APIs: + +- [gandi.net LiveDNS API](https://doc.livedns.gandi.net/) +- [http.net DNS API](https://www.http.net/docs/api/) (untested) +- [dyn.com API](https://help.dyn.com/remote-access-api/perform-update/) (untested) + +# Dependencies +- curl +- miniupnpc (optional, see the Configuration section) + +# Installation +TBD + +# Configuration +The configuration options are described in `homeserverdns.cfg`. First a protocol has to be defined, e.g. + +`` +protocol=gandi +`` + +For authentication at the domain provider, an authentication token has to be geven. Some protocols require a user name and an API address, too. + +`` +auth_key=g5Hdsfkj5J49li8HH3jfhsJp +user= # not required for gandi +api_address= # not required for gandi +`` + +Now the domains (and subdomains) we want to update A and AAAA records for have to be defined. + +`` +domains=mydomain.com sub.mydomain.com +`` + +By default `UPNP` is used for detecting the server's public IPv4 address. So we should check if upnp works and returns the correct IPv4 address. + +`` +$ upnpc -s +upnpc : miniupnpc library test client, version 1.9. + (c) 2005-2016 Thomas Bernard. +Go to http://miniupnp.free.fr/ or http://miniupnp.tuxfamily.org/ +for more information. +List of UPNP devices found on the network : + desc: http://10.0.0.1:5000/rootDesc.xml + st: urn:schemas-upnp-org:device:InternetGatewayDevice:1 + +Found valid IGD : http://10.0.0.1:5000/ctl/IPConn +Local LAN ip address : 10.0.0.23 +Connection Type : IP_Routed +Status : Connected, uptime=530079s, LastConnectionError : ERROR_NONE + Time started : Tue Oct 30 08:57:09 2018 +MaxBitRateDown : 10000000 bps (10.0 Mbps) MaxBitRateUp 1000000 bps (1.0 Mbps) +ExternalIPAddress = 85.98.82.44 +Bytes: Sent: 402633281 Recv: 816703147 +Packets: Sent: 3408416 Recv: 4216845 +`` + +If we don't get a value for `ExternalIPAddress`, we should check our router and firewall settings. If `UPNP` does not work for us (e.g. in case the server is behind a Carrier Grade NAT), we can define our own method for looking up our public IPv4 address using the `public_ip4_hook` config option, e.g. + +`` +public_ip4_hook=curl -s -4 https://ipecho.net/plain +`` diff --git a/homeserverdns.cfg b/homeserverdns.cfg index 3128b81..34ce7b4 100644 --- a/homeserverdns.cfg +++ b/homeserverdns.cfg @@ -1,5 +1,5 @@ # Protocol name, may be left empty when using a custom update_hook. -# The default update_hook supports: gandi, dyndns +# The default update_hook supports: gandi, httpnet, dyndns protocol= # The command to be called to determine our public IP address. By default UPNP