### Add Bitnami Helm Repository

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Adds the Bitnami Helm repository for installing PostgreSQL.

```bash
helm repo add bitnami https://charts.bitnami.com/bitnami
```

--------------------------------

### Install HA PostgreSQL using Helm

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Installs a highly-available PostgreSQL cluster using the Bitnami Helm chart.

```bash
helm install postgres bitnami/postgresql
```

--------------------------------

### Run Netmaker with a YAML Configuration File

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/configuration.md

Specify a custom YAML configuration file using the -c flag when starting Netmaker.

```bash
netmaker -c /path/to/config.yaml
```

--------------------------------

### Install Netmaker Open Source

Source: https://github.com/gravitl/netmaker/blob/develop/README.md

Run this script to quickly set up the open-source version of Netmaker on a cloud VM with Ubuntu 24.04. Ensure necessary ports are open and DNS is prepared.

```bash
sudo wget -qO /root/nm-quick.sh https://raw.githubusercontent.com/gravitl/netmaker/master/scripts/nm-quick.sh && sudo chmod +x /root/nm-quick.sh && sudo /root/nm-quick.sh
```

--------------------------------

### Get Server Info API Response

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Example JSON response when retrieving server configuration and status. This includes version, master public key, and message queue endpoint.

```json
{
  "version": "v1.6.0",
  "masterpublickey": "server-public-key",
  "messagequeueendpoint": "mqtt-broker:1883",
  "capturedfiles": []
}
```

--------------------------------

### Netmaker YAML Configuration Structure

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/configuration.md

This is a comprehensive example of the Netmaker YAML configuration file structure, covering server, MQTT, authentication, OAuth, email, and high availability settings.

```yaml
server:
  database: postgres
  api_host: 0.0.0.0
  api_port: 8081
  frontend_url: https://dashboard.netmaker.io
  api_conn_string: "host=postgres port=5432 user=postgres password=netmaker dbname=netmaker"
  caching_enabled: "true"
  rest_backend: "true"

mqtt:
  broker_endpoint: "mqtt-broker:1883"
  websocket_port: 8085
  username: "netmaker"
  password: "netmaker"

auth:
  master_key: "your-master-key"
  jwt_validity_duration: 43200

oauth:
  provider: "google"
  client_id: "your-client-id"
  client_secret: "your-client-secret"

email:
  smtp_host: "smtp.gmail.com"
  smtp_port: 587
  sender_addr: "noreply@netmaker.io"
  sender_user: "your-email@gmail.com"
  sender_password: "your-app-password"

ha:
  is_ha: false
  cluster_name: "netmaker"
  pod_name: "netmaker-0"
```

--------------------------------

### Create External Client Response

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Example JSON response after successfully creating an external client. It provides the client's ID, public key, and network details.

```json
{
  "clientid": "client-uuid",
  "publickey": "public-key",
  "privatekey": "private-key",
  "address": "10.0.0.100/32",
  "network": "network-name",
  "ingressgatewayendpoint": "203.0.0.113:51821"
}
```

--------------------------------

### Kubernetes HA Environment Variable Setup

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/configuration.md

Example of setting HA environment variables within a Kubernetes deployment configuration.

```yaml
env:
  - name: POD_NAME
    valueFrom:
      fieldRef:
        fieldPath: metadata.name
  - name: IS_HA
    value: "true"
  - name: CLUSTER_NAME
    value: "netmaker"
```

--------------------------------

### Get All Users

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Retrieves a list of all users in the system. The returned user objects exclude password information for security.

```Go
func GetUsers() ([]models.ReturnUser, error)
```

--------------------------------

### Create User API Request Body

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Example JSON request body for creating a new user. Ensure all required fields are provided. The 'isadmin' field defaults to false if not specified.

```json
{
  "username": "newuser",
  "password": "secure-password",
  "email": "user@example.com",
  "isadmin": false
}
```

--------------------------------

### Docker Compose Configuration for Netmaker

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/configuration.md

A Docker Compose setup for Netmaker, including PostgreSQL for the database and EMQX for the message broker. Ensure to set SERVER_HOST and MASTER_KEY environment variables.

```yaml
version: '3.8'

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: netmaker
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: netmaker
    volumes:
      - postgres_data:/var/lib/postgresql/data

  emqx:
    image: emqx/emqx:latest
    environment:
      EMQX_DEFAULT_USER: netmaker
      EMQX_DEFAULT_PASSWORD: netmaker
    ports:
      - "1883:1883"
      - "8083:8083"
      - "18083:18083"

  netmaker:
    image: gravitl/netmaker:latest
    depends_on:
      - postgres
      - emqx
    environment:
      SERVER_HOST: ${SERVER_HOST}
      API_PORT: 8081
      REST_BACKEND: "true"
      MESSAGEQUEUE_BACKEND: "true"
      DATABASE: postgres
      SQL_HOST: postgres
      SQL_DB: netmaker
      SQL_USER: postgres
      SQL_PASS: netmaker
      BROKER_ENDPOINT: emqx:1883
      MASTER_KEY: ${MASTER_KEY}
      JWT_VALIDITY_DURATION: 43200
      VERBOSITY: 2
    ports:
      - "8081:8081"
      - "51821-51831:51821-51831/udp"
    volumes:
      - ./data:/root/data
      - ./logs:/root/logs

volumes:
  postgres_data:
```

