mirror of
https://github.com/zerotier/ZeroTierOne.git
synced 2025-04-07 11:17:29 +00:00
Switch manual pages to "ronn," a program that converts MarkDown to roff man pages, and pre-build them. Also have the zerotier-cli(1) man page ready to go!
This commit is contained in:
Adam Ierymenko
parent
f9148bf9cb
commit
096db53822
2
.gitignore
vendored
2
.gitignore
vendored
@ -79,5 +79,3 @@ java/build_win32/
|
||||
windows/WinUI/obj/
|
||||
windows/WinUI/bin/
|
||||
windows/ZeroTierOne/Debug/
|
||||
/doc/*.1
|
||||
/doc/*.8
|
||||
|
||||
25
doc/build.sh
Executable file
25
doc/build.sh
Executable file
@ -0,0 +1,25 @@
|
||||
#!/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
|
||||
|
||||
if [ ! -f node_modules/ronn/bin/ronn.js ]; then
|
||||
echo 'Installing MarkDown to ROFF converter...'
|
||||
npm install ronn
|
||||
echo
|
||||
fi
|
||||
|
||||
rm -f zerotier-cli.1 *.roff
|
||||
|
||||
node node_modules/ronn/bin/ronn.js --build --roff zerotier-cli.1.md
|
||||
if [ -f zerotier-cli.1.roff ]; then
|
||||
mv zerotier-cli.1.roff zerotier-cli.1
|
||||
else
|
||||
echo 'Conversion of zerotier-cli.1.md failed!'
|
||||
exit 1
|
||||
fi
|
||||
|
||||
exit 0
|
||||
@ -1,52 +0,0 @@
|
||||
# doc/module.mk
|
||||
# Part of ZeroTier One, a software-defined network layer.
|
||||
#
|
||||
# Copyright © 2016 Ben Finney <ben+zerotier@benfinney.id.au>
|
||||
# This is free software: you may copy, modify, and/or distribute this
|
||||
# work under the terms of the GNU General Public License, version 3 or
|
||||
# later as published by the Free Software Foundation.
|
||||
# No warranty expressed or implied.
|
||||
# See the file ‘LICENSE.txt’ for details.
|
||||
|
||||
# Makefile module for ZeroTier One documentation.
|
||||
|
||||
TEMPFILE_SUFFIX = .tmp
|
||||
.INTERMEDIATE: ${DOCUMENTATION_DIR}/*${TEMPFILE_SUFFIX}
|
||||
|
||||
RST_SUFFIX = .txt
|
||||
manpage_sections = 1 2 3 4 5 6 7 8
|
||||
manpage_names += zerotier-one.8
|
||||
manpage_names += zerotier-idtool.1
|
||||
manpage_names += zerotier-cli.1
|
||||
manpage_source_paths = $(addprefix ${DOC_DIR}/, \
|
||||
$(addsuffix ${RST_SUFFIX},${manpage_names}))
|
||||
manpage_paths = $(addprefix ${DOC_DIR}/,${manpage_names})
|
||||
manpage_encoding_stub = ${DOC_DIR}/manpage_encoding_declaration.UTF-8
|
||||
|
||||
GENERATED_FILES += $(addprefix ${DOC_DIR}/,\
|
||||
$(foreach section,${manpage_sections},*.${section}))
|
||||
|
||||
RST2MAN = rst2man
|
||||
RST2MAN_OPTS =
|
||||
|
||||
|
||||
.PHONY: doc
|
||||
doc: manpages
|
||||
|
||||
.PHONY: manpages
|
||||
manpages: ${manpage_paths}
|
||||
|
||||
%.1: %.1${RST_SUFFIX}
|
||||
$(RST2MAN) "$<" > "$@"${TEMPFILE_SUFFIX}
|
||||
cat ${manpage_encoding_stub} "$@"${TEMPFILE_SUFFIX} > "$@"
|
||||
|
||||
%.8: %.8${RST_SUFFIX}
|
||||
$(RST2MAN) "$<" > "$@"${TEMPFILE_SUFFIX}
|
||||
cat ${manpage_encoding_stub} "$@"${TEMPFILE_SUFFIX} > "$@"
|
||||
|
||||
|
||||
# Local variables:
|
||||
# coding: utf-8
|
||||
# mode: makefile
|
||||
# End:
|
||||
# vim: fileencoding=utf-8 filetype=make :
|
||||
110
doc/zerotier-cli.1
Normal file
110
doc/zerotier-cli.1
Normal file
@ -0,0 +1,110 @@
|
||||
.\" Generated with Ronnjs 0.4.0
|
||||
.\" http://github.com/kapouer/ronnjs
|
||||
.
|
||||
.TH "ZEROTIER\-CLI" "1" "June 2016" "" ""
|
||||
.
|
||||
.SH "NAME"
|
||||
\fBzerotier-cli\fR \-\- control local ZeroTier virtual network service
|
||||
.
|
||||
.SH "SYNOPSIS"
|
||||
\fBzerotier\-cli\fR [\-switches] <command> [arguments]
|
||||
.
|
||||
.SH "DESCRIPTION"
|
||||
\fBzerotier\-cli\fR provides a simple command line interface to the local JSON API of the ZeroTier virtual network endpoint service zerotier\-one(8)\.
|
||||
.
|
||||
.P
|
||||
By default \fBzerotier\-cli\fR must be run as root or with \fBsudo\fR\|\. If you want to allow an unprivileged user to use \fBzerotier\-cli\fR to control the system ZeroTier service, you can create a local copy of the ZeroTier service authorization token in the user\'s home directory:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
sudo cp /var/lib/zerotier\-one/authtoken\.secret /home/user/\.zeroTierOneAuthToken
|
||||
chown user /home/user/\.zeroTierOneAuthToken
|
||||
chmod 0600 /home/user/\.zeroTierOneAuthToken
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
(The location of ZeroTier\'s service home may differ by platform\. See zerotier\-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
|
||||
\fBzerotier\-cli\fR has several command line arguments that are visible in \fBhelp\fR output\. The two most commonly used are \fB\-j\fR for raw JSON output and \fB\-D<path>\fR 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 \fB\-D<path>\fR 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\.
|
||||
.
|
||||
.SH "COMMANDS"
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBhelp\fR:
|
||||
Displays \fBzerotier\-cli\fR help\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBinfo\fR:
|
||||
Shows information about this device including its 10\-digit ZeroTier address and apparent connection status\. Use \fB\-j\fR for more verbose output\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBlistpeers\fR:
|
||||
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\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBlistnetworks\fR:
|
||||
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\.)
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBjoin\fR:
|
||||
To join a network just use \fBjoin\fR and its 16\-digit hex network ID\. That\'s it\. Then use \fBlistnetworks\fR 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\fR) on the network\'s controller\.
|
||||
.
|
||||
.IP "\(bu" 4
|
||||
\fBleave\fR:
|
||||
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\fR 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\.
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "EXAMPLES"
|
||||
Join "Earth," ZeroTier\'s big public party line network:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
$ 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 \.\.\.
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
Leave "Earth":
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
$ sudo zerotier\-cli leave 8056c2e21c000001
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.P
|
||||
List VL1 peers:
|
||||
.
|
||||
.IP "" 4
|
||||
.
|
||||
.nf
|
||||
$ sudo zerotier\-cli listpeers
|
||||
.
|
||||
.fi
|
||||
.
|
||||
.IP "" 0
|
||||
.
|
||||
.SH "COPYRIGHT"
|
||||
(c)2011\-2016 ZeroTier, Inc\.
|
||||
.
|
||||
.SH "SEE ALSO"
|
||||
zerotier\-one(8), zerotier\-idtool(1)
|
||||
68
doc/zerotier-cli.1.md
Normal file
68
doc/zerotier-cli.1.md
Normal 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.
|
||||
|
||||
## SEE ALSO
|
||||
|
||||
zerotier-one(8), zerotier-idtool(1)
|
||||
@ -1,109 +0,0 @@
|
||||
============
|
||||
zerotier-cli
|
||||
============
|
||||
|
||||
--------------------------------------------------
|
||||
management interface for ZeroTier One peer process
|
||||
--------------------------------------------------
|
||||
|
||||
:Author: |author|
|
||||
:Date: 2016-03-04
|
||||
:Copyright:
|
||||
Copyright © 2016 ZeroTier Inc.
|
||||
:Manual section: 1
|
||||
:Manual group: ZeroTier
|
||||
|
||||
.. |command| replace:: **zerotier-cli**
|
||||
.. |license| replace::
|
||||
`GNU General Public License, version 3 or later
|
||||
<https://www.gnu.org/licenses/#GPL>`__
|
||||
|
||||
|
||||
SYNOPSIS
|
||||
========
|
||||
|
||||
| |command| [ **-j** ] [ **-D** `HOMEDIR` ] [ **-p** `PORT` ] [ **-t** `AUTH_TOKEN` ] \
|
||||
`command` [ `COMMAND_ARG` ]
|
||||
|
||||
|
||||
DESCRIPTION
|
||||
===========
|
||||
|
||||
|command| is a tool to manage the running **zerotier-one**\ (8)
|
||||
process.
|
||||
|
||||
*ZeroTier* is a peer-to-peer virtual network. Its “virtual layer 1”
|
||||
(VL1) is implemented in the communication between ZeroTier One peers.
|
||||
This provides the OSI layer 1 functionality on which to build further
|
||||
network services.
|
||||
|
||||
|
||||
COMMANDS
|
||||
========
|
||||
|
||||
|command| **info**
|
||||
|
||||
*FIXME*: display status info
|
||||
|
||||
|command| **listpeers**
|
||||
|
||||
*FIXME*: list all peers
|
||||
|
||||
|command| **listnetworks**
|
||||
|
||||
*FIXME*: list all networks
|
||||
|
||||
|command| **join** `NETWORK`
|
||||
|
||||
*FIXME*: join the network `NETWORK`
|
||||
|
||||
|command| **leave** `NETWORK`
|
||||
|
||||
*FIXME*: leave the network `NETWORK`
|
||||
|
||||
|
||||
FILES
|
||||
=====
|
||||
|
||||
The |command| process will discover the running **zerotier-one**\ (8)
|
||||
process by examining the specified `HOMEDIR` directory (default:
|
||||
``/var/lib/zerotier-one``).
|
||||
|
||||
|
||||
SEE ALSO
|
||||
========
|
||||
|
||||
* **zerotier-one**\ (8)
|
||||
|
||||
* ZeroTier One documentation:
|
||||
|
||||
* Product page `<https://www.zerotier.com/product-one.shtml>`__.
|
||||
* Configuration guide `<https://www.zerotier.com/config.shtml>`__.
|
||||
* Technical FAQ `<https://www.zerotier.com/tech_faq.shtml>`__.
|
||||
|
||||
|
||||
HISTORY
|
||||
=======
|
||||
|
||||
The |command| program is developed by ZeroTier Inc.
|
||||
|
||||
This manual page was written by |author|. This is free software: you
|
||||
may copy, modify and/or distribute this work under the terms of the
|
||||
|license| as published by the Free Software Foundation. No warranty
|
||||
expressed or implied.
|
||||
|
||||
.. |author| replace:: |authorname| |authoremail|
|
||||
.. |authorname| replace:: Ben Finney
|
||||
.. |authoremail| replace:: <ben+zerotier@benfinney.id.au>
|
||||
|
||||
|
||||
..
|
||||
Local variables:
|
||||
mode: rst
|
||||
coding: utf-8
|
||||
time-stamp-format: "%:y-%02m-%02d"
|
||||
time-stamp-start: "^:Date:[ ]+"
|
||||
time-stamp-end: "$"
|
||||
time-stamp-line-limit: 20
|
||||
End:
|
||||
vim: filetype=rst fileencoding=utf-8 :
|
||||
Loading…
x
Reference in New Issue
Block a user