Zendemic

Zendemic Tunnel README

Zendemic Tunnel README
http://zendemic.net


WHAT IT IS
----------

Zendemic Tunnel is a program that allows you to create TCP connections between two nodes
on the Zendemic network.

Once you have configured and created a tunnel, you can point any program that makes TCP
connections at the tunnel and the connection will continue on the other end.

So for example, if you were to run a mail server at your house behind your firewall but
wanted to be able to access your mail server from your laptop at a friend's house, you
could set up a zendemic tunnel to connect port 110 (POP3) on your laptop to your mail
server at home. Once the tunnel was set up, you could tell the mail client to connect to
a user specified port on localhost and the connection would travel through the tunnel to
port 110 on your mail server.

You can do this with any TCP protocol including HTTP and SSH. Ssh is handy because once
you make an ssh connection, you can easily tunnel anything else you may have already set
up over that.

I suppose one humorous use of Zendemic Tunnel would be to tunnel zendemic server
peer connections.


REQUIREMENTS
------------

As Zendemic Tunnel is a java application it will not work without an installation of
java. Java 1.6 or later is required.

Zendemic Tunnel is a Zendemic application and thus requires a running installation of
Zendemic to work.

There is no Android version of Zendemic Tunnel at this time.


INSTALL
-------

The installation file is provided as a zip file. There is no special installation
procedure other than extracting the installation zip file into the base zendemic folder.

If you have not installed Zendemic yet, please go to http://zendemic.net and download the
Zendemic install zip file and create a folder for the installation and extract the zip
file there. That directory is the "base zendemic folder" into which all Zendemic
application install zip files should be extracted to.

Please read the README_ZENDEMIC.TXT file from the Zendemic installation zip file for more
detail on how to install and configure Zendemic.


CONFIGURATION
-------------

Zendemic Tunnel is intended for advanced users who are familiar with hand editing
configuration files, so it does not include a web interface like Zendemic Sync does.

There is one configuration file zendemictunnel.cfg located in the zentunnel directory
within the base zendemic folder after installation. A sample configuration is supplied.

There are two sections of configuration that can be set, one for client side tunnel setup
and one for server side tunnel setup.

A tunnel configuration requires that you define the list of ports on the client side that
you wish to connect to on localhost that will tunnel the connection to a mapped set of
ports on the server side.

So for example if you wanted to make a tunnel to connect to a web server you could
configure local port 8000 to connect to remote port 80.

You would configure the port 8000 part in the client's zendemictunnel.cfg file, and the
port 80 part in the server's zendemictunnel.cfg file.

One tunnel instance allows for multiple connections on the same tunnel map (8000->80) and
it supports multiple tunnel maps in one running instance. This collection of tunnel port
mappings is referred to as a host, in the configuration file.

You can define multiple hosts, so that you can configure different port tunneling setups
for different needs.

The first thing you must configure to define a host on both the client and server side is
the password for that host. This secret password is the key used to encrypt data over the
tunnel and is used to uniquely identify a particular server host when looking on the
Zendemic network for a particular host name.

So for example, you decided to set up a tunnel for your machine at your home, and called
it 'home'. You would add this line to both the client and server config files.

hostpassword-home supersecretpassword

Then if you wanted to set up a tunnel between the client to connect to port 80 on the
server you would add this on the client side:

portmap-home-1 8000, 80

And this on the server

hostallowedports-home 80

This tells the tunnel application to set up a tunnel that will listen on localhost:8000
on the client and tunnel connections to port 80 on the server. The server side of the
configuration is just to ensure you don't allow any connections that you don't intend, so
you must define what connections you will allow for a given host on the server.

With this set up you can make many concurrent TCP connections to port 8000 that will
tunnel to port 80 on the server side. To define multiple ports for one tunnel instance,
you would do this on the client side:

portmap-home-2 110, 110 portmap-home-3 2222, 22

These two port mapping will additionally listen on localhost:110 and localhost:2222 on
the client and connect to ports 110 and 22 on the server respectively.

To enable them on the server side, you would CHANGE the allowed ports line to this:

hostallowedports-samplezendemictunnelhost 80, 110, 22

There is only one line that lists all the allowed ports for a given host definition on
the server side. On the client side, you must add a configuration entry for each port map
you want to add. You must number them sequentially starting from 1. And if you skip a
number, no higher numbered port maps will be picked up.



RUNNING
-------

The tunnel once set up only runs in one direction, if you wanted to be able to make
connections from the server to the client, you must set up a separate tunnel making the
server machine be the client, and the client machine being the server.

