GetIP ReadMe - Release 0.1.1
============================

NAME
   getip.cmd

SYNOPSIS
   This short REXX script will retrieve the Internet IP address assigned to the 
   host PC. The information is retrieved from an external ECHO_SERVER or a 
   STATUS page of a router connected to the host PC itself. 
   
DESCRIPTION
   A little background first. There are (as far as the scope of this script is 
   concerned) 2 separate Internet IP address types assigned to a host PC, they 
   are either static or	dynamic IP addresses. Typically hosts with a static 
   Internet IP address never change and are directly reachable through internet. 
   This means that there are no other devices between this host PC and it's 
   Internet connection. The other situation is where a host PC sits behind a NAT
   router/firewall where on a LAN it may have a dynamic or a static IP address 
   assigned, but externally the Internet IP address assigned to the router is 
   really how this host PC is known to the outside world. This script is meant 
   to retrieve that external Internet IP address by which the host PC is known 
   to the outside world. This is typically the case when dealing with the 
   standard dial-up, DSL, Cable modem ISP accounts.

   In additon, if the external IP address assigned to the user's connection 
   (through the router or directly the PC itself) changes dynamically the script
   can be re-run to show the new resulting IP address. This is actually the 
   reason why I developed the code. I have a DSL connection to my ISP, it does 
   not change frequently, in fact it only seems to change if I specifically 
   disconnect and re-connect. I wanted an easy and reliable way of retrieving 
   my ISP assigned IP address. On my LAN I have several PCs which all have a 
   static IP address assigned to them. If I issue one of the standard TCP/IP 
   commands to retrieve the host PC IP address I would get the following:

   command: hostid
   result: 192.168.1.10

   As you can tell the IP address returned is my LAN static IP address, not the 
   external Internet IP address which has been assigned to my DSL connection by 
   my ISP. Since I wanted to run some Internet services on one of my machines I 
   needed a way to retrieve that external address.
   
LIST OF SUPPORTED ROUTERS
   Currently the retrieval of Internet IP address from the STATUS page of the 
   following routers is supported:
   
   - LinkSys BEFW11S4V4, firmware v1.5.0
   - LinkSys BEFSR11/BEFSR41/BEFSRU31, firmware v1.45.6
   
PROGRAM LOGIC
   The script can either use a publicly available echo server which will return
   your Internet IP address or it can query the built-in status page of your 
   router for this IP address. I am using a LinkSys wireless router here and 
   it's STATUS page provides just the information I was looking for, so it was 
   fairly easy to retrieve the Internet IP address information. I would imagine 
   other routers also have this capability.

COMMAND LINE PARAMETERS
   The program accepts a couple of parameters:

   operating_mode debug_mode

   where:
   
   "operating_mode"  - is the Internet IP address retrieval mode, it can be 
                       either "echo_server" which will default to query the 
                       www.whatismyip.com server, or it can be the name of a 
                       router which you are using for which support has been 
                       added to this script to retrieve the IP address through 
                       it's STATUS page.

   "debug_mode" - is the debug mode flag, it can be either "0" or "1", meaning 
                  debug OFF or debug ON respectively.
                  
   Example of usage, in order to query my Internet IP address I can issue the 
   following:
   
   getip LinkSys_BEFW11S4V4_1500 0
   
   which will retrieve the info using logic specific to my LinkSys router, and
   will not produce any DEBUG output. If I want DEBUG output I would issue the 
   following:
   
   getip LinkSys_BEFW11S4V4_1500 1
   
   I can also retrieve the info using the default ECHO_SERVER as follows:
   
   getip echo_server 0
   
   The last "debug_mode" parameter is optional, and by default assumes that no
   DEBUG output is to be produced, so unless you want to see a bunch of HTML 
   code you can simply leave it as "0" or skip it altogether on the command 
   line. So the following are valid non-debug invocations of the script:
   
   getip LinkSys_BEFW11S4V4_1500
   
   getip echo_server
   
OUTPUT
   This is your Internet IP address.
   
INSTALLATION
   Simply copy this script to any directory you want. The script only needs the
   rxsock.dll DLL to be present in your system and be accessible through 
   LIBPATH. If you intend on using the STATUS page of your router to get the 
   IP information you need to edit several variables in the script, they are:
   
   router_IP = ''
   router_userid = ''
   router_password = ''
   
   The script needs this in order to know which "server" to contact (server here
   being your local router) and how to build the proper authorization string if
   you password protected the access to your router (which is a very good idea 
   to start off with anyways).

FILES
   getip.cmd - REXX script
   getip.doc - the file you are reading, documentation
   
BUGS
   Script is pretty simple, but there are many ways that parsing of the returned
   HTML code can be buggered up. So if you hit a problem, send me the DEBUG 
   output of the program execution. As a matter of disclosure, the DEBUG output 
   will have your router userid/password, so you may want to EDIT that 
   information out. However, since I do NOT know your Internet IP address there 
   is no chance for me to try to hack your router, and besides I'm not 
   interested in doing that anyways.
   
   Send me an email addressed to : dariusz@mnsi.net, with a subject line that 
   reads: GETIP BUG.
   
CREDITS
   The following people have lent their time and effort to make this a better
   piece of code and so I extend my thanks to them:
   
   Hubert Piatkowski - tireless testing
   Mike Ruskai       - Base64 encoder procedure
   Daniela Engert    - for the format of this documentation
   Dennis Peterson   - for the original DNS update code on which this script is
                       based
   
TO DO
   - Develop error handling routines, if for whatever reason the router or the 
     ECHO_SERVER do NOT return a good HTML page with a valid IP address this 
     script will hang.
     
   - Add support for using the STATUS page of other routers: if you want your 
     particular router to be supported send me the HTML STATUS page which your
     router generates.
   
   
COPYRIGHT
   GetIP - Copyright (c) 2004 Dariusz Piatkowski. All rights reserved.

STATUS OF PROGRAM
   GetIP is freeware, send me an email or a card, or just say "Hi..."!
     
AUTHOR
   Dariusz Piatkowski
   Internet: dariusz@mnsi.net

HISTORY
   0.1.0 - first alpha release, support for the ECHO_SERVER and LinkSys 
           BEFW11S4V4 router, firmware v1.5.0
   0.1.1 - added support for LinkSys BEFSR11/BEFSR41/BEFSRU31 routers and 
           cleaned up the output.
