ExternalVendorCode/ZeroTierOne
1
0
Fork 0
mirror of https://github.com/zerotier/ZeroTierOne.git synced 2024-12-19 04:57:53 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

docs

Browse Source
This commit is contained in:
Adam Ierymenko 2015-06-02 16:16:14 -07:00
parent 648efff1f6
commit a2690047bb
4 changed files with 140 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
BUILDING.md
View File

@ -1,36 +0,0 @@
Building ZeroTier One from Source
======
(See RUNNING.md for what to do next.)
Developers note: there is currently no management of dependencies on *nix platforms, so you should 'make clean ; make' if you change a header (.h or .hpp) file. Need to fix eventually.
### Linux and BSD
Just type 'make' (or 'gmake' on BSD). You will need gcc/g++ or clang/clang++ installed. No other third party libraries are needed.
Very old versions of Linux or BSD may run into problems. On Linux our primary build container is CentOS 6 (for backward compatibility), and on FreeBSD we've only tested with FreeBSD 10.
### Macintosh
Just type 'make'. You'll need Xcode and the command line tools installed of course.
To install the tap driver, 'sudo make install-mac-tap' will place it in the default ZeroTier home directory. We ship a signed tap driver binary for ZeroTier One that should work for everyone.
If you do for some reason want to build ext/tap-mac you will need an older version of the OSX gcc compiler chain than what currently ships (clang) to build a properly backward compatibile image. A copy is hosted here:
http://download.zerotier.com/dev/llvm-g++-Xcode4.6.2.tar.bz2
Un-tar this into ext/ (it's excluded in .gitignore) and then 'make' in ext/tap-mac/tuntap/src/tap.
We really don't recommend messing with this build yourself unless you think there's a bug in the driver and want to try to fix it. So far the driver has been completely stable for a very long time and the old binaries continue to work flawlessly on (last we checked) 10.10.
### Windows
There's a Visual Studio 2012 solution file in windows/ that can be used. I've never tried it with MinGW, but theoretically this should be possible.
Windows is, of course, harder to build than any other platform.
### Debug builds
The Unix/Mac makefiles support a ZT_DEBUG=1 option ('make ZT_DEBUG=1') to build a version that will print a whole bunch of TRACE output to stderr as it runs. This also builds the binary with debug rather than production optimized flags.

163
README.md
View File

@ -1,39 +1,156 @@
ZeroTier One - Network Virtualization Everywhere ZeroTier One
====== ======
ZeroTier One is an ethernet virtualization engine. It creates virtual switched LANs of almost unlimited size that span physical network boundaries. To the operating system these behave just like ordinary Ethernet ports. Everything just works, even as your computer moves around or your physical Internet link changes. ZeroTier is a software defined networking layer for Earth. Our mission is to directly connect the world's devices via universal network virtualization that is ridiculously easy to use.
It's intended to replace conventional hub-and-spoke VPNs, provide provider-neutral secure private backplane networks to multi-data-center and hybrid cloud deployments, allow remote access to embedded devices, and much more. It creates virtual Ethernet networks that run over a global, secure, distributed, zero-configuration peer to peer network.
ZeroTier uses a peer to peer network with managed anchor points ("supernodes"). These are operated by ZeroTier Networks, and are free to use. They provides instant "zero configuration" startup, NAT traversal assistance, relaying in cases where NAT traversal doesn't work, and a trusted root authority for looking up peer public keys (identities). The supernodes run the same open-source software as regular nodes, are geographically distributed across three continents, and have remained stable for over a year. [This blog post](http://adamierymenko.com/decentralization-i-want-to-believe/) discusses the design rationale in some detail. *(TL;DR: this design represents a compromise between speed and ease of use and decentralization.)* It can be used for on-premise network virtualization, as a peer to peer VPN for mobile teams, for hybrid or multi-data-center cloud deployments, or just about anywhere else secure software defined virtual networking is useful. It even supports Ethernet bridging, allowing the seamless attachment of physical LANs to virtual ones for inter-office networking, gluing Docker an other VM/container backplanes together, remote access to legacy devices, and more.
ZeroTier One encrypts all traffic end-to-end with keys that only you control. Even when traffic is traversing our network we cannot decrypt it. It's not, however, a "strong privacy" tool since it would still be possible for us (or your ISP or anyone else in between) to observe "meta-data" about your traffic. If you need *that* level of anonymity, we recommend [Tor](https://www.torproject.org) or something similar. Onion routing is the only technology we're aware of that is capable of delivering that level of end-to-end privacy protection. ZeroTier One is our OS-level client application. It allows Mac, Linux, Windows, FreeBSD, and soon other types of clients to join ZeroTier virtual networks. It can run on native systems, VMs, or containers (Docker, OpenVZ, etc.).
At the moment the ZeroTier wire protocol is only documented in the source (start with the comments in Packet.hpp), but more formal documentation is planned for the near future. Encapsulation overhead is comparable to IPSec or OpenVPN. Visit [ZeroTier's site](https://www.zerotier.com/) for more information. You can also download professionally packaged binary installers/packages for a variety of supported OSes there if you don't want to build ZeroTier One from source.
[Visit ZeroTier Networks on the web](https://www.zerotier.com/) for more information. Follow the [ZeroTier blog](https://www.zerotier.com/blog/), [Twitter feed](https://twitter.com/ZeroTier) and the main [GitHub project](https://github.com/zerotier/ZeroTierOne) to stay up to date. See the GitHub-hosted wiki (sidebar) for more technical info and help for various platforms. There's also a [support portal](https://www.zerotier.com/support/) for more general information. ### Building from Source
### Getting Started For Mac, Linux, and BSD, just type "make" (or "gmake" on BSD). You won't need much installed; here are the requirements for various platforms:
Auto-updating binary packages that install easily [can be found here](https://www.zerotier.com/download.html) for officially supported platforms. Packages for popular Linux distributions that neatly wrap the Linux installer/uninstaller are coming soon. * Mac: Xcode command line tools, and [Packages](http://s.sudre.free.fr/Software/Packages/about.html) if you want to build an OSX .pkg installer ("make mac-dist-pkg"). It should build on OSX 10.7 or newer.
* Linux: the 'which' command, which is used to auto-detect whether to use the clang or the gcc compiler. (Clang is preferred if it's available, since it usually yields smaller and slightly faster binaries.)
* FreeBSD (and other BSD): C++ compiler (g++ usually) and GNU make (gmake).
If you want to build from source, clone this repository and see BUILDING.txt and RUNNING.txt. If you build manually you'll have to update manually, and we recommend doing so often as development is progressing very rapidly. (Protocol is pretty stable but you might miss out on new features or experience performance degradation if you're too far behind.) Each supported platform has its own *make-XXX.mk* file that contains the actual make rules for the platform. The right .mk file is included by the main Makefile based on the GNU make *OSTYPE* variable. Take a look at the .mk file for your platform for other targets, debug build rules, etc.
Once you are up and running, you have several options. Windows, of course, is special. We build for Windows with Microsoft Visual Studio 2012 on Windows 7. A solution file is located in the *windows* subfolder. Newer versions of Visual Studio (and Windows) may work but haven't been tested. Older versions almost certainly will not, since they lack things like *stdint.h* and certain STL features. MinGW or other ports of gcc/clang to Windows should also work but haven't been tested. Build steps for Windows are a bit more complicated. For the moment you are on your own there.
ZeroTier provides ZeroTier One for free, but to help finance development and operations we have a [user-friendly freemium control panel on the web](https://www.zerotier.com/admin.html). This control panel lets you quickly and easily create your own networks, and the operation of their controller node(s) is left to us. Public networks created on our site are free, and private networks are free for up to ten devices. After that there is a monthly charge. Mobile versions are in progress. They don't work yet, and in any case only the glue code will be included in this repository. The full mobile apps are in private repositories on our own git server.
You *only* need an account on our site if you want to use the control panel found there. Joining networks requires no account. To get authorized on a private network, just send your device's 10-digit ID to the network's administrator and they can add you. ### Supported Platforms
Public networks, as the name implies, can be joined without getting authorization from anyone. All you need is their 16-digit network ID. A public network called [Earth](https://www.zerotier.com/earth.html) (8056c2e21c000001) exists for everyone, but be sure your device is adequately secured and up to date before joining. CPU architecture shouldn't matter unless it's smaller than 32-bit or something really bizarre like a "middle-endian" processor. We have reports of ZeroTier One running on arm32, arm64, and MIPS. It builds and runs out of the box on Raspberry Pi, BeagleBone, BananaPi, and other ARM-based developer/hobbyist boards.
More products and services will be forthcoming. ZeroTier is written in C and C++ (C++03 / ISO/IEC 14882:2003) and uses data structures and algorithms from the C++03 STL. We do not use any C++11 features (yet), since we want to support a few old and embedded platforms that don't have C++11 compilers. You *will* require a compiler and headers new enough to support 64-bit integers (long long) and the *stdint.h* header. The latter could also be faked by adding defines for things like *uint32\_t*, *int64\_t*, etc.
### Basic Troubleshooting Typing "make selftest" will build a *zerotier-selftest* binary which unit tests various internals and reports on a few aspects of the build environment. It's a good idea to try this on novel platforms or architectures.
For about 95% of users, it just works. ### Running
If you are running a local system firewall, we recommend adding a rule permitting UDP port 9993 inbound and outbound. The binary Windows installer takes care of this for Windows' built-in firewall, but other platforms and third party firewall software may need this for optimal performance. Running *zerotier-one* with -h will show help.
On Linux and BSD you can start the service with:
sudo ./zerotier-one -d
A home folder for your system will automatically be created.
The service is controlled via the JSON API, which by default is available at 127.0.0.1 port 9993. We include a *zerotier-cli* command line utility to make API calls for standard things like joining and leaving networks. The *authtoken.secret* file in the home folder contains the secret token for accessing this API. See README.md in [service/](service/) for API documentation.
Here's where home folders live (by default) on each OS:
* Linux: /var/lib/zerotier-one
* BSD: /var/db/zerotier-one
* Mac: /Library/Application Support/ZeroTier/One
* Windows: \\ProgramData\\ZeroTier\\One (That's for Windows 7. The base 'shared app data' folder might be different on different Windows versions.)
Running ZeroTier One on a Mac is the same, but OSX requires a kernel extension. We ship a signed binary build of the ZeroTier tap device driver, which can be installed on Mac with:
sudo make install-mac-tap
This will create the home folder for Mac, place *tap.kext* there, and set its modes correctly to enable ZeroTier One to manage it with *kextload* and *kextunload*.
Windows, of course, is special. Once again you're on your own there for now. Running the .exe with -h will show options, including one to run at an admin console rather than as a service.
### Joining A Network
ZeroTier virtual networks are identified by 16-digit hexadecimal network IDs, which devices are identified by 10-digit addresses. To get your address run:
sudo zerotier-cli status
(Use ./zerotier-cli if you're running it right from your build folder.)
You should see something like:
200 info ########## ONLINE #.#.#
That 10-digit hex code is you. It's derived via a one-way proof of work function from your cryptographic public key. Your public key can be found in *identity.public* in ZeroTier's home folder, while *identity.secret* contains your full identity including the secret portion of the key pair.
By the way -- those identity files define your device's *identity*. Moving them to another system will move that identity. Be careful when cloning virtual machines that have identities stored on them. If two devices have the same identity, they'll "fight" over it and you won't know which device will receive network packets. (Multi-homing isn't supported yet, but we have plans for something like that.)
If you want to do a quick test, you can join [Earth](https://www.zerotier.com/earth.html). It's a global public network that anyone can join. Type:
sudo zerotier-cli join 8056c2e21c000001
Then:
sudo zerotier-cli listnetworks
After a few seconds to a minute you should see something like:
200 listnetworks 8056c2e21c000001 earth.zerotier.net ##:##:##:##:##:## OK PUBLIC zt0 ##.##.##.##/7
Earth will assign you an IP address in the "unofficially available" globally unrouted 28.0.0.0/7 IP block so as to avoid conflicts with local networks. (Your networks can use any IP scheme, or can even leave IP addresses unmanaged.) Once you get an IP, you should be able to ping something:
ping earth.zerotier.net
Go to [http://earth.zerotier.net/](http://earth.zerotier.net/) to see a short little welcome page that will tell you your IP and Ethernet MAC address.
Earth is a pretty public place. If you don't want to stick around run:
sudo zerotier-cli leave 8056c2e21c000001
The network (and associated interface) should be gone.
Joining and leaving virtual networks is almost as easy as an IRC channel or a chat room.
Networks are created and administrated by network controllers. Most users will want to use our hosted controllers. Visit [our web site](https://www.zerotier.com/) for more information. Later in this README there are brief instructions about building ZeroTier One with network controller support for those who want to try running their own.
Macintosh and Windows installers also install a GUI application.
### Installing
We don't have a "make install" rule quite yet. On Linux you can type:
make installer
This will build a binary that, when run, will install ZeroTier One on most current Linux distributions. We also have RPM and DEB build files in *ext/installfiles/linux* that wrap this installer in packages for RedHat/CentOS and Debian/Ubuntu derived distributions.
On Mac the best way is to install [Packages](http://s.sudre.free.fr/Software/Packages/about.html) and use:
make mac-dist-pkg
This builds a .pkg file that can be installed.
BSD has no installer yet. We're working on it.
Linux/BSD and Mac installations have an *uninstall.sh* file in their ZeroTier home folder that cleanly removes ZeroTier One from the system. Run this with:
sudo /path/to/ZeroTier/home/folder/uninstall.sh
Windows installers are insane. We build our .MSI installers with [Advanced Installer Enterprise](http://www.advancedinstaller.com), since it's the only way we could find to allow us to build a combined 32-bit/64-bit MSI file that deploys a driver, a service, and an application properly while retaining basic human sanity and will to live. To avoid trauma we really recommend just installing the pre-build Windows binaries from our web site if you want permanent installation on Windows.
### Building with Network Controller Support
Network controllers are nodes responsible for issuing configurations and certificates to members of ZeroTier virtual networks. Most users won't need to run their own, so this code is by default not included in the ZeroTier One binary.
You can build a network controller on Linux or Mac with:
make ZT_ENABLE_NETWORK_CONTROLLER=1
This will build a version that contains the Sqlite-backed network controller and associated extensions to the JSON local service control API. You will need the development headers for sqlite3 installed. On Mac these ship as part of Xcode, while on Linux they'll be found in packages for the various distributions.
See the JSON API documentation in [service/](service/) for more information about how to control controllers.
### Troubleshooting
For most users, it just works.
If you are running a local system firewall, we recommend adding a rule permitting UDP port 9993 inbound and outbound. If you installed binaries for Windows this should be done automatically. Other platforms might require manual editing of local firewall rules depending on your configuration.
The Mac firewall can be founder under "Security" in System Preferences. Linux has a variety of firewall configuration systems and tools. If you're using Ubuntu's *ufw*, you can do this:
sudo ufw allow 9993/udp
On CentOS check */etc/sysconfig/iptables* for IPTables rules. For other distributions consult your distribution's documentation. You'll also have to check the UIs or documentation for commercial third party firewall applications like Little Snitch (Mac), McAfee Firewall Enterprise (Windows), etc. if you are running any of those. Some corporate environments might have centrally managed firewall software, so you might also have to contact IT.
ZeroTier One peers will automatically locate each other and communicate directly over a local wired LAN *if UDP port 9993 inbound is open*. If that port is filtered, they won't be able to see each others' LAN announcement packets. If you're experiencing poor performance between devices on the same physical network, check their firewall settings. Without LAN auto-location peers must attempt "loopback" NAT traversal, which sometimes fails and in any case requires that every packet traverse your external router twice. ZeroTier One peers will automatically locate each other and communicate directly over a local wired LAN *if UDP port 9993 inbound is open*. If that port is filtered, they won't be able to see each others' LAN announcement packets. If you're experiencing poor performance between devices on the same physical network, check their firewall settings. Without LAN auto-location peers must attempt "loopback" NAT traversal, which sometimes fails and in any case requires that every packet traverse your external router twice.
@ -41,12 +158,8 @@ Users behind certain types of firewalls and "symmetric" NAT devices may not able
If you're interested, there's a [technical deep dive about NAT traversal on our blog](https://www.zerotier.com/blog/?p=226). A troubleshooting tool to help you diagnose NAT issues is planned for the future as are uPnP/IGD/NAT-PMP and IPv6 transport. If you're interested, there's a [technical deep dive about NAT traversal on our blog](https://www.zerotier.com/blog/?p=226). A troubleshooting tool to help you diagnose NAT issues is planned for the future as are uPnP/IGD/NAT-PMP and IPv6 transport.
If a firewall between you and the Internet blocks ZeroTier's UDP traffic, you will fall back to last-resort TCP tunneling to supernodes over port 443 (https impersonation). This will work almost anywhere but is *slow*. If performance seems just terrible, this is the first thing to check. If a firewall between you and the Internet blocks ZeroTier's UDP traffic, you will fall back to last-resort TCP tunneling to supernodes over port 443 (https impersonation). This will work almost anywhere but is *very slow* compared to UDP or direct peer to peer connectivity.
Some Windows users have reported a [problem with the TAP device driver](https://github.com/zerotier/ZeroTierOne/issues/107). From user reports this seems to occur on Windows systems that have not been updated through Windows Update. While we have a fix planned, we **really** recommend keeping your system up to date for security reasons. Frankly we're a bit torn on this one. If this is truly the cause, perhaps ZeroTier failing to work on unpatched Windows systems is a feature not a bug. ### License
More help can be found in the [GitHub wiki](https://github.com/zerotier/ZeroTierOne/wiki) and the [customer support portal / knowledge base](https://www.zerotier.com/support/). The ZeroTier source code is open source and is licensed under the GNU GPL v3 (not LGPL). If you'd like to embed it in a closed-source commercial product or appliance, please e-mail [contact@zerotier.com](mailto:contact@zerotier.com) to discuss commercial licensing. Otherwise it can be used for free.
The ZeroTier source code is open source and is licensed under the GNU GPL v3 (not LGPL). If you'd like to embed it in a closed-source commercial product or appliance, please e-mail [contact@zerotier.com](mailto:contact@zerotier.com) to discuss licensing.
*ZeroTier is keyboard crafted with coffee and sleep deprivation in Southern California.*

84
RUNNING.md
View File

@ -1,84 +0,0 @@
Running ZeroTier One
======
This guide is for those building and running from source. See BUILDING.md
first.
The wiki at GitHub contains several pages that are probably also of interest:
https://github.com/zerotier/ZeroTierOne/wiki
### MacOS
On Mac, the default ZeroTier home is:
/Library/Application Support/ZeroTier/One
ZeroTier ships with a kernel extension for its own tap device, which it
stores in the above directory. To install this, type:
sudo make install-mac-tap
This will create the ZeroTier One home above if it does not exist and install
the kext there. Note that the kext must be owned by root:wheel. The make
rule for install-mac-tap takes care of that.
Next, simply run the binary. It must be run as root to open the tap device.
If run with no options, it will use the default home directory above.
sudo ./zerotier-one &
### LINUX
On Linux, the default ZeroTier home is:
/var/lib/zerotier-one
Just type:
sudo mkdir /var/lib/zerotier-one
sudo ./zerotier-one &
Your system must have the Linux tun/tap driver available (tun). All tested
distributions so far ship with this driver as a module that will load
automatically.
UDP port 9993 must be open in your local firewall for this to work properly.
How to do this varies by Linux distribution.
- Opening port 9993 on Ubuntu
Follow the Ubuntu documentation about UFW https://help.ubuntu.com/community/UFW
Check if your UFW is active.
sudo ufw status verbose
If it is active, open UDP port 9993
sudo ufw allow 9993/udp
You should now be able to ping and browse earth.zerotier.net
### FreeBSD
FreeBSD is identical to Linux except that the default home is
/var/db/zerotier-one instead of /var/lib.
### WINDOWS
Run zerotier-one.exe -h for help. There's a command to install the current
binary as a service to run it that way, and another option to run it from
the Windows console.
### Once you're up and running...
To use the command line interface, see this guide:
https://github.com/zerotier/ZeroTierOne/wiki/Command-Line-Interface
If you want to test by joining the Earth network, try:
sudo ./zerotier-cli join 8056c2e21c000001
An interface called 'zt####' should appear and should get an IP address in
the 28.0.0.0/7 range (28.* or 29.*) within a few seconds or so. Then try
pinging earth.zerotier.net or navigating to http://earth.zerotier.net/ in
a web browser.

4
one.cpp
View File

@ -94,8 +94,8 @@ static void cliPrintHelp(const char *pn,FILE *out)
fprintf(out," -D<path> - ZeroTier home path for parameter auto-detect"ZT_EOL_S); fprintf(out," -D<path> - ZeroTier home path for parameter auto-detect"ZT_EOL_S);
fprintf(out," -p<port> - HTTP port (default: auto)"ZT_EOL_S); fprintf(out," -p<port> - HTTP port (default: auto)"ZT_EOL_S);
fprintf(out," -T<token> - Authentication token (default: auto)"ZT_EOL_S); fprintf(out," -T<token> - Authentication token (default: auto)"ZT_EOL_S);
//fprintf(out," -H<ip> - HTTP IP address (default: 127.0.0.1)"ZT_EOL_S""ZT_EOL_S); //fprintf(out," -H<ip> - HTTP server bind address (default: 127.0.0.1)"ZT_EOL_S);
fprintf(out,"Available commands:"ZT_EOL_S); fprintf(out,ZT_EOL_S"Available commands:"ZT_EOL_S);
fprintf(out," info - Display status info"ZT_EOL_S); fprintf(out," info - Display status info"ZT_EOL_S);
fprintf(out," listpeers - List all peers"ZT_EOL_S); fprintf(out," listpeers - List all peers"ZT_EOL_S);
fprintf(out," listnetworks - List all networks"ZT_EOL_S); fprintf(out," listnetworks - List all networks"ZT_EOL_S);