ztcli-async

ztcli-async is a thin async Python client wrapper for the zerotier-cli node API (mainly based on zerotier-client and the ZeroTier API doc). ztcli-async works with all node types, eg root (aka moon), network controller, and user nodes.

Getting Started

This is a Python thin client interface to the zerotier JSON API, only some of which is exposed by the zerotier-cli command-line interface. Packages are available for Debian and Ubuntu, and the latest can be installed on Gentoo using the ebuilds in this portage overlay.

Prerequisites

In Theory, this software should work on anything with a working ZeroTier package and Python, including most BSDs, Unix/Linux, MacOS, and Windows. That said, it has really only been tested on the Linux variants below.

Existing Packages

Older packages are available for some (tested) linux distributions, mainly something that uses either .ebuilds (eg, Gentoo or funtoo) or .deb packages, starting with at least Ubuntu xenial or Debian stretch (see the above PPA package repo on Launchpad).

For the latter, make sure you have the add-apt-repository command installed and then add the PPA:

$ sudo apt-get install software-properties-common
$ sudo add-apt-repository -y -s ppa:nerdboy/embedded

Note

Since the package series currently published are for xenial, bionic, and focal, the second command above will need to be manually corrected afterwards if installing on Debian.

To install on Debian you can use the above method, but you will need to edit the file under sources.d and set the distro to the "closest", then run the update command:

$ sudo apt-get update

If you get a key error you will also need to manually import the PPA signing key like so:

$ sudo apt-key adv --keyserver keyserver.ubuntu.com --recv-keys <PPA_KEY>

where <PPA_KEY> is the key shown in the launchpad PPA page under "Adding this PPA to your system", eg, 41113ed57774ed19 for Embedded device ppa.

Dev Install

As long as you have git and at least Python 3.6, then the "easy" dev install is to clone this repository and install the latest zerotier package (there are packages in the PPA and Gentoo overlay). Check the version of zerotier in the main portage tree; you will need at least version 1.4.6:0.

Do the usual install dance, either:

# emerge zerotier

or:

$ sudo apt-get install zerotier-one

Start zerotier according to your distro package; you can check the zerotier client state with:

$ sudo zerotier-cli info

which should respond with:

200 info <your ID> 1.4.6 ONLINE

If the above is working, you can try one of the examples below.

If you set an ACL (see note below), then try this:

$ git clone https://github.com/sarnold/ztcli-async
$ cd ztcli-async
$ tox -e dev
$ source .tox/dev/bin/activate
$ python3 examples/pprint_data.py
$ deactivate

Without an ACL, you'll need to install both async deps as system packages, eg, then try sudo without the venv:

$ sudo emerge aiohttp async-timeout
$ cd ztcli-async
$ sudo PYTHONPATH="." python examples/pprint_data.py

Note

By default you will not have correct permissions to access the local zerotier node directly, due to the permissions on zerotier identity files. You can either prefix the commands with sudo, or add a usr ACL (for your local user) to the authtoken.secret file.

Standards and Coding Style

Currently pep8 and flake8 are the only tests besides some CI code analysis checks for complexity and security issues (we try to keep the "cognitive complexity" low when possible).

User Install / Deployment

Use the latest ztcli-async package for your Linux distro and hardware architecture; all arch-specific packages should support at least the following:

• armhf/arm
• aarch64/arm64
• x86_64/amd64
• i686/x86

Software Stack and Tool Dependencies

• Python - at least version 3.6
• async-timeout - timeout context manager for asyncio
• aiohttp - http client/server for asyncio
• ZeroTier - network virtualization engine

Versioning

We use SemVer for versioning. For the versions available, see the releases in this repository.

Contributing

Please read CONTRIBUTING for details on the code of conduct and the process for submitting pull requests.

Authors

• Stephen Arnold - Current implementation and packaging - nerdboy
• Fabian Affolter - Original implementation - fabaff

License

This project is licensed under the MIT license - see the LICENSE file for details.

Acknowledgments

• Thanks to Fabian for the clean original client implementation and inspiration
• Thanks to the ZeroTier project for providing the network virtualization engine