README

      __                __ ___ ___ ______ _______ 
.----|  |-----.--.--.--|  |   |   |   __ \    |  |
|  __|  |  _  |  |  |  _  |   |   |    __/       |
|____|__|_____|_____|_____|\_____/|___|  |__|____|
                                                    

The multi-purpose cloud&open VPN by [exa]



Project goals:

Create a  network that consists of nodes with equal functionality, which are
connected in a mesh of any shape. One such mesh can effectively transport
packets of multiple protocols.

Optional goals:

Don't use a single malloc(), only stack/STL allocation allowed. (success!)



Made by:
[exa] exa.exa@gmail.com

License:
GNU GPLv3 (see LICENSE file)

Website:
http://e-x-a.org/?view=cloudvpn

(if you are not searching for technical info, check the quick howto:
http://e-x-a.org/?view=cloudvpn-howto )



Contents:
1] Terminology
2] Internals
3] Protocol
4] Compiling
5] Configuration

*********************************************************** TERMINOLOGY *******


To achieve the goal of having CloudVPN as good as it should be, we need to
split it to several parts that work independently, and are freely pluggable.

Base part of the tools is called CORE. That is most similar to the old
CloudVPN, in means of connecting the peers to the mesh, and routing information
through the resulting network.

As we want the inlying protocol independency, the core is free from any
protocol-specific stuff. This means that Ethernet "TAP backends" and similar
communication agents are moved from the core to separate programs, which
connect to core using a special protocol, announce themselves, and send/receive
packets, expecting that core will eventually mesh them correctly to marked
destinations. Those programs will be called CLIENTs. The connection between
client and mesh core is called GATE.

This requires core to distinguish between PROTOCOLS, so that it knows which
addresses are in one protocol and which aren't, and also whether given gate
will accept a packet or not. Therefore, gate implementations will have to agree
on a globally unique identifier of given protocol. (note: do not confuse
protocol IDs with next readme chapter called "protocol" because of describing
packet structures)

We might want to route more separate networks of one protocol on one mesh. This
implies that Protocol identifier will be needed to be combined with INSTANCE
identifier. Because of similarity of those identifiers, they are gonna be
united in higher/lower parts of a 32bit integer called just "instance".



************************************************************* INTERNALS *******


This section describes all the hacks used in how routing works.

Every node in the network handles packets, pings, and route information.

Packet is an unified datagram with source address, destination address, and
data, that comes also with a broadcast packet ID and TTL entry.

TTL and packet ID exist only for avoiding packet duplication.

Route information is an address-destination info shared among nodes. Route
entry consists of address, measured ping to given address, and distance of
address.

Route entries are sent as a block, but, better, as a "diff" from last state.

All route entries from all connections are merged to a table, which provides
fast packet-routing-direction lookup.

Clients connected to the mesh node can provide list of "their", local
addresses, which must not be broadcast. Those packets are then routed to them.



************************************************************** PROTOCOL *******


This section describes how CloudVPN core communicates with other cores, gates,
and authenticators.

1] Addresses

	Address is a arbitrarily-long sequence of bytes with instance prefix.

	The Protocol/Instance prefix of address is written in (full) 8 hexes
	before the address, separated by . Should be written this way:

	0001.0003.4c:00:10:02:34:56

	Note that, because of ease of parsing, THIS is not the same address:
	1.3.4c::10:2:34:56

	But this IS the same address:

	000100034c00103b83ad

	Adresses are matched by prefixes. That makes the packet with given
	address come not only to the destination with exactly the same address,
	but also to all destinations that request any prefix of given address,
	or any destinations whose prefix begins with given address. Therefore,
	among other:

	- instance-only destination means that packet is broadcast
	- instance-only route means that route is promiscuous
	- you can send a packet to whole "subnet" using a shortened destination
	- you can route whole subnet to yourself by the same way

2] Packet format
	
	Packet, in its basic form, incorporates:
	- instance ID
	- source address
	- destination address
	- payload

	Because we need interoperability with all possible protocols that
	place addresses on many different places and assign different sizes
	and addresses, but don't want to write those so-long addresses twice,
	those are indexed from the packet payload:

		PACKET---
		32b packet ID
		16b packet TTL
		32b instance ID
		16b dest offset
		16b dest size
		16b source offset
		16b source size
		16b payload size
		payload

	This adds 20 bytes header to each packet, which is acceptable.

3] Route entry format
	
	Route entry tells us:
	- distance of given destination
	- time needed to reach given destination
	- address of it

		ROUTE ENTRY---
		32b ping (measured in usec. gives us around 1.2 hour max ping.)
		32b distance (measured in hops)
		32b instance
		16b address size
		address

	Totally, this gives us 14 bytes + address size.

4] Inter-node protocol

	This protocol is used to guide communication between mesh cores. Most
	of it is implemented by "comm" module.
	
	Packet format is classical header-data.

		PACKET-HEADER---
		 8b type
		 8b special
		16b size
		payload

	Type is meant as "command" and can have values:
	1 - route-set         -- used to report state of routes
	2 - route-diff        -- used to update state of routes
	3 - packet            -- used to send packets
	4 - echo-request      -- ping
	5 - echo-reply        -- pong
	6 - route-request     -- used to request complete route-set packet

	Special field is used for ID-ing the pings, otherwise it should be zero.

	Size is a byte-size of the payload.

	Payload can contain:
	- packet structure, in case we transfer packet
	- list of route entries when we report or update route informaton
	
	When handling route-diff, and remote ping is equal to zero, it means
	that the route is no longer available. Ping should otherwise never
	be equal to zero (1 is minimum), even in case of route-set.

