scrounge.org

Use IPWatch to monitor your IP address

By Bruce Buhler and Wayne Larmon

3/22/2001 A user notified us that the JustLinux Dynanic DNS Service has been shut down.

2/27/2001 User submitted Cisco Router and fix for dhs.org/y2.org

The discussion group software broke. Apparently, it is not compatible with the version of MySQL that we are currently running.

IPWatch is a Linux shell script that will monitor your network connection and take corrective action when several problems happen. It is designed to be used with a Linux computer that has a permanent network connection, such as by using a cable modem, DSL, or other LAN type connection. Specifically, it monitors and attempts to correct two problems:

  1. When the network goes down (which could happen when your ISP forcibly changes your IP address.)
  2. When your IP address changes.

When the network goes down the script will attempt to do a network reinitialization. When your IP address changes, the script will optionally reinitialize your machine's hostname and restart the system logging facilities to use the new host name. It will optionally reconfigure a dynamic hostname service, if you use one. It currently supports yi.org, homepc.org, justlinux.com, dyndns.com, and dyndns.org. (IMPORTANT NOTE: dyndns.org and dyndns.com are completely untested. We would appreciate any feedback on the functionality of these services with this script.)

In all cases it will send an email notification message to a user specified address so that you will know what has happened. This email notification is real handy if you are normally at a different location than the computer and you need to know its IP address in order to access it. It also logs all operations in a log file.


Download

IPWatch has been tested on Red Hat 6.0, 6.2 and 7.0, and Mandrake 6.1, 7.0, 7.1 and 7.2.

Download ipwatch.txt (1.1b) 11/20/2000 and follow the installation instructions, below.
IPWatch changelog

Optional. Also download ipcheck.txt (1.1) 4/16/2000 to help with ipwatch.sh configuration and testing.
IPCheck changelog

IPCheck is neither required nor necessary to use IPWatch; it is simply a "plug-in" for IPWatch that will help diagnose problems, and will provide information about its configuration.

Installation (Short form)

Download ipwatch.txt and ipcheck.txt, (as root) rename them to be ipwatch.sh and ipcheck.sh, chmod them to be executable, (chmod 700 ipwatch.sh ipcheck.sh) and set the configuration variables in ipwatch.sh.

Test the configuration by running ./ipwatch.sh -c -v. If it shows errors, then edit the ipwatch.sh variables and repeat.

Then bring the network down (ifdown eth0) and run ./ipwatch.sh and see if it brings the network up. Then use a text editor to change /tmp/currentIP to be a different IP and run ./ipwatch.sh again.

Check the status messages that were mailed to MAILTO. If OK, then load ipwatch.sh into cron (with no command line options!) to be executed every 15 minutes, or so.

You still might want to scan through the Installation (Long form) instructions, because there are some odd tidbits there that might be helpful.

Installation (Long form)

(You must be root for the rest of this procedure.)

IPWatch has been tested with the dhcpcd DHCP client program. Many users have had problems with the pump DHCP client that is installed by default by current versions of Red Hat and Mandrake Linux. Here are instructions for installing dhcpcd. The script should work with any DHCP client, pump, BOOTP, or any other method of getting a changing IP address. /etc/rc.d/init.d/network is the script that will take care of which DHCP client to use, not our script. Our script simply calls the network script and restarts it, so it will use whatever client/protocol the user has configured on their system.

Download it

Download ipwatch.txt (and optionally ipcheck.txt) and copy it somewhere on your Linux machine. Make sure to use the "ASCII" mode for all FTP transfers. We use the /root/bin directory for custom system scripts like this. IPWatch was named "ipwatch.txt" to sidestep any MIME file extension problems that might happen with a file extension of "sh." So, after you have it downloaded and copied to the correct directory, rename it to be ipwatch.sh. (Rename ipcheck.txt to ipcheck.sh if you have downloaded it.) We will assume that you will put it in /root/bin.

