ZEBEDEE(1)		     Zebedee		       ZEBEDEE(1)

NAME
       Zebedee --- a simple, free, secure tunnel program

SYNOPSIS
       Server:
	   zebedee -s [-dDtu] [-f file] [-k keybits] [-n name]
	   [-o logfile] [-r ports] [-v level] [-x config] [-z
	   level] [targethost]

       Client:
	   zebedee [-dDmtu] [-e command] [-f file] [-k keybits]
	   [-n name] [-o log] [-v level] [-x config] [-z level]
	   [[clientports:]serverhost[:targetport]]

       Key generation:
	   zebedee -p [-f file]

	   zebedee -P [-p] [-f file]

       Hash generation:
	   zebedee -h [file ...]

	   zebedee -H string ...

       Windows Service:
	   zebedee [-n name] -S [install[=file] | remove | run]

DESCRIPTION
       Zebedee is a simple program to establish an encrypted,
       compressed "tunnel" for TCP/IP or UDP traffic between two
       systems. This allows data from, for example, telnet, ftp
       and X sessions to be protected from snooping.  You can
       also use compression, either with or without data encryp-
       tion, to gain performance over low-bandwidth networks.

       The main goals for Zebedee are to:

       o   Provide client and server functionality under both
	   UNIX and Windows 95/98/NT.

       o   Be easy to install, use and maintain with little or no
	   configuration required.

       o   Have a small footprint, low wire protocol overhead and
	   give significant traffic reduction by the use of com-
	   pression.

       o   Use only algorithms that are either unpatented or for
	   which the patent has expired.

       o   Be entirely free for commercial or non-commercial use
	   and distributed under the term of the GNU General Pub-
	   lic Licence (see the CREDITS AND LEGALITIES entry
	   elsewhere in this document).

       Of course, Zebedee is by no means the first, or only
       secure tunnel program available. It does not pretend to
       compete with the likes of ssh or SSL in terms of breadth
       of function but if you want something quick, simple and
       completely free then it may be the tool for you.

       This document describes the features of Zebedee as at
       release 2.0.0.

       What's in a name?

       In case you were wondering, or even if you weren't,
       Zebedee is named after its three main components:

       o   Zlib compression

       o   Blowfish encryption and

       o   Diffie-Hellman key agreement.

       So now you know!

       Basic Usage

       To set up a secure connection between your local machine
       and a remote host you need first to run Zebedee in server
       mode on the remote system. The easiest way to do this is
       to run Zebedee with the -s option. Like this:

	zebedee -s

       If all goes well (and it should!) Zebedee will detach from
       the terminal (or console window under Windows) and run in
       the background. It will then be listening for incoming
       requests from clients.

       On your local machine you then run Zebedee in client mode.
       You need to specify the name of the remote machine and the
       name of the service or number of the port to which the
       tunnel should be established --- we will call this the
       "target" port. If the remote machine is called `remhost'
       and you want to set up a secure telnet session then you
       would run:

	zebedee remhost:telnet

       In fact, if you don't specify a service or port the
       default is telnet so

	zebedee remhost

       would do just as well in this instance. When you run this
       command it will print out a message telling you the port
       number which is the local end of the tunnel. Zebedee will
       then detach from the terminal and run in the background
       waiting for you to connect to the local port. If, for
       example, the port number it printed out was 1234 then to
       connect to `remhost' using the secure tunnel you would
       run:

	telnet localhost 1234

       By default, Zebedee will continue to listen for connec-
       tions and tunnel them, handling multiple simultaneous con-
       nections if necessary, until you terminate the process.

       Sometimes you will want to start Zebedee and then run a
       command that connects to the port straight away. You can
       do this in a single invocation of Zebedee as follows:

	zebedee -e "telnet localhost %d" remhost

       The "`%d'" in the string is automatically replaced with
       the local port number so there is no need for Zebedee to
       print it out. If you specify a command like this then the
       local Zebedee client will exit once the command closes its
       connection.

       You may want or need to control the local port number that
       the client uses.	 This is necessary if the command whose
       connection you are trying to protect expects to connect
       only to a specific port. In this case you can also specify
       the local port number by invoking Zebedee as follows:

	zebedee clientport:hostname:targetport

       So, for example, the command:

	zebedee 8000:webhost:80

       will allow you to secure all HTTP connections to webhost
       if accessed via port 8000 on the client system. See the
       EXAMPLES manpage for more details.

       You can also use a single Zebedee client to handle multi-
       ple simultaneous tunnels to different target ports on the
       same remote host. In this case the client and target port
       specifications are lists of ports. For example:

	zebedee 9001,9002,9003:somehost:daytime,telnet,ftp

       This will tunnel traffic on the clientport 9001 to the
       daytime port on the remote target system, traffic on 9002
       to the telnet port and traffic on 9003 to the ftp port.

       See the clientport and targetport keywords for more
       details.

       UDP Tunnelling

       Originally Zebedee was designed only to be able to handle
       TCP/IP traffic.	As of version 2.0.0 it can also handle
       connectionless UDP data. To enable this start Zebedee with
       the -u option (or use the udpmode keyword). For example:

	zebedee -s -u

       on the server host and

	zebedee -u 10000:somehost:echo

       on the client. Note that a single client or server can
       only handle TCP or UDP data, not both. If you need to tun-
       nel both types of data you must run two separate
       instances. It is safe run both a TCP-mode and a UDP-mode
       server on the same system because they use different
       ports.

       The tunnel between Zebedee clients and servers still uses
       a TCP/IP connection even in UDP-mode. This connection is
       timed out after a certain period of inactivity.	It must
       be re-established if more data arrives. For this reason
       the performance in UDP mode may appear poor, depending on
       the nature of the application using it. You should note
       that there is also a limit on the size of UDP datagrams
       that can be handled.

       For further details see the maxbufsize, udpmode and udpti-
       meout keywords.

       Some Terminology

       Usually there will only be two systems involved when you
       run Zebedee. You will run a client on one and communicate
       with it via connections to local ports. On the other you
       will run a server which will speak to services local to
       that machine.  However, there can be up to four different
       systems involved, as shown below:

	[source] <===> [client] <=====> [server] <===> [target]
		   |		   |		   |
		   +- insecure	   |		   + insecure
		      connection   |		     connection
				   +- secure tunnel

       The Zebedee client runs on the "client" system and the
       server runs on the "server" host. The inital connection
       that causes a tunnel to be established between client and
       server originates from the "source" machine. This could be
       a different system than where the Zebedee client is run-
       ning, although it is usually the same. The server will
       ultimately communicate with the "target" system. Again,
       this is usually the local machine but does not have to be.

       Most of the time you will not have to be concerned with
       the distinction between source and client and server and
       target. The terminology is, however, reflected in a number
       of the keywords described in the following section so you
       should bear it in mind when reading their descriptions.

       In addition to the different systems involved in Zebedee
       tunnel there are also several different types of keys used
       to secure connection. The client and server generate or
       are provided with private key values. These are used to
       calculate public values which are exchanged and used to
       derive a shared secret key using the Diffie-Hellman key
       agreement mechanism.  From this shared key a unique ses-
       sion key is derived to secure an individual connections
       between client and server.

       Configuration File

       The behaviour of Zebedee is probably best controlled
       through the use of a configuration file. A configuration
       file can be specified using the -f command-line option.
       The file is read at the point at which the option is
       encountered so later command-line options may override the
       contents of the file.

       Lines are of the form:

	key value # optional comment

       The key is a single, case-insensitive word. The value is
       either a single word or a string. Strings are enclosed
       either in double quotes (`"like this"') or single quotes
       (`'like this''). Double quotes may appear in single quoted
       strings and vice versa (`"here's an example"'). Case is
       preserved in the values where appropriate.

       Blank lines and lines beginning with a "`#'" (after any
       leading whitespace) are ignored. Long strings may be con-
       tinued onto the next line by ending the line with a "`\'"
       character. This character is eliminated and the next line
       is joined on to the end. Note that there is a limit of a
       total of 1024 characters on any line and its continua-
       tions. Line continuation happens before anything else,
       including comment recognition so the lines:

	server false
	# This comment continues on the next line \
	server true

       will leave the value of server as false.

       The keys and their meanings are as described below. Most,
       but not all, keys have equivalent command-line options.
       These are shown where available.	 There are also a few
       command-line options that have no equivalent in the con-
       figuration file. These are described at the end of this
       section.

       If a key is described as being a boolean then its value
       must be one of the words true or false.

       Several keys require a list of ports to be specfied. Where
       this the case the value is string that consists of a comma
       or white-space delimited list of port names, numbers or
       numeric ranges. For example "`telnet, ftp 5900-5903'".
       This is equivalent to the list
       "`23,21,5900,5901,5902,5903'".

       A number of the keys are either only applicable to clients
       or only applicable to servers. The same Zebedee program
       runs as either client or server and will silently ignore
       inappropriate options for the current type of usage. The
       choice of client or server behaviour is controlled by the
       server keyword:

       server (command-line -s)
	   This is a boolean indicating whether the program
	   should run as a client or a server. The default is to
	   run as a client if this key is not specified. The com-
	   mand-line -s option is equivalent to setting this key-
	   word to true.

2000-08-13		  Zebedee 2.0.0				6


