        dnsupdate - An automatic IP address updater for dynamic DNS
        -----------------------------------------------------------

    Copyright (C) 2003, 2004 Masaki Suzuki. All rights reserved.

    $Id: README,v 1.10 2004/06/01 22:41:43 masaki Exp $

    This file is free software; as a special exception the author gives
    unlimited permission to copy and/or distribute it, with or without
    modifications, as long as this notice is preserved.

    This file is distributed in the hope that it will be useful, but
    WITHOUT ANY WARRANTY, to the extent permitted by law; without even the
    implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.


    About
    -----

    Dnsupdate is an IP address update program written in Perl for dynamic
    DNS updates as defined in RFC2136. This program submits dynamic IP
    address update requests to a name server automatically.

    Dnsupdate gets a current IP address with a simple cgi program (included
    in this package) which is put on an external HTTP server, and it will
    send update requests to a name server only if the IP address at the time
    of the last update is no longer valid.

    Dnsupdate can be executed as a daemon which repeatedly updates IP
    addresses for a domain at a specified interval in the background.

    Dnsupdate can add or delete an address record for a domain manually. And
    it can also add or delete an alias for a domain manually.

    Dnsupdate is released under the GNU General Public License. Please see
    the file "COPYING" included in this package for more information.


    Requirements
    ------------

    Dnsupdate is written in Perl and uses Net::DNS module.
    More specifically, the requirements for this program are:

    1) Un?x operating system. (e.g. *BSD, Linux, etc.)

    2) Perl >= 5.004 and Net::DNS module.

       http://www.perl.org/
       http://search.cpan.org/author/CREIN/Net-DNS-0.47/lib/Net/DNS.pm

    3) A name server (BIND 8 or later) which allows to update with signed
       key on the server side.

       http://www.isc.org/products/BIND/

    4) A HTTP server for the cgi program used to get a current IP Address
       by dnsupdate outside the host on which dnsupdate runs.


    Installation
    ------------

    1) Extract the tar archive.

    2) `cd' to the directory containing the package and type `make install'
       to install the program, any data files and documentation.

       By default, `make install' will install a program named `dnsupdate'
       in `/usr/local/bin', man pages in `/usr/local/share/man', a sample
       config file `dnsupdate.conf.sample' and a cgi program `addr.cgi' in
       `/etc/dnsupdate'.

       You want to install the package in other directories, you can give
       `make install' the environment variables `DESTDIR', `PREFIX',
       `BINDIR', `MANDIR'.

       e.g. To Install the program file `dnsupdate' in `/usr/bin', the man
            pages in `/use/share/man' and other files in `/etc/dnsupdate',
            make DESTDIR=/ PREFIX=/usr install


    Preparations
    ------------

    1) Set up a name server (BIND 8 or later) on the server side to allow
       updating the target zone with signed key. For more information for
       the configuration of BIND, please refer to the BIND Administrator
       Reference Manual, named.conf(5) and dnssec-keygen(8).

    2) Put the cgi program `addr.cgi' in the cgi directory of an external
       HTTP server which you can use. Don't forget to set the file mode of
       it correctly.

    3) Put the key file which contains the secret string generated by
       dnssec-keygen of BIND somewhere.

    4) Configure configuration file.

       The default configuration file is `/etc/dnsupdate/dnsupdate.conf'.

       The following options can be used:

       # A domain name to be updated.
       DOMAIN = host.example.com

       # The URL of the cgi program which returns client's IP address.
       # `http://' and a port number are optional ones.
       CGI = http://ww.example.net:80/cgi-bin/addr.cgi

       # The file which contains the last updated IP address.
       ADDR_FILE = /etc/dnsupdate/host.example.com

       # The name of the key. (an optional parameter)
       # If the key file which is set by the parameter `KEY_FILE' is only a
       # secret string, tihs parameter must be set.
       KEY_NAME = name

       # The key file which is generated by dnssec-keygen of BIND or
       # contains the secret string.
       KEY_FILE = /etc/dnsupdate/example.key

       # The value of ttl. (an optional parameter)
       # the default is 600 in seconds
       TTL = 600

       # Update interval for a daemon. (an optional parameter)
       # the default is 600 in seconds
       INTERVAL = 600

       # The pid file for a daemon process. (an optional parameter)
       # A relative pathname is set under `/var/run' directory.
       # the default is `/var/run/dnsupdate.pid'
       # e.g. `/some/where/dnsupdate.pid' or only `dnsupdate.pid'
       PID_FILE = dnsupdate.pid


    Usage
    -----

    dnsupdate [option]...

    [argument] is an optional argument.

    The following options can be used:

        --add address
                    Add an address record for the target domain manually.

        --del address
                    Delete an address record for the target domain manually.

        --addalias alias
                    Add an alias for the target domain manually.

        --delalias alias
                    Delete an alias for the target domain manually.

    -c, --config config_file
                    Set the configuration file which is used by dnsupdate
                    instead of the default.
                    The default configuration file is
                    `/etc/dnsupdate/dnsupdate.conf'.

    -d, --daemon [interval]
                    Execute dnsupdate as a daemon which updates an address
                    record for the target domain in the background.

        --debug, --verbose
                    Display verbose messages for debugging.

    -f, --force     Update ignoring the saved IP address, if possible.

    -h, --help      Display help information and exit.

    -i, --interval interval
                    Set update interval. It overrides the configuration
                    parameter `INTERVAL'.
                    The defaults value of `interval' is 600 in seconds.

    -k, --key [key_name:]key_file
                    Set the key name and the key file. `key_name' and
                    `key_file' override the configuration parameters
                    `KEY_NAME' and `KEY_FILE'.
                    `key_name:' is an optional argument. It needs in case a 
                    key file contains only a secret string.

        --kill      Terminate the daemon process which is running.

    -l, --log [log_file]
                    Log messages to the `log_file'.
                    `log_file' is an optional argument.
                    The default log file is `/var/log/dnsupdate.log'.

    -q, --quiet     Display nothing but stderr.

        --reload    Reload configurations for the daemon which is running.

        --restart   Restart the daemon which is running.

    -t, --ttl ttl   Set the ttl. It overrides the configuration parameter
                    `TTL'.
                    The defaults value of `ttl' is 600 in seconds.

    -v, --version   Display version information and exit.


    If you have an internal network with a NAT gateway, you will have to run
    the dnsupdate on an internal machine. because the dnsupdate needs to
    know the external address of the NAT gateway and must be able to check
    whether that address has changed.


    For More Information
    --------------------

    The World Wide Web page is "http://www.btree.org/dnsupdate/".

    Please send any questions or bug reports to <masaki@btree.org>.

