NMCTL¶
NMCTL is a CLI tool for interacting with the Netmaker API.
Quick Start¶
Start with getting the binary
wget https://github.com/gravitl/netmaker/releases/latest/download/nmctl
Make sure the binary is executable with chmod +x nmctl and then move it into your /usr/sbin folder.
If everything is setup ok, you should be able to type nmctl and see the following:
CLI for interacting with Netmaker Server
Usage:
nmctl [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
host Manage hosts
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 nmctl
Use "nmctl [command] --help" for more information about a command.
Your CLI should be ready to go at this point.
Before running any commands, a context has to be set which stores the API endpoint information.
You can use your username and password that you use to sign in to the dashboard UI to set the context. Then you can set the CLI to use that context.
nmctl context set dev --endpoint=https://api.netmaker.domain.com --username=admin --password=YOUR_PASSWORD
nmctl context use dev # this sets any defined context as the current context
You can see a list of all your networks that you have set with the following.
nmctl context list
That list also tells you what network is currently set.
Network¶
Create a network with the name test_net and CIDR 10.11.13.0/24.
nmctl network create --name="test_net" --ipv4_addr="10.11.13.0/24"
Fetch details of the created network.
nmctl network list
+----------+----------------------+----------------------+---------------------------+---------------------------+
| NETID | ADDRESS RANGE (IPV4) | ADDRESS RANGE (IPV6) | NETWORK LAST MODIFIED | NODES LAST MODIFIED |
+----------+----------------------+----------------------+---------------------------+---------------------------+
| test_net | 10.11.13.0/24 | | 2022-12-14T13:08:47+05:30 | 2022-12-14T13:08:47+05:30 |
+----------+----------------------+----------------------+---------------------------+---------------------------+
Access Key¶
Create an access key for the created network with 100 uses. This key shall be used by nodes to join the network test_net.
nmctl keys create test_net 100
{
"name": "key-818a4ac3fe85a9d0",
"value": "f0edf9ef08fa2b1a",
"accessstring": "eyJhcZljb25uc3RyaW5nIjoiYXBpLm5ldG1ha2VyLmV6ZmxvLmluOjQ0MyIsIm5ldHdvcmsiOiJ0ZXN0X25ldCIsImtleSI6ImYwZWRmOWVmMDhmYTJiMWEiLCJsb2NhbHJhbmdlIjoiIn0=",
"uses": 100,
"expiration": null
}
Nodes¶
Connect a node to the network using netclient and the access key created above. Use the accessstring as token.
netclient join -t <token>
List all nodes. This displays information about each node such as the address assigned, id, name etc
nmctl node list
+--------------+---------------------------+---------+----------+--------+---------+-------+--------------------------------------+
| NAME | ADDRESSES | VERSION | NETWORK | EGRESS | INGRESS | RELAY | ID |
+--------------+---------------------------+---------+----------+--------+---------+-------+--------------------------------------+
| test_node | 10.11.13.254 | v0.17.0 | test_net | no | no | no | 938d7861-55fc-40a9-970d-6d70acfc3a80 |
+--------------+---------------------------+---------+----------+--------+---------+-------+--------------------------------------+
Using nmctl, we can turn the node into egress, ingress or a relay. Lets turn the node into an ingress by supplying the network name and node id as parameters.
nmctl node create_ingress test_net 938d7861-55fc-40a9-970d-6d70acfc3a80
Fetching the node list once again we can see that our node has been turned into an ingress.
nmctl node list
+--------------+---------------------------+---------+----------+--------+---------+-------+--------------------------------------+
| NAME | ADDRESSES | VERSION | NETWORK | EGRESS | INGRESS | RELAY | ID |
+--------------+---------------------------+---------+----------+--------+---------+-------+--------------------------------------+
| test_node | 10.11.13.254 | v0.17.0 | test_net | no | yes | no | 938d7861-55fc-40a9-970d-6d70acfc3a80 |
+--------------+---------------------------+---------+----------+--------+---------+-------+--------------------------------------+
External Clients¶
Adding an external client to the network is just as easy. Requires the network name and node id as input parameters.
nmctl ext_client create test_net 938d7861-55fc-40a9-970d-6d70acfc3a80
Success
List all available external clients.
nmctl ext_client list
+--------------+---------+--------------+--------------+---------+-------------------------------+
| CLIENT ID | NETWORK | IPV4 ADDRESS | IPV6 ADDRESS | ENABLED | LAST MODIFIED |
+--------------+---------+--------------+--------------+---------+-------------------------------+
| limp-chicken |test_net | 10.11.13.2 | | true | 2022-11-23 18:28:57 +0530 IST |
+--------------+---------+--------------+--------------+---------+-------------------------------+
The wireguard config of an external client can also be fetched with the network name and external client id.
nmctl ext_client config test_net limp-chicken
[Interface]
Address = 10.11.13.2/32
PrivateKey = 4Ojhsn/uLcH6xta6zqokQ+GiRuZwesdzE2hDSa6vYWc=
MTU = 1280
[Peer]
PublicKey = h96G9R8qqHIm6OfFgIZNBlRE5uCumkSZv4Pwn2DVXEs=
AllowedIPs = 10.11.13.0/24
Endpoint = 138.209.145.214:51824
PersistentKeepalive = 20
Help¶
Further information about any subcommand is available using the –help flag
nmctl subcommand --help
Example:-
nmctl node --help
Manage nodes associated with a network
Usage:
nmctl node [command]
Available Commands:
create_egress Turn a Node into a Egress
create_ingress Turn a Node into a Ingress
create_relay Turn a Node into a Relay
delete Delete a Node
delete_egress Delete Egress role from a Node
delete_ingress Delete Ingress role from a Node
delete_relay Delete Relay role from a Node
get Get a node by ID
list List all nodes
uncordon Get a node by ID
update Update a Node
Flags:
-h, --help help for node
Use "nmctl node [command] --help" for more information about a command.