 ___       _       _ _ _ _
/ __| __ _| |_ ___| | (_) |_ ___
\__ \/ _` |  _/ -_) | | |  _/ -_)
|___/\__,_|\__\___|_|_|_|\__\___| v1.0.2

Satellite is covered by the GNU GPL. See the file "COPYING" for details.

General
-------

Satellite was written to keep track of many remote machines with
dynamic IP address. Public DNS servers are often used, but they suffer
from several problems:

- Failure.
Public DNS servers regularly fail due to overloading and sysadmin
problems.

- No notification.
There is no notification when a system goes online. Instead you need
to poll DNS regularly until the system comes online.

- Latency.
Updating can take from several minutes to several hours before the
change is made public. On systems with small idle timeouts it is often
impossible to find the current IP address via DNS.

- No dialup history.
Public DNS services only keep track of the current address and don't
record past times or changes.

Satellite goes direct from the client machine to your server,
bypassing many problems.

Each client is represented by a "token/secret" pair on the server.
This pair is used to authenticate the client with the server. On the
server the token is used to identify a particular client. The "secret"
is never transmitted across the net, and is only used to generate the
correct response to the server's challenge. You don't want a 3rd party
impersonating one of your servers.

Once the identify of the client is agreed upon the client token, IP
address and any message is logged. Optionally, satellited can run a
program to alert sysadmins or whatever you need. You will find an
example script called "satalert.sh" in the "scripts" directory of this
archive.

Also contained in this archive is "satwatch". It watches the log file
for a specific system to log on. It immediately displays a message
with the IP address of the system & any message contained. It tries to
keep the machine online for a small amount of time.


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

Satellite requires the GNU dbm library - gdbm. Most Linux
distributions should contain the library and install it by default. If
you are running *BSD check your ports collection. If you don't have
gdbm you can download it from ftp://ftp.gnu.org/gnu/gdbm/.


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

You can create an RPM from this archive by running:
# rpm -tb satellite-1.0.1.tar.gz
RPM will tell you where it has written the binary RPM just before it
finishes. If you are installing from the RPM ignore the server post
installation instructions below and follow RPM recommendations
instead.

If you don't use RPM you can compile from the source.

Useful configure options:
--help			Show basic configure help
--localstatedir		Directory for the satellite log file
--sysconfdir		Directory for the satellite configuration file

Under Linux run:

# ./configure --localstatedir=/var/log
# make
# make install

Under *BSD you may need to tell configure where to find gdbm:

# CPPFLAGS=-I/usr/local/include LDFLAGS=-L/usr/local/lib \
  ./configure --localstatedir=/var/log
# gmake
# gmake install


Post installation setup [SERVER]
--------------------------------

For security reasons you should create a separate system account to
run the server. In following examples I've chosen "satuser". You will
need to check the pathnames match your system.

1) Add a line to your /etc/services so inetd will recognise the service:

satellite       1764/tcp

2) Add the satellited line to /etc/inetd.conf:

satellite stream tcp nowait satuser /usr/local/sbin/satellited satellited -v
   OR
satellite stream tcp nowait satuser /usr/sbin/tcpd /usr/local/sbin/satellited -v

   Use the second line if you want to use TCP Wrappers for access control.

3) Create the initial configuration & log file and change the owner to the
   system account created earlier:

# satcfg -L
# touch /var/log/satellite
# chown satuser /usr/local/etc/satellite.db /var/log/satellite

If you decide to change any of the install directories or the username
remember to modify the above example appropriately.

Now you can run "satcfg -a TOKEN SECRET" to add your token/secret pairs
and the server can start answering requests.


Post installation setup [CLIENT]
--------------------------------

Add satellite to your interface up scripts. For systems running pppd
this will often be either /etc/ppp/ip-up or /etc/ppp/ip-up.local:

satellite SERVER CLIENT SECRET

SERVER		Your central satellited server IP address or hostname.
CLIENT		The token chosen to represent this particular client on the
		server.
SECRET		The corresponding SECRET from the token/secret pair on the
		server.

If you don't want to specify the SECRET on the command line, satellite
can read it from a configuration file. See the man pages for details.

On the client side you can specify the server using either a valid DNS
hostname or an IP address. Using a hostname will let you move your
server without having to update each of the client machines. If there
are problems with DNS you may find your server stops receiving
updates. Using a hostname adds an extra layer that can potentially
fail.

Using an IP address avoids any potential problems DNS, but makes it
difficult to change the location of the server. If you don't plan on
moving the server and/or you don't have too many clients to modify,
this may be the better choice.


Feel free to email me if you have any problems, comments or
suggestions.

Mark Pulford
mark@kyne.com.au