--------------------------------

### Host Not Found Error

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/errors.md

Indicates that a host with the specified ID could not be found. Ensure the Netclient is installed and running on the host.

```json
{
  "code": 404,
  "message": "Host not found",
  "response": null
}
```

--------------------------------

### Get Server Info

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Retrieve server configuration and status information. This includes version, public key, and message queue endpoint.

```APIDOC
## GET /api/server

### Description
Retrieve server configuration and status.

### Method
GET

### Endpoint
/api/server

### Response
#### Success Response (200)
- **version** (string) - The server version.
- **masterpublickey** (string) - The server's public key.
- **messagequeueendpoint** (string) - The endpoint for the message queue.
- **capturedfiles** (array) - A list of captured files (if any).

### Response Example
```json
{
  "version": "v1.6.0",
  "masterpublickey": "server-public-key",
  "messagequeueendpoint": "mqtt-broker:1883",
  "capturedfiles": []
}
```
```

--------------------------------

### List External Clients Response

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Example JSON response when listing all external clients for a network. It includes client details like public key, IP addresses, and associated network information.

```json
[
  {
    "clientid": "client-uuid",
    "publickey": "wireguard-public-key",
    "address": "10.0.0.100/32",
    "address6": "fd00::100/128",
    "network": "network-name",
    "dns": "10.0.0.1",
    "enabled": true,
    "ingressgatewayid": "node-uuid",
    "ingressgatewayendpoint": "203.0.0.113:51821",
    "allowed_ips": ["10.0.0.0/8"],
    "ownerid": "user-id"
  }
]
```

--------------------------------

### Get Server Configuration and Status (JSON Response)

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

This snippet displays the JSON response for retrieving server information. It includes the server version, master public key, and message queue endpoint.

```json
{
  "version": "v1.6.0",
  "masterpublickey": "server-wg-public-key",
  "messagequeueendpoint": "mqtt-broker:1883",
  "capturedfiles": []
}
```

--------------------------------

### Apply mosquitto.yaml

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Applies the configured mosquitto.yaml file to deploy the MQTT broker.

```bash
kubectl apply -f mosquitto.yaml
```

--------------------------------

### Get Egress Routes Response

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Example response for retrieving egress routes configured for a specific network. Includes egress node ID, IP ranges, NAT status, and operational status.

```json
[
  {
    "egress_id": "node-123",
    "ranges": ["192.168.0.0/16", "192.168.1.0/24"],
    "nat": true,
    "status": true
  }
]
```

--------------------------------

### Configure STUN and TURN Servers for NAT Traversal

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/configuration.md

Set up STUN and TURN servers to facilitate network traversal for clients behind NAT. Provide a list of STUN servers and details for the TURN server.

```bash
STUN_LIST="stun.l.google.com:19302,stun1.l.google.com:19302"
TURN_SERVER=turn.example.com
TURN_USERNAME=username
TURN_PASSWORD=password
```

--------------------------------

### Get Network

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/INDEX.md

Retrieves details for a specific network by its name. Requires authentication.

```APIDOC
## GET /api/networks/{name}

### Description
Gets a specific network by its name.

### Method
GET

### Endpoint
/api/networks/{name}

### Auth
✓
```

--------------------------------

### Get Network Details

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Retrieve a specific network by name. Requires OAuth authentication.

```APIDOC
## GET /api/networks/{networkname}

### Description
Retrieve a specific network by name.

### Method
GET

### Endpoint
/api/networks/{networkname}

### Parameters
#### Path Parameters
- **networkname** (string) - Required - Network identifier

### Request Example
None

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the network.
- **netid** (string) - The name of the network.
- **addressrange** (string) - The IPv4 address range for the network.
- **defaultkeepalive** (integer) - Default WireGuard keepalive interval in seconds.
- **defaultmtu** (integer) - Default Maximum Transmission Unit for the network.

#### Response Example
```json
{
  "id": "uuid",
  "netid": "network-name",
  "addressrange": "10.0.0.0/8",
  "defaultkeepalive": 20,
  "defaultmtu": 1280
}
```

#### Status Codes
- `200` - Success
- `404` - Network not found
- `500` - Internal server error
```

--------------------------------

### Get Network Egress Routes

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Retrieve all egress routes for a network. Requires OAuth authentication.

```APIDOC
## GET /api/networks/{networkname}/egress_routes

### Description
Retrieve all egress routes for a network.

### Method
GET

### Endpoint
/api/networks/{networkname}/egress_routes

### Parameters
#### Path Parameters
- **networkname** (string) - Required - Network identifier

### Request Example
None

### Response
#### Success Response (200)
- Array of egress route objects.

#### Response Example
None provided in source.

#### Status Codes
- `200` - Success
- `404` - Network not found
- `500` - Internal server error
```

--------------------------------

### GetNetworkNodes

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Get all nodes in a specific network. This is used for the network detail view and node listing.

