Curl and jq to Manage ZeroTier networks
Snippets of code for using the ZeroTier API to manage and monitor the devices on my networks. This is just curl and jq command-line-fu.
tldr; Snippets of code for using the ZeroTier API to manage and monitor the devices on my networks. This is just curl and jq command-line-fu.
I use ZeroTier as my VPN. It is effortless and works well. However, there is a bit of management overhead when you start connecting multiple networks and devices.
And, like many of you, I try to get as much done on the command line as possible.
There are only a few commands here, but they solve my immediate pain points. However, they should certaily show how easy it is to extend to your needs.
My use cases
- Simple hostname management - I use these scripts to help me keep my
/etc/hosts
file updated with the other machines on my networks. I use these commands to list the machines, and then I merge any updates into my hosts file. This obviates the need for additional DNS entries, and it works all the time. - Prune old entries / network housecleaning - I can keep the network clean and updated easily when moving VMs, machines, etc.
References
Requirements
Before you get started you will need the following:
- ZeroTier account (free to get, up to 100 connected devices I think)
- API Key (generated in the ZeroTier management admin)
curl
,jq
, andcolum
commands installed on your system.
List my Networks
Show the network names and ids to which I have access
note - api keys and network names have been changed
$ curl -s -H "Authorization: Bearer <my_api_key>" \¬
-H "Content-Type: application/json" \¬
https://my.zerotier.com/api/network \¬
| jq -r '.[]| "\(.config.name)***\(.id)"' | column -t -s "***"¬
MyNet Production c700000000000000
MyNet Staging e411111111111111
MyNet Ops e422222222222222
test e433333333333333
eval pcs 1d44444444444444
Let's unpack this a little bit:
- We use curl with some headers to talk to the ZeroTier API
- Using the API key as the token we make a request to a static endpoint.
- That enpoint returns a mess of JSON, which we neatly parse with the
jq
command. I recomment you read up the docs and the hunt for specific uses on Stackoverflow. I am not an expert. - Now that we have cherry-picked our data with
jq
we pass it into thecolumn
command to get the pretty able output. The three asterisks***
is simply a custom delimitere we use to denote columns.
List members (eg - devices) in a single network
Given the ID (collected from the command above), show the network members (names, ids, and ip addresses).
$ curl -s -H "Authorization: Bearer <my_api_key>" \¬
-H "Content-Type: application/json" \¬
https://my.zerotier.com/api/network/c700000000000000/member \¬
| jq -r '.[]| "\(.name)***\(.config.id)***\(.config.ipAssignments[0])"' | column -t -s "***" |sort
coffee-pot 1fffffffff 10.181.22.73
firewall-1 e222222222 10.181.22.152
macbook air 7000000000 10.181.22.98
streaming1 6aaaaaaaaa 10.181.22.81
vm-server1 6111111111 10.181.22.183
Now that we have the network id, we can see what devices are in it.
- Curl GET with API key in header to ZeroTier API endpoint
- Parse the JSON result
- pull out the device name, networkid, and IP address
- Pipe that into the
column
command - Pip that into sort to see it alphabetically
Limitations
- A device can have more than one IP per network. These scripts only take the first IP address in the list.
- There are not checks on the kind of access your API key has.
- These scripts are only for reading. None of them write to the API