Beacons
Beacons are a way to publish and retrieve addresses of nodes outside of the VpnCloud network in order to find new peers. This can be very helpful in cases where all nodes of the network have dynamic addresses or when the nodes with static addresses are not always reachable.
The main idea behind beacons is that VpnCloud provides means of exporting and importing beacons from files of by executing scripts, and the user is responsible for publishing and retrieving them on other nodes.
The beacons have some useful properties to help users:
- The beacons can be encrypted so only nodes with the same beacon password (
--beacon-password) can read the information in it. This makes it possible to publish beacons without fear of information leaks. - Beacons are highly compressed and so short that they can be shared on almost any medium. They are always shorter than 100 characters.
- The beacons consist only of alphanumeric characters so they can be published on any location that supports text. VpnCloud will ignore any non-alphanumeric characters when searching for beacons, so users can add spaces, line breaks, etc. as they wish.
- Beacons start and end with a prefix and suffix known by all nodes sharing the same magic and shared key, so they can be detected efficiently even in huge texts.
- Each beacon contains a timestamp that ensures that outdated beacons are ignored by other nodes.
- Beacons contain a small checksum to help detect and ignore invalid beacons.
A beacon can look like this example: 3hRD8BKvg7jotek0FGLeYtIc1zj7jzPRyQscQAe9tCqnFJ0vyVfIxYMB. This beacon contains 3 addresses, a timestamp and checksum and is guarded by the prefix 3hRD8 and the suffix IxYMB so it can be easily found by other nodes.
Using beacons
VpnCloud supports beacons via the parameters --beacon-store, --beacon-load, --beacon-interval, and --beacon-password as well as the config subkeys store, load, interval, and password of the main key beacon.
The interval is set in seconds and determines how often VpnCloud will search for beacons and write out its own beacon (if enabled via the other two parameters).
The store and load parameters enable beacon storing/loading and define a filename to store the beacon into or load the beacon from.
Instead of using files, VpnCloud also supports calling commands to store and load beacons. If the argument starts with a pipe character |, the rest of the argument is interpreted as a shell command which is passed to sh. In that command, the following variables can be used:
$begin: The prefix of the beacon$end: The suffix of the beacon$data: The inner data part of the beacon (do not use this without the prefix and the suffix)$beacon: The full beacon with prefix and suffix.
The variables $data and $beacon can only be used when storing a beacon, not when searching for one during load. The command used for load has to print all beacons to stdout. VpnCloud will detect all beacons in the output as long as the prefix and suffix is intact.
Examples
The beacon functionality can be tested by running two instances of VpnCloud on the same host:
$> vpncloud -l 3000 --beacon-store /tmp/beacon.txt
$> vpncloud -l 3001 --beacon-load /tmp/beacon.txt
The first peer stores the beacon to a temporary file and the second peer loads it from there. After a short while, both peers should be connected.
Some real examples are: