tzoupdate - TZO client for (much) any version of UNIX or Linux
Version 1.12 released October 2008
############################################################################

I - INSTALLATION INTRODUCTION

This is a simple installation guide suitable for the majority of Linux or
UNIX platforms. Additional documentation is referenced

Fully-supported Linux systems are best served by the provided 'package'
installers for those distributions (currently RedHat, CentOS, Ubuntu, 
and Debian). 

Other Linux distributions are supported however they are
manual installs. In most cases, you verify you have GCC installed
then simply run `make install` to get the tzoupdate software installed.

A complete 'walk through' of an installation is provided at the Support
section of the TZO.COM website.


II REQUIREMENTS AND DEPENDENCIES

NOTE: Never run the same domain name in MORE than one TZO Update client,
as this causes Update Abuse.

For RedHat, CentOS, Ubuntu or Debian:
1) You do not need to compile tzoupdate - just use the appropriate .rpm or
deb install package.  

For other Linux or UNIX (manual installs):
1) You need a fully working GNU TOOLCHAIN (inc. GCC and Make).
NOTE: Sun Solaris or SCO UNIX development tools are KNOWN TO FAIL.
Adding GCC tools may enable a build workaround, however you must test your
GCC build environment (example: you can also compile 'wget').
ALTERNATIVELY -- the compiled tzoupdate packaged as a .tar.gz or .zip file
MAY work on your Linux install (this type of error would not hurt the
system. Of course it becomes extra important to validate the first update).


III - INSTALL OPTIONS


OPTION #1) For REDHAT, CENTOS, UBUNTU, DEBIAN ONLY:
1) Install the .rpm/.deb release package for your OS
Remember, while the client is installed, it is not configured and is not 
running.

OPTION #2) MANUAL INSTALL - FOR OTHER LINUX/UNIX OR OS:
1) CAREFULLY review the Makefile, and if the file locations look OK to you 
simply run MAKE INSTALL.

OPTION #3) PATCH the tzoupdate client source so it installs cleanly on 
your OS:
1) tzoupdate has no dependencies outside kernel and stdlib functions.
2) Any distribution-specific patches are gratefully accepted; please send
modifications or diffs to devsupport@tzo.com


PLEASE NOTE
Linux installation questions should only be directed to support@tzo.com.


IV - CONFIGURATION

Use your favorite plain-text editor, open /etc/tzoupdate.conf and populate
the default values for your domain name, TZO Key, and email EXACTLY as
in the email from TZO. Avoid adding spaces and avoid using the www. prefix.
The fields for email and TZO key act as the domain's username and password,
and should match the case form used in your TZO email or on the TZO website.

Depending on your OS configuration, you probably need to do this from a
'root shell' or Terminal instance with root capability. vi is used as the
example text editor, but 'nano', 'pico', 'emacs' etc. also work great).

On most Linux systems you first execute 'su -' in a shell to become root),
and then you would edit your conf, for example: 'vi /etc/tzoupdate.conf'.
On Ubuntu and some Linux, you do this differently and in just one step:
'sudo vi /etc/tzoupdate.conf' (when prompted for your password, it wants
your OS login password before you can edit the file).


V - TEST RUN AND VERIFICATION

At a regular terminal (as a normal user context, not root) type:
/usr/local/bin/tzowrapper.sh

NOTE: During this test run of TZO, you are not permanently starting TZO
and therefore you do not need to send the application to the background.
Just leave tzowrapper.sh running for now.

If there were a major problem (such as a typo in your domain name), TZO 
will report a fatal error and do a complete client stop. Otherwise, all
other output gets written to /tmp/tzoupdate.txt.

Now open a NEW Terminal, and view the output:
cat /tmp/tzoupdate.txt

tzoupdate.txt contains extra status text useful for debugging, but you can
skip straight to the end of the file for the client result. If the update
was successful, that outcome is logged. If the update was "not needed"
because TZO already had your current IP, that is logged as well (hopefully
you are not running more than one TZO client for your domain name..). Fatal
or unrecoverable errors should always suggest bad account info in your
tzoupdate.conf.

VI - TELL THE OS TO START 'tzowrapper.sh' at during PC boot-up

If the test run did not reveal any errors, then (in a root context)
run vi /etc/rc.local, adding the following at the end of the file:

/usr/local/bin/tzowrapper.sh &

Note this time the & ampersand, which puts TZO in the background. Save the 
file then exit. Now instruct your system to REBOOT. 

When your system is back, check the /tmp/tzoupdate.txt logfile. 
This time the logfile is probably much shorter, and indicates 
"no update was required". The reason for not updating is because TZO already
has your current IP address.

VII - WHAT COMES NEXT?

Now TZO is configured to start with your PC, and ALWAYS ensure that your 
domain name points to your Internet IP held by your modem. 

From here, you can begin configuring or testing your network or server.


TROUBLESHOOTING

There are only two tests needed to isolate domain or server failures.

1) DNS
Use 'nslookup', 'host', or 'dig'.
Example:
dig example.tzo.com A -trace
This will trace the 'A' record of example.tzo.com, starting from the root
servers.

Avoid using 'ping', because ping will report a failure if the target
address does not respond to ICMP requests (many routers block this).

Write down the IP that the DNS test resolved to. Then manually check
the server's Internet/WAN IP. From the server itself, you can browse to
http://test.tzo.com/ and then compare the WAN IP detected. Or you can
get the servers connection IP by checking the router used by the server
(look for Connection IP/WAN on the STATUS page).

If the WAN IP matches the DNS record, then the problem is network related.
You can further demonstrate or isolate this by having the outside test
helper connect to your WAN IP and port 'directly'. This bypasses DNS.

Example, if this were a network camera running on port 82 @ 123.123.123.123:
http://123.123.123.123.ip:82/

For more troubleshooting tips, please see the TZO.COM Support site.

VIII - UNINSTALL

For a rpm or deb installation, use your OS package manager to remove tzoupdate.

For manual installations, simply reverse your installation steps (or you can
just comment out the TZO line you added to your rc.local, then reboot).


Copyright Tzolkin Corporation, 2007-2008
