How to Automate your WireGuard Virtual Networks with NMCTL and Netmaker

Netmaker recently released a new tool called nmctl, which makes automating virtual networks, and WireGuard, even easier!

Netmaker is a super powerful platform for automating virtual networks, however, up until now, you needed to use the UI to manage your networks. With NMCTL, all the power of the admin dashboard has been added to a simple command line utility.

If you’re familiar with kubectl, it shares some similarities, including how it authenticates with the server, and how you perform CRUD operations on different resource types.

You can download NMCTL from the assets in Netmaker releases: https://github.com/gravitl/netmaker/releases

Documentation can be found here: https://docs.netmaker.org/nmctl.html

Using NMCTL

Assuming you already have Netmaker set up, using NMCTL is relatively straightforward. First, I download and make the binary executable. I’m also adding it to my PATH for easy access:

wget https://github.com/gravitl/netmaker/releases/download/v0.17.1/nmctl && chmod +x nmctl && sudo mv nmctl /usr/local/bin/nmctl

I then test to make sure it’s available:

alex@zorg:~$ nmctl --help
CLI for interacting with Netmaker Server

Usage:
  netmaker [command]

Available Commands:
  acl          Manage Access Control Lists (ACLs)
  completion   Generate the autocompletion script for the specified shell
  context      Manage various netmaker server configurations
  dns          Manage DNS entries associated with a network
  ext_client   Manage External Clients
  help         Help about any command
  keys         Manage access keys associated with a network
  logs         Retrieve server logs
  metrics      Fetch metrics of nodes/networks
  network      Manage Netmaker Networks
  network_user Manage Network Users
  node         Manage nodes associated with a network
  server       Get netmaker server information
  user         Manage users and permissions
  usergroup    Manage User Groups

Flags:
  -h, --help     help for netmaker
  -t, --toggle   Help message for toggle

Use "netmaker [command] --help" for more information about a command.

Next, I login to my Netmaker server. You can use either your master key, or username/password:

alex@zorg:~$ nmctl context set default --endpoint=https://api.nm.111-222-111-222.nip.io --username=admin --password=XXXXXXX
alex@zorg:~$ nmctl context use default

I am then able to manage my networks with nmctl!

For instance, list nodes, networks, and users:

alex@zorg:~$ nmctl node list
+------------+----------------+---------+----------+--------+---------+-------+--------------------------------------+
|    NAME    |   ADDRESSES    | VERSION | NETWORK  | EGRESS | INGRESS | RELAY |                  ID                  |
+------------+----------------+---------+----------+--------+---------+-------+--------------------------------------+
| netmaker-1 | 10.101.255.254 | v0.17.1 | netmaker | no     | yes     | no    | 88278135-7b7b-4b83-833b-1df52d158715 |
+------------+----------------+---------+----------+--------+---------+-------+--------------------------------------+

alex@zorg:~$ nmctl network list
+----------+----------------------+----------------------+---------------------------+---------------------------+
|  NETID   | ADDRESS RANGE (IPV4) | ADDRESS RANGE (IPV6) |   NETWORK LAST MODIFIED   |    NODES LAST MODIFIED    |
+----------+----------------------+----------------------+---------------------------+---------------------------+
| netmaker | 10.101.0.0/16        |                      | 2022-12-13T14:22:47-05:00 | 2022-12-13T14:23:36-05:00 |
+----------+----------------------+----------------------+---------------------------+---------------------------+

alex@zorg:~$ nmctl user list
+-------+-------+----------+--------+
| NAME  | ADMIN | NETWORKS | GROUPS |
+-------+-------+----------+--------+
| admin | true  |          | *      |
+-------+-------+----------+--------+

Create Ingress Gateways and Ext Clients:

alex@zorg:~$ nmctl node create_ingress netmaker 88278135-7b7b-4b83-833b-1df52d158715
alex@zorg:~$ nmctl ext_client create netmaker 88278135-7b7b-4b83-833b-1df52d158715
alex@zorg:~$ nmctl ext_client list
+-------------+----------+--------------+--------------+---------+-------------------------------+
|  CLIENT ID  | NETWORK  | IPV4 ADDRESS | IPV6 ADDRESS | ENABLED |         LAST MODIFIED         |
+-------------+----------+--------------+--------------+---------+-------------------------------+
| idle-saturn | netmaker | 10.101.0.1   |              | true    | 2022-12-22 14:09:51 -0500 EST |
+-------------+----------+--------------+--------------+---------+-------------------------------+

Delete Access Keys:

alex@zorg:~$ nmctl keys delete netmaker netmaker-key
Success

And much more!

You can manage your ACL’s via a JSON file, retrieve node metrics, and pretty much everything you can do with the admin UI.

This tool is great for a few specific types of users:

1. Users with large networks: The admin UI can become unwieldy once you have hundreds or thousands of machines in a network. NMCTL vastly simplifies management for these large networks.
2. Users who need automation: Do you need to generate and distribute access keys to join networks on the fly? Do you need to delete nodes under certain conditions, or maybe modify access controls? NMCTL allows you to integrate your network management into scripts, CICD pipelines, and automation tools like Terraform and Ansible.
3. Users who love the command line: And of course, some users, given the choice, simply prefer a CLI over a GUI.

If any of those apply to you, check out NMCTL!