From 5bcbf877b74fc02f1ed596521cc57e112d259bcd Mon Sep 17 00:00:00 2001 From: Garrett D'Amore Date: Fri, 8 Jun 2018 09:44:04 -0700 Subject: fixes #512 ZeroTier can use master branch of ZeroTierOne now --- docs/BUILD_TLS.adoc | 56 ++++++++++++++++++++++++++++++ docs/BUILD_ZEROTIER.adoc | 82 ++++++++++++++++++++++++++++++++++++++++++++ docs/man/nng_zerotier.7.adoc | 9 ++--- 3 files changed, 143 insertions(+), 4 deletions(-) create mode 100644 docs/BUILD_TLS.adoc create mode 100644 docs/BUILD_ZEROTIER.adoc (limited to 'docs') diff --git a/docs/BUILD_TLS.adoc b/docs/BUILD_TLS.adoc new file mode 100644 index 00000000..242e7f44 --- /dev/null +++ b/docs/BUILD_TLS.adoc @@ -0,0 +1,56 @@ += Building for TLSv1.2 Support + +If you want to include support for Transport Layer Security +(tls+tcp:// and wss:// URLs) you should follow these directions. + +At this time, TLS support depends on the mbedTLS library. +See https://tls.mbed.org/ for details. + +IMPORTANT: mbedTLS is licensed under different terms than NNG. +You are responsible for reading those license terms, and ensuring +that your use conforms to them. + +On many distributions you may be able to install a pre-packaged version +of mbedTLS. We recommend doing so if this is an option for you. +For example, Ubuntu users can install the `libmbedtls-dev` package. + +You can also build mbedTLS from source; if you choose to do so, +please make sure you also *install* it somewhere (even a temporary +staging directory). + +== Configuring NNG with mbedTLS + +TLS support is not enabled by default, but can be enabled by configuring +with the CMake option `NNG_ENABLE_TLS=ON`. + +By default NNG searches for an installed copy of mbedTLS in `/usr/local`, +as well as the normal installation directories for libraries on your system. + +If you have installed mbedTLS elsewhere, you can direct the NNG configuration +to it by setting the `MBEDTLS_ROOT_DIR` CMake variable. + +== Example + +The following example would work on either Linux or macOS, and assumes +that we have checked out github source trees into `$HOME/work`. +It also assumes that mbedTLS is already installed in /usr/local or +a standard search path. + +[source, sh] +---- +$ export NNGDIR=$HOME/work/nng +$ mkdir build +$ cd build + +$ cmake -DNNG_ENABLE_TLS=ON .. + + ... (lots of lines of output from cmake...) + +$ make + + ... (lots of lines of output from make...) + +$ ./tests/tls +ok ./tests/tls 1.503s + +---- diff --git a/docs/BUILD_ZEROTIER.adoc b/docs/BUILD_ZEROTIER.adoc new file mode 100644 index 00000000..28f6098d --- /dev/null +++ b/docs/BUILD_ZEROTIER.adoc @@ -0,0 +1,82 @@ += Building for ZeroTier Support + +If you want to include support for the experimental ZeroTier +transport (zt:// URLs), you should follow these directions. + +You will need a checked out copy of the ZeroTierOne repository. +The repo is located at github.com/ZeroTier/ZeroTierOne. +These instructions have been tested with version 1.2.10 (tag) +of that repository. + +IMPORTANT: ZeroTier is licensed under different terms than NNG. +You are responsible for reading those license terms, and ensuring +that your use conforms to them. + +IMPORTANT: The ZeroTier transport, and these build instructions, are +experimental. We expect both to change over time as ZeroTier +and the NNG zt:// transport both mature. As always, _caveat emptor_. + +== Building libzerotiercore.a + +The ZeroTierOne repo is not set up for building this library by default, +so you'll need to explicitly build it. + +=== Using "make" +If you have a "make" based system such as Linux or macOS, you can +just do "make core" at the top-level. The end result will be a +libzerotiercore.a in that top level. + +=== Using "cmake" + +If not, you can use the CMakeLists file at the top of the ZeroTierOne tree. +That CMakeLists file only generates one output, the libzerotiercore.a +library, which will normally be a static delivery. + +Using your usual cmake tool chain, build the library. +The resulting library (usually `libzerotier.a`) will need to be copied +into the top-level of the ZeroTierOne tree, as that is where the NNG +build expects to find it. + +== Configuring NNG with ZT + +You will need to enable ZeroTier within NNG using the CMake option +`NNG_TRANSPORT_ZEROTIER=ON` and set the CMake option +`NNG_TRANSPORT_ZEROTIER_SOURCE` to the directory path of the ZeroTierOne +tree you have checked out. + +== Example + +The following example would work on either Linux or macOS, and assumes +that we have checked out github source trees into `$HOME/work`. + +[source, sh] +---- +$ export NNGDIR=$HOME/work/nng +$ export ZTDIR=$HOME/work/ZeroTierOne +$ cd $ZTDIR +$ mkdir build +$ cd build + + ... (lots of lines of output from cmake...) + +$ cmake .. +$ make + + ... (lots of lines of output from make...) + +$ cp libzerotiercore.a $ZTDIR +$ cd $NNGDIR +$ mkdir build +$ cd build +$ cmake -DNNG_TRANSPORT_ZEROTIER=ON -DNNG_TRANSPORT_ZEROTIER_SOURCE=${ZTDIR} .. + + ... (lots of lines of output from cmake...) + +$ make + + ... (lots of lines of output from make...) + +$ ./tests/zt + +ok ./tests/zt 22.837s +---- diff --git a/docs/man/nng_zerotier.7.adoc b/docs/man/nng_zerotier.7.adoc index 6a3c238c..1aca83ff 100644 --- a/docs/man/nng_zerotier.7.adoc +++ b/docs/man/nng_zerotier.7.adoc @@ -29,10 +29,11 @@ The ((_zt_ transport)) provides communication support for _nng_ applications over a http://www.zerotier.com[ZeroTier] network, using a Virtual Layer 2 packet facility. -IMPORTANT: This transport is very experimental. To utilize it at -present, the library must be built with support, and the -ZeroTierOne `dev` branch must be included; this will require -linking against a suitable ((`libzerotiercore`)) static library. +IMPORTANT: This transport is experimental. +To utilize it at present, the library must be built with support, and linked +against a suitable ((`libzerotiercore`)) library. +Further information about building with this support are in the build +documentation included with the distribution. IMPORTANT: The `libzerotiercore` library at present is covered under different license terms than the rest of _nng_. Please be careful to review -- cgit v1.2.3-70-g09d2