ns8-dnsmasq

This module allows to configure a dnsmasq instance, it offers DHCP and DNS services for the node.

Install

Install the module with:

add-module ghcr.io/nethserver/dnsmasq:latest

API Docs

The module provides the following API endpoints:

• get-available-interfaces: Get the available interfaces for the node
• configure-module: Configure the module
• get-configuration: Get the module configuration active
• get-dns-records: Get all the manual DNS records
• set-dns-records: Set the DNS records
• get-leases: Get the DHCP leases active

get-available-interfaces

Lists the interfaces that can be used by the module to provide DHCP and DNS services.

Example Request

api-cli run module/<module-id>/get-available-interfaces

Example Response

{
    "data": [
        {
            "name": "enp1s0",
            "network": "192.168.122.0/24"
        }
    ]
}

configure-module

Configures the module with the given parameters, it will then start the dnsmasq service.

Data Structure

{
    "interface": "enp0s3",
    "dhcp-server": {
        "end": "10.0.0.100",
        "enabled": true,
        "lease": 10,
        "start": "10.0.0.20"
    },
    "dns-server": {
        "enabled": true,
        "primary-server": "1.1.1.1",
        "secondary-server": ""
    }
}

• interface: The interface to use for the DHCP and DNS services, use the get-available-interfaces endpoint to get the available interfaces.
• dhcp-server: The DHCP server configuration
  • enabled: Enable or disable the DHCP server
  • start: The start of the DHCP range
  • end: The end of the DHCP range
  • lease: The lease time in hours
• dns-server: The DNS server configuration
  • enabled: Enable or disable the DNS server
  • primary-server: The primary DNS server to use, can be IPv4 or IPv6
  • secondary-server: The secondary DNS server to use, can be IPv4 or IPv6 or empty

Example Request

api-cli run module/<module-id>/configure-module --data '<json>'

get-configuration

Get the current configuration of the module, the response is the same as the configure-module request to keep consistency.

Example Request

api-cli run module/<module-id>/get-configuration

set-dns-records

Set the DNS records that the module needs to resolve without querying the upstream DNS servers.

Data Structure

{
    "records": [
        {
            "domain": "example.com",
            "address": "145.34.56.2"
        },
        {
            "domain": "www.example.com",
            "address": "234.67.22.111"
        }
    ]
}

• records: The list of DNS records to set
  • domain: The domain to resolve
  • address: The IP address to resolve the domain to, can be an IPv4 or IPv6 address

Example Request

api-cli run module/<module-id>/set-dns-records --data '<json>'

get-dns-record

Get the DNS records saved in the module. Returns the same structure as the set-dns-records request.

Example Request

api-cli run module/<module-id>/get-dns-records

get-leases

Get the active DHCP leases, with the IP address, MAC address, hostname and expiration time.

Example Request

api-cli run module/<module-id>/get-leases

Example Response

{
    "data": [
        {
            "ip": "10.0.1.20",
            "mac": "00:11:22:33:44:55",
            "hostname": "host1",
            "expires": "2021-12-12T12:12:12+00:00"
        }
    ]
}

Restore public interfaces

When installing the module from the version 1.2.0 and above, the module will hide the interfaces that have public IP addresses from the picker in the configuration. This is done to avoid the user to select an interface that is not meant to be used for DHCP and local DNS services. The list of the possibles IPs that are marked as global is taken from the IANA specs used by Python ipaddress module.

To restore the old behavior and show all the interfaces in the picker, you can either remove the DNSMASQ_STRICT_INTERFACE_VALIDATION environment variable from the module environment or set it to 0.

Uninstall

To uninstall the instance:

remove-module --no-preserve <module_instance>

Running tests locally

This module uses the NS8 standard testing infrastructure. For instructions on how to run the test suite locally, refer to the Running tests locally section of the ns8-github-actions repository.