When starting up a tunnel, you initiate the process from the client side, and if
configured and registered, the server side will be started by the Zendemic server on the
server machine.

There is one important caveat to getting this process to work.

The Zendemic server maintains a list of registered applications. You can see the current
list in the Zendemic Console. This is the list of applications and groups within those
applications that the Zendemic server will respond to as supporting that application and
recognizing that group.

In the context of the Zendemic Tunnel application, a group is synonymous with a host
definition. References to group names mean the same thing as references to host names.

An application registers with the Zendemic server the first time it runs and is able to
successfully connect to the local Zendemic server.

When starting up a tunnel for the first time from the client side, the tunnel application
registers itself with your local zendemic server. But the server side has not run yet so
the server will not answer to requests to start up a tunnel until it has been configured
and registered with the local Zendemic server on the server side.

You perform this action simply by configuring a host on the server side, and attempting
to start a tunnel for that given defined host. The tunnel can or will fail, but the
attempt will cause the tunnel application to register with the Zendemic server so future
requests from real clients will work.

With other applications like Zendemic Sync, the registration process is handled by the
web interface, but the tunnel application was intended for advanced users and doesn't (at
least yet) include a web interface.

So once you have completed the client and server configuration and have registered the
tunnel application on the server side, you stat up a tunnel instance by running the OS
appropriate script:

run_zendemic_tunnel.bat <host name> (windows)

run_zendemic_tunnel.sh <host name> (unix)

Where the host name is the name defined in the config file.

The tunnel will start up and remain active until either the client or server application
are stopped or connectivity on the Zendemic network between the two nodes is lost.

There is a log file zendemictunnel.log you can look at for information if there are
problems setting up the tunnel.


HOW ZENDEMIC WORKS
------------------

It might help to have an understanding of how the Zendemic network works to see how the
whole tunnel application functions when trying to diagnose a tunnel creation problem.

The Zendemic network is made up of nodes. Each node is a running instance of the zendemic
server program. The zendemic server is responsible for finding and connecting to other
zendemic servers thus forming the Zendemic network.

Each node can participate in one or more zones. Rather than have every node try and
connect to every other node on the internet, zendemic has a way of breaking up nodes into
little networks by a named zone. By participating in multiple zones, your zendemic server
can reach more nodes in a particular zone even if it is not directly attached to them and
this way not every zendemic server has to be in one giant network group.

The number of connections a zendemic server will try to connect to per zone is configurable (default of 3)
up to a maximum total number of connections which is also configurable (default 25).
These numbers can be changed via the zendemic console or by directly editing the zendemic.prefs config file.

Once a set of peers are connected to each other, you can run applications that use the zendemic network.

An application must run on the same machine as the zendemic server because it needs to use the zendemic
server to communicate with the other node running the application. The application deals with the application
level data, and the zendemic server worries about getting the information back and forth between nodes.

When a zendemic application starts up, in general it will be configured to speak to another instance of itself
somewhere else on the zendemic network in one of the zones you share, although this is not required. It is possible
to connect two instances of an application that do not participate in the same zone if they are joined by
a zendemic server that participates in both zones.

Applications have no concept of zones, they are concerned with groups. The zone concept exists solely to limit
the size of the network from becoming all nodes on the internet. This may change in the future if it turns out
that this limitation isn't restrictive enough.

The application will find other instances of itself by sending a broadcast request out to
all zone-connected nodes asking each if it is part of the application group that the
request came from. Each zendemic server has a list of registered applications, and groups
within the application that it will response to broadcasts for. This list can be viewed
in the zendemic console or the registeredapps.txt file.

If your zendemic server has an application and group name registered for a broadcast, it will respond to the
original requesting node saying that they are part of that group and can be called on to run the application for
that group.

The client side of the application can now request that the recently found zendemic server node answering to
the broadcast request, start up a server instance of that application. Once that happens and the server side
of the application is able to start up and respond, the application can communicate back and forth via the
zendemic network.

From there on, the applications do their thing, and the zendemic server serves only as a packet router.

All application data is encrypted using a key configured specific to the group and application.
If the passwords do not match on both sides, the server instance will not start up. This is also the main
form of security on the zendemic network, so when you create application and group passwords, keep them
secret.

If you have an application set up with an easy to guess group name and an easy to guess password, anybody
on the zendemic network will be able to connect to that application.

These are the basics of how the zendemic network works.








CONTACT INFORMATION
-------------------

http://zendemic.net will be updated with information as it becomes available. If you have
a question or comment email info@zendemic.net

---