```APIDOC
## GetNetworkNodes

### Description
Get all nodes in a specific network. Used by Network detail view and node listing.

### Method
GET

### Endpoint
/networks/{networkName}/nodes

### Parameters
#### Path Parameters
- **networkName** (string) - Required - The name of the network to retrieve nodes from.

#### Query Parameters
None

#### Request Body
None

### Response
#### Success Response (200)
- **nodes** ([]schema.Node) - A list of nodes within the specified network.

### Request Example
None provided

### Response Example
```json
{
  "nodes": [
    {
      "id": "uuid-node-1",
      "name": "node1",
      "ipv4": "10.0.0.1/24",
      "is_gateway": false,
      "is_relay": false,
      "region": "us-east-1",
      "dns": "node1.example.com"
    }
  ]
}
```
```

--------------------------------

### Subscribe to MQTT Topic

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/errors.md

Use `mosquitto_sub` to subscribe to a test topic and receive messages.

```bash
mosquitto_sub -h $BROKER_HOST -t "test/topic"
```

--------------------------------

### Get Egress Routes

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Retrieves the egress routes configured for a specific network. Requires authentication.

```APIDOC
## GET /api/networks/{networkname}/egress_routes

### Description
Get egress routes configured for a network.

### Method
GET

### Endpoint
/api/networks/{networkname}/egress_routes

### Parameters
#### Path Parameters
- **networkname** (string) - Required - Network identifier

### Request Example
None

### Response
#### Success Response (200)
- **egress_id** (string) - Identifier of the egress node
- **ranges** (array of strings) - List of IP ranges accessible via this egress
- **nat** (boolean) - Whether Network Address Translation is enabled
- **status** (boolean) - Status of the egress route

#### Response Example
```json
[
  {
    "egress_id": "node-123",
    "ranges": ["192.168.0.0/16", "192.168.1.0/24"],
    "nat": true,
    "status": true
  }
]
```

**Status Codes:**
- `200` - Success
- `404` - Network not found
- `500` - Server error
```

--------------------------------

### Create Netmaker Namespace

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Creates the 'netmaker' namespace and sets it as the current context.

```bash
kubectl create ns netmaker
kubectl config set-context --current --namespace=netmaker
```

--------------------------------

### Get server and network metrics

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Retrieves aggregated metrics data for the server and network. Authentication is required.

```APIDOC
## GET /api/metrics

### Description
Get server and network metrics.

### Method
GET

### Endpoint
/api/metrics

### Response
#### Success Response (200)
- Aggregated metrics data

#### Error Response
- **500** - Server error
```

--------------------------------

### Troubleshoot MQ Connection: Scale Up Netmaker

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Scale the Netmaker stateful set back up to the desired number of replicas.

```bash
kubectl scale sts netmaker --replicas=3
```

--------------------------------

### Retrieve All Enrollment Keys

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Retrieve all existing enrollment keys from the database.

```go
func GetAllEnrollmentKeys() ([]models.EnrollmentKey, error)
```

--------------------------------

### Get Network Details

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Retrieve a specific network by its name. The network name is a required path parameter.

```json
{
  "id": "uuid",
  "netid": "network-name",
  "addressrange": "10.0.0.0/8",
  "defaultkeepalive": 20,
  "defaultmtu": 1280
}
```

--------------------------------

### Create User

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Create a new user account on the server. Requires user credentials and optional administrative settings.

```APIDOC
## POST /api/users

### Description
Create a new user account.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **username** (string) - Required - Unique username.
- **password** (string) - Required - User password.
- **email** (string) - Optional - User email address.
- **isadmin** (boolean) - Optional - Grant admin privileges. Defaults to false.

### Request Example
```json
{
  "username": "newuser",
  "password": "secure-password",
  "email": "user@example.com",
  "isadmin": false
}
```

### Response
#### Success Response (201)
- (No specific fields documented for success response body)

#### Error Response
- **400** - Invalid parameters
- **409** - User already exists
- **500** - Internal server error
```

--------------------------------

### Get DNS Entries

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Retrieve all DNS entries for a given network. Requires the network name as a path parameter.

```json
[
  {
    "type": "node",
    "name": "server1",
    "address": "10.0.0.10",
    "address6": "fd00::10",
    "network": "network-name"
  }
]
```

--------------------------------

### Test PostgreSQL Database Connection

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/errors.md

Connect to a PostgreSQL database using the `psql` command-line utility.

```bash
# PostgreSQL
psql -h $SQL_HOST -U $SQL_USER -d $SQL_DB
```

--------------------------------

### Get Node Details

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Retrieve details for a specific node within a network. Requires both network and node identifiers.

```json
{
  "id": "uuid",
  "hostid": "uuid",
  "network": "network-name",
  "address": "10.0.0.1/24",
  "address6": "fd00::1/64",
  "connected": true,
  "status": "online",
  "lastcheckin": "2024-01-01T12:00:00Z",
  "expdatetime": null,
  "isegressgateway": false,
  "egressgatewayranges": [],
  "isingressgateway": false,
  "isrelay": false,
  "relayedby": "",
  "isrelayed": false,
  "egressgatewaynatenabled": false,
  "ingressgatewayrange": "",
  "metadata": ""
}
```

