.TH "ZEROTIER\-CLI" "1" "December 2016" "" ""
.SH "NAME"
\fBbackone-cli\fR \- control local BackOne virtual network service
.SH SYNOPSIS
.P
\fBbackone\-cli\fP [\-switches] <command> [arguments]
.SH DESCRIPTION
.P
\fBbackone\-cli\fR provides a simple command line interface to the local JSON API of the BackOne virtual network endpoint service backone\-one(8)\.
.P
By default \fBbackone\-cli\fR must be run as root or with \fBsudo\fP\|\. If you want to allow an unprivileged user to use \fBbackone\-cli\fR to control the system BackOne service, you can create a local copy of the BackOne service authorization token in the user's home directory:
.P
.RS 2
.nf
sudo cp /var/lib/backone\-one/authtoken\.secret /home/user/\.zeroTierOneAuthToken
chown user /home/user/\.zeroTierOneAuthToken
chmod 0600 /home/user/\.zeroTierOneAuthToken
.fi
.RE
.P
(The location of BackOne's service home may differ by platform\. See backone\-one(8)\.)
.P
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\.
.P
\fBbackone\-cli\fR has several command line arguments that are visible in \fBhelp\fP output\. The two most commonly used are \fB\-j\fP for raw JSON output and \fB\-D<path>\fP to specify an alternative BackOne service working directory\. Raw JSON output is easier to parse in scripts and also contains verbose details not present in the tabular output\. The \fB\-D<path>\fP option specifies where the service's backone\-one\.port and authtoken\.secret files are located if the service is not running at the default location for your system\.
.SH COMMANDS
.RS 0
.IP \(bu 2
\fBhelp\fP:
Displays \fBbackone\-cli\fR help\.
.IP \(bu 2
\fBinfo\fP:
Shows information about this device including its 10\-digit BackOne address and apparent connection status\. Use \fB\-j\fP for more verbose output\.
.IP \(bu 2
\fBlistpeers\fP:
This command lists the BackOne 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\.
.IP \(bu 2
\fBlistnetworks\fP:
This lists the networks your system belongs to and some information about them, such as any BackOne\-managed IP addresses you have been assigned\. (IP addresses assigned manually to BackOne interfaces will not be listed here\. Use the standard network interface commands to see these\.)
.IP \(bu 2
\fBjoin\fP:
To join a network just use \fBjoin\fP and its 16\-digit hex network ID\. That's it\. Then use \fBlistnetworks\fP 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 \fBinfo\fP) on the network's controller\.
.IP \(bu 2
\fBleave\fP:
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 \fBlistpeers\fP 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\.

.RE
.SH EXAMPLES
.P
Join "Earth," BackOne's big public party line network:
.P
.RS 2
.nf
$ sudo backone\-cli join 8056c2e21c000001
$ sudo backone\-cli listnetworks
( wait until you get an Earth IP )
$ ping earth\.backone\.net
( you should now be able to ping our Earth test IP )
.fi
.RE
.P
Leave "Earth":
.P
.RS 2
.nf
$ sudo backone\-cli leave 8056c2e21c000001
.fi
.RE
.P
List VL1 peers:
.P
.RS 2
.nf
$ sudo backone\-cli listpeers
.fi
.RE
.SH COPYRIGHT
.P
(c)2011\-2016 BackOne, Inc\. \-\- https://www\.backone\.com/ \-\- https://github\.com/backone
.SH SEE ALSO
.P
backone\-one(8), backone\-idtool(1)