A Smart Ethernet Switch for Earth
Go to file
2021-12-03 09:57:39 -08:00
.github 1.8.1 merge of changes in master 2021-10-28 14:46:38 -04:00
artwork Added 90x90 AppIcon 2019-05-01 12:53:50 -07:00
attic 1.8.1 merge of changes in master 2021-10-28 14:46:38 -04:00
controller encode network ID into sso state param 2021-12-01 15:02:21 -08:00
debian Another build speedup. 2021-11-30 15:35:18 -05:00
doc . 2017-06-01 17:21:57 -07:00
dockerbuild add kali rolling 2020-02-03 10:46:39 -08:00
ext Merge branch 'dev' into zeroidc 2021-11-30 18:42:45 -08:00
include rename stuff for clarity 2021-11-11 16:19:26 -08:00
java remove BondController.cpp from android makefile 2021-10-28 12:37:36 -07:00
node oidc stuff coming across the wire properly and generating a working login URL 2021-12-01 13:01:32 -08:00
osdep Remove managed routes in destructor (regression fix). 2021-11-15 19:48:07 -05:00
rule-compiler BSL date bump 2020-08-20 12:51:39 -07:00
service On our way to processing tokens 2021-12-01 16:57:18 -08:00
snap Add minor help tip to Snap instructions 2021-11-29 19:44:34 -08:00
windows Version bump. 2021-09-21 14:26:00 -04:00
zeroidc Post ID token to Central 2021-12-03 09:57:39 -08:00
.clang-format Add ZeroTier standard .clang-format -- Keeping tabs for 1.X line. Mostly based on LLVM format. 2021-05-03 13:00:30 -07:00
.dockerignore can now build centos8 docker container with Redis support 2020-05-12 15:17:57 -07:00
.gitattributes force eol=crlf for driver .inf files 2020-11-25 18:22:52 -08:00
.gitignore Merge branch 'dev' into zeroidc 2021-11-11 16:20:43 -08:00
AUTHORS.md Relicense: GPLv3 -> ZeroTier BSL 1.1 2019-08-23 09:23:39 -07:00
CMakeLists.txt Removed build flag in CMake script 2017-12-13 14:57:20 -08:00
COPYING Relicense: GPLv3 -> ZeroTier BSL 1.1 2019-08-23 09:23:39 -07:00
cycle_controllers.sh add application_name to pgbouncer connectio string 2018-12-10 12:26:20 -08:00
Dockerfile.ci more RELEASE-NOTES 2021-09-15 08:12:25 +02:00
Dockerfile.release Multiple image fixes: 2021-04-13 13:18:21 -07:00
entrypoint.sh.release Fix issue requiring CAP_SYS_PTRACE 2021-06-01 12:30:01 -07:00
Jenkinsfile Update jenkinsfile for new build process 2020-02-03 12:51:46 -08:00
LICENSE.txt BSL date bump 2020-08-20 12:51:39 -07:00
make-bsd.mk Add ZT_NO_UNALIGNED_ACCESS for ARMv6/7 on FreeBSD 2020-11-21 13:30:31 -08:00
make-linux.mk Merge branch 'dev' into zeroidc 2021-12-01 16:59:06 -08:00
make-mac.mk make service objs dependent on zeroidc 2021-11-18 10:42:12 -08:00
make-netbsd.mk fix RTF_MULTICAST and g++ -w 2016-12-27 13:07:05 +01:00
Makefile Use clang on OpenBSD 2021-05-06 13:04:58 +02:00
objects.mk Revert "Backport guts of 1.8 to 1.6 tree so we can point release without waiting for UI quirks to be fixed." 2021-09-21 11:51:26 -04:00
OFFICIAL-RELEASE-STEPS.md Version bump -- still pre1.8 2021-08-23 11:57:12 -04:00
one.cpp clear variables between gets for dump 2021-09-22 16:13:54 -07:00
README.docker.md Expand links in a few spots since this'll be used in the docker image 2021-06-02 14:36:55 -07:00
README.md Minor Readme updates 2021-07-16 15:17:54 -07:00
RELEASE-NOTES.md ARM32 flags update. 2021-11-30 12:35:22 -05:00
selftest.cpp Build fix. 2021-09-22 09:20:53 -04:00
update_controllers.sh update docker registry used 2019-02-08 10:40:57 -08:00
version.h 1.8.4 🦃 2021-11-23 16:39:20 -05:00
windows-clean.bat Batch file to clean Windows build dir 2019-08-01 13:21:36 -07:00
zerotier-cli-completion.bash Create a bash completion script. 2020-07-23 13:40:48 -07:00
zerotier-one.spec 1.8.4 🦃 2021-11-23 16:39:20 -05:00