--------------------------------

### Create User

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Creates a new user account. The function automatically hashes the password using bcrypt, generates a user ID, and sets the creation timestamp. Requires a unique username, a password of at least 8 characters, and optionally an email.

```Go
func CreateUser(user *schema.User) error
```

--------------------------------

### Apply Netmaker UI Configuration

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Apply the Netmaker UI Kubernetes configuration using kubectl.

```bash
kubectl apply -f netmaker-ui.yaml
```

--------------------------------

### Get details of a specific node

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Retrieves detailed information for a single node identified by its network and node ID.

```APIDOC
## GET /api/nodes/{networkname}/{nodeid}

### Description
Get details of a specific node.

### Method
GET

### Endpoint
/api/nodes/{networkname}/{nodeid}

#### Path Parameters
- **networkname** (string) - Network identifier
- **nodeid** (string) - Node UUID

### Response
#### Success Response (200)
Single node object (see above format).

#### Response Example
{
  "example": "{
    "id": "node-uuid",
    "hostid": "host-uuid",
    "network": "production",
    "address": "10.0.0.1/32",
    "address6": "fd00::1/128",
    "connected": true,
    "status": "online",
    "isegressgateway": false,
    "isingressgateway": false,
    "isrelay": false,
    "lastcheckin": "2024-01-15T10:35:00Z"
  }"
}
```

--------------------------------

### Configure Netmaker UI Subdomain

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Use sed to replace the placeholder for the Netmaker subdomain in the UI configuration file.

```bash
sed -i 's/NETMAKER_SUBDOMAIN/<your subdomain>/g' netmaker-ui.yaml
```

--------------------------------

### Get Specific Network Details

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Retrieves detailed information about a specific network identified by its name. Requires authentication.

```APIDOC
## GET /api/networks/{networkname}

### Description
Get details of a specific network.

### Method
GET

### Endpoint
/api/networks/{networkname}

### Parameters
#### Path Parameters
- **networkname** (string) - Required - Network identifier

### Request Example
None

### Response
#### Success Response (200)
Returns a single network object (see GET /api/networks for format).

**Status Codes:**
- `200` - Success
- `404` - Network not found
- `500` - Server error
```

--------------------------------

### Test SQLite Database Connection

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/errors.md

Connect to an SQLite database file using the `sqlite3` command-line utility.

```bash
# SQLite
sqlite3 ./netmaker.db
```

--------------------------------

### Get server configuration and status

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Retrieves the server's configuration details and current status. This endpoint is publicly accessible.

```APIDOC
## GET /api/server

### Description
Get server configuration and status.

### Method
GET

### Endpoint
/api/server

### Response
#### Success Response (200)
- **version** (string) - The server version.
- **masterpublickey** (string) - The server's public key.
- **messagequeueendpoint** (string) - The endpoint for the message queue.
- **capturedfiles** (array) - List of captured files.

#### Response Example
{
  "version": "v1.6.0",
  "masterpublickey": "server-wg-public-key",
  "messagequeueendpoint": "mqtt-broker:1883",
  "capturedfiles": []
}
```

--------------------------------

### Troubleshoot MQ Connection: Scale Down Netmaker

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Scale down the Netmaker stateful set to zero replicas to prepare for a restart.

```bash
kubectl scale sts netmaker --replicas=0
```

--------------------------------

### Retrieve Network Nodes

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Get all nodes belonging to a specific network. This is used in the network detail view and node listing.

```go
func GetNetworkNodes(ctx context.Context, networkName string) ([]schema.Node, error)
```

--------------------------------

### Apply Netmaker Server Configuration

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Apply the Netmaker server Kubernetes configuration using kubectl.

```bash
kubectl apply -f netmaker-server.yaml
```

--------------------------------

### Create an enrollment key

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Generates a new enrollment key for a specified network. Requires admin authentication.

```APIDOC
## POST /api/enrollmentkeys/{networkname}

### Description
Create an enrollment key.

### Method
POST

### Endpoint
/api/enrollmentkeys/{networkname}

### Parameters
#### Path Parameters
- **networkname** (string) - Network for key

#### Request Body
- **networks** (array) - Required - Network names
- **tags** (array) - Optional - Node tags
- **type** (int) - Required - 1=TimeExp, 2=Uses, 3=Unlimited
- **unlimited** (boolean) - Optional - Unlimited flag
- **uses_remaining** (int) - Optional - For Uses type
- **expiration** (int) - Optional - Unix timestamp
- **default** (boolean) - Optional - Default key
- **auto_egress** (boolean) - Optional - Auto-configure egress
- **auto_assign_gw** (boolean) - Optional - Auto-assign gateway

### Request Example
```json
{
  "networks": ["production", "staging"],
  "tags": ["prod", "auto-config"],
  "type": 1,
  "unlimited": false,
  "uses_remaining": 10,
  "expiration": 1735689599,
  "default": false,
  "auto_egress": true,
  "auto_assign_gw": false
}
```
```

--------------------------------

### Retrieve All Nodes (Deprecated)

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Use this function to get all nodes across all networks. Note that this model is deprecated; prefer schema.Node for new code.

