EZ DDNS Client Files

Project: EZ DDNS Client
Description: A Dynamic DNS updater client.

Author: John Walsh
Maintainer: John Walsh

Copyright (C) 2003, John Walsh, all rights reserved.
Created: Oct 17 2003

https://sourceforge.net/projects/ez-ddns-client/

----

This is 'EZ DDNS Client'.

It is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

It is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

There should be a copy of the GNU General Public License
in the file 'COPYING'.  If not, see <http://www.gnu.org/licenses/>.


----------------------------------------------------------------------

Change Log / Development History
================================

Version: 1.0.1 - 17/07/2020

Updated this README file, better background about usage and installing.

----

Version: 1.0.0 - 01/06/2020

First release.

Works with:

www.dnsexit.com


----------------------------------------------------------------------

Description
===========

Designed for Linux machines/servers, using 'dhclient' (NOT NetworkManager).

EZ DDNS is a set of 'ddns client' support scripts for running an internet
server using a dynamic IP (via DHCP).
eg. from a home ISP network.


It is designed to be used with the DDNS service from:

http://www.dnsexit.com/

but could be adapted for any DDNS service that uses a URL to
perform DDNS updates.


Note:

I wrote these scripts in 2001 to 2003 and used them until 2010.
I didn't get around to publishing them until 2020.

So, at the time of publishing, they have not been tested, recently.

I don't think dhcp and dhclient for Linux has changed in any way
that would effect these scripts, so they should still work, but
the install is different now.

If you have any problems, feel free to report any problems.


---------------------------------------------------------------------

Why I wrote these scripts
=========================

The other DDNS clients I looked at all seamed to work the same way.
They ran some deamon that checked the machines IP every 10 minutes
or so, and if they saw that it had changed, then they did the DDNS
update.

I just thought that there must be a better way to detect a change
of IP, one that was event driven, and so be able to do the DDNS
update in a more responsive way, rather than posibly having a few
minutes delay...

I looked into the DHCP client (dhclient) and found that it could
be configured to call a script on any action that it took.

So I used that to 'hook' these ddns scripts into dhclient, so that
the DDNS update is triggered as soon as a changed of IP happens.

DDNS hooks into the DHCP client and gets notified when the IP
changes.

The advantages are:

* you don't need a have some background script running/waiting,
so no extra 'startup' required, or problems if it gets killed.

* it gets to know of any IP change as soon as it happens.


---------------------------------------------------------------------

How it works
============

Background:

https://linux.die.net/man/8/dhclient
https://linux.die.net/man/5/dhclient.conf
https://linux.die.net/man/8/dhclient-script
https://linux.die.net/man/5/dhcp-options


The basic idea is simple. When dhclient runs (ie. any time the IP
address needs checking), we want our ddns-script.bash to be called,
with all the parameters that dhclient sets up, so it knows whats
going on and can act accordingly.

While doing the update, EZ DDNS produces some log/email files... All
these are named with a prefix of 'tmp-', but can be changed in the
conf file too.

If an update fails, it will keep repeating the update attempt (after
a delay) until successful.


Howto Install
=============

When I first installed these scripts, I don't remember the dhclient
actually using it's supporting script, so I could just get it to use
the ddns-* scripts without overwriting any of it's normal opperations.

There was not even a config file: /etc/dhclient.conf

If you look at the 'dhclient.conf' in this project (provided as a
reference, NOT to be used), all it does is set the support script,
and installing ddns simply put that config file in /etc/.


Update in 2020:

Running on a Debian machine, the dhclient 'area' has move to:
/etc/dhcp/

Now as I look at the dhclient config, the config file does exist
and does a couple of things, so I would not want to replace it.

It does contain the definition for the supporting script, but might
be commented out, thus:

#script "/sbin/dhclient-script";

That seams to be the default script, and will be called/used if it
has not been redefined by the config file - so don't change the
config file.


As I read the man pages, and the script file '/sbin/dhclient-script',
it will call any user scripts, if they exist.

To check your distros config, look for the function 'run_hookdir'
in the script: /sbin/dhclient-script


It will try:

FIRST - on entry:

