vpncloud/ethcloud.md

ethcloud(1) -- Layer 2 VPN over UDP

SYNOPSIS

Usage:
    ethcloud [options]

Options:
    -d <device>, --device <device>         Name of the tap device [default: ethcloud%d]
    -l <listen>, --listen <listen>         Address to listen on [default: 0.0.0.0:3210]
    -t <token>, --token <token>            Token that identifies the network [default: 0]
    -c <connect>, --connect <connect>      List of peers (addr:port) to connect to
    --peer-timeout <peer_timeout>          Peer timeout in seconds [default: 1800]
    --mac-timeout <mac_timeout>            Mac table entry timeout in seconds [default: 300]
    -v, --verbose                          Log verbosely
    -q, --quiet                            Only print error messages

DESCRIPTION

Ethcloud is a simple layer 2 VPN over UDP. It creates an ethernet based network interface on the host and forwards all received frames via UDP to the destination. The forwarding is based on traditional switch behavior with MAC address learning. Whenever a frame is received, the sender UDP address and MAC address are associated and used for replies. Frames for unknown addresses will be broadcast to all peers. All connected ethcloud programs will form a peer-to-peer network and cross-connect automatically until the network is fully connected.

The token is used to distinguish different networks and discard foreign packets. It should be unique.

Ethcloud does not implement any loop-avoidance. Since data received on the UDP socket will only be sent to the local network interface and vice versa, ethcloud cannot produce loops on its own.

IEEE 802.1q frames (VLAN tagged) are detected and forwarded based on separate MAC tables. All frames without a tag will be treated as having tag 0.

The peer-to-peer protocol will cause nodes to exchange information about their peers. For nodes behind a firewall or a NAT, this can function as hole-punching.

NETWORK PROTOCOL

The protocol of ethcloud is kept as simple as possible to allow other implementations and to maximize the performance.

The first 8 bytes of each packet are the token that is used to distinguish different networks and sort out stray packets that do not belong.

After that, the 9th byte is a switch that determines the structure of the rest of the packet:

• Frame packet (value 0): This packet contains an actual ethernet frame which starts right after the switch byte and ends at the end of the packet. It contains the main ethernet frame data starting with the destination MAC and ending with the payload. It does not contain the preamble, SFD, padding, and CRC fields.

• Peer list (value 1): This packet contains the peer list of the sender. The first byte after the switch byte contains the number of IPv4 addresses that follow. After that, the specified number of addresses follow, where each address is encoded in 6 bytes. The first 4 bytes are the IPv4 address and the later 2 bytes are port number (both in network byte order). After those addresses, the next byte contains the number of IPv6 addresses that follow. After that, the specified number of addresses follow, where each address is encoded in 18 bytes. The first 16 bytes are the IPv6 address and the later 2 bytes are port number (both in network byte order).

• Get peer list (value 2): This packet requests that the receiver sends its peer list to the sender. It does not contain any further data.

• Close (value 3): This packet requests that the receiver removes the sender from its peer list and stops sending data to it. It does not contain any further data.

Nodes are expected to request the peer list from the initial nodes they are connecting to. After that, they should periodically send their peer list to all of their peers to spread this information and to avoid peer timeouts. To avoid the cubic growth of management traffic, nodes should select a subset of peers and send them a subset of their peer information. A reasonable number would be the square root of the number of peers. The subsets can be selected using round robin (making sure all peers eventually receive all information) or randomly.

Nodes should remove peers from their peer list after a certain period of inactivity or when receiving a Close message. Before shutting down, nodes should send the Close message to all of their peers in order to avoid receiving further data until the timeout is reached.

Nodes should only add nodes to their peer list after receiving a message from them instead of adding them right from the peer list of another peer. This is necessary to avoid the case of a large network keeping dead nodes alive

COPYRIGHT

Copyright (C) 2015 Dennis Schwerdel