```go
func GetAllNodes() ([]models.Node, error)
```

--------------------------------

### Create Client

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/INDEX.md

Creates a new external client for a specified network. Requires authentication.

```APIDOC
## POST /api/extclients/{net}

### Description
Creates a new external client.

### Method
POST

### Endpoint
/api/extclients/{net}

### Auth
✓
```

--------------------------------

### Publish to MQTT Topic

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/errors.md

Use `mosquitto_pub` to send a test message to a specified MQTT topic.

```bash
mosquitto_pub -h $BROKER_HOST -t "test/topic" -m "test"
```

--------------------------------

### Get DNS Entries

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Retrieve all DNS entries associated with a specific network. This endpoint allows you to view the current DNS configuration for a given network.

```APIDOC
## GET /api/dns/{networkname}

### Description
Retrieve all DNS entries for a network.

### Method
GET

### Endpoint
/api/dns/{networkname}

### Parameters
#### Path Parameters
- **networkname** (string) - Required - Network identifier

### Response
#### Success Response (200)
- **type** (string) - Type of the DNS entry (e.g., "node", "custom")
- **name** (string) - DNS hostname
- **address** (string) - IPv4 address
- **address6** (string) - IPv6 address
- **network** (string) - Network identifier

#### Response Example
```json
[
  {
    "type": "node",
    "name": "server1",
    "address": "10.0.0.10",
    "address6": "fd00::10",
    "network": "network-name"
  }
]
```
```

--------------------------------

### List Enrollment Keys

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Retrieve all enrollment keys for a specific network. Requires the network name as a path parameter.

```json
[
  {
    "value": "enrollment-key-string",
    "networks": ["network-name"],
    "tags": ["auto", "prod"],
    "unlimited": false,
    "type": 1,
    "uses_remaining": 5,
    "expiration": "2024-12-31T23:59:59Z",
    "default": false
  }
]
```

--------------------------------

### API Reference and Endpoints

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/GENERATED.txt

This section details the REST API specifications, including HTTP endpoints, request/response examples, and parameter documentation for the Netmaker project.

```APIDOC
## API Reference and Endpoints

This documentation covers the REST API specifications and HTTP endpoints for Netmaker. It includes detailed information on available operations, request and response formats, and parameter definitions.

### Accessing API Documentation

Refer to `api-reference.md` for complete API documentation and `endpoints.md` for HTTP endpoint specifications.
```

--------------------------------

### Create Enrollment Key

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/INDEX.md

Creates a new enrollment key for a specified network. Requires authentication.

```APIDOC
## POST /api/enrollmentkeys/{net}

### Description
Creates a new enrollment key.

### Method
POST

### Endpoint
/api/enrollmentkeys/{net}

### Auth
✓
```

--------------------------------

### Get User by Username

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Retrieves a single user's details by their username. Returns the user object or an error if the user is not found or a database issue occurs.

```Go
func GetUser(ctx context.Context, username string) (*schema.User, error)
```

--------------------------------

### Configure Netmaker Server API Master Key

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Use sed to replace the placeholder for the Netmaker API master key in the server configuration file.

```bash
sed -i 's/REPLACE_MASTER_KEY/<super secret password>/g' netmaker-server.yaml
```

--------------------------------

### Get Specific ACL Rule

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Fetches a single ACL rule by its unique identifier. Returns the ACL rule or an error if not found or a database issue occurs.

```go
func GetACL(ctx context.Context, aclID string) (*models.Acl, error)
```

--------------------------------

### Create an Enrollment Key

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Generate a new enrollment key with specified properties like network association, tags, expiration, and usage limits. This key is used for new device enrollment.

```json
{
  "networks": ["production", "staging"],
  "tags": ["prod", "auto-config"],
  "type": 1,
  "unlimited": false,
  "uses_remaining": 10,
  "expiration": 1735689599,
  "default": false,
  "auto_egress": true,
  "auto_assign_gw": false
}
```

--------------------------------

### Configure Netmaker Server Database Name

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Use sed to replace the placeholder for the PostgreSQL deployment name in the server configuration file.

```bash
sed -i 's/DB_NAME/<postgres helm name>/g' netmaker-server.yaml
```

--------------------------------

### Manage Zombie Nodes

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Cleans up stale or zombie nodes, specifically hosts that no longer have any active nodes associated with them. This process runs periodically on the master pod in an HA setup.

```go
func ManageZombies(ctx context.Context)
```

--------------------------------

### Create External Client

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Registers a new external client. This function generates WireGuard keys and allocates an IP address if not provided, and creates the client configuration file. Required fields include Network, IngressGatewayID, and PublicKey/PrivateKey.

```go
func CreateExtClient(ctx context.Context, client *models.ExtClient) error
```

--------------------------------

### Configure Netmaker Server Subdomain

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Use sed to replace the placeholder for the Netmaker subdomain in the server configuration file.

```bash
sed -i 's/NETMAKER_SUBDOMAIN/<your subdomain>/g' netmaker-server.yaml
```

--------------------------------

### Create Enrollment Key

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Generate a new enrollment key for node registration. Supports keys with time expiration, limited uses, or unlimited validity.