ZeroTier - Global Area Networking

This document is written for a software developer audience. For information on using ZeroTier, see the: Website, Documentation Site, and Discussion Forum

ZeroTier is a smart programmable Ethernet switch for planet Earth. It allows all networked devices, VMs, containers, and applications to communicate as if they all reside in the same physical data center or cloud region.

This is accomplished by combining a cryptographically addressed and secure peer to peer network (termed VL1) with an Ethernet emulation layer somewhat similar to VXLAN (termed VL2). Our VL2 Ethernet virtualization layer includes advanced enterprise SDN features like fine grained access control rules for network micro-segmentation and security monitoring.

All ZeroTier traffic is encrypted end-to-end using secret keys that only you control. Most traffic flows peer to peer, though we offer free (but slow) relaying for users who cannot establish peer to peer connections.

The goals and design principles of ZeroTier are inspired by among other things the original Google BeyondCorp paper and the Jericho Forum with its notion of "deperimeterization."

Visit ZeroTier's site for more information and pre-built binary packages. Apps for Android and iOS are available for free in the Google Play and Apple app stores.

ZeroTier is licensed under the BSL version 1.1. See LICENSE.txt and the ZeroTier pricing page for details. ZeroTier is free to use internally in businesses and academic institutions and for non-commercial purposes. Certain types of commercial use such as building closed-source apps and devices based on ZeroTier or offering ZeroTier network controllers and network management as a SaaS service require a commercial license.

A small amount of third party code is also included in ZeroTier and is not subject to our BSL license. See AUTHORS.md for a list of third party code, where it is included, and the licenses that apply to it. All of the third party code in ZeroTier is liberally licensed (MIT, BSD, Apache, public domain, etc.).

Getting Started

Everything in the ZeroTier world is controlled by two types of identifier: 40-bit/10-digit ZeroTier addresses and 64-bit/16-digit network IDs. These identifiers are easily distinguished by their length. A ZeroTier address identifies a node or "device" (laptop, phone, server, VM, app, etc.) while a network ID identifies a virtual Ethernet network that can be joined by devices.

ZeroTier addresses can be thought of as port numbers on an enormous planet-wide enterprise Ethernet smart switch supporting VLANs. Network IDs are VLAN IDs to which these ports may be assigned. A single port can be assigned to more than one VLAN.

A ZeroTier address looks like 8056c2e21c and a network ID looks like 8056c2e21c000001. Network IDs are composed of the ZeroTier address of that network's primary controller and an arbitrary 24-bit ID that identifies the network on this controller. Network controllers are roughly analogous to SDN controllers in SDN protocols like OpenFlow, though as with the analogy between VXLAN and VL2 this should not be read to imply that the protocols or design are the same. You can use our convenient and inexpensive SaaS hosted controllers at my.zerotier.com or run your own controller if you don't mind messing around with JSON configuration files or writing scripts to do so.

Project Layout