Make it be executable

A script must have the proper access bits set in order to execute, so type chmod 700 ipwatch.sh It also must be "owned" by root, so type chown root:root ipwatch.sh (Same with ipcheck.sh.) Use ls to ensure that this has been done:

ls -l ipwatch.sh
-rwx------   1 root     root         7393 Nov  5 18:40 ipwatch.sh

(Further explanation of access bits.)

Configure it for your computer

Now you must edit several configuration variables in ipwatch.sh to make it work on your machine. Load the script in a text editor, read the comments at the beginning of the file, and follow the instructions to configure the script. Make sure to set the MAILTO variable to the email address that you want to receive status messages at.

The only variable that you have to configure is SERVER. This must be set to an IP address that is always available. It should be close to you for maximum relability. Even though you could set SERVER to "yahoo.com", this is a bad idea: 1., because yahoo.com is (probably) a considerable distance from you, which means that testing it might give you false failures because of net congestion and 2., because it is not polite for lots of users to continually ping "yahoo.com."

You should set SERVER to an IP address like your DHCP server. If you don't know that IP address, then fire up a Windows computer and run WinIPCFG. This will display the IP address of your DHCP server. Test the IP address from the command prompt by typing nslookup IP_address_you_are_testing. Don't try running IPWatch until you have set SERVER to an address that works with nslookup.

Another hint. Even if you are using one of the dynamic host update services, consider not enabling it in the configuration file until you have tested the script as described below. Ditto with the firewall initialization. After you have got it to work doing the standard system updating, then try enabling the additional services and testing it again.

Similarily, when you are first testing the script, set TIMELIMIT to some short period of time, like 10 (seconds), so the script won't "hang" while you are shaking out the configuration stuff. Then, after you have everything working, lengthen TIMELIMIT when you are ready to use the script as a cron job.

Special instructions for the JustLinux service: Before you configure the script, first you need to make sure that your browser is set to accept cookies. Then go to:

http://www.justlinux.com/bin/login?location=http://www.justlinux.com/bin/controlpanel/controlpanel.pl

and enter your username and password and click the Login button. Then click on Dynamic DNS services, select your hostname, and click on the Update button. You can then look at the URL in your browser. Towards the end of the URL, it will say "dnsid=xxxxx" where xxxxx is a number - that's the number you need to enter into the $DNSID variable in the script.

Additional instructions for Red Hat Linux 6.2 (and newer?) IPWatch uses Lynx to interface with the dynamic DNS services. JustLinux requires two accesses. A cookie is used to maintain the state between the two accesses. Lynx in Red Hat 6.2 (and possibly other distros) requires that variables be set in /etc/lynx.cfg in order that the cookies are saved to disk between the two Lynx accesses. Make sure that these variables are uncommented and set in /etc/lynx.cfg

SET_COOKIES:TRUE
PERSISTENT_COOKIES:TRUE
COOKIE_FILE:~/.lynx_cookies
COOKIE_SAVE_FILE:~/.lynx_cookies

Whew!

All configured. Good. Now let's test it.

Testing to see if it works

First do a sanity check on the configuration

Your network must be connected and functional. You should be able to receive email at the MAILTO address. The above configuration steps must have been completed. You must have good karma.

If you downloaded ipcheck.sh, you can use it to test ipwatch.sh's configuration. Type ./ipwatch.sh -c -v. This will start ipwatch.sh but tells it to run ipcheck.sh to test ipwatch.sh's configuration and to display the configuration variables. It should display something like this:

The Network is up. Current IP Your_IP_Address is unchanged.

EXTIF = eth0 (is our Internet connection.) SERVER = Your_SERVER_Address (is what we ping to see if the network is up.) FIREWALL = Your_firewall_script (is how we restart our firewall.) UPDATEHOST = yes We will be updating the hostname. TIMELIMIT = 300 seconds. LOGFILE = /var/log/ipwatch (ipwatch.sh and ipcheck.ch log file location.) MAILTO = Your_MAILTO_address (status messages will be mailed here.) Using Your_Dynamic_DNS_Service for Dynamic DNS.

