diff --git a/.travis.yml b/.travis.yml deleted file mode 100644 index 8924071..0000000 --- a/.travis.yml +++ /dev/null @@ -1,38 +0,0 @@ -dist: xenial -sudo: required -language: rust -cache: cargo -rust: - - nightly - - beta - - stable -matrix: - allow_failures: - - rust: nightly -addons: - apt: - packages: - - libcurl4-openssl-dev - - libelf-dev - - libdw-dev - - binutils-dev - - cmake - - ruby-ronn -before_script: - - export PATH=$HOME/.cargo/bin:$PATH - - cargo install cargo-update || echo "cargo-update already installed" - - cargo install cargo-travis || echo "cargo-travis already installed" - - cargo install-update -a # update outdated cached binaries -script: - - | - cargo build && cargo test -after_success: - - | - [ $TRAVIS_RUST_VERSION = stable ] && cargo coveralls -env: - global: - - TRAVIS_CARGO_NIGHTLY_FEATURE="" -notifications: - email: - on_success: never - diff --git a/CHANGELOG.md b/CHANGELOG.md index c08a6a7..b6cf217 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,11 +5,14 @@ This project follows [semantic versioning](http://semver.org). ### UNRELEASED - [added] Added option to listen on specified IP +- [added] Added support for statsd monitoring - [changed] No longer using two sockets for ipv4 and ipv6 - [changed] Warning for missing router is now info - [changed] New warning on claimed addresses in learning mode -- [changed] Updated dependencies - [changed] Rewrote argument parsing +- [changed] Changed stats file format to YAML +- [changed] Using asciidoc for manpage +- [changed] Updated dependencies - [fixed] Fixed problem that could lead to 100% cpu consumption - [fixed] Fixed startup race condition diff --git a/Cargo.lock b/Cargo.lock index b99912b..9c506c1 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -45,7 +45,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" [[package]] name = "bumpalo" -version = "3.3.0" +version = "3.4.0" source = "registry+https://github.com/rust-lang/crates.io-index" [[package]] @@ -259,9 +259,9 @@ version = "1.0.2" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "proc-macro-error-attr 1.0.2 (registry+https://github.com/rust-lang/crates.io-index)", - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", "version_check 0.9.2 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -270,9 +270,9 @@ name = "proc-macro-error-attr" version = "1.0.2" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", "syn-mid 0.5.0 (registry+https://github.com/rust-lang/crates.io-index)", "version_check 0.9.2 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -284,7 +284,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index" [[package]] name = "proc-macro2" -version = "1.0.17" +version = "1.0.18" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "unicode-xid 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", @@ -295,7 +295,7 @@ name = "quote" version = "1.0.6" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -350,7 +350,7 @@ dependencies = [ [[package]] name = "ring" -version = "0.16.13" +version = "0.16.14" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "cc 1.0.54 (registry+https://github.com/rust-lang/crates.io-index)", @@ -372,7 +372,7 @@ dependencies = [ [[package]] name = "ryu" -version = "1.0.4" +version = "1.0.5" source = "registry+https://github.com/rust-lang/crates.io-index" [[package]] @@ -390,17 +390,17 @@ source = "registry+https://github.com/rust-lang/crates.io-index" [[package]] name = "serde" -version = "1.0.110" +version = "1.0.111" source = "registry+https://github.com/rust-lang/crates.io-index" [[package]] name = "serde_derive" -version = "1.0.110" +version = "1.0.111" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -409,8 +409,8 @@ version = "1.0.53" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "itoa 0.4.5 (registry+https://github.com/rust-lang/crates.io-index)", - "ryu 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)", - "serde 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)", + "ryu 1.0.5 (registry+https://github.com/rust-lang/crates.io-index)", + "serde 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -420,8 +420,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "dtoa 0.4.5 (registry+https://github.com/rust-lang/crates.io-index)", "linked-hash-map 0.5.3 (registry+https://github.com/rust-lang/crates.io-index)", - "serde 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)", - "yaml-rust 0.4.3 (registry+https://github.com/rust-lang/crates.io-index)", + "serde 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)", + "yaml-rust 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -476,11 +476,11 @@ name = "stdweb-derive" version = "0.5.3" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", - "serde 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)", - "serde_derive 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "serde 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)", + "serde_derive 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -489,13 +489,13 @@ version = "0.2.9" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "base-x 0.2.6 (registry+https://github.com/rust-lang/crates.io-index)", - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", - "serde 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)", - "serde_derive 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)", + "serde 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)", + "serde_derive 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)", "serde_json 1.0.53 (registry+https://github.com/rust-lang/crates.io-index)", "sha1 0.6.0 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -525,17 +525,17 @@ source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "heck 0.3.1 (registry+https://github.com/rust-lang/crates.io-index)", "proc-macro-error 1.0.2 (registry+https://github.com/rust-lang/crates.io-index)", - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] name = "syn" -version = "1.0.27" +version = "1.0.30" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", "unicode-xid 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -545,9 +545,9 @@ name = "syn-mid" version = "0.5.0" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -600,10 +600,10 @@ version = "0.1.1" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "proc-macro-hack 0.5.16 (registry+https://github.com/rust-lang/crates.io-index)", - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", "standback 0.2.8 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -680,16 +680,16 @@ dependencies = [ "pkg-config 0.3.17 (registry+https://github.com/rust-lang/crates.io-index)", "privdrop 0.3.4 (registry+https://github.com/rust-lang/crates.io-index)", "rand 0.7.3 (registry+https://github.com/rust-lang/crates.io-index)", - "ring 0.16.13 (registry+https://github.com/rust-lang/crates.io-index)", - "serde 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)", - "serde_derive 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)", + "ring 0.16.14 (registry+https://github.com/rust-lang/crates.io-index)", + "serde 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)", + "serde_derive 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)", "serde_yaml 0.8.12 (registry+https://github.com/rust-lang/crates.io-index)", "signal 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)", "siphasher 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)", "structopt 0.3.14 (registry+https://github.com/rust-lang/crates.io-index)", "tempfile 3.1.0 (registry+https://github.com/rust-lang/crates.io-index)", "time 0.2.16 (registry+https://github.com/rust-lang/crates.io-index)", - "yaml-rust 0.4.3 (registry+https://github.com/rust-lang/crates.io-index)", + "yaml-rust 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)", ] [[package]] @@ -711,12 +711,12 @@ name = "wasm-bindgen-backend" version = "0.2.63" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "bumpalo 3.3.0 (registry+https://github.com/rust-lang/crates.io-index)", + "bumpalo 3.4.0 (registry+https://github.com/rust-lang/crates.io-index)", "lazy_static 1.4.0 (registry+https://github.com/rust-lang/crates.io-index)", "log 0.4.8 (registry+https://github.com/rust-lang/crates.io-index)", - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", "wasm-bindgen-shared 0.2.63 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -734,9 +734,9 @@ name = "wasm-bindgen-macro-support" version = "0.2.63" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ - "proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)", + "proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)", "quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)", - "syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)", + "syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)", "wasm-bindgen-backend 0.2.63 (registry+https://github.com/rust-lang/crates.io-index)", "wasm-bindgen-shared 0.2.63 (registry+https://github.com/rust-lang/crates.io-index)", ] @@ -789,7 +789,7 @@ dependencies = [ [[package]] name = "yaml-rust" -version = "0.4.3" +version = "0.4.4" source = "registry+https://github.com/rust-lang/crates.io-index" dependencies = [ "linked-hash-map 0.5.3 (registry+https://github.com/rust-lang/crates.io-index)", @@ -802,7 +802,7 @@ dependencies = [ "checksum base-x 0.2.6 (registry+https://github.com/rust-lang/crates.io-index)" = "1b20b618342cf9891c292c4f5ac2cde7287cc5c87e87e9c769d617793607dec1" "checksum bitflags 1.2.1 (registry+https://github.com/rust-lang/crates.io-index)" = "cf1de2fe8c75bc145a2f577add951f8134889b4795d47466a54a5c846d691693" "checksum boxfnonce 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)" = "5988cb1d626264ac94100be357308f29ff7cbdd3b36bda27f450a4ee3f713426" -"checksum bumpalo 3.3.0 (registry+https://github.com/rust-lang/crates.io-index)" = "5356f1d23ee24a1f785a56d1d1a5f0fd5b0f6a0c0fb2412ce11da71649ab78f6" +"checksum bumpalo 3.4.0 (registry+https://github.com/rust-lang/crates.io-index)" = "2e8c087f005730276d1096a652e92a8bacee2e2472bcc9715a74d2bec38b5820" "checksum bytes 0.5.4 (registry+https://github.com/rust-lang/crates.io-index)" = "130aac562c0dd69c56b3b1cc8ffd2e17be31d0b6c25b61c96b76231aa23e39e1" "checksum cc 1.0.54 (registry+https://github.com/rust-lang/crates.io-index)" = "7bbb73db36c1246e9034e307d0fba23f9a2e251faa47ade70c1bd252220c8311" "checksum cfg-if 0.1.10 (registry+https://github.com/rust-lang/crates.io-index)" = "4785bdd1c96b2a846b2bd7cc02e86b6b3dbf14e7e53446c4f54c92a361040822" @@ -834,7 +834,7 @@ dependencies = [ "checksum proc-macro-error 1.0.2 (registry+https://github.com/rust-lang/crates.io-index)" = "98e9e4b82e0ef281812565ea4751049f1bdcdfccda7d3f459f2e138a40c08678" "checksum proc-macro-error-attr 1.0.2 (registry+https://github.com/rust-lang/crates.io-index)" = "4f5444ead4e9935abd7f27dc51f7e852a0569ac888096d5ec2499470794e2e53" "checksum proc-macro-hack 0.5.16 (registry+https://github.com/rust-lang/crates.io-index)" = "7e0456befd48169b9f13ef0f0ad46d492cf9d2dbb918bcf38e01eed4ce3ec5e4" -"checksum proc-macro2 1.0.17 (registry+https://github.com/rust-lang/crates.io-index)" = "1502d12e458c49a4c9cbff560d0fe0060c252bc29799ed94ca2ed4bb665a0101" +"checksum proc-macro2 1.0.18 (registry+https://github.com/rust-lang/crates.io-index)" = "beae6331a816b1f65d04c45b078fd8e6c93e8071771f41b8163255bbd8d7c8fa" "checksum quote 1.0.6 (registry+https://github.com/rust-lang/crates.io-index)" = "54a21852a652ad6f610c9510194f398ff6f8692e334fd1145fed931f7fbe44ea" "checksum rand 0.7.3 (registry+https://github.com/rust-lang/crates.io-index)" = "6a6b1679d49b24bbfe0c803429aa1874472f50d9b363131f0e89fc356b544d03" "checksum rand_chacha 0.2.2 (registry+https://github.com/rust-lang/crates.io-index)" = "f4c8ed856279c9737206bf725bf36935d8666ead7aa69b52be55af369d193402" @@ -842,13 +842,13 @@ dependencies = [ "checksum rand_hc 0.2.0 (registry+https://github.com/rust-lang/crates.io-index)" = "ca3129af7b92a17112d59ad498c6f81eaf463253766b90396d39ea7a39d6613c" "checksum redox_syscall 0.1.56 (registry+https://github.com/rust-lang/crates.io-index)" = "2439c63f3f6139d1b57529d16bc3b8bb855230c8efcc5d3a896c8bea7c3b1e84" "checksum remove_dir_all 0.5.2 (registry+https://github.com/rust-lang/crates.io-index)" = "4a83fa3702a688b9359eccba92d153ac33fd2e8462f9e0e3fdf155239ea7792e" -"checksum ring 0.16.13 (registry+https://github.com/rust-lang/crates.io-index)" = "703516ae74571f24b465b4a1431e81e2ad51336cb0ded733a55a1aa3eccac196" +"checksum ring 0.16.14 (registry+https://github.com/rust-lang/crates.io-index)" = "06b3fefa4f12272808f809a0af618501fdaba41a58963c5fb72238ab0be09603" "checksum rustc_version 0.2.3 (registry+https://github.com/rust-lang/crates.io-index)" = "138e3e0acb6c9fb258b19b67cb8abd63c00679d2851805ea151465464fe9030a" -"checksum ryu 1.0.4 (registry+https://github.com/rust-lang/crates.io-index)" = "ed3d612bc64430efeb3f7ee6ef26d590dce0c43249217bddc62112540c7941e1" +"checksum ryu 1.0.5 (registry+https://github.com/rust-lang/crates.io-index)" = "71d301d4193d031abdd79ff7e3dd721168a9572ef3fe51a1517aba235bd8f86e" "checksum semver 0.9.0 (registry+https://github.com/rust-lang/crates.io-index)" = "1d7eb9ef2c18661902cc47e535f9bc51b78acd254da71d375c2f6720d9a40403" "checksum semver-parser 0.7.0 (registry+https://github.com/rust-lang/crates.io-index)" = "388a1df253eca08550bef6c72392cfe7c30914bf41df5269b68cbd6ff8f570a3" -"checksum serde 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)" = "99e7b308464d16b56eba9964e4972a3eee817760ab60d88c3f86e1fecb08204c" -"checksum serde_derive 1.0.110 (registry+https://github.com/rust-lang/crates.io-index)" = "818fbf6bfa9a42d3bfcaca148547aa00c7b915bec71d1757aa2d44ca68771984" +"checksum serde 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)" = "c9124df5b40cbd380080b2cc6ab894c040a3070d995f5c9dc77e18c34a8ae37d" +"checksum serde_derive 1.0.111 (registry+https://github.com/rust-lang/crates.io-index)" = "3f2c3ac8e6ca1e9c80b8be1023940162bf81ae3cffbb1809474152f2ce1eb250" "checksum serde_json 1.0.53 (registry+https://github.com/rust-lang/crates.io-index)" = "993948e75b189211a9b31a7528f950c6adc21f9720b6438ff80a7fa2f864cea2" "checksum serde_yaml 0.8.12 (registry+https://github.com/rust-lang/crates.io-index)" = "16c7a592a1ec97c9c1c68d75b6e537dcbf60c7618e038e7841e00af1d9ccf0c4" "checksum sha1 0.6.0 (registry+https://github.com/rust-lang/crates.io-index)" = "2579985fda508104f7587689507983eadd6a6e84dd35d6d115361f530916fa0d" @@ -864,7 +864,7 @@ dependencies = [ "checksum strsim 0.8.0 (registry+https://github.com/rust-lang/crates.io-index)" = "8ea5119cdb4c55b55d432abb513a0429384878c15dde60cc77b1c99de1a95a6a" "checksum structopt 0.3.14 (registry+https://github.com/rust-lang/crates.io-index)" = "863246aaf5ddd0d6928dfeb1a9ca65f505599e4e1b399935ef7e75107516b4ef" "checksum structopt-derive 0.4.7 (registry+https://github.com/rust-lang/crates.io-index)" = "d239ca4b13aee7a2142e6795cbd69e457665ff8037aed33b3effdc430d2f927a" -"checksum syn 1.0.27 (registry+https://github.com/rust-lang/crates.io-index)" = "ef781e621ee763a2a40721a8861ec519cb76966aee03bb5d00adb6a31dc1c1de" +"checksum syn 1.0.30 (registry+https://github.com/rust-lang/crates.io-index)" = "93a56fabc59dce20fe48b6c832cc249c713e7ed88fa28b0ee0a3bfcaae5fe4e2" "checksum syn-mid 0.5.0 (registry+https://github.com/rust-lang/crates.io-index)" = "7be3539f6c128a931cf19dcee741c1af532c7fd387baa739c03dd2e96479338a" "checksum tempfile 3.1.0 (registry+https://github.com/rust-lang/crates.io-index)" = "7a6e24d9338a0a5be79593e2fa15a648add6138caa803e2d5bc782c371732ca9" "checksum textwrap 0.11.0 (registry+https://github.com/rust-lang/crates.io-index)" = "d326610f408c7a4eb6f51c37c330e496b08506c9457c9d34287ecc38809fb060" @@ -893,4 +893,4 @@ dependencies = [ "checksum winapi-x86_64-pc-windows-gnu 0.4.0 (registry+https://github.com/rust-lang/crates.io-index)" = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f" "checksum xml-rs 0.8.3 (registry+https://github.com/rust-lang/crates.io-index)" = "b07db065a5cf61a7e4ba64f29e67db906fb1787316516c4e6e5ff0fea1efcd8a" "checksum xmltree 0.10.0 (registry+https://github.com/rust-lang/crates.io-index)" = "77a607efe600db25447a8d9bab1f39217a82c4ba160b51b027d7c4f6053004df" -"checksum yaml-rust 0.4.3 (registry+https://github.com/rust-lang/crates.io-index)" = "65923dd1784f44da1d2c3dbbc5e822045628c590ba72123e1c73d3c230c4434d" +"checksum yaml-rust 0.4.4 (registry+https://github.com/rust-lang/crates.io-index)" = "39f0c922f1a334134dc2f7a8b67dc5d25f0735263feec974345ff706bcf20b0d" diff --git a/README.md b/README.md index e45db97..3766230 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,7 @@ somewhat stable state. VpnCloud features the following functionality: ### Installing #### Compiling from source -Prerequisites: Git, [Cargo](https://www.rust-lang.org/install.html), Ronn +Prerequisites: Git, [Cargo](https://www.rust-lang.org/install.html), asciidoctor The checked-out code can be compiled with ``cargo build`` or ``cargo build --release`` (release version). The binary could then be found in `target/release/vpncloud`. diff --git a/assets/vpncloud.1 b/assets/vpncloud.1 index 99c24a1..14bc5a7 100644 --- a/assets/vpncloud.1 +++ b/assets/vpncloud.1 @@ -1,414 +1,860 @@ -.\" generated with Ronn/v0.7.3 -.\" http://github.com/rtomayko/ronn/tree/0.7.3 -. -.TH "VPNCLOUD" "1" "February 2019" "" "" -. +'\" t +.\" Title: vpncloud +.\" Author: [see the "AUTHORS" section] +.\" Generator: Asciidoctor 1.5.5 +.\" Date: 2020-06-03 +.\" Manual: \ \& +.\" Source: \ \& +.\" Language: English +.\" +.TH "VPNCLOUD" "1" "2020-06-03" "\ \&" "\ \&" +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.ss \n[.ss] 0 +.nh +.ad l +.de URL +\\$2 \(laURL: \\$1 \(ra\\$3 +.. +.if \n[.g] .mso www.tmac +.LINKSTYLE blue R < > .SH "NAME" -\fBvpncloud\fR \- Peer\-to\-peer VPN -. +vpncloud \- Peer\-to\-peer VPN .SH "SYNOPSIS" -\fBvpncloud [options] [\-\-config ] [\-t ] [\-d ] [\-l ] [\-c \.\.\.]\fR -. +.sp +\fBvpncloud [options] [\-\-config ] [\-t ] [\-d ] [\-l ] [\-c ...]\fP .SH "OPTIONS" -. -.TP -\fB\-\-config \fR: -. -.IP -Read configuration options from the specified file\. Please see the section \fBCONFIG FILES\fR for documentation on the file format\. If the same option is defined in the config file and as a parameter, the parameter overrides the config file\. -. -.TP -\fB\-t \fR, \fB\-\-type \fR: -. -.IP -Set the type of network\. There are two options: \fBtap\fR devices process Ethernet frames \fBtun\fR devices process IP packets\. [default: \fBtap\fR] -. -.TP -\fB\-d \fR, \fB\-\-device \fR: -. -.IP -Name of the virtual device\. Any \fB%d\fR will be filled with a free number\. [default: \fBvpncloud%d\fR] -. -.TP -\fB\-\-device\-path \fR: -. -.IP -The path of the base device inode, e\.g\. /dev/net/run\. -. -.TP -\fB\-m \fR, \fB\-\-mode \fR: -. -.IP -The mode of the VPN\. The VPN can like a router, a switch or a hub\. A \fBhub\fR will send all data always to all peers\. A \fBswitch\fR will learn addresses from incoming data and only send data to all peers when the address is unknown\. A \fBrouter\fR will send data according to known subnets of the peers and ignore them otherwise\. The \fBnormal\fR mode is switch for tap devices and router for tun devices\. [default: \fBnormal\fR] -. -.TP -\fB\-l \fR, \fB\-\-listen \fR: -. -.IP -The port number on which to listen for data\. [default: \fB3210\fR] -. -.TP -\fB\-c \fR, \fB\-\-connect \fR: -. -.IP -Address of a peer to connect to\. The address should be in the form \fBaddr:port\fR\. If the node is not started, the connection will be retried periodically\. This parameter can be repeated to connect to multiple peers\. -. -.TP -\fB\-s \fR, \fB\-\-subnet \fR: -. -.IP -The local subnets to use\. This parameter should be in the form \fBaddress/prefixlen\fR 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: \fB10\.1\.1\.0/24\fR\. -. -.TP -\fB\-\-shared\-key \fR: -. -.IP -An optional shared key to encrypt the VPN data\. If this option is not set, the traffic will be sent unencrypted\. -. -.TP -\fB\-\-crypto \fR: -. -.IP -The encryption method to use ("aes256", or "chacha20")\. Most current CPUs have special support for AES256 so this should be faster\. For older computers lacking this support, only CHACHA20 is supported\. [default: \fBchacha20\fR] -. -.TP -\fB\-\-magic \fR: -. -.IP -Override the 4\-byte magic header of each packet\. This header identifies the network and helps to distinguish it from other networks and other applications\. The id can either be a 4 byte / 8 character hexadecimal string or an arbitrary string prefixed with "hash:" which will then be hashed into 4 bytes\. -. -.TP -\fB\-\-peer\-timeout \fR: -. -.IP -Peer timeout in seconds\. The peers will exchange information periodically and drop peers that are silent for this period of time\. [default: \fB1800\fR] -. -.TP -\fB\-\-dst\-timeout \fR: -. -.IP -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: \fB300\fR] -. -.TP -\fB\-\-ifup \fR: -. -.IP -A command to setup the network interface\. The command will be run (as parameter to \fBsh \-c\fR) when the device has been created to configure it\. The name of the allocated device will be available via the environment variable \fBIFNAME\fR\. Please note that this command is executed with the full permissions of the caller\. -. -.TP -\fB\-\-ifdown \fR: -. -.IP -A command to bring down the network interface\. The command will be run (as parameter to \fBsh \-c\fR) to remove any configuration from the device\. The name of the allocated device will be available via the environment variable \fBIFNAME\fR\. Please note that this command is executed with the (limited) permissions of the user and group given as \fB\-\-user\fR and \fB\-\-group\fR\. -. -.TP -\fB\-\-pid\-file \fR: -. -.IP -Store the process id in this file when running in the background\. If set, the given file will be created containing the process id of the new background process\. This option is only used when running in background\. -. -.TP -\fB\-\-user \fR: - -. -.TP -\fB\-\-group \fR: -. -.IP -Change the user and/or group of the process once all the setup has been done and before spawning the background process\. This option is only used when running in background\. -. -.TP -\fB\-\-log\-file \fR: -. -.IP -If set, print logs also to the given file\. The file will be created and truncated if is exists\. -. -.TP -\fB\-\-stats\-file \fR: -. -.IP -If set, periodically write statistics on peers and current traffic to the given file\. The file will be periodically overwritten with new data\. -. -.TP -\fB\-\-daemon\fR: -. -.IP -Spawn a background process instead of running the process in the foreground\. If this flag is set, the process will first carry out all the initialization, then drop permissions if \fB\-\-user\fR or \fB\-\-group\fR is used and then spawn a background process and write its process id to a file if \fB\-\-pid\-file\fR is set\. Then, the main process will exit and the background process continues to provide the VPN\. At the time, when the main process exits, the interface exists and is properly configured to be used\. -. -.TP -\fB\-\-no\-port\-forwarding\fR: -. -.IP -Disable automatic port forward\. If this option is not set, VpnCloud tries to detect a NAT router and automatically add a port forwarding to it\. -. -.TP -\fB\-v\fR, \fB\-\-verbose\fR: -. -.IP -Print debug information, including information for data being received and sent\. -. -.TP -\fB\-q\fR, \fB\-\-quiet\fR: -. -.IP -Only print errors and warnings\. -. -.TP -\fB\-h\fR, \fB\-\-help\fR: -. -.IP -Display the help\. -. +.sp +\fB\-\-config \fP +.RS 4 +Read configuration options from the specified file. Please see the section +\fBCONFIG FILES\fP for documentation on the file format. +If the same option is defined in the config file and as a parameter, the +parameter overrides the config file. +.RE +.sp +\fB\-t \fP, \fB\-\-type \fP +.RS 4 +Set the type of network. There are two options: \fBtap\fP devices process +Ethernet frames \fBtun\fP devices process IP packets. [default: \fBtap\fP] +.RE +.sp +\fB\-d \fP, \fB\-\-device \fP +.RS 4 +Name of the virtual device. Any \fB%d\fP will be filled with a free number. +[default: \fBvpncloud%d\fP] +.RE +.sp +\fB\-\-device\-path \fP +.RS 4 +The path of the base device inode, e.g. /dev/net/run. +.RE +.sp +\fB\-m \fP, \fB\-\-mode \fP +.RS 4 +The mode of the VPN. The VPN can like a router, a switch or a hub. A \fBhub\fP +will send all data always to all peers. A \fBswitch\fP will learn addresses +from incoming data and only send data to all peers when the address is +unknown. A \fBrouter\fP will send data according to known subnets of the +peers and ignore them otherwise. The \fBnormal\fP mode is switch for tap +devices and router for tun devices. [default: \fBnormal\fP] +.RE +.sp +\fB\-l \fP, \fB\-\-listen \fP +.RS 4 +The address on which to listen for data. This can be simply a port number +or a full address in form IP:PORT. If the IP is specified as \(aq\(rs*\(aq or only +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: \fB3210\fP] +.RE +.sp +\fB\-c \fP, \fB\-\-connect \fP +.RS 4 +Address of a peer to connect to. The address should be in the form +\fBaddr:port\fP. If the node is not started, the connection will be retried +periodically. This parameter can be repeated to connect to multiple peers. +.RE +.sp +\fB\-s \fP, \fB\-\-subnet \fP: + The local subnets to use. This parameter should be in the form + \fBaddress/prefixlen\fP 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: \fB10.1.1.0/24\fP. +.sp +\fB\-\-shared\-key \fP +.RS 4 +An optional shared key to encrypt the VPN data. If this option is not set, +the traffic will be sent unencrypted. +.RE +.sp +\fB\-\-crypto \fP +.RS 4 +The encryption method to use ("aes256", or "chacha20"). Most current CPUs +have special support for AES256 so this should be faster. For older +computers lacking this support, only CHACHA20 is supported. +[default: \fBchacha20\fP] +.RE +.sp +\fB\-\-magic \fP +.RS 4 +Override the 4\-byte magic header of each packet. This header identifies the +network and helps to distinguish it from other networks and other +applications. The id can either be a 4 byte / 8 character hexadecimal +string or an arbitrary string prefixed with "hash:" which will then be +hashed into 4 bytes. +.RE +.sp +\fB\-\-peer\-timeout \fP +.RS 4 +Peer timeout in seconds. The peers will exchange information periodically +and drop peers that are silent for this period of time. [default: \fB600\fP] +.RE +.sp +\fB\-\-keepalive \fP +.RS 4 +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: \fBpeer\-timeout/2\-60\fP] +.RE +.sp +\fB\-\-dst\-timeout \fP +.RS 4 +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: \fB300\fP] +.RE +.sp +\fB\-\-beacon\-store \fP +.RS 4 +Periodically store beacons containing the address of this node in the given +file or via the given command. If the parameter value starts with a pipe +character (\fB|\fP), the rest of the value is interpreted as a shell command. +Otherwise the value is interpreted as a file to write the beacon to. +If this parameter is not given, beacon storage is disabled. +Please see the section \fBBEACONS\fP for more information. +.RE +.sp +\fB\-\-beacon\-load \fP +.RS 4 +Periodically load beacons containing the addresses of other nodes from the +given file or via the given command. If the parameter value starts with a +pipe character (\fB|\fP), the rest of the value is interpreted as a shell +command. Otherwise the value is interpreted as a file to read the beacon +from. +If this parameter is not given, beacon loading is disabled. +Please see the section \fBBEACONS\fP for more information. +.RE +.sp +\fB\-\-beacon\-interval \fP +.RS 4 +Beacon storage/loading interval in seconds. If configured to do so via +\fB\-\-beacon\-store\fP and \fB\-\-beacon\-load\fP, the node will periodically store its +beacon and load beacons of other nodes. This parameter defines the interval +in seconds. [default: \fB3600\fP] +.RE +.sp +\fB\-\-ifup \fP +.RS 4 +A command to setup the network interface. The command will be run (as +parameter to \fBsh \-c\fP) when the device has been created to configure it. +The name of the allocated device will be available via the environment +variable \fBIFNAME\fP. +Please note that this command is executed with the full permissions of the +caller. +.RE +.sp +\fB\-\-ifdown \fP +.RS 4 +A command to bring down the network interface. The command will be run (as +parameter to \fBsh \-c\fP) to remove any configuration from the device. +The name of the allocated device will be available via the environment +variable \fBIFNAME\fP. +Please note that this command is executed with the (limited) permissions of +the user and group given as \fB\-\-user\fP and \fB\-\-group\fP. +.RE +.sp +\fB\-\-pid\-file \fP +.RS 4 +Store the process id in this file when running in the background. If set, +the given file will be created containing the process id of the new +background process. This option is only used when running in background. +.RE +.sp +\fB\-\-user \fP, \fB\-\-group \fP +.RS 4 +Change the user and/or group of the process once all the setup has been +done. +.RE +.sp +\fB\-\-log\-file \fP +.RS 4 +If set, print logs also to the given file. The file will be created and +truncated if is exists. +.RE +.sp +\fB\-\-stats\-file \fP +.RS 4 +If set, periodically write statistics on peers and current traffic to the +given file. The file will be periodically overwritten with new data. +.RE +.sp +\fB\-\-daemon\fP +.RS 4 +Spawn a background process instead of running the process in the foreground. +If this flag is set, the process will first carry out all the +initialization, then drop permissions if \fB\-\-user\fP or \fB\-\-group\fP is used and +then spawn a background process and write its process id to a file if +\fB\-\-pid\-file\fP is set. Then, the main process will exit and the background +process continues to provide the VPN. At the time, when the main process +exits, the interface exists and is properly configured to be used. +.RE +.sp +\fB\-\-no\-port\-forwarding\fP +.RS 4 +Disable automatic port forward. If this option is not set, VpnCloud tries to +detect a NAT router and automatically add a port forwarding to it. +.RE +.sp +\fB\-v\fP, \fB\-\-verbose\fP +.RS 4 +Print debug information, including information for data being received and +sent. +.RE +.sp +\fB\-q\fP, \fB\-\-quiet\fP +.RS 4 +Only print errors and warnings. +.RE +.sp +\fB\-h\fP, \fB\-\-help\fP +.RS 4 +Display the help. +.RE .SH "DESCRIPTION" -\fBVpnCloud\fR is a simple VPN over UDP\. It creates a virtual network interface on the host and forwards all received data via UDP to the destination\. It can work in 3 different modes: -. -.IP "\(bu" 4 -\fBSwitch mode\fR: In this mode, the VPN will dynamically learn addresses as they are used as source addresses and use them to forward data to its destination\. Addresses that have not been seen for some time (option \fBdst_timeout\fR) 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 packets\. -. -.IP "\(bu" 4 -\fBHub mode\fR: 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\. -. -.IP "\(bu" 4 -\fBRouter mode\fR: In this mode, data will be forwarded based on preconfigured address ranges ("subnets")\. Data for unknown nodes will be silently ignored\. This mode is the default mode for TUN devices that work with IP packets but it can also be used with TAP devices and Ethernet frames\. -. -.IP "" 0 -. -.P -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 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: -. -.IP "\(bu" 4 -To avoid that different networks that reuse each others addresses merge due to the cross\-connect behavior, the \fBmagic\fR option can be used and set to any unique string to identify the network\. The \fBmagic\fR must be the same on all nodes of the same VPN network\. -. -.IP "\(bu" 4 -The cross\-connect behavior can be able to connect nodes that are behind firewalls or NATs as it can function as hole\-punching\. -. -.IP "\(bu" 4 -The management traffic will increase with the peer number quadratically\. It should still be reasonably small for high node numbers (below 10 KiB/s for 10\.000 nodes)\. A longer \fBpeer_timeout\fR can be used to reduce the traffic further\. For high node numbers, router mode should be used as it never broadcasts data\. -. -.IP "" 0 -. -.P -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 transported to avoid loops caused by other network components\. -. -.P -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\. -. +.sp +\fBVpnCloud\fP is a simple VPN over UDP. It creates a virtual network interface on +the host and forwards all received data via UDP to the destination. It can work +in 3 different modes: +.sp +\fBSwitch mode\fP +.RS 4 +In this mode, the VPN will dynamically learn addresses +as they are used as source addresses and use them to forward data to its +destination. Addresses that have not been seen for some time +(option \fBdst_timeout\fP) 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 +packets. +.RE +.sp +\fBHub mode\fP +.RS 4 +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. +.RE +.sp +\fBRouter mode\fP +.RS 4 +In this mode, data will be forwarded based on preconfigured +address ranges ("subnets"). Data for unknown nodes will be silently ignored. +This mode is the default mode for TUN devices that work with IP packets but +it can also be used with TAP devices and Ethernet frames. +.RE +.sp +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 +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: +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +To avoid that different networks that reuse each others addresses merge due +to the cross\-connect behavior, the \fBmagic\fP option can be used and set +to any unique string to identify the network. The \fBmagic\fP must be the +same on all nodes of the same VPN network. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +The cross\-connect behavior can be able to connect nodes that are behind +firewalls or NATs as it can function as hole\-punching. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +The management traffic will increase with the peer number quadratically. +It should still be reasonably small for high node numbers (below 10 KiB/s +for 10.000 nodes). A longer \fBpeer_timeout\fP can be used to reduce the traffic +further. For high node numbers, router mode should be used as it never +broadcasts data. +.RE +.sp +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 +transported to avoid loops caused by other network components. +.sp +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. .SH "EXAMPLES" -. .SS "Switched TAP scenario" -In the example scenario, a simple layer 2 network tunnel is established\. Most likely those commands need to be run as \fBroot\fR using \fBsudo\fR\. -. -.P -First, VpnCloud need to be started on both nodes (the address after \fB\-c\fR is the address of the remote node and the the \fBX\fR in the interface address must be unique among all nodes, e\.g\. 0, 1, 2, \.\.\.): -. -.IP "" 4 -. +.sp +In the example scenario, a simple layer 2 network tunnel is established. Most +likely those commands need to be run as \fBroot\fP using \fBsudo\fP. +.sp +First, VpnCloud need to be started on both nodes (the address after \fB\-c\fP is the +address of the remote node and the the \fBX\fP in the interface address must be +unique among all nodes, e.g. 0, 1, 2, ...): +.sp +.if n \{\ +.RS 4 +.\} .nf - -vpncloud \-c REMOTE_HOST:PORT \-\-ifup \'ifconfig $IFNAME 10\.0\.0\.X/24 mtu 1400 up\' -. +vpncloud \-c REMOTE_HOST:PORT \-\-ifup \(aqifconfig $IFNAME 10.0.0.X/24 mtu 1400 up\(aq .fi -. -.IP "" 0 -. -.P -Afterwards, the interface can be used to communicate\. -. +.if n \{\ +.RE +.\} +.sp +Afterwards, the interface can be used to communicate. .SS "Routed TUN example" -In this example, 2 nodes and their subnets should communicate using IP\. First, VpnCloud need to be started on both nodes: -. -.IP "" 4 -. +.sp +In this example, 2 nodes and their subnets should communicate using IP. +First, VpnCloud need to be started on both nodes: +.sp +.if n \{\ +.RS 4 +.\} .nf - -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 \-\-subnet 10.0.X.0/24 \-\-ifup \(aqifconfig $IFNAME 10.0.X.1/16 mtu 1400 up\(aq .fi -. -.IP "" 0 -. -.P -It is important to configure the interface in a way that all addresses on the VPN can be reached directly\. E\.g\. if subnets 10\.0\.1\.0/24, 10\.0\.2\.0/24 and so on are used, the interface needs to be configured as 10\.0\.1\.1/16\. For TUN devices, this means that the prefix length of the subnets (/24 in this example) must be different than the prefix length that the interface is configured with (/16 in this example)\. -. +.if n \{\ +.RE +.\} +.sp +It is important to configure the interface in a way that all addresses on the +VPN can be reached directly. E.g. if subnets 10.0.1.0/24, 10.0.2.0/24 and so on +are used, the interface needs to be configured as 10.0.1.1/16. +For TUN devices, this means that the prefix length of the subnets +(/24 in this example) must be different than the prefix length that the +interface is configured with (/16 in this example). .SS "Important notes" -. -.IP "\(bu" 4 -VpnCloud can be used to connect two separate networks\. TAP networks can be bridged using \fBbrctl\fR and TUN networks must be routed\. It is very important to be careful when setting up such a scenario in order to avoid network loops, security issues, DHCP issues and many more problems\. -. -.IP "\(bu" 4 -TAP devices will forward DHCP data\. If done intentionally, this can be used 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\. -. -.IP "\(bu" 4 -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 \fIScryptSalsa208Sha256\fR to derive a key, which is used to encrypt the payload of messages using \fIChaCha20Poly1305\fR or \fIAES256\-GCM\fR\. 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)\. -. -.IP "" 0 -. +.sp +.RS 4 +.ie n \{\ +\h'-04' 1.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 1." 4.2 +.\} +VpnCloud can be used to connect two separate networks. TAP networks can be +bridged using \fBbrctl\fP and TUN networks must be routed. It is very important +to be careful when setting up such a scenario in order to avoid network loops, +security issues, DHCP issues and many more problems. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 2.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 2." 4.2 +.\} +TAP devices will forward DHCP data. If done intentionally, this can be used +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. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04' 3.\h'+01'\c +.\} +.el \{\ +.sp -1 +.IP " 3." 4.2 +.\} +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 \fIScryptSalsa208Sha256\fP to derive a key, +which is used to encrypt the payload of messages using \fIChaCha20Poly1305\fP or +\fIAES256\-GCM\fP. 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). +.RE .SH "CONFIG FILES" -The config file is a YAML file that contains configuration values\. All entries are optional and override the defaults\. Please see the section \fBOPTIONS\fR for detailed descriptions of the options\. -. -.IP "\(bu" 4 -\fBdevice_type\fR: Set the type of network\. Same as \fB\-\-type\fR -. -.IP "\(bu" 4 -\fBdevice_name\fR: Name of the virtual device\. Same as \fB\-\-device\fR -. -.IP "\(bu" 4 -\fBdevice_path\fR: Set the path of the base device\. Same as \fB\-\-device\-path\fR -. -.IP "\(bu" 4 -\fBifup\fR: A command to setup the network interface\. Same as \fB\-\-ifup\fR -. -.IP "\(bu" 4 -\fBifdown\fR: A command to bring down the network interface\. Same as \fB\-\-ifdown\fR -. -.IP "\(bu" 4 -\fBcrypto\fR: The encryption method to use\. Same as \fB\-\-crypto\fR -. -.IP "\(bu" 4 -\fBshared_key\fR: The shared key to encrypt all traffic\. Same as \fB\-\-shared\-key\fR -. -.IP "\(bu" 4 -\fBmagic\fR: Override the 4\-byte magic header of each packet\. Same as \fB\-\-magic\fR -. -.IP "\(bu" 4 -\fBport\fR: The port number on which to listen for data\. Same as \fB\-\-listen\fR -. -.IP "\(bu" 4 -\fBpeers\fR: A list of addresses to connect to\. See \fB\-\-connect\fR -. -.IP "\(bu" 4 -\fBpeer_timeout\fR: Peer timeout in seconds\. Same as\fB\-\-peer\-timeout\fR -. -.IP "\(bu" 4 -\fBmode\fR: The mode of the VPN\. Same as \fB\-\-mode\fR -. -.IP "\(bu" 4 -\fBdst_timeout\fR: Switch table entry timeout in seconds\. Same as \fB\-\-dst\-timeout\fR -. -.IP "\(bu" 4 -\fBsubnets\fR: A list of local subnets to use\. See \fB\-\-subnet\fR -. -.IP "\(bu" 4 -\fBport_forwarding\fR: Whether to activate port forwardig\. See \fB\-\-no\-port\-forwarding\fR -. -.IP "\(bu" 4 -\fBuser\fR: The name of a user to run the background process under\. See \fB\-\-user\fR -. -.IP "\(bu" 4 -\fBgroup\fR: The name of a group to run the background process under\. See \fB\-\-group\fR -. -.IP "\(bu" 4 -\fBpid_file\fR: The path of the pid file to create\. See \fB\-\-pid\-file\fR -. -.IP "\(bu" 4 -\fBstats_file\fR: The path of the statistics file\. See \fB\-\-stats\-file\fR -. -.IP "" 0 -. +.sp +The config file is a YAML file that contains configuration values. All entries +are optional and override the defaults. Please see the section \fBOPTIONS\fP for +detailed descriptions of the options. +.sp +\fBdevice_type\fP +.RS 4 +Set the type of network. Same as \fB\-\-type\fP +.RE +.sp +\fBdevice_name\fP +.RS 4 +Name of the virtual device. Same as \fB\-\-device\fP +.RE +.sp +\fBdevice_path\fP +.RS 4 +Set the path of the base device. Same as \fB\-\-device\-path\fP +.RE +.sp +\fBifup\fP +.RS 4 +A command to setup the network interface. Same as \fB\-\-ifup\fP +.RE +.sp +\fBifdown\fP +.RS 4 +A command to bring down the network interface. Same as \fB\-\-ifdown\fP +.RE +.sp +\fBcrypto\fP +.RS 4 +The encryption method to use. Same as \fB\-\-crypto\fP +.RE +.sp +\fBshared_key\fP +.RS 4 +The shared key to encrypt all traffic. Same as \fB\-\-shared\-key\fP +.RE +.sp +\fBmagic\fP +.RS 4 +Override the 4\-byte magic header of each packet. Same as \fB\-\-magic\fP +.RE +.sp +\fBport\fP +.RS 4 +A port number to listen on. This option is DEPRECATED. +.RE +.sp +\fBlisten\fP +.RS 4 +The address on which to listen for data. Same as \fB\-\-listen\fP +.RE +.sp +\fBpeers\fP +.RS 4 +A list of addresses to connect to. See \fB\-\-connect\fP +.RE +.sp +\fBpeer_timeout\fP +.RS 4 +Peer timeout in seconds. Same as\fB\-\-peer\-timeout\fP +.RE +.sp +\fBbeacon_store\fP +.RS 4 +Path or command to store beacons. Same as \fB\-\-beacon\-store\fP +.RE +.sp +\fBbeacon_load\fP +.RS 4 +Path or command to load beacons. Same as \fB\-\-beacon\-load\fP +.RE +.sp +\fBbeacon_interval\fP +.RS 4 +Interval for loading and storing beacons in seconds. Same as \fB\-\-beacon\-interval\fP +.RE +.sp +\fBmode\fP +.RS 4 +The mode of the VPN. Same as \fB\-\-mode\fP +.RE +.sp +\fBdst_timeout\fP +.RS 4 +Switch table entry timeout in seconds. Same as \fB\-\-dst\-timeout\fP +.RE +.sp +\fBsubnets\fP +.RS 4 +A list of local subnets to use. See \fB\-\-subnet\fP +.RE +.sp +\fBport_forwarding\fP +.RS 4 +Whether to activate port forwardig. See \fB\-\-no\-port\-forwarding\fP +.RE +.sp +\fBuser\fP +.RS 4 +The name of a user to run the background process under. See \fB\-\-user\fP +.RE +.sp +\fBgroup\fP +.RS 4 +The name of a group to run the background process under. See \fB\-\-group\fP +.RE +.sp +\fBpid_file\fP +.RS 4 +The path of the pid file to create. See \fB\-\-pid\-file\fP +.RE +.sp +\fBstats_file\fP +.RS 4 +The path of the statistics file. See \fB\-\-stats\-file\fP +.RE .SS "Example" -device_type: tun device_name: vpncloud%d ifup: ifconfig $IFNAME 10\.0\.1\.1/16 mtu 1400 up crypto: aes256 shared_key: mysecret port: 3210 peers: \- remote\.machine\.foo:3210 \- remote\.machine\.bar:3210 peer_timeout: 1800 mode: normal subnets: \- 10\.0\.1\.0/24 port_forwarding: true user: nobody group: nogroup pid_file: /run/vpncloud\.pid -. +.sp +.if n \{\ +.RS 4 +.\} +.nf +device_type: tun +device_name: vpncloud%d +ifup: ifconfig $IFNAME 10.0.1.1/16 mtu 1400 up +crypto: aes256 +shared_key: mysecret +listen: 3210 +peers: + \- remote.machine.foo:3210 + \- remote.machine.bar:3210 +peer_timeout: 600 +mode: normal +subnets: + \- 10.0.1.0/24 +port_forwarding: true +user: nobody +group: nogroup +pid_file: /run/vpncloud.pid +.fi +.if n \{\ +.RE +.\} +.SH "BEACONS" +.sp +Beacons are short character sequences that contain a timestamp and a list of +addresses. They can be published and retrieved by other nodes to find peers +without the need for static addresses. +.sp +The beacons are short (less than 100 characters), encrypted and encoded with +printable characters to allow publishing them in various places on the +internet, e.g.: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +On shared drives or synchronized folders (e.g. on Dropbox) +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Via a dedicated database +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Via a general purpose message board of message service (e.g. Twitter) +.RE +.sp +The beacons are very robust. They only consist of alphanumeric characters +and can be interleaved with non\-alphanumeric characters (e.g. whitespace). +Also the beacons contain a prefix and suffix that depends on the configured +network magic and secret key (if set) so that all nodes can find beacons in +a long text. +.sp +When beacons are stored or loaded via a command (using the pipe character \fB|\fP), +the command is interpreted using the configured shell \fBsh\fP. This command has +access to the following environment variables: +.sp +\fB$begin\fP +.RS 4 +The prefix of the beacon. +.RE +.sp +\fB$end\fP +.RS 4 +The suffix of the beacon. +.RE +.sp +\fB$data\fP (only on store) +.RS 4 +The middle part of the beacon. Do not use this +without prefix and suffix! +.RE +.sp +\fB$beacon\fP (only on store) +.RS 4 +The full beacon consisting of prefix, data and +suffix. +The commands are called in separate threads, so even longer running commands +will not block the node. +.RE .SH "NETWORK PROTOCOL" -The protocol of VpnCloud is kept as simple as possible to allow other implementations and to maximize the performance\. -. -.P +.sp +The protocol of VpnCloud is kept as simple as possible to allow other +implementations and to maximize the performance. +.sp Every packet sent over UDP contains the following header (in order): -. -.IP "\(bu" 4 -4 bytes \fBmagic\fR -. -.IP -This field is used to identify the packet and to sort out packets that do not belong\. The default is \fB[0x76, 0x70, 0x6e, 0x01]\fR ("vpn\ex01")\. This field can be used to identify VpnCloud packets and might be set to something different to hide the protocol\. -. -.IP "\(bu" 4 -1 byte \fBcrypto method\fR -. -.IP -This field specifies the method that must be used to decrypt the rest of the data\. The currently supported methods are: -. -.IP "\(bu" 4 -Method \fB0\fR, \fBNo encryption\fR: Rest of the data can be read without decrypting it\. -. -.IP "\(bu" 4 -Method \fB1\fR, \fBChaCha20\fR: The header is followed by a 12 byte \fInonce\fR\. The rest of the data is encrypted with the \fBlibsodium::crypto_aead_chacha20poly1305_ietf\fR method, using the 8 byte header as additional data\. -. -.IP "\(bu" 4 -Method \fB2\fR, \fBAES256\fR: The header is followed by a 12 byte \fInonce\fR\. The rest of the data is encrypted with the \fBlibsodium::crypto_aead_aes256gcm\fR method, using the 8 byte header as additional data\. -. -.IP "" 0 - -. -.IP "\(bu" 4 -2 \fBreserved bytes\fR that are currently unused and set to 0 -. -.IP "\(bu" 4 -1 byte for the \fBmessage type\fR -. -.IP -This byte specifies the type of message that follows\. Currently the following message types are supported: -. -.IP "\(bu" 4 +.sp +4 bytes \fBmagic\fP +.RS 4 +This field is used to identify the packet and to sort out packets that do +not belong. The default is \fB[0x76, 0x70, 0x6e, 0x01]\fP ("vpn\(rsx01"). +This field can be used to identify VpnCloud packets and might be set to +something different to hide the protocol. +.RE +.sp +1 byte \fBcrypto method\fP +.RS 4 +This field specifies the method that must be used to decrypt the rest of the +data. The currently supported methods are: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Method \fB0\fP, \fBNo encryption\fP: Rest of the data can be read without +decrypting it. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Method \fB1\fP, \fBChaCha20\fP: The header is followed by a 12 byte +\fInonce\fP. The rest of the data is encrypted with the +\fBlibsodium::crypto_aead_chacha20poly1305_ietf\fP method, using the 8 byte +header as additional data. +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} +Method \fB2\fP, \fBAES256\fP: The header is followed by a 12 byte \fInonce\fP. +The rest of the data is encrypted with the +\fBlibsodium::crypto_aead_aes256gcm\fP method, using the 8 byte header +as additional data. +.RE +.RE +.sp +2 \fBreserved bytes\fP +.RS 4 +that are currently unused and set to 0 +.RE +.sp +1 byte for the \fBmessage type\fP +.RS 4 +This byte specifies the type of message that follows. Currently the +following message types are supported: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} Type 0: Data packet -. -.IP "\(bu" 4 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} Type 1: Peer list -. -.IP "\(bu" 4 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} Type 2: Initial message -. -.IP "\(bu" 4 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} Type 3: Closing message -. -.IP "" 0 - -. -.IP "" 0 -. -.P -After this 8 byte header, the rest of the message follows\. It is encrypted using the method specified in the header\. -. -.P -In the decrypted data, the message as specified in the \fBmessage type\fR field will follow: -. -.IP "\(bu" 4 -\fBData packet\fR (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\. -. -.IP "\(bu" 4 -\fBPeer list\fR (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)\. -. -.IP "\(bu" 4 -\fBInitial message\fR (message type 2): This packet contains the following information: -. -.IP "\(bu" 4 +.RE +.RE +.sp +After this 8 byte header, the rest of the message follows. It is encrypted using +the method specified in the header. +.sp +In the decrypted data, the message as specified in the \fBmessage type\fP field +will follow: +.sp +\fBData packet\fP (message type 0) +.RS 4 +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. +.RE +.sp +\fBPeer list\fP (message type 1) +.RS 4 +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). +.RE +.sp +\fBInitial message\fP (message type 2) +.RS 4 +This packet contains the following information: +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} The stage of the initialization process -. -.IP "\(bu" 4 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} A random node id to distinguish different nodes -. -.IP "\(bu" 4 +.RE +.sp +.RS 4 +.ie n \{\ +\h'-04'\(bu\h'+03'\c +.\} +.el \{\ +.sp -1 +.IP \(bu 2.3 +.\} All the local subnets claimed by the nodes -. -.IP "" 0 -. -.IP -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\. -. -.IP "\(bu" 4 -\fBClosing message\fR (message type 3): This packet does not contain any more data\. -. -.IP "" 0 -. -.P -Nodes are expected to send an \fBinitial message\fR 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 \fBpeer list\fR message should be sent as a reply\. -. -.P -When connected, nodes should periodically send their \fBpeer list\fR 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\. -. -.P -Nodes should remove peers from their peer list after a certain period of inactivity or when receiving a \fBclosing message\fR\. 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\. -. -.P -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\. -. +.RE +.sp +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. +.RE +.sp +\fBClosing message\fP (message type 3) +.RS 4 +This packet does not contain any more data. +.RE +.sp +Nodes are expected to send an \fBinitial message\fP 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 \fBpeer list\fP message should +be sent as a reply. +.sp +When connected, nodes should periodically send their \fBpeer list\fP 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. +.sp +Nodes should remove peers from their peer list after a certain period of +inactivity or when receiving a \fBclosing message\fP. 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. +.sp +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. .SH "COPYRIGHT" -Copyright (C) 2015\-2020 Dennis Schwerdel This software is licensed under GPL\-3 or newer (see LICENSE\.md) +.sp +Copyright \(co 2015\-2020 Dennis Schwerdel +This software is licensed under GPL\-3 or newer (see LICENSE.md) \ No newline at end of file diff --git a/build.rs b/build.rs index ba3e46d..a7e9439 100644 --- a/build.rs +++ b/build.rs @@ -13,17 +13,21 @@ fn main() { println!("cargo:rerun-if-changed=src/c/tuntap.c"); cc::Build::new().file("src/c/tuntap.c").include("src").compile("libtuntap.a"); - // Process manpage using ronn command - println!("cargo:rerun-if-changed=vpncloud.md"); - fs::copy("vpncloud.md", Path::new(&out_dir).join("vpncloud.1.ronn")).unwrap(); - match Command::new("ronn").args(&["-r", "vpncloud.1.ronn"]).current_dir(&Path::new(&out_dir)).status() { + // Process manpage using asciidoctor command + println!("cargo:rerun-if-changed=vpncloud.adoc"); + fs::copy("vpncloud.adoc", Path::new(&out_dir).join("vpncloud.adoc")).unwrap(); + match Command::new("asciidoctor") + .args(&["-b", "manpage", "vpncloud.adoc"]) + .current_dir(&Path::new(&out_dir)) + .status() + { Ok(_) => { Command::new("gzip").args(&["vpncloud.1"]).current_dir(&Path::new(&out_dir)).status().unwrap(); fs::copy(Path::new(&out_dir).join("vpncloud.1.gz"), "target/vpncloud.1.gz").unwrap(); } Err(err) => { println!("cargo:warning=Error building manpage: {}", err); - println!("cargo:warning=The manpage will not be build. Do you have 'ronn'?"); + println!("cargo:warning=The manpage will not be build. Do you have 'asciidoctor'?"); } } } diff --git a/builder/Dockerfile-deb b/builder/Dockerfile-deb index c786c12..9c68365 100644 --- a/builder/Dockerfile-deb +++ b/builder/Dockerfile-deb @@ -10,7 +10,7 @@ RUN apt-get update \ libc6-dev-armhf-cross \ libc6-dev-i386 \ gcc-5-multilib \ - ruby-ronn \ + asciidoctor \ && rm -rf /var/cache/dpkg RUN ln -s asm-generic/ /usr/include/asm diff --git a/builder/Dockerfile-rpm b/builder/Dockerfile-rpm index 6ae7fa6..db6d7ed 100644 --- a/builder/Dockerfile-rpm +++ b/builder/Dockerfile-rpm @@ -1,9 +1,7 @@ FROM centos:7 RUN yum groupinstall -y 'Development Tools' - -RUN yum-config-manager --add-repo http://springdale.math.ias.edu/data/puias/computational/7/x86_64 \ - && yum install --nogpgcheck -y rubygem-ronn +RUN yum install -y ruby && gem install asciidoctor RUN useradd -ms /bin/bash user USER user diff --git a/vpncloud.adoc b/vpncloud.adoc new file mode 100644 index 0000000..da3bba8 --- /dev/null +++ b/vpncloud.adoc @@ -0,0 +1,465 @@ +vpncloud(1) +=========== + +== Name +vpncloud - Peer-to-peer VPN + + +== SYNOPSIS + +*vpncloud [options] [--config ] [-t ] [-d ] [-l ] [-c ...]* + + +== OPTIONS + +*--config *:: + Read configuration options from the specified file. Please see the section + *CONFIG FILES* for documentation on the file format. + If the same option is defined in the config file and as a parameter, the + parameter overrides the config file. + +*-t *, *--type *:: + Set the type of network. There are two options: *tap* devices process + Ethernet frames *tun* devices process IP packets. [default: *tap*] + +*-d *, *--device *:: + Name of the virtual device. Any *%d* will be filled with a free number. + [default: *vpncloud%d*] + +*--device-path *:: + The path of the base device inode, e.g. /dev/net/run. + +*-m *, *--mode *:: + The mode of the VPN. The VPN can like a router, a switch or a hub. A *hub* + will send all data always to all peers. A *switch* will learn addresses + from incoming data and only send data to all peers when the address is + unknown. A *router* will send data according to known subnets of the + peers and ignore them otherwise. The *normal* mode is switch for tap + devices and router for tun devices. [default: *normal*] + +*-l *, *--listen *:: + The address on which to listen for data. This can be simply a port number + or a full address in form IP:PORT. If the IP is specified as \'\*' or only + 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 *, *--connect *:: + 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 *: + The local subnets to use. 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 *:: + An optional shared key to encrypt the VPN data. If this option is not set, + the traffic will be sent unencrypted. + +*--crypto *:: + The encryption method to use ("aes256", or "chacha20"). Most current CPUs + have special support for AES256 so this should be faster. For older + computers lacking this support, only CHACHA20 is supported. + [default: *chacha20*] + +*--magic *:: + Override the 4-byte magic header of each packet. This header identifies the + network and helps to distinguish it from other networks and other + applications. The id can either be a 4 byte / 8 character hexadecimal + string or an arbitrary string prefixed with "hash:" which will then be + hashed into 4 bytes. + +*--peer-timeout *:: + Peer timeout in seconds. The peers will exchange information periodically + and drop peers that are silent for this period of time. [default: **600**] + +*--keepalive *:: + 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 *:: + 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**] + +*--beacon-store *:: + Periodically store beacons containing the address of this node in the given + file or via the given command. If the parameter value starts with a pipe + character (*|*), the rest of the value is interpreted as a shell command. + Otherwise the value is interpreted as a file to write the beacon to. + If this parameter is not given, beacon storage is disabled. + Please see the section *BEACONS* for more information. + +*--beacon-load *:: + Periodically load beacons containing the addresses of other nodes from the + given file or via the given command. If the parameter value starts with a + pipe character (*|*), the rest of the value is interpreted as a shell + command. Otherwise the value is interpreted as a file to read the beacon + from. + If this parameter is not given, beacon loading is disabled. + Please see the section *BEACONS* for more information. + +*--beacon-interval *:: + 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**] + +*--ifup *:: + A command to setup the network interface. The command will be run (as + parameter to *sh -c*) when the device has been created to configure it. + 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. + +*--ifdown *:: + A command to bring down the network interface. The command will be run (as + parameter to *sh -c*) to remove any configuration from the device. + The name of the allocated device will be available via the environment + variable *IFNAME*. + Please note that this command is executed with the (limited) permissions of + the user and group given as *--user* and *--group*. + +*--pid-file *:: + Store the process id in this file when running in the background. If set, + the given file will be created containing the process id of the new + background process. This option is only used when running in background. + +*--user *:: +*--group *:: + Change the user and/or group of the process once all the setup has been + done. + +*--log-file *:: + If set, print logs also to the given file. The file will be created and + truncated if is exists. + +*--stats-file *:: + If set, periodically write statistics on peers and current traffic to the + given file. The file will be periodically overwritten with new data. + +*--daemon*:: + Spawn a background process instead of running the process in the foreground. + If this flag is set, the process will first carry out all the + initialization, then drop permissions if *--user* or *--group* is used and + then spawn a background process and write its process id to a file if + *--pid-file* is set. Then, the main process will exit and the background + process continues to provide the VPN. At the time, when the main process + exits, the interface exists and is properly configured to be used. + +*--no-port-forwarding*:: + Disable automatic port forward. If this option is not set, VpnCloud tries to + detect a NAT router and automatically add a port forwarding to it. + +*-v*, *--verbose*:: + Print debug information, including information for data being received and + sent. + +*-q*, *--quiet*:: + Only print errors and warnings. + +*-h*, *--help*:: + Display the help. + + +== DESCRIPTION + +*VpnCloud* is a simple VPN over UDP. It creates a virtual network interface on +the host and forwards all received data via UDP to the 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 +destination. Addresses that have not been seen for some time +(option *dst_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 +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. +This mode is the default mode for TUN devices that work with IP 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 +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. +It should still be reasonably small for high node numbers (below 10 KiB/s +for 10.000 nodes). A longer *peer_timeout* can be used to reduce the traffic +further. For high node numbers, router mode should be used as it never +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 +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 + +In the example scenario, a simple layer 2 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 +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' +---- + +Afterwards, the interface can be used to communicate. + +=== Routed TUN example + +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' +---- + +It is important to configure the interface in a way that all addresses on the +VPN can be reached directly. E.g. if subnets 10.0.1.0/24, 10.0.2.0/24 and so on +are used, the interface needs to be configured as 10.0.1.1/16. +For TUN devices, this means that the prefix length of the subnets +(/24 in this example) must be different than the prefix length that the +interface is configured with (/16 in this example). + +=== Important notes + +. VpnCloud can be used to connect two separate networks. TAP networks can be +bridged using *brctl* and TUN networks must be routed. It is very important +to be careful when setting up such a scenario in order to avoid network loops, +security issues, DHCP issues and many more problems. +. TAP devices will forward DHCP data. If done intentionally, this can be used +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 _ScryptSalsa208Sha256_ to derive a key, +which is used to encrypt the payload of messages using _ChaCha20Poly1305_ 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 + +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_name*:: Name of the virtual device. Same as *--device* +*device_path*:: Set the path of the base device. Same as *--device-path* +*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* +*shared_key*:: The shared key to encrypt all traffic. Same as *--shared-key* +*magic*:: Override the 4-byte magic header of each packet. Same as *--magic* +*port*:: A port number to listen on. This option is DEPRECATED. +*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** +*beacon_store*:: Path or command to store beacons. Same as *--beacon-store* +*beacon_load*:: Path or command to load beacons. Same as *--beacon-load* +*beacon_interval*:: Interval for loading and storing beacons in seconds. Same as *--beacon-interval* +*mode*:: The mode of the VPN. Same as *--mode* +*dst_timeout*:: Switch table entry timeout in seconds. Same as *--dst-timeout* +*subnets*:: A list of local subnets to use. See *--subnet* +*port_forwarding*:: Whether to activate port forwardig. See *--no-port-forwarding* +*user*:: The name of a user to run the background process under. See *--user* +*group*:: The name of a group to run the background process under. See *--group* +*pid_file*:: The path of the pid file to create. See *--pid-file* +*stats_file*:: The path of the statistics file. See *--stats-file* + +=== Example + + device_type: tun + device_name: vpncloud%d + ifup: ifconfig $IFNAME 10.0.1.1/16 mtu 1400 up + crypto: aes256 + shared_key: mysecret + listen: 3210 + peers: + - remote.machine.foo:3210 + - remote.machine.bar:3210 + peer_timeout: 600 + mode: normal + subnets: + - 10.0.1.0/24 + port_forwarding: true + user: nobody + group: nogroup + pid_file: /run/vpncloud.pid + +== BEACONS + +Beacons are short character sequences that contain a timestamp and a list of +addresses. They can be published and retrieved by other nodes to find peers +without the need for static addresses. + +The beacons are short (less than 100 characters), encrypted and encoded with +printable characters to allow publishing them in various places on the +internet, e.g.: + +* On shared drives or synchronized folders (e.g. on Dropbox) +* Via a dedicated database +* Via a general purpose message board of message service (e.g. Twitter) + +The beacons are very robust. They only consist of alphanumeric characters +and can be interleaved with non-alphanumeric characters (e.g. whitespace). +Also the beacons contain a prefix and suffix that depends on the configured +network magic and secret key (if set) so that all nodes can find beacons in +a long text. + +When beacons are stored or loaded via a command (using the pipe character *|*), +the command is interpreted using the configured shell *sh*. This command has +access to the following environment variables: + +*$begin*:: The prefix of the beacon. +*$end*:: The suffix of the beacon. +*$data* (only on store):: The middle part of the beacon. Do not use this +without prefix and suffix! +*$beacon* (only on store):: The full beacon consisting of prefix, data and +suffix. +The commands are called in separate threads, so even longer running commands +will not block the node. + +== NETWORK PROTOCOL + +The protocol of VpnCloud is kept as simple as possible to allow other +implementations and to maximize the performance. + +Every packet sent over UDP contains the following header (in order): + +4 bytes *magic*:: +This field is used to identify the packet and to sort out packets that do +not belong. The default is *[0x76, 0x70, 0x6e, 0x01]* ("vpn\x01"). +This field can be used to identify VpnCloud packets and might be set to +something different to hide the protocol. + +1 byte *crypto method*:: +This field specifies the method that must be used to decrypt the rest of the +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 + +Copyright (C) 2015-2020 Dennis Schwerdel +This software is licensed under GPL-3 or newer (see LICENSE.md) diff --git a/vpncloud.md b/vpncloud.md deleted file mode 100644 index 8661ba6..0000000 --- a/vpncloud.md +++ /dev/null @@ -1,507 +0,0 @@ -vpncloud(1) -- Peer-to-peer VPN -=============================== - -## SYNOPSIS - -`vpncloud [options] [--config ] [-t ] [-d ] [-l ] [-c ...]` - - -## OPTIONS - - * `--config `: - - Read configuration options from the specified file. Please see the section - **CONFIG FILES** for documentation on the file format. - If the same option is defined in the config file and as a parameter, the - parameter overrides the config file. - - * `-t `, `--type `: - - Set the type of network. There are two options: **tap** devices process - Ethernet frames **tun** devices process IP packets. [default: `tap`] - - * `-d `, `--device `: - - Name of the virtual device. Any `%d` will be filled with a free number. - [default: `vpncloud%d`] - - * `--device-path `: - - The path of the base device inode, e.g. /dev/net/run. - - * `-m `, `--mode `: - - The mode of the VPN. The VPN can like a router, a switch or a hub. A **hub** - will send all data always to all peers. A **switch** will learn addresses - from incoming data and only send data to all peers when the address is - unknown. A **router** will send data according to known subnets of the - peers and ignore them otherwise. The **normal** mode is switch for tap - devices and router for tun devices. [default: `normal`] - - * `-l `, `--listen `: - - The address on which to listen for data. This can be simply a port number - or a full address in form IP:PORT. If the IP is specified as '*' or only - 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 `, `--connect `: - - 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 `: - - The local subnets to use. 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 `: - - An optional shared key to encrypt the VPN data. If this option is not set, - the traffic will be sent unencrypted. - - * `--crypto `: - - The encryption method to use ("aes256", or "chacha20"). Most current CPUs - have special support for AES256 so this should be faster. For older - computers lacking this support, only CHACHA20 is supported. - [default: `chacha20`] - - * `--magic `: - - Override the 4-byte magic header of each packet. This header identifies the - network and helps to distinguish it from other networks and other - applications. The id can either be a 4 byte / 8 character hexadecimal - string or an arbitrary string prefixed with "hash:" which will then be - hashed into 4 bytes. - - * `--peer-timeout `: - - Peer timeout in seconds. The peers will exchange information periodically - and drop peers that are silent for this period of time. [default: `600`] - - * `--keepalive `: - - 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 `: - - 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`] - - * `--beacon-store `: - - Periodically store beacons containing the address of this node in the given - file or via the given command. If the parameter value starts with a pipe - character (`|`), the rest of the value is interpreted as a shell command. - Otherwise the value is interpreted as a file to write the beacon to. - If this parameter is not given, beacon storage is disabled. - Please see the section **BEACONS** for more information. - - * `--beacon-load `: - - Periodically load beacons containing the addresses of other nodes from the - given file or via the given command. If the parameter value starts with a - pipe character (`|`), the rest of the value is interpreted as a shell - command. Otherwise the value is interpreted as a file to read the beacon - from. - If this parameter is not given, beacon loading is disabled. - Please see the section **BEACONS** for more information. - - * `--beacon-interval `: - - 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`] - - * `--ifup `: - - A command to setup the network interface. The command will be run (as - parameter to `sh -c`) when the device has been created to configure it. - 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. - - * `--ifdown `: - - A command to bring down the network interface. The command will be run (as - parameter to `sh -c`) to remove any configuration from the device. - The name of the allocated device will be available via the environment - variable `IFNAME`. - Please note that this command is executed with the (limited) permissions of - the user and group given as `--user` and `--group`. - - * `--pid-file `: - - Store the process id in this file when running in the background. If set, - the given file will be created containing the process id of the new - background process. This option is only used when running in background. - - * `--user `: - * `--group `: - - Change the user and/or group of the process once all the setup has been - done. - - * `--log-file `: - - If set, print logs also to the given file. The file will be created and - truncated if is exists. - - * `--stats-file `: - - If set, periodically write statistics on peers and current traffic to the - given file. The file will be periodically overwritten with new data. - - * `--daemon`: - - Spawn a background process instead of running the process in the foreground. - If this flag is set, the process will first carry out all the - initialization, then drop permissions if `--user` or `--group` is used and - then spawn a background process and write its process id to a file if - `--pid-file` is set. Then, the main process will exit and the background - process continues to provide the VPN. At the time, when the main process - exits, the interface exists and is properly configured to be used. - - * `--no-port-forwarding`: - - Disable automatic port forward. If this option is not set, VpnCloud tries to - detect a NAT router and automatically add a port forwarding to it. - - * `-v`, `--verbose`: - - Print debug information, including information for data being received and - sent. - - * `-q`, `--quiet`: - - Only print errors and warnings. - - * `-h`, `--help`: - - Display the help. - - -## DESCRIPTION - -**VpnCloud** is a simple VPN over UDP. It creates a virtual network interface on -the host and forwards all received data via UDP to the 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 - destination. Addresses that have not been seen for some time - (option `dst_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 - 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. - This mode is the default mode for TUN devices that work with IP 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 -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. - It should still be reasonably small for high node numbers (below 10 KiB/s - for 10.000 nodes). A longer `peer_timeout` can be used to reduce the traffic - further. For high node numbers, router mode should be used as it never - 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 -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 - -In the example scenario, a simple layer 2 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 -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' -``` - -Afterwards, the interface can be used to communicate. - - -### Routed TUN example - -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' -``` - -It is important to configure the interface in a way that all addresses on the -VPN can be reached directly. E.g. if subnets 10.0.1.0/24, 10.0.2.0/24 and so on -are used, the interface needs to be configured as 10.0.1.1/16. -For TUN devices, this means that the prefix length of the subnets -(/24 in this example) must be different than the prefix length that the -interface is configured with (/16 in this example). - - -### Important notes - -- VpnCloud can be used to connect two separate networks. TAP networks can be - bridged using `brctl` and TUN networks must be routed. It is very important - to be careful when setting up such a scenario in order to avoid network loops, - security issues, DHCP issues and many more problems. - -- TAP devices will forward DHCP data. If done intentionally, this can be used - 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 *ScryptSalsa208Sha256* to derive a key, - which is used to encrypt the payload of messages using *ChaCha20Poly1305* 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 - -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_name`: Name of the virtual device. Same as `--device` -* `device_path`: Set the path of the base device. Same as `--device-path` -* `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` -* `shared_key`: The shared key to encrypt all traffic. Same as `--shared-key` -* `magic`: Override the 4-byte magic header of each packet. Same as `--magic` -* `port`: A port number to listen on. This option is DEPRECATED. -* `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` -* `beacon_store`: Path or command to store beacons. Same as `--beacon-store` -* `beacon_load`: Path or command to load beacons. Same as `--beacon-load` -* `beacon_interval`: Interval for loading and storing beacons in seconds. Same as `--beacon-interval` -* `mode`: The mode of the VPN. Same as `--mode` -* `dst_timeout`: Switch table entry timeout in seconds. Same as `--dst-timeout` -* `subnets`: A list of local subnets to use. See `--subnet` -* `port_forwarding`: Whether to activate port forwardig. See `--no-port-forwarding` -* `user`: The name of a user to run the background process under. See `--user` -* `group`: The name of a group to run the background process under. See `--group` -* `pid_file`: The path of the pid file to create. See `--pid-file` -* `stats_file`: The path of the statistics file. See `--stats-file` - - -### Example - -device_type: tun -device_name: vpncloud%d -ifup: ifconfig $IFNAME 10.0.1.1/16 mtu 1400 up -crypto: aes256 -shared_key: mysecret -listen: 3210 -peers: - - remote.machine.foo:3210 - - remote.machine.bar:3210 -peer_timeout: 600 -mode: normal -subnets: - - 10.0.1.0/24 -port_forwarding: true -user: nobody -group: nogroup -pid_file: /run/vpncloud.pid - - -## BEACONS - -Beacons are short character sequences that contain a timestamp and a list of -addresses. They can be published and retrieved by other nodes to find peers -without the need for static addresses. - -The beacons are short (less than 100 characters), encrypted and encoded with -printable characters to allow publishing them in various places on the -internet, e.g.: -- On shared drives or synchronized folders (e.g. on Dropbox) -- Via a dedicated database -- Via a general purpose message board of message service (e.g. Twitter) - -The beacons are very robust. They only consist of alphanumeric characters -and can be interleaved with non-alphanumeric characters (e.g. whitespace). -Also the beacons contain a prefix and suffix that depends on the configured -network magic and secret key (if set) so that all nodes can find beacons in -a long text. - -When beacons are stored or loaded via a command (using the pipe character `|`), -the command is interpreted using the configured shell `sh`. This command has -access to the following environment variables: -* `$begin`: The prefix of the beacon. -* `$end`: The suffix of the beacon. -* `$data` (only on store): The middle part of the beacon. Do not use this - without prefix and suffix! -* `$beacon` (only on store): The full beacon consisting of prefix, data and - suffix. -The commands are called in separate threads, so even longer running commands -will not block the node. - - -## NETWORK PROTOCOL - -The protocol of VpnCloud is kept as simple as possible to allow other -implementations and to maximize the performance. - -Every packet sent over UDP contains the following header (in order): - - * 4 bytes `magic` - - This field is used to identify the packet and to sort out packets that do - not belong. The default is `[0x76, 0x70, 0x6e, 0x01]` ("vpn\x01"). - This field can be used to identify VpnCloud packets and might be set to - something different to hide the protocol. - - * 1 byte `crypto method` - - This field specifies the method that must be used to decrypt the rest of the - 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 - -Copyright (C) 2015-2020 Dennis Schwerdel -This software is licensed under GPL-3 or newer (see LICENSE.md)