ipcheck.py homepage

[Source Forge] [dyndns]

Download the latest release  
Older Releases Older releases directory.

Last updated August 21, 2011.


This is a simple Python script to register your dynamic IP address using the NIC V2.0 protocol. We aim to be fully compliant with the dyndns client specification. A big thank you to everyone that has contributed to this script or sent along a note of encouragement. I try to keep organized with who sent in what but if I've missed something in the acknowledgements section of the script, please let me know.

The script is very easy to use and supports multiple methods for determining the external IP (parsing interfaces on the local machine, web based IP detection, direct support for devices from Linksys, Netgear, Draytek, Netopia, HawkingTech, Watchgard, Cayman, Nexland, ZyXEL, SMC, Compex, UgatePlus, DLink and Cisco).

Run the script with no command line arguments for quick start instructions.


Make sure you can write to the current directory for data
files and that you always run from the same directory.
The first time you run the script, you will be asked to run
with the --makedat option in addition to any other options.
This will create the data files for the hostnames and options 
you specify on the command line.  You should only do this once.
Subsequent runs should be made without the --makedat option.

For help with different options: python ipcheck.py -h
For supported devices listing  : python ipcheck.py --devices
For long detailed help text    : python ipcheck.py --help

Example 1: the external IP is on eth0 of the current machine
python ipcheck.py -l -i eth0 username password hostnames

Example 2: you are using the Linksys routing device
python ipcheck.py -l -L linksyspassword username password hostnames

Example 3: you want to use web based ip detection
python ipcheck.py -l -r checkip.dyndns.org:8245 ...

where ... is your dyndns username password and hostnames.
Hostnames should be comma delimited if there are more than one.

Usage  : ipcheck.py [options] Username Password Hostnames
or       ipcheck.py [options] --acctfile acct_info_file 

Options: -a address     manually specify the address 
         -r URL         NAT router, use web IP detection 
         -A text        scan syslog for an IP after text (Unix only) 
         -F filename    guess the WAN IP from a firewall log 
         -b             backup mx option ON (default OFF) 
         -c             custom dns option (default dynamic) 
         -d dir         directory for data files (default current)
         -e script      execute script after a successful update 
         -f             force update regardless of current state 
         -g             NAT router, let dyndns guess your IP 
                        (do not use this in a cronjob, try -r) 
         -h             print this help text 
         --help         print all available help text 
         -i interface   interface for local address (default ppp0) 
         -l             log debugging text to ipcheck.log file 
         --syslog       log debugging text to syslog (Unix only) 
         -m mxhost      mx host (default NOCHG) 
         -o             set dyndns offline mode 
         -p             proxy bypass on port 8245 
         -q             quiet mode (unless there is an error) 
         -s             static dns option (default dynamic) 
         -t             test run, do not send the update 
         -v             verbose mode 
         -w             wildcard mode ON (default OFF) 
         --makedat      create the ipcheck.dat file by dns lookup
         --devices      print router options (Linksys, Netgear, etc)

For help with different options: python ipcheck.py -h
For supported devices listing  : python ipcheck.py --devices
For long detailed help text    : python ipcheck.py --help

