@database dyndns.guide
@author nsoggia@telnetwork.it
@smartwrap
@$VER: DynDNS.guide 37.01 (08.06.97) by Nik Soggia

@rem ********************************************************************
@rem *                                                                  *
@rem * the "title" macro under kickstart 1.3 and 2.0 is drawn as a link *
@rem * instead of a centered bold text, this could be confusing.        *
@rem * real links have at least a space before and after the string.    *
@rem *                                                                  *
@rem ********************************************************************

@macro title "@{jcenter}@{b}@{par}$1@{par}@{ub}@{jleft}"
@macro msg "@{u}$1@{uu}"
@macro rev "@{par}@{b}$1@{ub} $2 public release.@{par}"
@macro cli "@{par}@{b}$1@{ub} [$2]@{par}"

@node main "Monolith's dynamic DNS client for the Amiga"

@{code}@{jcenter}@{b}
___________________________________________________________________________
____________@{bg shadow}      @{bg back}___________________@{bg shadow}      @{bg back}___@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}___@{bg shadow}     @{bg back}______________
____________@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__________________@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}   @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}_____________
____________@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}     @{bg back}___@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}    @{bg back}_@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__________________
____________@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}_@{bg shadow}    @{bg back}___@{bg shadow}     @{bg back}______________
____________@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}   @{bg back}_______@{bg shadow}  @{bg back}_____________
____________@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}___@{bg shadow}    @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}_____________
____________@{bg shadow}      @{bg back}_____@{bg shadow}  @{bg back}____@{bg shadow}  @{bg back}__@{bg shadow}  @{bg back}__@{bg shadow}      @{bg back}___@{bg shadow}  @{bg back}___@{bg shadow}  @{bg back}___@{bg shadow}     @{bg back}______________
_____________________@{bg shadow}   @{bg back}___________________________________________________

"Monolith's dynamic DNS client for the Amiga"

DynDNS v37.01 (8-Jun-97)
@{fg shine}_____________________________________________________________________________@{fg text}
ŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻŻ
@{ub}@{jleft}
  @{" Foreword      " link fore} Information about dynamic DNS
  @{" User's manual " link tech} Command line arguments and error codes
  @{" History       " link hist} Program's history
@{body}
@{title "DISTRIBUTION"}

This package is released under the concept of freeware, the package must
be distributed as one whole. The distributor may charge a fee up to the
cost of the medium for the entire package.

@{title "NO WARRANTY"}

This package is provided as is, without warranty of any kind, either
expressed or implied.
Should the package prove defective, you assume the entire cost of all
necessary servicing, repair or correction even if I have been advised of
the possibility of such damages.
I'm not responsible of the results of the use of the package.

@{title "SUPPORT"}

If you have any suggestions, bug reports, or wish to let me know something
about the package feel free to contact me at nsoggia@telnetwork.it

@endnode
@node fore "Foreword on DynDNS"

@{title "ABOUT MONOLITH AND DYNAMIC DNS"}

