dyndns.pl - Update IP address to dynamic DNS (DDNS) provider
dyndns.pl --login LOGIN --password PASSWORD \
--Host yourhost.dyndns.org
Note: By Default this program expects www.dyndns.org provider. If you use other provider, see option --Provider
List of configuration files to read. No command line options other than --verbose, --debug or --test should be appended or results are undefined. Each file must contain complete DDNS account configuration.
The FILE part wll go through Perl's glob() function, meaning that
the filenames are expanded if standard shell wild card is supplied.
Series of configuration files can be run at once e.g. within directory
/etc/dyndns/ by using a single option. The order of the files processed
is alphabetical:
--Config=/etc/dyndns/*
See section CONFIGURATION FILE for more information how to write the files.
Use registered HOST(s).
This option is only for --Provider noip
Assign IP to GROUP. Do you have many hosts that all update to the same IP address? Update a group instead of a many hosts.
DDNS account's LOGIN name.
This option is only for --Provider dyndns
Update account information with MX hostname. Specifies a Mail eXchanger for use with the host being modified. Must resolve to an static IP address, or it will be ignored. If you don't know DNS, don't touch this option.
The servers you list need to be correctly configured to accept mail for your hostname, or this will do no good. Setting up a server as an MX without permission of the administrator may get them angry at you. If someone is contacted about such an infraction, your MX record will be removed and possibly further action taken to prevent it from happening again. Any mail sent to a misconfigured server listed as an MX may bounce, and may be lost.
This option is only for --Provider dyndns
Turn on MX option. Request that the MX in the previous parameter be set up as a backup. This means that mail will first attempt to deliver to your host directly, and will be delivered to the MX listed as a backup.
Note regarding provider noip:
Update clients cannot change this value. Clients can only submit requests to the php script to update the A record. Changes such as MX records must be done through website.
If given, set the host to offline mode.
Note: [dyndns] This feature is only available to donators. The
"!donator" return message will appear if this is set on a non-donator
host.
This is useful if you will be going offline for an extended period of time. If someone else gets your old IP your users will not go to your old IP address.
DDNS account's PASSWORD.
This option is only for --Provider dyndns
The system you wish to use for this update. dyndns will update a dynamic
host, custom will update a MyDynDNS Custom DNS host and statdns will
update a static host. The default value is dyndns and you cannot use
other options (statdns|custom) unless you donate and gain access to the
more advanced features.
Turn on wildcard option. The wildcard aliases *.yourhost.ourdomain.ext
to the same address as yourhost.ourdomain.ext
Enter daemon mode. The term "daemon" refers to a standalone processes
which keep serving until killed. In daemon mode program enters
into infinite loop where IP address changes are checked periodically.
For each new ip address check, program waits for WAIT-MINUTES.
Messages in this mode are reported using syslog(3).
This option is designed to be used in systems that do not provide Unix-like
cron capabilities (e.g under Windows OS). It is better to use cron(8) and
define an entry using crontab(5) notation to run the update in periodic
intervals. This will use less memory when Perl is not permanently kept in
memory like it would with option --Daemon.
The update to DDNS provider happens only if
1) IP address changes
2) or it has taken 30 days since last update.
(See DDNS providers' account expiration time documentation)
The minumum sleep time is 5 minutes. Program will not allow faster wake up times(*). The value can be expressed in formats:
15 Plain number, minutes
15m (m)inutes. Same sa above
1h (h)ours
1d (d)days
This options is primarily for cable and DSL users. If you have a
dial-up connection, it is better to arrange the IP update at the same
time as when the connection is started. In Linux this would happen
during ifup(1).
(*) Perl language is CPU intensive so any faster check would put considerable strain on system resources. Normally a value of 30 or 60 minutes will work fine in most of the ADSL lines. Monitor the ISP's IP rotation time to adjust the time in to use sufficiently long wake up times.
In Linux system, the automatic IP detection uses program
ifconfig(1). If you have multiple network cards, select the correct
card with this option. The default device queried is eth0.
Prefix where to save IP information. This can be a) a absolute path name to a file b) directory where to save or c) directory + prefix where to save. Make sure that files in this location do not get deleted. If they are deleted and you happen to update SAME ip twice within a short period - according to www.dyndns.org FAQ - your address may be blocked.
On Windows platform all filenames must use forward slashs like C:/somedir/to/, not C:\somedir\to.
The PREFIX is only used as a basename for supported DDNS accounts (see --Provider). The saved filename is constructed like this:
PREFIX<ethernet-card>-<update-system>-<host>-<provider>.log
|
See option --system
A sample filename in Linux could be something like this if PREFIX were set
to /var/log/dyndns/:
/var/log/dyndns/eth0-statdns-my.dyndns.org-dyndns.log
Use reasonable default for saved IP file PREFIX (see --file). Under Windows, %WINDIR% is used. Under Linux the PREFIXes searched are
/var/log/dyndns/ (if directory exists)
/var/log/ (system's standard)
$HOME/tmp or $HOME if process is not running under root
Use HOST as outgoing HTTP proxy.
By default, program connects to dyndns.org to update the dynamic IP
address. There are many free dynamic DNS providers are reported.
Supported list of TYPES in alphabetical order:
hnorg No domain name limists
Basic DDNS service is free (as of 2003-10-02)
http://hn.org/
dyndns No domain name limits.
Basic DDNS service is free (as of 2003-10-02)
http://www.dyndns.org/
See also http://members.dyndns.org/
noip No domain name limits.
Basic DDNS service is free (as of 2003-10-02)
http://www.no-ip.com/
Query current IP address and quit. Note: if you use router, you may need --urlping* option, otherwise the IP address returned is your subnet's DHCP IP and not the ISP's Internet IP.
Output of the command is at least two string. The second string is
last-ip-info-not-available if the saved ip file name is not specified.
In order to program to know where to look for saved IP files you need to
give some --file* or --Config option. The second string can also be
nochange if current IP address is same as what was found from saved
file. Examples:
100.197.1.6 last-ip-info-not-available
100.197.1.6 100.197.1.7
100.197.1.6 nochange 18
|
How many days since last saved IP
Note for tool developers: additional information may be provided in future. Don't rely on the count of the output words, but instead parse output from left to right.
Print message if IP has changed or not. This option can take
an optional string argument exitcode which causes program to
indicate changed ip address with standard shell status code
(in bash shell that would available at variable $?):
$ dyndns.pl --Query-ipchange exitcode --file-default \
--Provider dyndns --Host xxx.dyndns.org
$ echo $?
... the status code of shell ($?) would be:
0 true value, changed
1 false value, error code, i.e. not changed
Without the exitcode argument, the returned strings are:
Current IP address
|
changed 35 111.222.333.444
nochange 18
|
Days since last IP update. Based on saved IP file's
time stamp.
If the last saved IP file's time stamp is too old, then even if the IP were
not really changed, the situation is reported with word changed. This is
due to time limits the DDNS providers have. The account would expire unless
it is updated in NN days.
Note for tool developers: additional information may be provided in future. Don't rely on the count of the output words, but instead parse output from left to right.
Print the name of the IP file and quit.
Note: In order for this option to work, you must supply all other options would be normally pass to update the DDNS account, because the Ip filename depends on these options. Alternatively provide option --Config FILE from where all relevant information if read.
--ethernet [optional, defaults to eth0]
--Provider [optional, defaults to dyndns]
--system [optional, defaults to dyndns]
--Host required.
Here is an example which supposed that directory /var/log/dyndns/
already exists:
$ dyndns.pl --file-default --Query-ipfile \
--Provider dyndns --Host xxx.dyndns.org
/var/log/dyndns/eth0-dyndns-dyndns-xxx-dyndns.org.log
In host, which has multiple netword cards, the response can include
multiple IP addresses. The default is to pick always the first choice, but
that may not be what is wanted. The regexp MUST not contain capturing
parentheses: if you need one, use non-capturing choice (?:). Refer to Perl
manual page perlre for more information about non-cpaturing regular
expression parentheses.
Here is an example from Windows:
Ethernet adapter {3C317757-AEE8-4DA7-9B68-C67B4D344103}:
Connection-specific DNS Suffix . :
Autoconfiguration IP Address. . . : 169.254.241.150
Subnet Mask . . . . . . . . . . . : 255.255.0.0
Default Gateway . . . . . . . . . :
Ethernet adapter Local Area Connection 3:
Connection-specific DNS Suffix . : somewhere.net
IP Address. . . . . . . . . . . . : 193.10.221.45
Subnet Mask . . . . . . . . . . . : 255.255.0.0
Default Gateway . . . . . . . . . : 10.10.0.101
The 193.10.221.45 is the intended dynamic IP address, not the first one. To instruct searching from somewhere else in the listing, supply a regular expressions that can match a portion in the listing after which the IP address appears. In the above case, the regexp could be:
--regexp "Connection 3:"
In Windows, the words that follow "IP Address" are automatically expected, so you should not add them to the regexp.
In FreeBSD 4.5, you may get following response:
tun0: flags <UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1492
inet6 fe80::250:4ff:feef:7998%tun0 prefixlen 64 scopeid 0x7
inet 62.214.33.49 --> 255.255.255.255 netmask 0xffffffff
inet 62.214.32.12 --> 255.255.255.255 netmask 0xffffffff
inet 62.214.35.49 --> 255.255.255.255 netmask 0xffffffff
inet 62.214.33.163 --> 62.214.32.1 netmask 0xff000000
Opened by PID 64
The correct IP address to pick from the listing is the one, which does not contain netmask 0xffffffff. The picked address for above is therefore 62.214.33.163. The regexp that finds that line is:
--regexp ".*0xffffffff.*?inet"
| |
| Search minimum match until word "inet"
search maximum match
This will match all the way until the the last line with netmask
0xffffffff, after which shortest match .*? to inet is reached to read
the number following it. The regexp must make sure that the next word
after its match point is the wanted address.
If you do not have direct access to world known real IP address, but to
a subnet IP address, then you cannot determine your outside world IP
address from your machine directly. See picture below:
router/subnet Internet
+-------------+ +-----------+
Your PC: | | maps address | |
connect to ISP --> | ROUTER | -------------> | |
| 192.168.... | | 80.1.1.1 |
local ip says: +-------------+ +-----------+
192.168.xxx.xxx THE REAL IP
ASDL and cable modem and other connections may not be directly connected to Internet, but to a router to allow subnnetting internal hosts. This makes several computers to access the Internet while the ISP has offered only one visible IP address to you. The router makes the mapping of the local subnet IP to the world known IP address, provided by the ISP when the connection was established.
You need some way to find out what is the real IP is. The simplest way is to connect to a some web page, which runs a reverse lookup service which can show the connecting IP address.
Note: the following web web page does not exists. To find a service
that is able to display your IP address, do a google search. Let's
say, that you found a fictional service
http://www.example.com/showip and somewhere in the web page it
reads:
Your IP address is: 212.111.11.10
This is what you need. To automate the lookup from web page, you need
to instruct the program to connect to URL page and tell how to read
the ip from page by using a regular expression. Consult Perl's manual
page perlre if you are unfamiliar with the regular expressions. For
the above fictional service, the options needed would be:
--urlping "http://showip.org/?showit.pl";
--urlping-regexp "address is:\s+([\d.]+)"
| ||
| |+- Read all digits and periods
| |
| +- capturing parentheses
|
+- expect any number of whitespaces
NOTE: The text to match from web page is not text/plain, but text/html, so you must look at the HTML page's sources to match the IP address correctly without the bold <b> tags etc.
Web page where world known IP address can be read. If you find a Web server that is running some program, which can show your IP addres, use it. The example below connects to site and calls CGI program to make show the connector's IP address. Be polite. Making calls like this too often may cause putting blocks to your site.
http://www.dyndns.org/cgi-bin/check_ip.cgi
Be sure to use period of 60 minutes or more with --Daemon option to not increase the load in the "ping" site and cause admin's to shut down the service.
Contact to www.dyndns.org service to obtain IP address information. This is shorthand to more general optiopn --urlping.
Specialized router option for Linksys products.
This option connects to Linksys Wireless LAN 4-point router, whose page is by default at local network address -<http://192.168.1.1/Status.htm>. The world known IP address (which is provided by ISP) is parsed from that page. The product is typically connected to the cable or DSL modem. Refer to routing picture presented previously.
If the default login and password has been changed, options --urlping-login and --urlping-password must be supplied
For TYPE information, See <http://www.linksys.com/>. Products codes currently supported include:
- BEFW11S4, Wireless Access Point Router with 4-Port Switch. Page: http://192.168.1.1/Status.htm - WRT54GL, Wireless WRT54GL Wireless-G Broadband Router. Page: http://192.168.1.1/Status_Router.asp
If --urlping web page requires authentication, supply user name for
a secured web page.
If --urlping web page requires authentication, supply password for
a secured web page.
After connecting to page with --urlping URL, the web page is examined for REGEXP. The regexp must catch the IP to perl match $1. Use non-capturing parenthesis to control the match as needed. For example this is incorrect:
--urlping-regexp "(Address|addr:)\s+([0-9.]+)"
| |
$1 $2
The match MUST be in "$1", so you must use non-capturing perl paentheses for the first one:
--urlping-regexp "(?:Address|addr:) +([0-9.]+)"
| |
non-capturing $1
If this option is not given, the default value is to find first word that matches:
([0-9]+\.[0-9]+\.[0-9]+\.[0-9]+)
Turn on debug with optional positive LEVEL. Use this if you want to know details how the program initiates connection or if you experience trouble contacting DDNS provider.
Print help
Print help in HTML format.
Print help page in Unix manual page format. You want to feed this output to nroff -man in order to read it.
Run in test mode, do not actually update anything. LEVEL 1 allows sending HTTP ping options and getting answers.
This is for developer only. Run internal integrity tests.
This is for developer only. Uses DYNDNS test account options. All command line values that set host information or provider are ignored. Refer to client page at http://clients.dyndns.org/devel/
Print informational messages.
Print version and contact information.
Perl client for updating a dynamic DNS IP information at supported
providers (see --Provider). Visit the page of the provider and create an
account. Write down the login name, password and host name you registered.
Program has been designed to work under any version of Windows or Linux, possibly Mac OS included. It may not work under other Unix variants due to different commands and outputs to get network IP assignment information. Please see BUGS section how to provide details to add support to other operating systems.
The dynamic DNS service allows mapping a dynamic IP address to a static hostname. This way the computer can be refereed by name instead of ever changing IP address from ISP's pool. The DDNS providers have may have basic services, like single account and single host name, which may still be free of charge. Please check the current status form the pages of the providers.
Separate files are used for remembering the last IP address to prevent updating the same IP address again. This is necessary in order to comply guidelines of the providers where multiple updates of the same IP address could cause your domain to be blocked. You should not normally need to touch the files where the ip addresses are stored.
If you know what you are doing and desperately need a forced update, delete the IP files and start program with apropriate arguments. Without the information about previous IP address, program sends a new update request to the provider.
For windows operating systems, you need to install Perl. There are two
Perl incarnatons: Native Windows version (Activestate Perl) and Cygwin
version. It is recommended that you install Cygwin suite, which
includes Perl from http://www.cygwin.com/. The Cygwin is a Unix
layer running on top of windws and makes it possible to use cron jobs
etc. just like in Linux systems. If you have no prior experience on
Unix/Linux, then the Activestate Perl might be better for Windows.
Activestate includes a Windows installer, but the Perl programs must
be run through Perl interpreter. For Activestate, put programs along
PATH and use command line call with option -S to instruct to search
PATH:
perl -S dyndns.pl [options]
To check current IP address:
dyndns.pl --Query [--urlping...]
|
Select correct option to do the "ping" for IP
Show where the ip file is/would be stored with given connect options. The option --file-default uses OS's default directory structure.
dyndns.pl --file-default --Query-ipfile --Provider dyndns \
--Host xxx.dyndns.org
To upate account information to DDNS provider:
dyndns.pl --login <login> --password <pass> --Host your.dyndns.org
If you have a cable or DSL and your router can display a web page
containing the world known IP address, you can instruct to "ping"
it. Suppose that router occupies address 192.168.1.1 and page that
displays the world known IP is status.html, and you have to log in
the router using username foo and password bar:
dyndns.pl --urlping http://192.168.1.1/Status.html \
--urlping-login foo \
--urlping-pass bar \
If the default regexp does not find IP address from the page, supply your own match with option --urlping-regexp. In case of doubt, add option --debug 1 and examine the responses. In serious doubt, contact the maintainer (see option --Version) and send the full debug output.
Tip: if you run a local web server, provider www.dyndns.org can direct
calls to it. See option --Wildcard to enable `*.your.dyndns.org' domain
delegation, like if it we accessed using `www.your.dyndns.org'.
Instead of supplying options at command line, the options can be stored to configuration files. For each DDNS account and different domains, a separate configuration file must be created. The configuration files are read with option --Config.
The syntax of the configuration file includes comments that start with (#). Anything after hash-sign is interpreted as comment. Values are set in KEY = VALUE fashion, where spaces are non-significant. Keys are not case sensitive, but values are.
Below, lines marked with [default] need only be set if the default value
needs to be changed. Lines marked with [noip] or [dyndns] apply to only
those providers' DDNS accounts. Notice that some keys, like host, can
take multple values seprated by colons. On/Off options take values [1/0]
respectively. All host name values below are fictional.
# /etc/dyndns/dyndns.conf
# Set to "yes" to make this configuration file excluded
# from updates.
disable = no # [default]
ethernet = eth0 # [default]
group = mygourp # [noip]
host = host1.dyndns.org, host1.dyndns.org
# If you route mail. See dyndns.org documentation for details
# how to set up MX records. If you know nothing about DNS/BIND
# Don't even consider using this option. Misuse or broken
# DNS at your end will probably terminate your 'free' dyndns contract.
mxhost = mxhost.dyndns.org
# Details how to get the world known IP address, in case the standard
# Linux 'ifconfig' or Windows 'ipconfig' programs cannot be used. This
# interests mainly Cable, DSL and router owners. NOTE: You may
# not use all these options. E.g. [urlping-linksys4] is alternate
# to [urlping] etc. See documentation.
urlping-linksys = BEFW11S4
urlping-login = joe
urlping-password = mypass
urlping = fictional.showip.org
urlping-regexp = (Address|addr:)\s+([0-9.]+)
# Where IPs are stored. Directory name or Directory name with
# additional file prefix. The directory part must exist. You could
# say 'file = /var/log/dyndns/' but that's the default.
file = default # Use OS's default location
# The DDNS account details
login = mylogin
password = mypass
provider = dyndns # [default]
proxy = myproxy.myisp.net # set only if needed for HTTP calls
# Hou need this option only if you have multiple ethernet cards.
# After which regexp the IP number appers in ifconfig(1) listing?
regexp = .*0xffffffff.*?inet
# What account are you using? Select 'dyndns|statdns|custom'
system = dyndns # Provider [dyndns] only
# Yes, delegate all *.mydomain.dyndns.org calls
wildcard = 1
# End of cnfiguration file
See the details of all of these options from the corresponding command line option descriptions. E.g. option 'ethernet' in configuration file corresponds to --ethernet command line option. The normal configuration file for average user would only include few lines:
# /etc/dyndns/myhost.dyndns.org.conf
host = myhost.dyndns.org
file = default # Use OS's default location
login = mylogin
password = mypassword
provider = dyndns
system = dyndns # or 'statdns'
wildcard = 1 # Delegate *.mydomain.dyndns.org
# End of cnfiguration file
TODO (write Debian daemon scripts) FIXME:
update-rc.d dyndns start 3 4 5 6 # Debian
For new Operating System, provide all relevant commands, their options, examples and their output which answer to following questions. The items in parentheses are examples from Linux:
- How is the OS detected? Send result of 'id -a', or if file/dir
structure can be used to detect the system. In Lunux the
existence of /boot/vmlinuz could indicate that "this is a Linux
OS".
- What is the command to get network information (commandlike 'ifconfig')
- Where are the system configuration files stored (in directory /etc?)
- Where are the log files stored (under /var/log?)
To add support for routers that can be connected through HTTP protocol or with some other commands, please provide connection details and full HTTP response:
lynx -dump http://192.168.1.0/your-network/router/page.html
1. Turn on --debug to see exact details how the program runs and what HTTP requests are sent and received.
2. Most of the <--Query> options can't be used standalone. Please see documentation what additional options you need to supply with them.
Directory of temporary files. Defaults to system temporary dir.
Daemon startup file
/etc/default/dyndns
In Linux the syslog message files are:
/etc/syslog.conf daemon.err daemon.warning
/var/log/daemon.log
There is no default location where program would search for configuration
files. At installation, configuration examples are put in directory
/etc/dyndns/examples. It is recommended that the examples are modified
and copied one directorory up in order to use option --Config
/etc/dyndns/*.
If program is run with Windows Activestate Perl, the log file is stored to
file C:/syslog.txt.
syslog(3), Debian package ddclient(1)
See other dyndns.org clients at http://clients.dyndns.org/
There is no syslog daemon in Cygwin. The Cygwin POSIX emulation layer takes
care about syslog requests. On NT and above systems it logs to the
Windows's event manager, on Win9x and ME a file is created in the root of
drive C:. See message <http://cygwin.com/ml/cygwin/2002-10/msg00219.html>
for more details.
You can see the entries in W2K Start => Settings => Administrative Tools => Computer Management: [ System Tools / Event Viewer / Application ]
Please use option --debug 2 and save the result. Contact maintainer if you find bugs or need new features.
http://freecode.net/projects/perl-dyndns
The client specification is at https://www.dyndns.com/developers/specs/
CPAN/Administrative
CPAN/Networking
HTTP::Headers HTTP::Request::Common LWP::UserAgent LWP::Simple Sys::Syslog
None.
any
Copyright (C) 1999-2009 Jari Aalto. All rights reserved. This program is free software; you can redistribute and/or modify program under the terms of GNU General Public license v2 or later.
This documentation may be distributed subject to the terms and conditions set forth in GNU General Public License v2 or later (GNU GPL); or, at your option, distributed under the terms of GNU Free Documentation License version 1.2 or later (GNU FDL).