```go
func CreateEnrollmentKey(ctx context.Context, key *models.EnrollmentKey) (*models.EnrollmentKey, error)
```

--------------------------------

### GET /api/acls/{networkname}

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Retrieves a list of all Access Control List (ACL) rules configured for a specific network. This endpoint is useful for auditing or understanding the current network access policies.

```APIDOC
## GET /api/acls/{networkname}

### Description
List all ACL rules for a network.

### Method
GET

### Endpoint
/api/acls/{networkname}

### Parameters
#### Path Parameters
- **networkname** (string) - Network identifier

### Response
#### Success Response (200)
- **id** (string) - Unique identifier for the ACL rule.
- **network_id** (string) - The ID of the network this ACL belongs to.
- **name** (string) - A descriptive name for the ACL rule.
- **policy_type** (string) - The type of policy (e.g., "user-policy").
- **src_type** (array) - Defines the source of the traffic.
- **dst_type** (array) - Defines the destination of the traffic.
- **protocol** (string) - The network protocol (e.g., "tcp", "udp").
- **type** (string) - The type of rule (e.g., "SSH", "HTTPS").
- **ports** (array) - An array of port numbers allowed.
- **allowed_traffic_direction** (int) - Traffic direction (0 for uni-directional, 1 for bi-directional).
- **enabled** (boolean) - Indicates if the rule is currently active.
- **created_by** (string) - The user who created the rule.
- **created_at** (string) - The timestamp when the rule was created.

#### Response Example
```json
[
  {
    "id": "acl-uuid",
    "network_id": "production",
    "name": "Allow SSH",
    "policy_type": "user-policy",
    "src_type": [
      {"id": "user", "name": "admins", "value": "admin-group"}
    ],
    "dst_type": [
      {"id": "device", "name": "Servers", "value": "server-tag"}
    ],
    "protocol": "tcp",
    "type": "SSH",
    "ports": ["22"],
    "allowed_traffic_direction": 1,
    "enabled": true,
    "created_by": "admin",
    "created_at": "2024-01-15T10:00:00Z"
  }
]
```

#### Error Responses
- **404** - Network not found
- **500** - Server error
```

--------------------------------

### Configure Frontend URL

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/README.md

Set the frontend URL for Netmaker, ensuring HTTPS is used in production environments.

```bash
export FRONTEND_URL="https://dashboard.example.com"
```

--------------------------------

### Mark Stale Nodes Offline

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Periodically marks nodes as offline if they haven't checked in for more than 10 minutes. This function runs on the master pod in an HA setup and may trigger alerts.

```go
func MarkStaleNodesOffline(ctx context.Context)
```

--------------------------------

### CreateExtClient

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Registers a new external client. The system can generate WireGuard keys and allocate an IP address if not provided.

```APIDOC
## CreateExtClient

### Description
Register a new external client. WireGuard keys and IP addresses can be generated/allocated if not provided.

### Method
POST

### Endpoint
/extclients

### Parameters
#### Request Body
- **client** (models.ExtClient) - Required - Client configuration
  - **Network** (string) - Required
  - **IngressGatewayID** (string) - Required
  - **PublicKey** (string) - Optional - Generated if empty
  - **PrivateKey** (string) - Optional - Generated if empty
  - **Address** (string) - Optional - Allocated from gateway range

### Request Example
```json
{
  "Network": "network-id-1",
  "IngressGatewayID": "gateway-id-1",
  "PublicKey": "optional-public-key",
  "PrivateKey": "optional-private-key",
  "Address": "10.0.0.1/24"
}
```

### Response
#### Success Response (201)
- **No Content**

#### Error Response (400, 500)
- **error** - Database error
```

--------------------------------

### Create New Network

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Creates a new network with specified configuration. Requires admin authentication.

```APIDOC
## POST /api/networks

### Description
Create a new network.

### Method
POST

### Endpoint
/api/networks

### Parameters
#### Request Body
- **netid** (string) - Required - 1-32 chars, alphanumeric
- **addressrange** (string) - Required - Valid IPv4 CIDR
- **addressrange6** (string) - Optional - Valid IPv6 CIDR
- **defaultkeepalive** (integer) - Optional - 0-1000 (default: 20)
- **defaultmtu** (integer) - Optional - 1280-65535 (default: 1280)
- **auto_join** (boolean) - Optional - Default: false
- **auto_remove** (boolean) - Optional - Default: false
- **jit_enabled** (boolean) - Optional - Default: false

### Request Example
```json
{
  "netid": "staging",
  "addressrange": "172.16.0.0/12",
  "addressrange6": "fd10::/8",
  "defaultkeepalive": 25,
  "defaultmtu": 1500,
  "auto_join": true,
  "auto_remove": false,
  "jit_enabled": false
}
```

### Response
#### Success Response (201)
Network created successfully.

**Status Codes:**
- `201` - Created
- `400` - Invalid parameters
- `401` - Unauthorized
- `409` - Network already exists
- `500` - Server error
```

--------------------------------

### List Enrollment Keys for a Network

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Retrieve a list of enrollment keys associated with a specific network. This helps in managing device onboarding and access.