Current IP is located in /tmp/currentIP. (Currently is (Your_IP_Address.)

(Items that are italicized will display the values that you have configured in ipwatch.sh.) The way it displays above is how it should display. If it displays any error messages, then go back and edit the ipwatch.sh configuration section and re-run ./ipwatch.sh -c -v until the error messages go away. (Of course, you don't have to define the FIREWALL or DYNDNS (Dynamic DNS) variables if you aren't using those services.)

Can it detect normal network conditions?

Now we'll try ipwatch.sh with no command line options. Type ./ipwatch.sh. The script should start and return to the command prompt in a few seconds. It should not display any messages. ipwatch.sh checked to see that the network was up (good), and that the IP address hadn't changed (good), so it exited.

If it doesn't return to the command prompt in a few seconds, then the most likely reason is because you didn't set the SERVER variable to be an IP address that is accessable. You can force the script to terminate by pressing Ctrl-C. You also might have to remove the lock file. If you don't know a valid IP and if you are using dhcpcd, then you can look at /etc/dhcpc/dhcpcd-eth0.info. Try using either the DHCPSIADDR (DHCP server), DNS (DNS server), or GATEWAY (your gateway machine) addresses. Test the IP address from the command prompt by typing nslookup IP_address_you_are_testing.

Can it detect and fix the network being down?

Now we are ready to test ipwatch.sh's ability to detect and fix problems and to mail status messages.

Bring your network down by typing dhcpcd -k (If dhcpcd isn't installed then you will get an error message. See the instructions for installing dhcpcd.) If you are using some other DHCP client program then you can use ifdown eth0 (assuming that your network connection is through eth0.)

Is the network down? Now run the script. After a few seconds the script should have reinitialized the network connections and mailed a status message to your MAILTO address. Examine the status message that was emailed to you closely to make sure that all operations were completed properly. It should look something like this:

Subject: Your network has been restarted

[11/07/99 12:45:16] Network initialization SUCCESSFUL

Shutting down interface eth0 [  OK  ]
Shutting down interface eth1 [  OK  ]
Disabling IPv4 packet forwarding [  OK  ]
Enabling IPv4 packet forwarding [  OK  ]
Bringing up interface lo [  OK  ]
Bringing up interface eth0 [  OK  ]
Bringing up interface eth1 [  OK  ]

Also check the IPWatch log file. This is currently defined as /var/log/ipwatch.

Run the script again. It should do nothing now, because the network should be back up and connected. Note that the script should not display anything on your console (because it is designed to run in the background.) All notifications are done through the email status message and by writing to the IPWatch log file.

Can it detect and fix a changed IP?

You should also test the "IP has changed" processing by editing the IPFILE file (currently defined as /tmp/currentIP) that the current IP is stored in, changing this to be some different IP address and running the script. The script will treat this as a changed IP and should do the appropriate processing. If you have enabled the optional dynamic DNS update, check the messages that the dynamic hostname service returns (which will be contained in your status email.) The status mail message should look like this:

Subject: Your IP address has changed to xx.xx.xx.xx
[11/06/99 21:15:01] Restarting the firewall

(Will display your firewall initialization, if you defined one.)

[11/06/99 21:15:02] Setting new hostname to your_new_hostname

[11/06/99 21:15:02] Restarting logging daemon

Shutting down kernel logger: [  OK  ]
Shutting down system logger: [  OK  ]
Starting system logger: [  OK  ]
Starting kernel logger: [  OK  ]

[11/06/99 21:15:09] Dynamic hostname renewal SUCCESSFUL

(Will display whatever your Dynamic Hostname service's update returns.)

When you are satisfied that the script operates the way that you expect it to, it is time to install it as a cron job so that the system will automatically run the script at intervals that you specify.

Installing the script as a cron job

(You must be root when doing this.)

Create a file and enter this line:

0,15,30,45 * * * * /root/bin/ipwatch.sh

Save the file with a name like ipwatch.cron

The above file specifies that /root/bin/ipwatch.sh will be executed at intervals of every fifteen minutes. The * values for the following fields mean that you want it to run every hour, day of month, month, and day of week. So in other words, it will run every 15 minutes as long as your machine is turned on.

To load this into cron, type:

crontab ipwatch.cron

This installs ipwatch.cron into cron. It will now execute /root/bin/ipwatch.sh once every 15 minutes.

Type crontab -l to display the current crontab (i.e., what we just did.)

If you don't want the script to be run by cron then you must remove it. To remove it from cron, type crontab -r (as root.) Type crontab -l to verify that it has been removed.

If you want to change cron parameters, say to make the script execute more (or less) often, edit ipwatch.cron, remove it from crontab with crontab -r and then install it again. crontab ipwatch.cron

Optional. ipwatch.sh monitors your computer and will take corrective action after a problem has been detected and will mail you a status message describing the action it has taken. But you might want a periodic confirmation that your computer is operating properly. You can use the capabilities that ipcheck.sh adds to ipwatch.sh to do this.

To have ipwatch.sh send you a status message once a day, add the following line to the cron job file you just created:

10 5 * * * /root/bin/ipwatch.sh -c -m -n -s

This tells cron to invoke ipwatch.sh once a day at 5:10am and check, send a status message to the MAILTO address, don't echo to the console, and also display the last part of the ipwatch log file.

Important! Make sure to add this line in addition to the line described above, because whenever you use any of the -c command line options, then ipwatch.sh only does display diagnostics. It does not do its normal processing. That is why you must also invoke ipwatch.sh from cron with no command line options.

-c options are for checking. No options is for processing.

More information on using cron.

ipwatch (ipcheck) options

  Usage:  Run ipwatch.sh with appropriate command line arguments.

          -c      Displays status on console
          -c -m   Sends status message to address defined with MAILTO
          -c -l   Writes status to log file
          -c -n   Suppresses display on console
          -c -v   Display all variable settings
          -c -s   Show ipwatch log file

 Can also specify options verbosely:

          -c or --check
          -m or --mail
          -l or --log
          -n or --nolog
          -v or --variable
          -s or --show

Again, run ipwatch.sh with the above options. Do not run ipcheck.sh by itself. ipcheck.sh must be in the same directory that ipwatch.sh is.

Troubleshooting

Lock file

One potential pitfall is if the computer is reset while the script is running. This should not normally be a problem because the script starts, checks to see if the network is functioning and exits, usually in a matter of seconds. But if there was some prolonged network problem, then the script will be executing while waiting for the network problem to be corrected so that it can do its initialization. When the script is executing it creates a "lock" file. When the script first starts it checks for the existance of this "lock" file. If it exists, then the script assumes that another instance of itself is executing, so it immediatly exits.

This creates a problem if the computer is rebooted when the script is executing. The lock file will never be erased, and the script will never execute properly until the lock file has been erased.

There are two ways to solve this. The most simple way is to manually erase this lock file if you suspect a problem. The lock file is currently defined as /var/lock/subsys/ipwatch. (Check the script for the exact file name and location.)

You can also add a line at the end of the /etc/rc.d/rc.local file to erase this file every time the machine boots. To do this, edit /etc/rc.d/rc.local, and add

rm -f /var/lock/subsys/ipwatch

at the end of the file. Save /etc/rc.d/rc.local. It will now erase /var/lock/subsys/ipwatch (if it exists) every time the machine boots.

Mail problems

If you aren't recieving the status mail at the address you expect it, try changing the MAILTO variable back to the default MAILTO="root@localhost". Then IPWatch will mail the status message to root's mailbox. You can "read" this by doing a cat /var/spool/mail/root | more

If mailing the status message doesn't work at all, then maybe the mail program hasn't been installed. On Red Hat 6.0 and Mandrake 6.1 the mail program is installed from the mailx rpm file. Type rpm -qi mailx to see if it is installed. If it isn't, then install it from your Linux installation CD.

Hanging

There is a possibility that IPWatch could "hang" while attempting to do some operation and multiple instances if IPWatch would be launched by cron. We have attempted to minimize this possiblilty by several methods:

  1. By using a "lock" file. Each time that IPWatch is started it checks for the existance of a lock file (that IPWatch creates when it is running and erases when it finishes its processing.) If IPWatch detects the presence of a lock file then it uses the ps command to check to see if a previous instance of itself is running. If so, then it exits.

  2. By periodically comparing the value of the TIMELIMIT variable with the "time-that-IPWatch-has-been-running" and aborting if this time exceeds TIMELIMIT. TIMELIMIT should be set to be less than the interval that you are using to start IPWatch with cron. TIMELIMIT (probably) should never be set to 0.

But.... Stuff happens. So it is probably a good idea to periodically use the ps ax | grep ipwatch.sh command to make sure that multiple instances of IPWatch aren't somehow running. If they are, then this means that you have some type of problem. Use the kill command to kill off the spurious instances of IPWatch (Kill the pids that ps ax | grep ipwatch.sh returned.

And examine IPWatch and try to figure what operation is not completing. Be especially suspicious of the Dynamic DNS updating, because that depends on these service's web sites behaving the way that they were when the script was written.

If you have any problems with IPWatch "hanging", please let us know about it.

Dynamic DNS updating of dhs.org doesn't work

Uh, it doesn't. dhs.org changed their updating interface and we haven't gotten around to making IPWatch work with it. Sorry. Hopefully by the next release.

Problem detecting that the network is up (or down.)

Look at the isnetup function. It is currently
# Is Network up?  0 if up, non-zero if down
isnetup() {
    local VAR

    VAR=`nslookup -retry=2 -timeout=5 $SERVER > /dev/null; echo $?`
    # Let's make sure we've really lost our connection
    if [ $VAR -ne 0 ]; then
        VAR=`nslookup -retry=4 -timeout=5 $SERVER > /dev/null; echo $?`
    fi

    return $VAR
}

Some users have reported that the nslookup test doesn't work reliably for them. If you are having problems, try changing the nslookup test to a ping test by modifying the script like this:

# Is Network up?  0 if up, non-zero if down
isnetup() {
    local VAR

#   VAR=`nslookup -retry=2 -timeout=5 $SERVER > /dev/null; echo $?`
    VAR=`ping -s 1 -c 1 $SERVER > /dev/null; echo $?`
    # Let's make sure we've really lost our connection
    if [ $VAR -ne 0 ]; then
#      VAR=`nslookup -retry=4 -timeout=5 $SERVER > /dev/null; echo $?`
       VAR=`ping -s 1 -c 5 $SERVER > /dev/null; echo $?`
    fi

    return $VAR
}
Add the lines that are in red, above. And comment out the lines with the nslookup test by putting a # character at the beginning.

"Dynamic hostname renewal SUCCESSFUL" isn't really.

Well, our test is a bit simplistic. What it really tests is if the URL that is defined for DYNDNS achieves a successful httpd access. Meaning that NOT SUCCESSFUL really means something like "Page not found.", and SUCCESSFUL only means that IPWatch was able to access the web site. But IPWatch doesn't (currently) determine if the IP updating was in fact successful. It does alert you to gross configuration problems, or if the Dynamic DNS service was out of service.

You have to examine the text that the Dynamic DNS Service returns in your status email to determine if the update was, in fact, successful.

Also see this User Submitted Fix.


Back to the scrounge.org home page.