The script will locate the address of your router automatically by
looking at the default route of the machine you are running on.
Then it will read the status page for the external IP address
and use that for updates.  You need to specify the admin password
with the appropriate option.

         --pfile        device password below is actually a filename 
         -B password    New Barricade with password on port 88
         --VWBR         Use with -B to indicate 7004VWBR Router
         -C password    Cisco (667i) DSL router password
         -D password    Draytek (Vigor2000) NAT router password
         -E             Eicon Diva (no password needed)
         -G             UgatePlus (no password needed)

         -H password    HawkingTech router password
         -I password    Cisco (700 series) ISDN router password
         -J password    ZyXEL prestige 642ME router password
         -K password    Compex NetPassage 15
         -L password    Linksys (BEFSR41) NAT router password
         -M password    MacSense password
         -N password    Netgear RT311 NAT router password
         -O password    Netopia (R9100) NAT router password
         -P port[,password]
                         Nexland Pro800Turbo, WAN port, port==any use the
                         first connected port; port=[01] use the port'th port
                         if available, else any; port=-[01] use port'th port
                         if available, else fail.  Specify password if
                         required.  For example, -P any,123 says to use the
                         first port and password 123.  -P 1 says prefer port
                         #1 and no password is required.  -P -0,xyz forces
                         port 0 and uses password xyz.
         -Q pword,iface password and interface for Instant Internet 
         -R password    Netgear FR3114 password
         -S             SMC Barricade (no password needed)
         --WBR password Use with -S if 2404WBR with password
         -T password    Alcatel Speed Touch Pro password
                        (you can also try -r
         -V password    Eicon Diva (see -E for no password)
         -W password    Watchguard SOHO NAT firewall password
         -X             Nexland router (no password set)
         -Y password    Cayman DSL 3220H NAT router password
         -Z password    ZyXEL 642R and Zywall 10 router password
         -1 password    DLink DSL504 password
	 -2 password    Siemens SpeedStream 2620 router password
         -3 password    Netgear RT338 ISDN router
         -4 password    Gnet model BB0040 ADSL router password
         -5             DLink DI704 with no password
         -6 password    DLink DI704 password
         -7 password    DLink DI701 password
         -8 password    DLink DI804/DI614+ password
         -9 password    DLink DI713P password
         --VT1000v      Motorola VT1000v VoIP voice terminal (no password needed)
You can change the default username for the above devices with:
         -U username    override the default NAT router username
                        leave this option out to use the default

For Cisco IOS devices and any others that understand SNMP, you
can also use --snmp to detect the external IP.

         --snmp snmp_agent,community,numeric_objectid
You will need the v1.x pysnmp module from http://pysnmp.sourceforge.net/
The snmp code does not work with v2.x or 3.x of pysnmp
You also need to know the agent, community and numeric objectid:
python ipcheck.py --snmp,public,. ...
where ... = username password hostnames

Alternate/Generic SNMP retrieval
         --snmpget snmp_agent,community,numeric_objectid
You will need the v1.x pysnmp module from http://pysnmp.sourceforge.net/
The snmp code does not work with v2.x or 3.x of pysnmp
You also need to know the agent(hostname or ip), community and
numeric objectid:
python ipcheck.py --snmpget router,public,. ...
where ... = username password hostnames
This option will do a snmp get to the specified objectid which needs to be
that of the ip to be used in the update

         --forward port[/protocol],...
Ports to be forward from your router to this machine.
Defaults to tcp protocol. Stay set until router turned off.
example: -T password --forward=80,time/udp,21/6

Start ipcheck.py with no arguments to get some quick examples.

The script creates data files in the current working directory.
Make sure you have write permission and that you run the script
from the same directory each time.  You can use the -d option
to specify an alternate directory for data files. 

The first time you run the script, you will be asked to run
with the --makedat option.  This will create the data files
and complete the update.  You should only do this once.
Subsequent runs should be made without the --makedat option.

If -f is set, all hosts will be updated regardless of the 
current error, wait or IP state.  You should never need this. 

You can place your username password and hostnames in a file 
(all on the first line) and use the --acctfile option if you do 
not wish your password to show up on a ps. 

The best way to run ipcheck is in the /etc/ppp/ip-up.local file 
or the BSD ppp.linkup file (you will need to sleep 30 before 
running the script since ppp.linkup runs before the link is up.) 
The script will also run from a cronjob.  Just make sure the 
hostnames are the same in each execution.  You should make sure
it is using the same directory each time for data files.  The -d 
option can be used to specify where data files go.

The file ipcheck.dat contains the IP address and hostnames 
used in the last update.  If the ipcheck.dat file is older 
than 25 days, an update will be made to touch 
the hostnames. 

The file ipcheck.wait is created if dyndns requests a wait 
before retrying.  This file will be automatically removed when 
the wait is no longer in effect. 

The file ipcheck.err is created if the response is an error. 
It will not try to update again until this error is resolved. 
You must remove the file yourself once the problem is fixed. 

If your ISP has a badly behaved transparent proxy on port 80 
traffic, you can try the -p option to use port 8245. 

If a http message is sent to dyndns.org, the response will be 
saved in the ipcheck.html file.

Custom domains can be specified with the -c option.  You must 
first complete the create database step on the Dyndns web page. 
Suppose you have the domain ipcheck.org defined as an A record 
and your nodes aliased to ipcheck.org with CNAME records.  Use: 
python ipcheck.py -c username password ipcheck.org 

Note that if you intended to maintain both a custom domain and 
a dyndns domain (ie. ipcheck.dyndns.org) you should be using 
the -d option to keep the data files in separate directories. 
The custom domains are not compatible with the offline, mx, 
backmx and wildcard options.  Setup your database accordingly. 

The script can find your public IP address in one of several ways:

1) interface IP detection is the default method and appropriate
if the machine you are running on has an interface with the public
IP addressed assigned.  The script knows how to query various 
operating systems for the address of an interface specified 
with the -i option (default ppp0).  Note on Win32 systems 
specify the MAC address device after -i and on BeOS systems 
specify the interface number after -i (eg. -i 1). 

2) router IP detection is used if you have a routing device
such as a Netgear RT311.  Use the --devices option to get a
help on specific devices.  This method is used by the script
if you specify one of the device-related options.

3) web IP detection may be used if your device is not supported
python ipcheck.py -r checkip.dyndns.org:8245 ... 
where ... = username password hostnames 
This method is used if you specify the -r option.
IMPORTANT: Do not run web based IP detection more often 
than once every 15 minutes.  It is costing dyndns bandwidth. 

4) you can explicitly set the desired IP address with -a

5) when -g is used, the script will not send any IP address
at all (even ones detected by the previous options).  Only
the account information will be sent to the dyndns server.
The dyndns server will assign the hostnames to the source
IP address of the request.  The assigned address is saved in
the ipcheck.dat file.  IMPORTANT: Do not run this from a cronjob
unless you know the address saved in the ipcheck.dat file 
matches locally detected public IP to prevent unnecessary updates.

If your have an unsupported device and are willing to help with
some testing, email me. 

The ipcheck homepage can be found at:

Client development information can be found at:

Please include the ipcheck.log file if you email me with a problem. 

Custom Domains

We support updating your MyDynDns custom domains with the -c option. Note that you need to keep separate data files if you want to update both your custom domains and your dyndns domains. Example:
python ipcheck.py -c -l -d /etc/mydyndns uname pword foo.com
python ipcheck.py -l -d /etc/dyndns uname pword foo.dyndns.org,bar.dyndns.org