DocsAPI

Generate Config Files using API and NMCTL

Power users may wish to bulk-create and manage wireguard config files for their network. For this, we recommend using the API or NMCTL.

Generating Clients via APICopied!

Static client configurations can also be generated using the “createExtClient” endpoint of the netmaker api. Authorization to the API needs to be done for accessing relevant API endpoints.

  1. Generate and grab a JWT token from the authenticate api endpoint using the following curl command (https://openapi.netmaker.io/#tag/authenticate/operation/authenticateUser):

    curl -X POST --location 'https://api.netmaker.example.com/api/users/adm/authenticate' --header 'Content-Type: application/json' --data '{ "username":"<netmaker username>", "password":"<netmaker password>" }'

  2. Copy the JWT token printed onto the terminal to use for subsequent API requests

  3. Create a config file for a specified Remote Access Gateway.

    1. The following API endpoint should be used for generating static client configurations: https://openapi.netmaker.io/#tag/ext_client/operation/createExtClient

    2. The endpoint requires the netmaker “network” name and the “Remote Access Gateway”’s “Network Host ID” on the URL to make the request for generating static client configurations.

    3. To get the “Device Network ID” of the gateway, we can simple navigate to the netmaker network and click on the host name to reveal the id as shown below:

    4. Make the API POST request to the endpoint using the following command:

curl -X POST -L "https://api.netmaker.example.com/api/extclients/<network name>/<host network id>" -H "Content-Type: application/json" -H "Authorization: Bearer <AuthToken>" --data '{"clientid":"SiteC"}'

On successful execution of the POST request, there will be no reply or error message from the api endpoint. To list out all the static client configurations, we can make the following API request:

curl -X GET -L "https://api.netmaker.example.com/api/extclients/<network name>" -H "Content-Type: application/json" -H "Authorization: Bearer <AuthToken>"

The API server will reply with a list of all the static clients on the particular network in JSON format.

To retrieve a WireGuard configuration for a specific static client, the following API request can be made:

curl -X GET -L "https://api.netmaker.example.com/api/extclients/<network name>/<static client id>/file" -H "Content-Type: application/json" -H "Authorization: Bearer <AuthToken>"

This request should provide the WireGuard configuration file in response.

The extclients API endpoint can be used to generate, delete and remotely manage static client configurations in bulk. Also, this can be implemented into custom systems for automating the whole process.

Create Clients via NMCTLCopied!

NMCTL is a great command line utility for interacting with the netmaker server. This command line utility can be used to basically authenticate and make API calls to the netmaker server but using a CLI.

Setup NMCTLCopied!

  1. Download the latest NMCTL tool from: https://github.com/gravitl/netmaker/releases/latest

    1. Make sure to download the build supported by your CPU and operating system architecture.

    2. Make sure necessary executable permissions are set on the nmctl binary after downloading.

  2. Open up the terminal and execute the following commands for authenticating, adding and setting the netmaker server into the current CLI context:

    1. nmctl context set <context name> --endpoint=https://api.netmaker.example.com  --username=<username> --password=<password>

    2. nmctl context use <context name>


The context name can be set accordingly to easily identify and manage multiple netmaker servers from nmctl command line interface. It needs to be unique for different servers. The endpoint is the api endpoint URL of your netmaker server and the username, password are the netmaker dashboard login username and password respectively.

Create ClientCopied!

  1. To create a static client under a “Remote Access Gateway” we need to get two pieces of information. The netmaker network name in which the gateway resides and static clients will be created, and the “Host Network ID” of the “Remote Access Gateway” host.

  2. To get the “Device Network ID” of the gateway, we can simple navigate to the netmaker network and click on the host name to reveal the id as shown below:

  3. Generate a static client configuration by executing the following command with nmctl: nmctl ext_client create <network name> <host network id> --id <static client id>

    1. Static client id must be set to uniquely identify and manage different client configurations

  4. If the above command response comes out as a “Success” message, that means the static client has been created successfully.

Get ClientCopied!

Now to retrieve the static client configuration which we created just now, the following command should be executed using nmctl:

nmctl ext_client config <network name> <static client id>

This will provide the WireGuard configuration file for this static client which can be used to setup the WireGuard plugin on the device.


Other Options with NMCTLCopied!

NMCTL also provide options to delete and update these static clients and a list of some other helpful commands which can be retrieved using this command:

nmctl ext_client --help