```json
[
  {
    "value": "abcd1234efgh5678ijkl9012mnop3456",
    "networks": ["production"],
    "tags": ["prod", "auto"],
    "type": 1,
    "unlimited": false,
    "uses_remaining": 5,
    "expiration": "2024-12-31T23:59:59Z",
    "default": false,
    "auto_egress": false,
    "auto_assign_gw": false
  }
]
```

--------------------------------

### Get All Hosts

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Retrieve a list of all registered hosts in the Netmaker network. This endpoint returns basic host information including ID, name, OS, version, public key, endpoint IP, and associated nodes.

```json
[
  {
    "id": "host-uuid",
    "name": "server1",
    "os": "linux",
    "version": "netclient-version",
    "publickey": "wireguard-public-key",
    "endpointip": "203.0.113.1",
    "nodes": ["node-uuid-1", "node-uuid-2"]
  }
]
```

--------------------------------

### Get Specific External Client

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Retrieves detailed information about a single external client using its network name and client ID. This endpoint is useful for inspecting the configuration and status of a particular remote access client.

```APIDOC
## GET /api/extclients/{networkname}/{clientid}

### Description
Get a specific external client.

### Method
GET

### Endpoint
/api/extclients/{networkname}/{clientid}

### Parameters
#### Path Parameters
- **networkname** (string) - Required - Network identifier
- **clientid** (string) - Required - Client UUID

### Response
#### Success Response (200)
(Response structure is similar to the list endpoint, returning details for a single client)

#### Error Responses
- **404** - Client not found
- **500** - Server error
```

--------------------------------

### List Enrollment Keys

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/INDEX.md

Retrieves a list of enrollment keys for a specified network. Requires authentication.

```APIDOC
## GET /api/enrollmentkeys/{net}

### Description
Lists enrollment keys for a network.

### Method
GET

### Endpoint
/api/enrollmentkeys/{net}

### Auth
✓
```

--------------------------------

### Enable Debug Logging

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/errors.md

Set environment variables to enable trace-level logging and debugging output for Netmaker.

```bash
VERBOSITY=4  # Trace level
DEBUG=true
```

--------------------------------

### Troubleshoot MQ Connection: Wait for Pods to be Down

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Wait command to ensure all Netmaker pods are terminated before scaling back up.

```bash
wait until pods are down
```

--------------------------------

### List All Users (JSON Response)

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

This snippet shows the expected JSON response when listing all users. It includes details like username, email, and administrative privileges.

```json
[
  {
    "username": "admin",
    "email": "admin@example.com",
    "isadmin": true,
    "issuperadmin": true
  }
]
```

--------------------------------

### Validate Netmaker Configuration

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/errors.md

Run the Netmaker CLI with a configuration file to load and validate its settings.

```bash
netmaker -c config.yaml  # Load and validate config
```

--------------------------------

### Create Network

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Create a new network. Requires OAuth authentication.

```APIDOC
## POST /api/networks

### Description
Create a new network.

### Method
POST

### Endpoint
/api/networks

### Parameters
#### Request Body
- **netid** (string) - Required - Network identifier (1-32 characters)
- **addressrange** (string) - Required - IPv4 CIDR (validated as cidrv4)
- **addressrange6** (string) - Optional - IPv6 CIDR (validated as cidrv6)
- **defaultkeepalive** (integer) - Optional - Default WireGuard keepalive in seconds (0-1000) (Default: 20)
- **defaultmtu** (integer) - Optional - Default MTU for network (Default: 1280)
- **auto_join** (boolean) - Optional - Enable automatic node joining (Default: false)
- **auto_remove** (boolean) - Optional - Enable automatic node removal (Default: false)
- **jit_enabled** (boolean) - Optional - Enable Just-In-Time access (Default: false)

### Request Example
```json
{
  "netid": "network-name",
  "addressrange": "10.0.0.0/8",
  "addressrange6": "fd00::/8",
  "defaultkeepalive": 20,
  "defaultmtu": 1280,
  "auto_join": false,
  "auto_remove": false,
  "jit_enabled": false
}
```

### Response
#### Success Response (201)
- **id** (string) - Unique identifier for the created network.
- **netid** (string) - The name of the created network.

#### Response Example
```json
{
  "id": "uuid",
  "netid": "network-name"
}
```

#### Status Codes
- `201` - Created
- `400` - Invalid parameters
- `409` - Network already exists
- `500` - Internal server error
```

--------------------------------

### Create Enrollment Key Response

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Response upon successful creation of an enrollment key. Includes the key value and associated network.

```json
{
  "value": "key-string",
  "networks": ["network-name"],
  "token": "base64-encoded-token"
}
```

--------------------------------

### Create a new user

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/endpoints.md

Creates a new user in the system. Requires administrator or owner authentication.

```APIDOC
## POST /api/users

### Description
Create a new user.

### Method
POST

### Endpoint
/api/users

### Parameters
#### Request Body
- **username** (string) - Required - 3-32 chars, unique
- **password** (string) - Required - Minimum 8 chars
- **email** (string) - Optional - Valid email format
- **isadmin** (boolean) - Optional - Default: false

### Request Example
{
  "username": "newuser",
  "password": "secure-password-123",
  "email": "user@example.com",
  "isadmin": false
}

### Response
#### Success Response (201)
- The newly created user object.

#### Error Response
- **400** - Invalid parameters
- **401** - Unauthorized
- **409** - User exists
- **500** - Server error
```