The base path contains the ZeroTier One service main entry point (one.cpp), self test code, makefiles, etc.

  • artwork/: icons, logos, etc.
  • attic/: old stuff and experimental code that we want to keep around for reference.
  • controller/: the reference network controller implementation, which is built and included by default on desktop and server build targets.
  • debian/: files for building Debian packages on Linux.
  • doc/: manual pages and other documentation.
  • ext/: third party libraries, binaries that we ship for convenience on some platforms (Mac and Windows), and installation support files.
  • include/: include files for the ZeroTier core.
  • java/: a JNI wrapper used with our Android mobile app. (The whole Android app is not open source but may be made so in the future.)
  • macui/: a Macintosh menu-bar app for controlling ZeroTier One, written in Objective C.
  • node/: the ZeroTier virtual Ethernet switch core, which is designed to be entirely separate from the rest of the code and able to be built as a stand-alone OS-independent library. Note to developers: do not use C++11 features in here, since we want this to build on old embedded platforms that lack C++11 support. C++11 can be used elsewhere.
  • osdep/: code to support and integrate with OSes, including platform-specific stuff only built for certain targets.
  • rule-compiler/: JavaScript rules language compiler for defining network-level rules.
  • service/: the ZeroTier One service, which wraps the ZeroTier core and provides VPN-like connectivity to virtual networks for desktops, laptops, servers, VMs, and containers.
  • windows/: Visual Studio solution files, Windows service code, and the Windows task bar app UI.

Build and Platform Notes

To build on Mac and Linux just type make. On FreeBSD and OpenBSD gmake (GNU make) is required and can be installed from packages or ports. For Windows there is a Visual Studio solution in windows/.

  • Mac
    • Xcode command line tools for OSX 10.8 or newer are required.
  • Linux
    • The minimum compiler versions required are GCC/G++ 4.9.3 or CLANG/CLANG++ 3.4.2. (Install clang on CentOS 7 as G++ is too old.)
    • Linux makefiles automatically detect and prefer clang/clang++ if present as it produces smaller and slightly faster binaries in most cases. You can override by supplying CC and CXX variables on the make command line.
  • Windows
    • Windows 7 or newer is supported. This may work on Vista but isn't officially supported there. It will not work on Windows XP.
    • We build with Visual Studio 2017. Older versions may not work. Clang or MinGW will also probably work but may require some makefile hacking.
  • FreeBSD
    • GNU make is required. Type gmake to build.
  • OpenBSD
    • There is a limit of four network memberships on OpenBSD as there are only four tap devices (/dev/tap0 through /dev/tap3).
    • GNU make is required. Type gmake to build.

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.

Running

Running zerotier-one with -h option will show help.

On Linux and BSD, if you built from source, you can start the service with:

sudo ./zerotier-one -d

On most distributions, macOS, and Windows, the installer will start the service and set it up to start on boot.

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 service/README.md for API documentation.

Here's where home folders live (by default) on each OS:

  • Linux: /var/lib/zerotier-one
  • FreeBSD / OpenBSD: /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.)

Basic Troubleshooting

For most users, it just works.

If you are running a local system firewall, we recommend adding a rules permitting zerotier. 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.

See the documentation site for more information.

The Mac firewall can be found under "Security" in System Preferences. Linux has a variety of firewall configuration systems and tools.

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.

Users behind certain types of firewalls and "symmetric" NAT devices may not able able to connect to external peers directly at all. ZeroTier has limited support for port prediction and will attempt to traverse symmetric NATs, but this doesn't always work. If P2P connectivity fails you'll be bouncing UDP packets off our relay servers resulting in slower performance. Some NAT router(s) have a configurable NAT mode, and setting this to "full cone" will eliminate this problem. If you do this you may also see a magical improvement for things like VoIP phones, Skype, BitTorrent, WebRTC, certain games, etc., since all of these use NAT traversal techniques similar to ours.

If a firewall between you and the Internet blocks ZeroTier's UDP traffic, you will fall back to last-resort TCP tunneling to rootservers over port 443 (https impersonation). This will work almost anywhere but is very slow compared to UDP or direct peer to peer connectivity.

Additional help can be found in our knowledge base.