The script:
/etc/dhcp/dhclient-enter-hooks

Then the dir:
/etc/dhcp/dhclient-enter-hooks.d/


LAST - on exit:

The script:
/etc/dhcp/dhclient-exit-hooks

Then the dir:
/etc/dhcp/dhclient-exit-hooks.d/


I would suggest putting the ddns-script.bash script into the dir:
/etc/dhcp/dhclient-exit-hooks.d/

Then it should get called after all the system DNS stuff is completed.

The 'install.sh' script will do that for you, and create the ddns
dir in /etc/.


----------------------------------------------------------------------

Configuration
=============

file: ddns-conf.bash

Parameters that begin with 'ddns_' are required script parameters.
others are user defined.


The sections:

######################################################################
# system config
######################################################################

Generally leave alone, but one that you might like to change is :-

* ddns_testing

set to 0 or 1
1 = testing,
Will echo the update, rather than doing the curl,
and you can also check the log files after running.
eg. ddns-force.bash


* ddns_log_level

0 = none
1 = basic - updates only
2 = full - all actions and decisions
3 = verbose/debug - currently no extra

see: fn_ddns_log


######################################################################
# system functions
######################################################################

fn_ddns_log ()

Is used to do the system log update.
If your disto uses a different 'logger', you may update this fn.


######################################################################
# user config
######################################################################

* ddns_if_regexp

Is used to check your interface name(s) - they must match this regex,
else an update will be ignored.

eg. if you have multiple interfaces,
and you only want to do the update for the external/public interface.


* ddns_email_*

If you only have remote access to your server,
suggest to use an email address that is not on your server.


* ddns_update_*

The URL you use to do the DDNS update to your ddns system/server.

For the case of 'dnsexit' :-

ddns_update_url="http://update.dnsexit.com/RemoteUpdate.sv"
ddns_update_user="USERNAME"
ddns_update_password="PASSWORD"

Note: also see the doc file from dnsexit: ipUpdateDev.doc


* ddns_hosts_list

SPACE seperated list of FQDM's to update.
Each group will trigger a seperate call to the DDNS update function.

For the case of 'dnsexit', multiple FQDM's within a group are seperated
by ';'.


######################################################################
# user functions
######################################################################

The DDNS update function :-

ddns_create_update_url ()

Is called with 2 parameters:

$1 = a group from 'ddns_hosts_list'
$2 = the new IP

It has to return (create) 1 parameter:

ddns_update_url = the URL that will be used to perform the update.


----------------------------------------------------------------------

dnsexit
=======

Useful links:

http://www.dnsexit.com/Direct.sv?cmd=dynDns

http://www.dnsexit.com/Direct.sv?cmd=ipClients

https://www.dnsexit.com/ipupdate/dyndata.txt


Return code from a DDNS update:

Any code >= 2 means errors.

0=Success
1=IP is the same as the IP on the system

2=Invalid password
3=User not found
4=Update too often. Please wait at least 8 minutes since the last update
10=Hostname is not specified

Any code greater than 10, System error on dnsExit.com

11=system error and the error message depends on the generated error
13=parameter validation error


----------------------------------------------------------------------

Suggested way to Setup DNS and MX Records
=========================================

Only one name/IP pair needs to be setup, usually this is the domain
name without any prefix (an A record).

eg. domain.ext

Then, all the other domain names with prefixs are defined to be an
alias (a CNAME record) for the base domain, eg:

MX Records (MX)

mail server:    mail.doamin.ext
Priority #:     10
TTL(seconds):   28800 (8 hours)


Host Records (A)

doamin.ext, IP.IP.IP.IP, 120  === dynamic IP


Alias Records (CNAME)

MACHINE.doamin.ext => my_domain_name.ext, 120
mail.doamin.ext => my_domain_name.ext, 120
www.doamin.ext => my_domain_name.ext, 120
ftp.doamin.ext => my_domain_name.ext, 120

----

If you wish to split the web and email services across two different
machines, simply set a different IP for the mail server, eg:

MX Records (MX)

mail server:    mail.doamin.ext
Priority #:     10
TTL(seconds):   28800 (8 hours)