--------------------------------

### Enrollment Key Not Found Error

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/errors.md

Indicates that the provided enrollment key value does not exist. Check the key value or generate a new one.

```json
{
  "code": 404,
  "message": "Enrollment key not found",
  "response": null
}
```

--------------------------------

### CreateUser

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Creates a new user account with provided credentials. The password will be securely hashed using bcrypt.

```APIDOC
## CreateUser

### Description
Create a new user account. Validates username, password, and email. Hashes password with bcrypt and generates a user ID.

### Method
Not applicable (Go function)

### Parameters
#### Function Parameters
- **user** (*schema.User) - Required - User object with credentials

### Request Example
```go
// Example usage requires a schema.User object
// user := &schema.User{Username: "testuser", Password: "password123", Email: "test@example.com"}
// err := CreateUser(user)
```

### Response
#### Success Response
No explicit return value on success, nil error.

#### Error Response
- `error` - Validation or database error
```

--------------------------------

### Configure PostgreSQL Connection Pooling

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/configuration.md

Optimize database performance by configuring connection pooling for PostgreSQL. Set the maximum number of open and idle connections.

```bash
SQL_MAX_OPEN_CONNS=25
SQL_MAX_IDLE_CONNS=5
```

--------------------------------

### Create External Client

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/api-reference.md

Creates a new external client, establishing a remote access point to a specified network. Configuration for the gateway and allowed IP ranges can be provided.

```APIDOC
## POST /api/extclients/{networkname}

### Description
Create a new remote access client.

### Method
POST

### Endpoint
/api/extclients/{networkname}

### Parameters
#### Path Parameters
- **networkname** (string) - Required - Network identifier

#### Request Body
- **ingressgatewayid** (string) - Required - ID of the ingress gateway node
- **extraallowedips** (array of strings) - Optional - Additional IP ranges client can access
- **enabled** (boolean) - Optional - Enable/disable client access (defaults to true)
- **dns** (string) - Optional - DNS server for the client

### Request Example
```json
{
  "ingressgatewayid": "node-uuid",
  "extraallowedips": ["192.168.0.0/16"],
  "enabled": true,
  "dns": "10.0.0.1"
}
```

### Response
#### Success Response (201)
- **clientid** (string) - The unique identifier for the newly created client.
- **publickey** (string) - The public key for the client's WireGuard configuration.
- **privatekey** (string) - The private key for the client's WireGuard configuration (should be kept secure).
- **address** (string) - The IP address assigned to the client within the network.
- **network** (string) - The name of the network the client is associated with.
- **ingressgatewayendpoint** (string) - The endpoint (IP:port) of the ingress gateway node.

#### Response Example
```json
{
  "clientid": "client-uuid",
  "publickey": "public-key",
  "privatekey": "private-key",
  "address": "10.0.0.100/32",
  "network": "network-name",
  "ingressgatewayendpoint": "203.0.113.1:51821"
}
```
```

--------------------------------

### Retrieve All External Clients

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Fetches all remote access clients across all networks. This operation can be expensive on large deployments.

```go
func GetAllExtClients() ([]models.ExtClient, error)
```

--------------------------------

### Create DNS Entry

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/logic-module.md

Adds a DNS entry to a network. Supports both auto-created node entries and user-created custom entries. Requires a valid hostname, IP address, and an existing network.

```Go
func CreateDNSEntry(ctx context.Context, entry *models.DNSEntry) error
```

--------------------------------

### Configure Netmaker Server Database Password

Source: https://github.com/gravitl/netmaker/blob/develop/k8s/server/README.md

Use sed to replace the placeholder for the PostgreSQL password in the server configuration file.

```bash
sed -i 's/DB_PASS/<postgres helm password>/g' netmaker-server.yaml
```

--------------------------------

### RQLite Database Configuration

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/configuration.md

Configure Netmaker to use RQLite. This is recommended for distributed and edge deployments. Connection details can be provided via environment variables.

```bash
DATABASE=rqlite
SQL_HOST=rqlite-server
SQL_PORT=4001
```

--------------------------------

### Create User

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/INDEX.md

Creates a new user within the Netmaker system. Requires authentication.

```APIDOC
## POST /api/users

### Description
Creates a new user.

### Method
POST

### Endpoint
/api/users

### Auth
✓
```

--------------------------------

### Configure Database Connection Pool

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/README.md

Tune the database connection pool settings to manage the number of open and idle connections, optimizing performance.

```bash
export SQL_MAX_OPEN_CONNS=25
export SQL_MAX_IDLE_CONNS=5
```

--------------------------------

### Create Network

Source: https://github.com/gravitl/netmaker/blob/develop/_autodocs/INDEX.md

Creates a new network within the Netmaker system. Requires authentication.

```APIDOC
## POST /api/networks

### Description
Creates a new network.

### Method
POST

### Endpoint
/api/networks

### Auth
✓
```