Skip to content

Latest commit

 

History

History
222 lines (175 loc) · 5.87 KB

README.md

File metadata and controls

222 lines (175 loc) · 5.87 KB
Raw

ddns-updater

Library for updating dynamic DNS.

NPM

The library supports the following Dynamic DNS services:

For external IP resolving it uses service:

Introduction blog post with details on how the package can be used in QNAP NAS.

Usage

var UpdaterClient = require("ddns-updater");
var config = require('./config.json');
var updater = new UpdaterClient(config);
updater.start();

where config.json:

{
    "domains" : [{
        "service"   : "namecheap",
        "name"      : "chebyrashka.guru",
        "hosts"     : ["@"],
        "settings"  : {
            "password": "1a111v11111111a1aaa11a11111111a1"
        }
    }],
    "interval"      : { "hours": 1 },
    "updateAlways"  : false
}

It makes sense to run the package via pm2 or the similar.

More advanced usage

var UpdaterClient = require("ddns-updater");
var config = { /* skipped*/ };
var updater = new UpdaterClient(config);

updater.on('ip:resolve:success', function (service, ip) {
    console.log('External IP resolved via ' + service + ' : ' + ip);
});

updater.on('ip:resolve:error', function (service, err) {
    .log('Failed to resolve external IP: ');
    console.log(err);
});

updater.on('ip:change', function (newIP, oldIP) {
    console.log("IP changed from " + oldIP + " to " + newIP);
});

updater.on('update:success', function (domain) {
    console.log("updated: " + JSON.stringify(domain));
});

updater.on('update:error', function (err, domain) {
    console.log('Failed to update IP via ' + domain.service + ':');
    console.log(err);
});

updater.start();

API

Config

domains

Type: Array
An array of objects describing a domain.
Every object in the array:

  • service - name of Dynamic DNS service. e.g. "namecheap". Every supported service should have a corresponding module in 'updaters' folder (module file name w/o extension equals to service name, e.g. namecheap.js for "namecheap" service).
  • name - name of domain, e.g. "example.com"
  • hosts - array of host to map to the domain, if you only want naked domain ("example.com") specify "@" or omit field completely.
  • settings - an object specific for the service, usually containing auth info.
  • enable - setting to false allow to ignore domain updating (useful to temporary disable)

Example:

    "domains" : [{
        "service"  : "namecheap",
        "name"     : "chebyrashka.guru",
        "hosts"    : ["@", "www"],
        "settings" : {
            "password": "1a111v11111111a1aaa11a11111111a1"
        },
        "enable"   :  false
    }, {
        "service"  : "noip",
        "name"     : "my-awesome-cloud.ddns.net",
        "settings" : {
            "username": "[email protected]",
            "password": "my no-ip password"
        }
    }],

interval

Type: Object
How often to check external IP (and update if it's changed).
Value: An object in terms of interval.
Default: 1 hour
Example:

"internal": {"days": 1}

updateAlways

Type: Boolean
Default: false
true to update IP every time (once in interval), otherwise update only if IP changed.

resolver

Type: String
Default: "ipify"
Name of public IP resolve service. Currently supported:

updaters

Type: Object
An object with mapping of service name to updater class.

See Updaters below.

Events

"ip:resolve:success"

External IP was resolved. Arguments:

  • service (String) - service name used for resolving
  • ip (String) - IP address

"ip:resolve:error"

An error occurred during IP resolving.
Arguments:

  • service (String) - service name used for resolving
  • err (Object) - error

"ip:change"

External IP change was detected.
Arguments:

  • newIP (String) - new IP
  • oldIP (String) - old IP

"update:success"

IP update successully completed.
Arguments:

  • domain (Object):
  • service (String)
  • name (String)
  • host (String)

"update:error"

An error occured during updating IP.
Arguments:

  • err (Object)
  • domain (Object):
  • service (String)
  • name (String)
  • host (String)

Updaters

Every service from config (domains[].service) is an Updater module. The tool expects every updater to implement the following API:

  • module exports a class (will be created via new)
  • updater class should implement update method:
/**
 * @param {String} domain
 * @param {String} host
 * @param {String} ip
 * @param {Object} settings
 * @return {Promise}
 */
function update (domain, host, ip, settings)

By default tool loads updaters from updaters folder. By you can specify them explicitly with updaters option:

var UpdaterClient = require("ddns-updater");
var SomeUpdater = require("ddns-updater-someservice");
var config = require('./config.json');
config.updaters = {"some": SomeUpdater};
var updater = new UpdaterClient(config);

Resolvers

Resolver is a module loaded from resolvers folder. Module should implement the following API:

  • module exports a class (will be created via new)
  • resolver class implements resolve method returning a Promise resolved to IP value

Name of resolver to use is specified in resolver config option.

Acknowledgments

The package was inspired by:

License

MIT