Host Records (A)

doamin.ext, IP.IP.IP.IP, 120  === dynamic IP
mail.doamin.ext, IP2.IP2.IP2.IP2, 120  === dynamic IP


Alias Records (CNAME)

MACHINE.doamin.ext => my_domain_name.ext, 120
www.doamin.ext => my_domain_name.ext, 120
ftp.doamin.ext => my_domain_name.ext, 120

----

If an IP is static, the TTL should be set to 28800 (8 hours) instead
of 2 minutes.

NB. the mail server (MX record) should always be set to the longer
time, indeed, there is a minimum, and if it is set too short, email
servers may reject email, thinking it is SPAM.


----------------------------------------------------------------------

Howto Setup and Use
===================

1) setup your DNS with your ISP/host

I like to have 2 'A' records for each of my domains:

DOMAIN.EXT
mail.DOMAIN.EXT

And then for each 'machine' in the domain, an alias (CNAME) record
that points to the 'A' record DOMAIN.EXT

NB. mail.DOMAIN.EXT could be an alias too, but I keep it seperate
just in case I need to move where/how I handle email.

eg. I have www. and MACHINE. (my server name) aliases.


Set the DNS to be 'dynamic' with a 'TTL' for the 'A' records to
something short. I use 10 minutes, but it could be 1 minute.

That is important - it's no good doing an immediate DDNS update,
if all the other DNS servers/caches are told to only update the
DNS once every 8 hours.


For dnsexit.com :-

You can (should) have a different 'update' username and password
to your web account.

NB. it's been a while, so I can't remember: when you create your
account, you give your email and set a password for your account,
and also get to set a 'user ID' that will be used for remote/URL
updates.

To set the password for the remote/URL updates:

login, go into your 'Account Profile'

set the 'IP Update Password'


NB. the 'ddns_update_user' and 'ddns_update_password' values in the
DDNS config script, come from your dnsexit.com
'Account User ID' and 'IP Update Password' values.



2) install DDNS

You need to edit: ddns-conf.bash

Set all the 'user' values for your needs.

run: install.sh

Check the hook into the DHCP Client.



3) testing

You should be good to go, but you can/should give it a test.

Use 'ddns-force.bash' to set an IP.

NB. don't use it too much, dnsexit.com don't like you forcing too
many updates in a short period of time.

You can set a 'different' IP, to check that it does get applied.

Login to your account to view the DNS settings...

See how long it takes for other DNS servers to update by using 'host'
or 'dig'.

When your happy, 'ddns-force.bash' your correct IP.


----------------------------------------------------------------------

Technical Documentation
=======================

* ddns-update.bash

Is the actual IP updating script. Not really for direct 'user' calling.

It takes 1 parameter, the new IP address:

ddns-update.bash IP.IP.IP.IP


It will create the file: ${ddns_new_ip_file}

It does all the URL updating...

It will send an email about the update: ${ddns_email_to}
It will send an email about the update status: failed/successful
It will log the curl results for each update: ${ddns_update_logfile}
It will system log each overall update success/fail.

It will keep trying to update until successful.

When finished, it moves the new IP file the old IP file:
${ddns_old_ip_file}

SO: you know when the update script is running, because the file
${ddns_new_ip_file} exists.

--

* ddns-script.bash

This is the DHCP 'hook' script, that should be called by dhclient.

NO NEED for it to call the original/default DHCP update script.

It checks if an IP update is required, and if it is, calls:
ddns-update.bash

--

* ddns-force.bash

You can use this to force an IP update, run it as:

ddns-force.bash IP.IP.IP.IP

--

* ddns-conf.bash

Defines all parameters, system and user,
and functions too, like loging and forming the URL update strings.

You should be able to make EZ DDNS work with other DDNS services
by changing only this file, as long as their API is via a web URL.

--

* ddns-email-body.txt

The text of the email DDNS will send on an IP change.

--

* logging

Any system log messages can be seen by:

journalctl -t ddns


----------------------------------------------------------------------

To Do
=====

* add a max retry timeout ?


----------------------------------------------------------------------