5] Gate protocol

	Gate protocol basically allows clients to connect to mesh core,
	send and receive packets using it, and announce its "local" addresses.

	Note that gate connection is not supposed to be encrypted, and is
	essentially meant to be "private", just as its listening socket is.


	Gate protocol uses header-data format too.

		GATE-HEADER---
		8b type
		16b size
		payload

	Size means the size of payload.
	Type can have following values:

	1 - keep-alive  -- client sends those back to core to verify activity
	2 - route       -- client sends this to core to report addresses
	3 - packet      -- data transfer

	keep-alive requests are sent to client periodically, and client is
	expected to reply as fast as possible. If client fails to reply several
	times, he might be considered dead, and disconnected.

	route requests are sent from to core to announce that certain addresses
	are reachable at the client side. it is followed by a list of simplified
	route entries:

		GATE-ROUTE---
		16b size
		32b inst
		address

	packets are sent by both sides, to enable data transfer



************************************************************* COMPILING *******

We use standard GNU Autotools scheme, with script-generated Makefile.am.
Because of simplicity, all auto* stuff is wrapped in single shell script now,
called autogen.sh (but it's not classical autogen.sh!).

Therefore, compile like with any other autotools project:

$ ./autogen.sh
$ ./configure && make && make install

Please remember to add -Ox optimization to CXXFLAGS. CloudVPN makes heavy usage
of STL routines, which, unoptimized, are REALLY slow.

If you hit compile errors, be sure to check that following things are available:

 - correct polling device for your platform, and headers for it
 - STL-capable compiler (any gcc should be good)
 - GnuTLS library version 2.6 or better

To compile CloudVPN for Windows, you will need some kind of MinGW with enough
libraries (GnuTLS&co.), and then configure this:

$ LIBS="-lws2_32" ./configure --host=mingw32

Because of library compatibility, many people asked about compiling CloudVPN
tools statically. This can be easily achieved with autotools. This works in
most common cases:

LDFLAGS=-static LIBS="-ltasn1 -lgpg-error -lz" ./configure

(and then continue like everytime.)
LIBS are needed because gcc doesn't resolve library dependencies when static
linking is active. You might either need more libraries, or maybe none of those.



********************************************************* CONFIGURATION *******


This section lists all configuration options available for running CloudVPN
core and some of the most important CloudVPN gates/auth daemons.

First off, you will most probably need some keys. To generate some, you can use
any openssl or gnutls howto available on the net, or just follow simple
GnuTLS's certtool instructions here:


	GENERATING KEYS AND CERTIFICATES

First, generate a CA key (DSA, 3072 bits):
$ certtool -p --outfile ca.key --dsa --bits 3072
(remember to keep this key for yourself)

Then, make a self-signed certificate of that authority:
$ certtool -s --load-privkey ca.key --outfile ca.crt
(now you must fill in several options - be sure to check that this key can be
used for signing certificates, and as a certificate authority)

Now we need a private key for encryption. Let's use RSA one:
$ certtool -p --outfile ssl.key --bits 4096
(you should check whether using RSA key of given size is legal in your country)

Now, sign the certificate using the generated CA:
$ certtool -c --outfile ssl.crt --load-privkey ssl.key \
    --load-ca-privkey ca.key --load-ca-certificate ca.crt
(you will be asked the same questions as those from CA self-signing - you
should now disable signing of certificates, but instead enable TLS server and
client purposes.)

Also, you might need some generated DH parameters - this can be done easily:
$ certtool --generate-dh-params --bits 1024 --outfile dh1024.pem
(you will need to remove extra lines from the .pem, so GnuTLS can read it
properly. Just make sure that the very first line of the .pem file looks
exactly like "-----BEGIN DH PARAMETERS-----")


	PROGRAM CONFIGURATION

Program options consist of pairs name/value, which can be specified on
commandline (using 'program -name value -name value' syntax), or using config
files, where name/value pairs are written line-by-line, first word of each line
being name, rest value. #-beginning lines are comments.

There's a special @include option, which loads the config file. So, to start
something with a config file, you can use 'program -@include /etc/program.conf'

Boolean values are used with 'yes' or 'no'. Also, note that multiple options of
same name can be specified and valid. If program needs only one of given
options, then the last specified one is valid. When setting a number, start
with 'x' character to set a hexadecimal value.

Note of a warning: following list is a list of _all_ options, and 80% of them
are unusuable for normal people (moreover, those will usually break something).
If you are searching some good default configuration, check the website first.


	COMMON among all programs
user
group
chroot
mlockall	--security options

max_input_queue_size   --memory limit

tcp_nodelay
ip_tos
listen_backlog	--socket parameters


	ETHER

instance
proto		--dont set this, its good as it is.
promisc		--usuable for bridging

tunctl		--TAP configuration
iface_dev	--dev name
iface_persist	--persistent bool

gate		--cloud connection point

tap_component_id tap0901
		--name of TAP you installed on Win32. tap0901 is for the latest
		--Tap-win32 from OpenVPN-2.1.x. If it doesn't find one, and
		--you are sure that you installed a TAP, try some others,
		--like tap0800, tap0802, or tap0801co (from coLinux)

	CLOUD

heartbeat
poll_interval

ca
key
cert
crl
dh

comm_close_timeout
conn-mtu
conn_keepalive
conn_retry
conn_timeout
max_connections
max_remote_routes
max_waiting_data_size
max_waiting_proto_size
max_gates

connect
gate
listen

packet_id_cache_size
route_broadcast_ttl
route_max_dist
route_hop_penalization
report_ping_changes_above
multipath
multipath_ratio
shared_uplink

status-file
status-interval
status-verbose

tls_loglevel
tls_prio_str

red-ratio
uplimit-burst
uplimit-conn
uplimit-total
downlimit-burst
downlimit-conn
downlimit-total