Monolith (http://www.ml.org) maintains a project named dynamic DNS, or
DYNDNS: if you do not have a static IP address, but instead recieve a new
IP every time you login, you can use their free service to get a fixed
host name under the dyn.ml.org domain.

@{title "ABOUT THE PROGRAM"}

Monolith DOES NOT endorse this program in any way.
The only way to update your database Monolith endorses is using a web
browser to update a form in their website. This client simulates a
browser sending data you typed in a form and makes some blind assumption
about monolith's web site structure, so it may fail if Monolith makes
radical changes to its site.

@{title "ADVANTAGES OF THE CLIENT"}

The client takes care of all technical matters, less critical data is
passed on the command line once. The client is faster than a web browser
and returns a condition code in case of error.

@{title "SECURITY"}

Your monolith id and numbers will be sent over an insecure path and no
attempt is made to keep this data secure. DynDNS is designed to protect
both Monolith's server and your Amiga against any attack or misuse.

@{title "ABOUT NAMES"}

Machine names can only contain letters from "a" to "z", digits from "0" to
"9" and a hyphen symbol (-), case insensitive.@{par}
If you pass a machine name that contains dots (.), the word after the last
dot will be used as machine name ("amiga.mynet" -> "mynet"), as Monolith's
DNS will reroute any access to "amiga.mynet.dyn.ml.org" to "mynet.dyn.org"
automatically.

@endnode
@node tech "DynDNS user manual"

@{title "REQUIREMENTS"}

DynDNS is a pure program that runs on any Amiga under Kickstart 2.0 or
later releases with 4 Kb or more of stack memory. It requires a
bsdsocket.library compatible TCP/IP stack to connect to Monolith's server.

@{title "TYPICAL USAGE"}

The typical usage is in the "startnet" (online) and "stopnet" (offline)
scripts: the DYNDNS service will not keep track of you going online and
offline, it is up to you to update the database each time you connect and
disconnect. If you forget to remove your machine from the dyn.ml.org
domain before you go offline, the domain you created will point to someone
else sharing the IP you used last time you registered. If you forget to
add your machine at logon either your domain will not exist or your domain
will point to the IP you used last time you connected.

@{title "SHELL USAGE"}

DynDNS accepts 5 mandatory arguments and 4 optional arguments:

@{cli "MID/A" "mandatory string"}
The monolith-id string you obtained from Monolith.@{par}
(e.g. "datta1")

@{cli "SEC1/N/A" "mandatory number"}
The Security number 1 you obtained from Monolith.@{par}
(e.g. "2" for 2-4-71)

@{cli "SEC2/N/A" "mandatory number"}
The Security number 2 you obtained from Monolith.@{par}
(e.g. "4" for 2-4-71)

@{cli "SEC3/N/A" "mandatory number"}
The Security number 3 you obtained from Monolith.@{par}
(e.g. "71" for 2-4-71)

@{cli "DOMAIN/A" "mandatory string"}
your machine name in the dyn.ml.org domain.@{par}
(e.g. "osiris" will become osiris.dyn.ml.org)

@{cli "WWW/S" "switch, optional"}
set this switch if your Amiga can offer www service, do not set this
switch if you don't have a www server running on your Amiga.

@{cli "ADD/S" "switch, optional"}
set this switch to add your domain for the first time or to add it after
you removed it (typically at logon), do not set this switch if you are
just modifying your domain.

@{cli "REMOVE/S" "switch, optional"}
set this switch if you want to remove your machine from the dyn.ml.org
domain (typically at logoff), do not set this switch if you want to add or
modify your machine name in the dyn.ml.org domain.

@{cli "LOG/K" "keyword, optional"}
give a filename to this keyword to save the HTML response from the
Monolith's server in a file. The file will be created only if DynDNS
successfully sends the request. If the file aleady exists (and is
writable) will be overwritten. Maximum file size will be limited at about
30 Kb.

@{title "EXAMPLES"}
@{code}
DynDNS datta1 2 4 71 add osiris
; add osiris under the dyn.ml.org domain (osiris.dyn.ml.org)

DynDNS datta1 2 4 71 isis
; change your machine name from osiris.dyn.ml.org to isis.dyn.ml.org

DynDNS datta1 2 4 71 isis www
; tell to the database that isis now offers www

DynDNS datta1 2 4 71 isis
; tell to database that isis doesn't offers www anymore

DynDNS datta1 2 4 71 remove isis log=ram:removed.html
; remove isis.dyn.ml.org from the database and save a log to ram-disk
@{body}
@{title "ERROR MESSAGES"}

TCP/IP error messages are translated as standard AmigaDOS localized
messages, the only custom error message is "unsuccessful response" and
happens when the HTTP server at Monolith doesn't aknowledge an "add" or
"modify" request. Return code can be OK (0) when all went fine, and FAIL
(20) for TCP/IP related errors, wrong command line, or when requests are
not acknowledged. FAIL conditions always have a diagnostic string on
standard output handle, OK condition is always quiet.

@{title "SCRIPT EXAMPLE"}

This script tries to add a machine named "osiris", if the add request
fails the script will assume the name is taken and tries to just modify
the IP address of osiris, if this second try fails, the script will open a
window to inform the user it failed. The user may get more details
clicking the "view report" button in the error window (note that
"your-browser" is a pseudo-command).

@{code}
failat 21
echo >ram:dyndns.html "<title>DynDNS failed</title><h2>No answer...</h2>"
dyndns >env:dyndns datta1 2 4 71 add osiris log=ram:dyndns.html
if fail
   dyndns >env:dyndns datta1 2 4 71 osiris log=ram:dyndns.html
   if fail
      setenv dyndns `requestchoice "DynDNS failed" "$dyndns" "View report" Ok`
      if $dyndns eq 1
         if exists ram:dyndns.html
            run your-browser ram:dyndns.html
         endif
     endif
   endif
endif
unsetenv dyndns
@{body}

@endnode
@node hist "History of DynDNS"

@{title "DEVELOPMENT"}

I write and test DynDNS on an A3000/060, before releasing each new version
to the public I test the program under Enforcer and Mungwall on Kickstart
3.1 and Miami 2.1a.

@{title "DYNDNS RELEASE HISTORY"}
@{rev "DynDNS 37.01 (08-Jun-97)" "First"}
@{msg "BUG(?)"}: monolith-id is filtered like the domain name: allowed
characters are [a-z] and [0-9], all other characters will be changed in
"-".

@endnode