github/nastools_zerotierone
1
0
Fork 0
mirror of https://github.com/NAStools/zerotierone.git synced 2025-08-14 10:37:44 -07:00
Code Issues Projects Releases Packages Wiki Activity Actions

Imported Upstream version 1.1.14

Browse source
This commit is contained in:
NAStools 2016-11-01 16:45:16 -07:00
commit bb232b9d52
557 changed files with 115164 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

6
doc/README.md Normal file
View file

@ -0,0 +1,6 @@
Manual Pages and Other Documentation
=====
Use "./build.sh" to build the manual pages.
You'll need either NodeJS/npm installed (script will then automatically install the npm *marked-man* package) or */usr/bin/ronn*. The latter is a Ruby program packaged on some distributions as *rubygem-ronn* or *ruby-ronn* or installable as *gem install ronn*. The Node *marked-man* package and *ronn* from rubygems are two roughly equivalent alternatives for compiling MarkDown into roff/man format.

42
doc/build.sh Executable file
View file

@ -0,0 +1,42 @@
#!/bin/bash
export PATH=/bin:/usr/bin:/usr/local/bin:/sbin:/usr/sbin:/usr/local/sbin
if [ ! -f zerotier-cli.1.md ]; then
echo 'This script must be run from the doc/ subfolder of the ZeroTier tree.'
fi
rm -f *.1 *.2 *.8
if [ -e /usr/bin/ronn -o -e /usr/local/bin/ronn ]; then
# Use 'ronn' which is available as a package on many distros including Debian
ronn -r zerotier-cli.1.md
ronn -r zerotier-idtool.1.md
ronn -r zerotier-one.8.md
else
# Use 'marked-man' from npm
NODE=/usr/bin/node
if [ ! -e $NODE ]; then
if [ -e /usr/bin/nodejs ]; then
NODE=/usr/bin/nodejs
elif [ -e /usr/local/bin/node ]; then
NODE=/usr/local/bin/node
elif [ -e /usr/local/bin/nodejs ]; then
NODE=/usr/local/bin/nodejs
else
echo 'Unable to find ronn or node/npm -- cannot build man pages!'
exit 1
fi
fi
if [ ! -f node_modules/marked-man/bin/marked-man ]; then
echo 'Installing npm package "marked-man" -- MarkDown to ROFF converter...'
npm install marked-man
fi
$NODE node_modules/marked-man/bin/marked-man zerotier-cli.1.md >zerotier-cli.1
$NODE node_modules/marked-man/bin/marked-man zerotier-idtool.1.md >zerotier-idtool.1
$NODE node_modules/marked-man/bin/marked-man zerotier-one.8.md >zerotier-one.8
fi
exit 0

52
doc/contact@zerotier.com.gpg Normal file
View file

@ -0,0 +1,52 @@
-----BEGIN PGP PUBLIC KEY BLOCK-----
Comment: GPGTools - https://gpgtools.org
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
=JgAv
-----END PGP PUBLIC KEY BLOCK-----

1
doc/manpage_encoding_declaration.UTF-8 Normal file
View file

@ -0,0 +1 @@
'\" -*- coding: utf-8 -*-

68
doc/zerotier-cli.1.md Normal file
View file

