Manpage

src/config.rs

@@ -101,17 +101,19 @@ impl Default for Config {
 impl Config {
     #[allow(clippy::cognitive_complexity)]
     pub fn merge_file(&mut self, mut file: ConfigFile) {
-        if let Some(val) = file.device_type {
+        if let Some(device) = file.device {
-            self.device_type = val;
+            if let Some(val) = device.type_ {
-        }
+                self.device_type = val;
-        if let Some(val) = file.device_name {
+            }
-            self.device_name = val;
+            if let Some(val) = device.name {
-        }
+                self.device_name = val;
-        if let Some(val) = file.device_path {
+            }
-            self.device_path = Some(val);
+            if let Some(val) = device.path {
-        }
+                self.device_path = Some(val);
-        if let Some(val) = file.fix_rp_filter {
+            }
-            self.fix_rp_filter = val;
+            if let Some(val) = device.fix_rp_filter {
+                self.fix_rp_filter = val;
+            }
         }
         if let Some(val) = file.ip {
             self.ip = Some(val);
@@ -134,17 +136,19 @@ impl Config {
         if let Some(val) = file.keepalive {
             self.keepalive = Some(val);
         }
-        if let Some(val) = file.beacon_store {
+        if let Some(beacon) = file.beacon {
-            self.beacon_store = Some(val);
+            if let Some(val) = beacon.store {
-        }
+                self.beacon_store = Some(val);
-        if let Some(val) = file.beacon_load {
+            }
-            self.beacon_load = Some(val);
+            if let Some(val) = beacon.load {
-        }
+                self.beacon_load = Some(val);
-        if let Some(val) = file.beacon_interval {
+            }
-            self.beacon_interval = val;
+            if let Some(val) = beacon.interval {
-        }
+                self.beacon_interval = val;
-        if let Some(val) = file.beacon_password {
+            }
-            self.beacon_password = Some(val);
+            if let Some(val) = beacon.password {
+                self.beacon_password = Some(val);
+            }
         }
         if let Some(val) = file.mode {
             self.mode = val;
@@ -167,11 +171,13 @@ impl Config {
         if let Some(val) = file.stats_file {
             self.stats_file = Some(val);
         }
-        if let Some(val) = file.statsd_server {
+        if let Some(statsd) = file.statsd {
-            self.statsd_server = Some(val);
+            if let Some(val) = statsd.server {
-        }
+                self.statsd_server = Some(val);
-        if let Some(val) = file.statsd_prefix {
+            }
-            self.statsd_prefix = Some(val);
+            if let Some(val) = statsd.prefix {
+                self.statsd_prefix = Some(val);
+            }
         }
         if let Some(val) = file.user {
             self.user = Some(val);
@@ -319,7 +325,7 @@ pub struct Args {
     pub mode: Option<Mode>,
 
     /// The shared password to encrypt all traffic
-    #[structopt(short, long, required_unless = "private-key", env)]
+    #[structopt(short, long, required_unless_one = &["private-key", "config"], env)]
     pub password: Option<String>,
 
     /// The private key to use
@@ -331,15 +337,15 @@ pub struct Args {
     pub public_key: Option<String>,
 
     /// Other public keys to trust
-    #[structopt(long, name = "trusted-key", alias = "trust", use_delimiter = true)]
+    #[structopt(long = "trusted-key", alias = "trust", use_delimiter = true)]
     pub trusted_keys: Vec<String>,
 
     /// Algorithms to allow
-    #[structopt(long, name = "algorithm", alias = "algo", use_delimiter=true, case_insensitive = true, possible_values=&["plain", "aes128", "aes256", "chacha20"])]
+    #[structopt(long = "algorithm", alias = "algo", use_delimiter=true, case_insensitive = true, possible_values=&["plain", "aes128", "aes256", "chacha20"])]
     pub algorithms: Vec<String>,
 
     /// The local subnets to claim (IP or IP/prefix)
-    #[structopt(long, name = "claim", use_delimiter = true)]
+    #[structopt(long = "claim", use_delimiter = true)]
     pub claims: Vec<String>,
 
     /// Do not automatically claim the device ip
@@ -355,14 +361,14 @@ pub struct Args {
     pub listen: Option<String>,
 
     /// Address of a peer to connect to
-    #[structopt(short = "c", name = "peer", long, alias = "connect")]
+    #[structopt(short = "c", long = "peer", alias = "connect")]
     pub peers: Vec<String>,
 
     /// Peer timeout in seconds
     #[structopt(long)]
     pub peer_timeout: Option<Duration>,
-    /// Periodically send message to keep connections alive
 
+    /// Periodically send message to keep connections alive
     #[structopt(long)]
     pub keepalive: Option<Duration>,
 
@@ -451,14 +457,37 @@ pub struct Args {
     pub log_file: Option<String>
 }
 
+#[derive(Serialize, Deserialize, Debug, PartialEq, Default)]
+#[serde(rename_all = "kebab-case", deny_unknown_fields, default)]
+pub struct ConfigFileDevice {
+    #[serde(rename = "type")]
+    pub type_: Option<Type>,
+    pub name: Option<String>,
+    pub path: Option<String>,
+    pub fix_rp_filter: Option<bool>
+}
+
+#[derive(Serialize, Deserialize, Debug, PartialEq, Default)]
+#[serde(rename_all = "kebab-case", deny_unknown_fields, default)]
+pub struct ConfigFileBeacon {
+    pub store: Option<String>,
+    pub load: Option<String>,
+    pub interval: Option<Duration>,
+    pub password: Option<String>
+}
+
+#[derive(Serialize, Deserialize, Debug, PartialEq, Default)]
+#[serde(rename_all = "kebab-case", deny_unknown_fields, default)]
+pub struct ConfigFileStatsd {
+    pub server: Option<String>,
+    pub prefix: Option<String>
+}
 
 #[derive(Serialize, Deserialize, Debug, PartialEq, Default)]
 #[serde(rename_all = "kebab-case", deny_unknown_fields, default)]
 pub struct ConfigFile {
-    pub device_type: Option<Type>,
+    pub device: Option<ConfigFileDevice>,
-    pub device_name: Option<String>,
+
-    pub device_path: Option<String>,
-    pub fix_rp_filter: Option<bool>,
     pub ip: Option<String>,
     pub ifup: Option<String>,
     pub ifdown: Option<String>,
@@ -468,10 +497,8 @@ pub struct ConfigFile {
     pub peers: Option<Vec<String>>,
     pub peer_timeout: Option<Duration>,
     pub keepalive: Option<Duration>,
-    pub beacon_store: Option<String>,
+
-    pub beacon_load: Option<String>,
+    pub beacon: Option<ConfigFileBeacon>,
-    pub beacon_interval: Option<Duration>,
-    pub beacon_password: Option<String>,
     pub mode: Option<Mode>,
     pub switch_timeout: Option<Duration>,
     pub claims: Option<Vec<String>>,
@@ -479,8 +506,7 @@ pub struct ConfigFile {
     pub port_forwarding: Option<bool>,
     pub pid_file: Option<String>,
     pub stats_file: Option<String>,
-    pub statsd_server: Option<String>,
+    pub statsd: Option<ConfigFileStatsd>,
-    pub statsd_prefix: Option<String>,
     pub user: Option<String>,
     pub group: Option<String>
 }
@@ -517,10 +543,12 @@ statsd-server: example.com:1234
 statsd-prefix: prefix
     ";
     assert_eq!(serde_yaml::from_str::<ConfigFile>(config_file).unwrap(), ConfigFile {
-        device_type: Some(Type::Tun),
+        device: Some(ConfigFileDevice {
-        device_name: Some("vpncloud%d".to_string()),
+            type_: Some(Type::Tun),
-        device_path: Some("/dev/net/tun".to_string()),
+            name: Some("vpncloud%d".to_string()),
-        fix_rp_filter: None,
+            path: Some("/dev/net/tun".to_string()),
+            fix_rp_filter: None
+        }),
         ip: Some("10.0.1.1/16".to_string()),
         ifup: Some("ifconfig $IFNAME 10.0.1.1/16 mtu 1400 up".to_string()),
         ifdown: Some("true".to_string()),
@@ -529,10 +557,12 @@ statsd-prefix: prefix
         peers: Some(vec!["remote.machine.foo:3210".to_string(), "remote.machine.bar:3210".to_string()]),
         peer_timeout: Some(600),
         keepalive: Some(840),
-        beacon_store: Some("/run/vpncloud.beacon.out".to_string()),
+        beacon: Some(ConfigFileBeacon {
-        beacon_load: Some("/run/vpncloud.beacon.in".to_string()),
+            store: Some("/run/vpncloud.beacon.out".to_string()),
-        beacon_interval: Some(3600),
+            load: Some("/run/vpncloud.beacon.in".to_string()),
-        beacon_password: Some("test123".to_string()),
+            interval: Some(3600),
+            password: Some("test123".to_string())
+        }),
         mode: Some(Mode::Normal),
         switch_timeout: Some(300),
         claims: Some(vec!["10.0.1.0/24".to_string()]),
@@ -542,8 +572,10 @@ statsd-prefix: prefix
         group: Some("nogroup".to_string()),
         pid_file: Some("/run/vpncloud.run".to_string()),
         stats_file: Some("/var/log/vpncloud.stats".to_string()),
-        statsd_server: Some("example.com:1234".to_string()),
+        statsd: Some(ConfigFileStatsd {
-        statsd_prefix: Some("prefix".to_string())
+            server: Some("example.com:1234".to_string()),
+            prefix: Some("prefix".to_string())
+        })
     })
 }
 
@@ -551,10 +583,12 @@ statsd-prefix: prefix
 fn config_merge() {
     let mut config = Config::default();
     config.merge_file(ConfigFile {
-        device_type: Some(Type::Tun),
+        device: Some(ConfigFileDevice {
-        device_name: Some("vpncloud%d".to_string()),
+            type_: Some(Type::Tun),
-        device_path: None,
+            name: Some("vpncloud%d".to_string()),
-        fix_rp_filter: None,
+            path: None,
+            fix_rp_filter: None
+        }),
         ip: None,
         ifup: Some("ifconfig $IFNAME 10.0.1.1/16 mtu 1400 up".to_string()),
         ifdown: Some("true".to_string()),
@@ -563,10 +597,12 @@ fn config_merge() {
         peers: Some(vec!["remote.machine.foo:3210".to_string(), "remote.machine.bar:3210".to_string()]),
         peer_timeout: Some(600),
         keepalive: Some(840),
-        beacon_store: Some("/run/vpncloud.beacon.out".to_string()),
+        beacon: Some(ConfigFileBeacon {
-        beacon_load: Some("/run/vpncloud.beacon.in".to_string()),
+            store: Some("/run/vpncloud.beacon.out".to_string()),
-        beacon_interval: Some(7200),
+            load: Some("/run/vpncloud.beacon.in".to_string()),
-        beacon_password: Some("test123".to_string()),
+            interval: Some(7200),
+            password: Some("test123".to_string())
+        }),
         mode: Some(Mode::Normal),
         switch_timeout: Some(300),
         claims: Some(vec!["10.0.1.0/24".to_string()]),
@@ -576,8 +612,10 @@ fn config_merge() {
         group: Some("nogroup".to_string()),
         pid_file: Some("/run/vpncloud.run".to_string()),
         stats_file: Some("/var/log/vpncloud.stats".to_string()),
-        statsd_server: Some("example.com:1234".to_string()),
+        statsd: Some(ConfigFileStatsd {
-        statsd_prefix: Some("prefix".to_string())
+            server: Some("example.com:1234".to_string()),
+            prefix: Some("prefix".to_string())
+        })
     });
     assert_eq!(config, Config {
         device_type: Type::Tun,

vpncloud.adoc

@@ -7,7 +7,7 @@ vpncloud - Peer-to-peer VPN
 
 == SYNOPSIS
 
-*vpncloud [options] [--config <file>] [-t <type>] [-d <name>] [-l <addr>] [-c <addr>...]*
+*vpncloud [options] [--config <file>] [-p <password>] [-l <addr>] [-c <addr>...]*
 
 
 == OPTIONS
@@ -20,14 +20,18 @@ vpncloud - Peer-to-peer VPN
 
 *-t <type>*, *--type <type>*::
   Set the type of network. There are two options: *tap* devices process
-  Ethernet frames *tun* devices process IP packets. [default: *tap*]
+  Ethernet frames *tun* devices process IP packets. [default: *tun*]
 
 *-d <name>*, *--device <name>*::
   Name of the virtual device. Any *%d* will be filled with a free number.
   [default: *vpncloud%d*]
 
 *--device-path <path>*::
-  The path of the base device inode, e.g. /dev/net/run.
+  The path of the base device inode, e.g. /dev/net/tun.
+
+*--fix-rp-filter*::
+  If this option is set, VpnCloud will change the rp_filter settings to protect
+  against a potential system vulnerability. See *SECURITY* for more info.
 
 *-m <mode>*, *--mode <mode>*::
   The mode of the VPN. The VPN can like a router, a switch or a hub. A *hub*
@@ -43,47 +47,66 @@ vpncloud - Peer-to-peer VPN
   a port number is given, then the socket will listen on all IPs (v4 and v6),
   otherwise the socket will only listen on the given IP. [default: **3210**]
 
-*-c <addr>*, *--connect <addr>*::
+*-c <addr>*, *--peer <addr>*, *--connect <addr>*::
   Address of a peer to connect to. The address should be in the form
   *addr:port*. If the node is not started, the connection will be retried
   periodically. This parameter can be repeated to connect to multiple peers.
 
-*-s <subnet>*, *--subnet <subnet>*::
+*--claim <subnet>*::
-  The local subnets to use. This parameter should be in the form
+  The local subnets to claim. This parameter should be in the form
   *address/prefixlen* where address is an IPv4 address, an IPv6 address, or a
   MAC address. The prefix length is the number of significant front bits that
   distinguish the subnet from other subnets. Example: *10.1.1.0/24*.
 
-*--shared-key <key>*::
+*--no-auto-claim*::
-  An optional shared key to encrypt the VPN data. If this option is not set,
+  Do not automatically claim the IP set on the virtual interface (on TUN 
-  the traffic will be sent unencrypted.
+  devices).
 
-*--crypto <method>*::
+*-p <key>*, *--password <key>*::
-  The encryption method to use ("aes128", "aes256", or "chacha20"). Most 
+  A password to encrypt the VPN data. This parameter must be set unless a 
-  current CPUs have special support for AES256 so this should be faster. For 
+  password is given in a config file or a private key is set.
-  older computers lacking this support, CHACHA20 is the fastest option.
+  See *SECURITY* for more info.
-  [default: *chacha20*]
 
-*--magic <id>*::
+*--key <key>*, *--private-key <key>*::
-  Override the 4-byte magic header of each packet. This header identifies the
+  A private key to use for encryption. The key must be given as base62 as 
-  network and helps to distinguish it from other networks and other
+  generated by *--genkey*. See *SECURITY* for more info.
-  applications. The id can either be a 4 byte / 8 character hexadecimal
+
-  string or an arbitrary string prefixed with "hash:" which will then be
+*--public-key <key>*::
-  hashed into 4 bytes.
+  A public key matching the given private key. The key must be given as base62
+  as generated by *--genkey*. This argument is purely optional. See *SECURITY*
+  for more info.
+
+*--trust <key>*, **--trusted-key <key>*::
+  A public key to trust. Any peer must have a key pair that is trusted by this
+  node, otherwise it will be rejected. The key must be given as base62 as 
+  generated by *--genkey*. This argument can be given multiple times. If it is 
+  not set, only the own public key will be trusted. See *SECURITY* for more 
+  info.
+
+*--genkey*::
+  Generate and print a random key pair and exit. The key pair is printed as 
+  base62 and can be used as private-key, public-key and trusted-key options.
+
+*--algo <method>*, *--algorithm <method>*::
+  Supported encryption algorithms ("plain", "aes128", "aes256", or "chacha20").
+  Nodes exchange the supported algorithms and select the one that is fastest on
+  both ends. This parameter can be given multiple times to enable multiple 
+  algorithms. *Warning:* "plain" means unencrypted and needs to be enabled 
+  explicitly. As default, all algorithms except "plain" are enabled.
 
 *--peer-timeout <secs>*::
   Peer timeout in seconds. The peers will exchange information periodically
-  and drop peers that are silent for this period of time. [default: **600**]
+  and drop peers that are silent for this period of time. [default: *300*]
 
 *--keepalive <secs>*::
   Interval of peer exchange messages in seconds. The peers will exchange
   information periodically to keep connections alive. This setting overrides
   how often this will happen. [default: *peer-timeout/2-60*]
 
-*--dst-timeout <secs>*::
+*--switch-timeout <secs>*::
   Switch table entry timeout in seconds. This parameter is only used in switch
   mode. Addresses that have not been seen for the given period of time  will
-  be forgotten. [default: **300**]
+  be forgotten. [default: *300*]
 
 *--beacon-store <path|command>*::
   Periodically store beacons containing the address of this node in the given
@@ -106,7 +129,18 @@ vpncloud - Peer-to-peer VPN
   Beacon storage/loading interval in seconds. If configured to do so via
   *--beacon-store* and *--beacon-load*, the node will periodically store its
   beacon and load beacons of other nodes. This parameter defines the interval
-  in seconds. [default: **3600**]
+  in seconds. [default: *3600*]
+
+*--beacon-password <password>*::
+  An optional password to use to encrypt all beacon data. See the section 
+  *BEACONS* for more information.
+
+*--ip <address>*::
+  An IP address (plus optional prefix length) for the interface. If this 
+  argument is given, the address (and if a prefix length is given, also the
+  netmask) is configured on the device and the device is activated.
+  If also *--ifup* is given, the interface is configured before the ifup 
+  command is executed. Please see *DEVICE SETUP* for more info.
 
 *--ifup <command>*::
   A command to setup the network interface. The command will be run (as
@@ -114,7 +148,7 @@ vpncloud - Peer-to-peer VPN
   The name of the allocated device will be available via the environment
   variable *IFNAME*.
   Please note that this command is executed with the full permissions of the
-  caller.
+  caller. Please see *DEVICE SETUP* for more info.
 
 *--ifdown <command>*::
   A command to bring down the network interface. The command will be run (as
@@ -175,13 +209,13 @@ vpncloud - Peer-to-peer VPN
 
 == DESCRIPTION
 
-*VpnCloud* is a simple VPN over UDP. It creates a virtual network interface on
+*VpnCloud* is a peer-to-peer VPN over UDP. It creates a virtual network 
-the host and forwards all received data via UDP to the destination. It can work
+interface on the host and forwards all received data via UDP to the 
-in 3 different modes:
+destination. It can work in 3 different modes:
 
 *Switch mode*:: In this mode, the VPN will dynamically learn addresses
-as they are used as source addresses and use them to forward data to its
+as they are used as source addresses by peers and use them to forward data to 
-destination. Addresses that have not been seen for some time
+its destination. Addresses that have not been seen for some time
 (option *switch_timeout*) will be forgotten. Data for unknown addresses will be
 broadcast to all peers. This mode is the default mode for TAP devices that
 process Ethernet frames but it can also be used with TUN devices and IP
@@ -189,9 +223,9 @@ packets.
 *Hub mode*:: In this mode, all data will always be broadcast to all peers.
 This mode uses lots of bandwidth and should only be used in special cases.
 *Router mode*:: In this mode, data will be forwarded based on preconfigured
-address ranges ("subnets"). Data for unknown nodes will be silently ignored.
+address ranges ("claims"). Data for unclaimed addresses will be silently 
-This mode is the default mode for TUN devices that work with IP packets but
+ignored. This mode is the default mode for TUN devices that work with IP 
-it can also be used with TAP devices and Ethernet frames.
+packets but it can also be used with TAP devices and Ethernet frames.
 
 All connected VpnCloud nodes will form a peer-to-peer network and cross-connect
 automatically until the network is fully connected. The nodes will periodically
@@ -199,10 +233,6 @@ exchange information with the other nodes to signal that they are still active
 and to allow the automatic cross-connect behavior. There are some important
 things to note:
 
-. To avoid that different networks that reuse each others addresses merge due
-to the cross-connect behavior, the *magic* option can be used and set
-to any unique string to identify the network. The *magic* must be the
-same on all nodes of the same VPN network.
 . The cross-connect behavior can be able to connect nodes that are behind
 firewalls or NATs as it can function as hole-punching.
 . The management traffic will increase with the peer number quadratically.
@@ -213,17 +243,18 @@ broadcasts data.
 
 VpnCloud 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, VpnCloud
-cannot produce loops on its own. On the TAP device, however STP data can be
+cannot produce loops on its own. On a TAP device, however STP data can be
 transported to avoid loops caused by other network components.
 
 For TAP devices, IEEE 802.1q frames (VLAN tagged) are detected and forwarded
 based on separate MAC tables. Any nested tags (Q-in-Q) will be ignored.
 
+
 == EXAMPLES
 
-=== Switched TAP scenario
+=== Simple multi-node connectivity
 
-In the example scenario, a simple layer 2 network tunnel is established. Most
+In the example scenario, a simple layer-3 network tunnel is established. Most
 likely those commands need to be run as *root* using *sudo*.
 
 First, VpnCloud need to be started on both nodes (the address after *-c* is the
@@ -231,7 +262,7 @@ address of the remote node and the the *X* in the interface address must be
 unique among all nodes, e.g. 0, 1, 2, ...):
 
 ----
-vpncloud -c REMOTE_HOST:PORT --ifup 'ifconfig $IFNAME 10.0.0.X/24 mtu 1400 up'
+vpncloud -c REMOTE_HOST:PORT --ip 10.0.0.X/24 --password PASSWORD
 ----
 
 Afterwards, the interface can be used to communicate.
@@ -242,7 +273,7 @@ In this example, 2 nodes and their subnets should communicate using IP.
 First, VpnCloud need to be started on both nodes:
 
 ----
-vpncloud -t tun -c REMOTE_HOST:PORT --subnet 10.0.X.0/24 --ifup 'ifconfig $IFNAME 10.0.X.1/16 mtu 1400 up'
+vpncloud -t tun -c REMOTE_HOST:PORT --ip 10.0.X.1 --claim 10.0.X.0/24 --password PASSWORD
 ----
 
 It is important to configure the interface in a way that all addresses on the
@@ -262,16 +293,7 @@ security issues, DHCP issues and many more problems.
 to assign unique addresses to all participants. If this happens accidentally,
 it can conflict with DHCP servers of the local network and can have severe
 side effects.
-. VpnCloud is not designed for high security use cases. Although the used crypto
+
-primitives are expected to be very secure, their application has not been
-reviewed.
-The shared key is hashed using _PBKDF2_HMAC_SHA256_ to derive a key,
-which is used to encrypt the payload of messages using _ChaCha20Poly1305_,
-_AES128-GCM_, or _AES256-GCM_. The encryption includes an authentication that
-also protects the header.
-This method does only protect against attacks on single messages but not
-against attacks that manipulate the message series itself (i.e. suppress
-messages, reorder them, or duplicate them).
 
 == CONFIG FILES
 
@@ -279,52 +301,108 @@ The config file is a YAML file that contains configuration values. All entries
 are optional and override the defaults. Please see the section *OPTIONS* for
 detailed descriptions of the options.
 
-*device_type*:: Set the type of network. Same as *--type*
+*device*:: A key-value map with device settings
-*device_name*:: Name of the virtual device. Same as *--device*
+  *type*:: Set the type of network. Same as *--type*
-*device_path*:: Set the path of the base device. Same as *--device-path*
+  *name*:: Name of the virtual device. Same as *--device*
+  *path*:: Set the path of the base device. Same as *--device-path*
+  *fix-rp-filter*:: Fix the rp_filter settings on the host. Same as *--fix-rp-filter*
+*ip*:: An IP address (plus optional prefix length) for the interface. Same as *--ip*
 *ifup*:: A command to setup the network interface. Same as *--ifup*
 *ifdown*:: A command to bring down the network interface. Same as *--ifdown*
-*crypto*:: The encryption method to use. Same as *--crypto*
+*crypto*:: A key-value map with crypto settings
-*shared_key*:: The shared key to encrypt all traffic. Same as *--shared-key*
+  *algorithms*:: The encryption algorithms to support. See *--algorithm*
-*magic*:: Override the 4-byte magic header of each packet. Same as *--magic*
+  *password*:: The password to use for encryption. Same as *--password*
-*port*:: A port number to listen on. This option is DEPRECATED.
+  *private-key*:: The private key to use. Same as *--private-key*
+  *public-key*:: The public key to use. Same as *--public-key*
+  *trusted-keys*:: Other public keys to trust. See *--trusted-key*
 *listen*:: The address on which to listen for data. Same as *--listen*
 *peers*:: A list of addresses to connect to. See *--connect*
-*peer_timeout*:: Peer timeout in seconds. Same as**--peer-timeout**
+*peer_timeout*:: Peer timeout in seconds. Same as *--peer-timeout*
-*beacon_store*:: Path or command to store beacons. Same as *--beacon-store*
+*keepalive*:: Periodically send message to keep connections alive. Same as *--keepalive*
-*beacon_load*:: Path or command to load beacons. Same as *--beacon-load*
+*beacon*:: A key-value map with beacon settings
-*beacon_interval*:: Interval for loading and storing beacons in seconds. Same as *--beacon-interval*
+  *store*:: Path or command to store beacons. Same as *--beacon-store*
+  *load*:: Path or command to load beacons. Same as *--beacon-load*
+  *interval*:: Interval for loading and storing beacons in seconds. Same as *--beacon-interval*
+  *password*:: Password to encrypt the beacon with. Same as *--beacon-password*
 *mode*:: The mode of the VPN. Same as *--mode*
-*switch_timeout*:: Switch table entry timeout in seconds. Same as *--dst-timeout*
+*switch_timeout*:: Switch table entry timeout in seconds. Same as *--switch-timeout*
-*subnets*:: A list of local subnets to use. See *--subnet*
+*claims*:: A list of local subnets to claim. See *--claim*
+*auto-claim*:: Whether to automatically claim the device ip. See *--no-auto-claim*
 *port_forwarding*:: Whether to activate port forwardig. See *--no-port-forwarding*
 *user*:: The name of a user to run the background process under. Same as *--user*
 *group*:: The name of a group to run the background process under. Same as *--group*
 *pid_file*:: The path of the pid file to create. Same as *--pid-file*
 *stats_file*:: The path of the statistics file. Same as *--stats-file*
-*statsd_server*:: Server to report statistics to. Same as *--statsd-server*
+*statsd*:: A key-value map with statsd settings
-*statsd_prefix*:: Prefix to use when reporting to statsd. Same as *--statsd-prefix*
+  *server*:: Server to report statistics to. Same as *--statsd-server*
+  *prefix*:: Prefix to use when reporting to statsd. Same as *--statsd-prefix*
 
 === Example
 
- device_type: tun
+ device:
- device_name: vpncloud%d
+   type: tun
- ifup: ifconfig $IFNAME 10.0.1.1/16 mtu 1400 up
+   name: vpncloud%d
- crypto: aes256
+ ip: 10.0.1.1/16
- shared_key: mysecret
+ crypto: 
+   password: mysecret
  listen: 3210
  peers:
    - remote.machine.foo:3210
    - remote.machine.bar:3210
  peer_timeout: 600
  mode: normal
- subnets:
+ claims:
    - 10.0.1.0/24
  port_forwarding: true
  user: nobody
  group: nogroup
  pid_file: /run/vpncloud.pid
 
+
+== SECURITY
+
+VpnCloud uses strong cryptography based on modern cryptographic primitives.
+
+Before exchanging any payload data with peers a secure connection is 
+initialized based on key pairs. Each node has a key pair consisting of a 
+private and a public key (*--private-key* and *--public-key*). Those key pairs
+can be generated via *--genkey*. 
+To allow connections, nodes need to list the public keys of all other nodes as 
+trusted keys (*--trusted-key*). To simplify the key exchange, key pairs can be
+derived from passwords (*--password*). If no trusted keys are configured, nodes
+will only trust their own public key. Nodes configured with the same password
+will therefore trust each others.
+
+In the initialization phase of the connection, nodes agree on a temporary key 
+that is used to encrypt the next messages using a fast encryption algorithm.
+VpnCloud automatically benchmarks all supported algorithms and negotiates to 
+use the fastest algorithm for each connection. Users can limit the supported
+algorithms if they wish using *--algorithm*. Although highly discouraged, users
+can opt out of encryption altogether by enabling the *plain* algorithm. (Note:
+both nodes in a connection must support this, otherwise encryption will take 
+place.)
+
+The temporary encryption keys are rotated periodically so they are never used 
+for a longer time.
+
+Please refer to the security whitepaper for more details.
+
+=== CVE-2019-14899
+
+The Linux kernel contains a vulnerability that affects all VPNs disregarding of
+the specific technology being used. Under some circumstances, the kernel accepts
+packets for the address range configured on the vpn interface also on other 
+interfaces. This way, an attacker can test the presence of a VPN and find out 
+the IPs being used. Also the attacker can with some effort inject data and 
+manipulate connections that should be protected by the VPN.
+To mitigate this, the rp_filter setting should be configured to strict mode, 
+which unfortunately a lot of distributions do not set as default.
+VpnCloud will detect this misconfiguration and offers to fix it via 
+*--fix-rp-filter*.
+Note: This vulnerability affects all VPN technologies as it is not located in
+the VPN software but in the Linux kernel.
+
+
 == BEACONS
 
 Beacons are short character sequences that contain a timestamp and a list of
@@ -383,115 +461,28 @@ All keys are prefixed by a common prefix. The prefix defaults to *vpncloud* but
 can be changed via **--statsd-prefix** or the config option **statsd_prefix**.
 
 
-== NETWORK PROTOCOL
+== DEVICE SETUP
 
-The protocol of VpnCloud is kept as simple as possible to allow other
+The device is setup using the following steps:
-implementations and to maximize the performance.
 
-Every packet sent over UDP contains the following header (in order):
+. The device is created with the type and name given as *--type* and *--device*.
+. Depending on the device type and the main network device of the systme, the 
+  optimal MTU is determined and configured on the device.
+. If and IP address (and optional prefix length) is given via *--ip*, the 
+  interface is configured with the address and the given netmask (default: 
+  255.255.255.0). Also the interface is set to be active.
+. If a command is given as *--ifup*, the given command will be executed. The 
+  name of the interface is stored in an environment variable as "IFNAME". Note 
+  that VpnCloud waits for the command to exit before starting its normal 
+  operation.
 
-4 bytes *magic*::
+Note that most of the steps will need elevated permissions, so the vpncloud 
-This field is used to identify the packet and to sort out packets that do
+command needs to be executed as root (e.g. via sudo). Beware that the ifup 
-not belong. The default is *[0x76, 0x70, 0x6e, 0x01]* ("vpn\x01").
+command will also be executed using those permissions.
-This field can be used to identify VpnCloud packets and might be set to
-something different to hide the protocol.
 
-1 byte *crypto method*::
+VpnCloud can drop the elevated permissions when *--user* and *--group* is 
-This field specifies the method that must be used to decrypt the rest of the
+given.
-data. The currently supported methods are:
 
- ** Method *0*, *No encryption*: Rest of the data can be read without
-decrypting it.
- ** Method *1*, *ChaCha20*: The header is followed by a 12 byte
-_nonce_. The rest of the data is encrypted with the
-*libsodium::crypto_aead_chacha20poly1305_ietf* method, using the 8 byte
-header as additional data.
- ** Method *2*, *AES256*: The header is followed by a 12 byte _nonce_.
-The rest of the data is encrypted with the
-*libsodium::crypto_aead_aes256gcm* method, using the 8 byte header
-as additional data.
-
-2 *reserved bytes*::
-that are currently unused and set to 0
-
-1 byte for the *message type*::
-This byte specifies the type of message that follows. Currently the
-following message types are supported:
-
- ** Type 0: Data packet
- ** Type 1: Peer list
- ** Type 2: Initial message
- ** Type 3: Closing message
-
-After this 8 byte header, the rest of the message follows. It is encrypted using
-the method specified in the header.
-
-In the decrypted data, the message as specified in the *message type* field
-will follow:
-
-*Data packet* (message type 0)::
-This packet contains payload. The format of the data depends on the device
-type. For TUN devices, this data contains an IP packet. For TAP devices it
-contains an Ethernet frame. The data starts right after the header and ends
-at the end of the packet.
-If it is an Ethernet frame, it will start with the destination MAC and end
-with the payload. It does not contain the preamble, SFD, padding, and CRC
-fields.
-*Peer list* (message type 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).
-*Initial message* (message type 2)::
-This packet contains the following information:
- ** The stage of the initialization process
- ** A random node id to distinguish different nodes
- ** All the local subnets claimed by the nodes
-
-+
-Its first byte marks the stage of the initial handshake process.
-The next 16 bytes contain the unique node id. After that,
-the list of local subnets follows.
-The subnet list is encoded in the following way: Its first byte of data
-contains the number of encoded subnets that follow. After that, the given
-number of encoded subnets follow.
-For each subnet, the first byte is the length of bytes in the base address
-and is followed by the given number of base address bytes and one additional
-byte that is the prefix length of the subnet.
-The addresses for the subnet will be encoded like they are encoded in their
-native protocol (4 bytes for IPv4, 16 bytes for IPv6, and 6 bytes for a MAC
-address) with the exception of MAC addresses in a VLan which will be encoded
-in 8 bytes where the first 2 bytes are the VLan number in network byte order
-and the later 6 bytes are the MAC address.
-*Closing message* (message type 3)::
-This packet does not contain any more data.
-
-Nodes are expected to send an *initial message* with stage 0 whenever they
-connect to a node they were not connected to before. As a reply to this message,
-another initial should be sent with stage 1. Also a *peer list* message should
-be sent as a reply.
-
-When connected, nodes 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 at a certain
-network size start sending partial peer lists instead of the full list. A
-reasonable number would be about 20 peers. The subsets should be selected
-randomly.
-
-Nodes should remove peers from their peer list after a certain period of
-inactivity or when receiving a *closing message*. Before shutting down, nodes
-should send the closing 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 an initial
-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