@ -0,0 +1,68 @@
zerotier-cli(1) -- control local ZeroTier virtual network service
=================================================================
## SYNOPSIS
`zerotier-cli` [-switches] <command> [arguments]
## DESCRIPTION
**zerotier-cli** provides a simple command line interface to the local JSON API of the ZeroTier virtual network endpoint service zerotier-one(8).
By default **zerotier-cli** must be run as root or with `sudo`. If you want to allow an unprivileged user to use **zerotier-cli** to control the system ZeroTier service, you can create a local copy of the ZeroTier service authorization token in the user's home directory:
sudo cp /var/lib/zerotier-one/authtoken.secret /home/user/.zeroTierOneAuthToken
chown user /home/user/.zeroTierOneAuthToken
chmod 0600 /home/user/.zeroTierOneAuthToken
(The location of ZeroTier's service home may differ by platform. See zerotier-one(8).)
Note that this gives the user the power to connect or disconnect the system to or from any virtual network, which is a significant permission.
**zerotier-cli** has several command line arguments that are visible in `help` output. The two most commonly used are `-j` for raw JSON output and `-D<path>` to specify an alternative ZeroTier service working directory. Raw JSON output is easier to parse in scripts and also contains verbose details not present in the tabular output. The `-D<path>` option specifies where the service's zerotier-one.port and authtoken.secret files are located if the service is not running at the default location for your system.
## COMMANDS
* `help`:
Displays **zerotier-cli** help.
* `info`:
Shows information about this device including its 10-digit ZeroTier address and apparent connection status. Use `-j` for more verbose output.
* `listpeers`:
This command lists the ZeroTier VL1 (virtual layer 1, the peer to peer network) peers this service knows about and has recently (within the past 30 minutes or so) communicated with. These are not necessarily all the devices on your virtual network(s), and may also include a few devices not on any virtual network you've joined. These are typically either root servers or network controllers.
* `listnetworks`:
This lists the networks your system belongs to and some information about them, such as any ZeroTier-managed IP addresses you have been assigned. (IP addresses assigned manually to ZeroTier interfaces will not be listed here. Use the standard network interface commands to see these.)
* `join`:
To join a network just use `join` and its 16-digit hex network ID. That's it. Then use `listnetworks` to see the status. You'll either get a reply from the network controller with a certificate and other info such as IP assignments, or you'll get "access denied." In this case you'll need the administrator of this network to authorize your device by its 10-digit device ID (visible with `info`) on the network's controller.
* `leave`:
Leaving a network is as easy as joining it. This disconnects from the network and deletes its interface from the system. Note that peers on the network may hang around in `listpeers` for up to 30 minutes until they time out due to lack of traffic. But if they no longer share a network with you, they can't actually communicate with you in any meaningful way.
## EXAMPLES
Join "Earth," ZeroTier's big public party line network:
$ sudo zerotier-cli join 8056c2e21c000001
$ sudo zerotier-cli listnetworks
( wait until you get an Earth IP )
$ ping earth.zerotier.net
( you should now be able to ping our Earth test IP )
Leave "Earth":
$ sudo zerotier-cli leave 8056c2e21c000001
List VL1 peers:
$ sudo zerotier-cli listpeers
## COPYRIGHT
(c)2011-2016 ZeroTier, Inc. -- https://www.zerotier.com/ -- https://github.com/zerotier
## SEE ALSO
zerotier-one(8), zerotier-idtool(1)

65
doc/zerotier-idtool.1.md Normal file
View file

@ -0,0 +1,65 @@
zerotier-idtool(1) -- tool for creating and manipulating ZeroTier identities
============================================================================
## SYNOPSIS
`zerotier-idtool` <command> [args]
## DESCRIPTION
**zerotier-idtool** is a command line utility for doing things with ZeroTier identities. A ZeroTier identity consists of a public/private key pair (or just the public if it's only an identity.public) and a 10-digit hexadecimal ZeroTier address derived from the public key by way of a proof of work based hash function.
## COMMANDS
When command arguments call for a public or secret (full) identity, the identity can be specified as a path to a file or directly on the command line.
* `help`:
Display help. (Also running with no command does this.)
* `generate` [secret file] [public file] [vanity]:
Generate a new ZeroTier identity. If a secret file is specified, the full identity including the private key will be written to this file. If the public file is specified, the public portion will be written there. If no file paths are specified the full secret identity is output to STDOUT. The vanity prefix is a series of hexadecimal digits that the generated identity's address should start with. Typically this isn't used, and if it's specified generation can take a very long time due to the intrinsic cost of generating identities with their proof of work function. Generating an identity with a known 16-bit (4 digit) prefix on a 2.8ghz Core i5 (using one core) takes an average of two hours.
* `validate` <identity, only public part required>:
Locally validate an identity's key and proof of work function correspondence.
* `getpublic` <full identity with secret>:
Extract the public portion of an identity.secret and print to STDOUT.
* `sign` <full identity with secret> <file to sign>:
Sign a file's contents with SHA512+ECC-256 (ed25519). The signature is output in hex to STDOUT.
* `verify` <identity, only public part required> <file to check> <signature in hex>:
Verify a signature created with `sign`.
* `mkcom` <full identity with secret> [id,value,maxdelta] [...]:
Create and sign a network membership certificate. This is not generally useful since network controllers do this automatically and is included mostly for testing purposes.
## EXAMPLES
Generate and dump a new identity:
$ zerotier-idtool generate
Generate and write a new identity, both secret and public parts:
$ zerotier-idtool generate identity.secret identity.public
Generate a vanity address that begins with the hex digits "beef" (this will take a while!):
$ zerotier-idtool generate beef.secret beef.public beef
Sign a file with an identity's secret key:
$ zerotier-idtool sign identity.secret last_will_and_testament.txt
Verify a file's signature with a public key:
$ zerotier-idtool verify identity.public last_will_and_testament.txt
## COPYRIGHT
(c)2011-2016 ZeroTier, Inc. -- https://www.zerotier.com/ -- https://github.com/zerotier
## SEE ALSO
zerotier-one(8), zerotier-cli(1)

95
doc/zerotier-one.8.md Normal file
View file

@ -0,0 +1,95 @@
zerotier-one(8) -- ZeroTier virtual network endpoint service
============================================================
## SYNOPSIS
`zerotier-one` [-switches] [working directory]
## DESCRIPTION
**zerotier-one** is the service/daemon responsible for connecting a Unix (Linux/BSD/OSX) system to one or more ZeroTier virtual networks and presenting those networks to the system as virtual network ports. You can think of it as a peer to peer VPN client.
It's typically run by init systems like systemd (Linux) or launchd (Mac) rather than directly by the user, and it must be run as root unless you give it the `-U` switch and don't plan on actually joining networks (e.g. to run a network controller microservice only).
The **zerotier-one** service keeps its state and other files in a working directory. If this directory is not specified at launch it defaults to "/var/lib/zerotier-one" on Linux, "/Library/Application Support/ZeroTier/One" on Mac, and "/var/db/zerotier-one" on FreeBSD and other similar BSDs. The working directory should persist. It shouldn't be automatically cleaned by system cleanup daemons or stored in a volatile location. Loss of its identity.secret file results in loss of this system's unique 10-digit ZeroTier address and key.
Multiple instances of **zerotier-one** can be run on the same system as long as they are run with different primary ports (see switches) and a different working directory. But since a single service can join any number of networks, typically there's no point in doing this.
The **zerotier-one** service is controlled via a JSON API available at 127.0.0.1:<primary port> with the default primary port being 9993. Access to this API requires an authorization token normally found in the authtoken.secret file in the service's working directory. On some platforms access may be guarded by other measures such as socket peer UID/GID lookup if additional security options are enabled (this is not the default).
The first time the service is started in a fresh working directory, it generates a ZeroTier identity. On slow systems this process can take ten seconds or more due to an anti-DDOS/anti-counterfeit proof of work function used by ZeroTier in address generation. This only happens once, and once generated the result is saved in identity.secret in the working directory. This file represents and defines/claims your ZeroTier address and associated ECC-256 key pair.
## SWITCHES
* `-h`:
Display help.
* `-v`:
Display ZeroTier One version.
* `-U`:
Skip privilege check and allow to be run by non-privileged user. This is typically used when **zerotier-one** is built with the network controller option included. In this case the ZeroTier service might only be acting as a network controller and might never actually join networks, in which case it does not require elevated system permissions.
* `-p<port>`:
Specify a different primary port. If this is not given the default is 9993. If zero is given a random port is chosen each time.
* `-d`:
Fork and run as a daemon.
* `-i`:
Invoke the **zerotier-idtool** personality, in which case the binary behaves like zerotier-idtool(1). This happens automatically if the name of the binary (or a symlink to it) is zerotier-idtool.
* `-q`:
Invoke the **zerotier-cli** personality, in which case the binary behaves like zerotier-cli(1). This happens automatically if the name of the binary (or a symlink to it) is zerotier-cli.
## EXAMPLES
Run as daemon with OS default working directory and default port:
$ sudo zerotier-one -d
Run as daemon with a different working directory and port:
$ sudo zerotier-one -d -p12345 /tmp/zerotier-working-directory-test
## FILES
These are found in the service's working directory.
* `identity.public`:
The public portion of your ZeroTier identity, which is your 10-digit hex address and the associated public key.
* `identity.secret`:
Your full ZeroTier identity including its private key. This file identifies the system on the network, which means you can move a ZeroTier address around by copying this file and you should back up this file if you want to save your system's static ZeroTier address. This file must be protected, since theft of its secret key will allow anyone to impersonate your device on any network and decrypt traffic. For network controllers this file is particularly sensitive since it constitutes the private key for a certificate authority for the controller's networks.
* `authtoken.secret`:
The secret token used to authenticate requests to the service's local JSON API. If it does not exist it is generated from a secure random source on service start. To use, send it in the "X-ZT1-Auth" header with HTTP requests to 127.0.0.1:<primary port>.
* `devicemap`:
Remembers mappings of zt# interface numbers to ZeroTier networks so they'll persist across restarts. On some systems that support longer interface names that can encode the network ID (such as FreeBSD) this file may not be present.
* `zerotier-one.pid`:
ZeroTier's PID. This file is deleted on normal shutdown.
* `zerotier-one.port`:
ZeroTier's primary port, which is also where its JSON API is found at 127.0.0.1:<this port>. This file is created on startup and is read by zerotier-cli(1) to determine where it should find the control API.
* `controller.db`:
If the ZeroTier One service is built with the network controller enabled, this file contains the controller's SQLite3 database.
* `controller.db.backup`:
If the ZeroTier One service is built with the network controller enabled, it periodically backs up its controller.db database in this file (currently every 5 minutes if there have been changes). Since this file is not a currently in use SQLite3 database it's safer to back up without corruption. On new backups the file is rotated out rather than being rewritten in place.
* `iddb.d/` (directory):
Caches the public identity of every peer ZeroTier has spoken with in the last 60 days. This directory and its contents can be deleted, but this may result in slower connection initations since it will require that we go out and re-fetch full identities for peers we're speaking to.
* `networks.d` (directory):
This caches network configurations and certificate information for networks you belong to. ZeroTier scans this directory for <network ID>.conf files on startup to recall its networks, so "touch"ing an empty <network ID>.conf file in this directory is a way of pre-configuring ZeroTier to join a specific network on startup without using the API. If the config file is empty ZeroTIer will just fetch it from the network's controller.
## COPYRIGHT
(c)2011-2016 ZeroTier, Inc. -- https://www.zerotier.com/ -- https://github.com/zerotier
## SEE ALSO
zerotier-cli(1), zerotier-idtool(1)