DOCSEARCHbyAlgolia
Submit Docs

MaraDNS Documentation

repository·master·Indexed 20 days ago

https://github.com/samboy/maradns

A small, lightweight, and secure open-source DNS server implementation designed for POSIX and Windows. It features coLunacyDNS, which allows server control and query processing via a Lua 5.1 configuration file, including a custom coDNS library for upstream DNS lookups, logging, and restricted file I/O. The project also includes the blockhash tool for creating compact binary databases for high-speed domain blacklist lookups.

Tokens
106.2K
Snippets
378
Records
573
Agent score
64%

What's inside MaraDNS

  1. Understand the MaraDNS update and release history

    master

    MaraDNS uses two different release methodologies depending on the version branch:

    • 3.4 Legacy Branch: Updates are managed via a shell script that applies a series of patches to the code. This branch is primarily used for security and critical fixes.
    • Modern Releases (Post-2020): Stable releases are made directly from Git.

    If you are looking for the history of changes associated with the legacy system, they are contained within this directory. For corresponding changes in the Deadwood project, refer to the deadwood-{version}/update folder.

  2. Overview of MaraDNS components

    master

    MaraDNS 3.5 is a suite of DNS tools composed of several distinct daemons and utilities, each serving a specific role in the DNS ecosystem:

    • maradns: The authoritative DNS server. It is UDP-only and used for hosting your own domains and providing information to the rest of the internet.
    • Deadwood: The recursive DNS server. It is used to find domains on the internet for web browsers and other clients. It is lightweight and suitable for embedded systems.
    • coLunacyDNS: A Lua-powered DNS server. It uses C for high-performance socket handling and Lua for flexible query logic. It can return A (IPv4) and AAAA (IPv6) records and customize responses via Lua scripts.
    • zoneserver: A separate DNS-over-TCP server. Since the main maradns daemon is UDP-only, zoneserver provides support for standard DNS-over-TCP and DNS zone transfers.
    • Duende: A daemonization utility. Neither maradns nor the UNIX version of Deadwood support daemonization natively; Duende is used to run them as background processes.
    • askmara: A simple DNS querying tool.

    Platform Support:

    • maradns is a native UNIX program (can run on Windows via Cygwin).
    • Deadwood and coLunacyDNS are cross-platform with full Windows ports.

  3. What is blockhash?

    master
    The blockhash tool generates a compact database from a list of binary strings and associated hashing. This format allows for high-speed lookups to determine if a specific binary string exists within a large list. It is specifically designed for 'naughty lists' (domain blacklists) to minimize memory usage. For example, a list of 200,000 domains that would normally require ~200 MB of memory in Deadwood can be reduced to less than 8 MB using this compact format.

  4. Understand Deadwood security and entropy

    master

    Deadwood uses a strong pseudo-random number generator (32-bit RadioGatun) for query IDs and source ports.

    Entropy Requirements:

    • Linux/POSIX: Deadwood uses /dev/urandom by default. It is critical that your system has a working /dev/urandom to prevent forged DNS packets.
    • Windows: Use the included mkSecretTxt.exe to create a 64-byte random file named secret.txt. This file can then be used via the random_seed_file parameter.
    • Hashing Security: To protect against DoS attacks, Deadwood uses a random 31-bit prime for cache hashing. This prime is generated by RandomPrime.c and stored in DwRandPrime.h during compilation or when make clean is run.

  5. How MD and MF records are handled

    master

    MD and MF records are obsolete types replaced by MX records. While some servers (like BIND) reject them, MaraDNS automatically converts them into MX records.

    An MD record is converted to an MX record with priority 0. An MF record is converted to an MX record with priority 10.

    # Input
example.net. MD a.example.net. ~
example.net. MF b.example.net. ~

# Equivalent Output
example.net. MX 0 a.example.net. ~
example.net. MX 10 b.example.net. ~

  6. Deadwood configuration file format and parameter types

    master

    The Deadwood configuration file (dwood3rc) is modeled after Python 2 syntax, though it is more flexible (e.g., leading whitespace is allowed). There are three parameter types you must follow strictly:

    1. Numeric parameters: Must not be surrounded by quotes.

      filter_rfc1918 = 0

      Note: Using quotes for numeric values will trigger an "Unknown dwood3rc string parameter" error.

    2. String parameters: Must be surrounded by quotes.

      bind_address = "127.0.0.1"

    3. Dictionary parameters: Must be initialized before use, and both the index and the value must be surrounded by quotes.

      upstream_servers = {}
upstream_servers["."] = "8.8.8.8, 8.8.4.4"
    filter_rfc1918 = 0
bind_address = "127.0.0.1"
upstream_servers = {}
upstream_servers["."] = "8.8.8.8, 8.8.4.4"

  7. Format CSV2 zone files

    master

    The csv2 format is a flexible zone file format used by MaraDNS. Key features include:

    • SOA Records: Not strictly required, but if provided, they must be the first record in the zone.
    • NS Records: If not provided, MaraDNS synthesizes them based on the IP addresses the server is bound to (prioritizing public IPs).
    • Compact A Records: IPv4 addresses can be written directly after the name.
    • Load Balancing: Providing multiple IPs for a single name allows MaraDNS to rotate them for clients.
    • Percent Shortcut (%): Using % indicates the name should terminate with the current zone's name.
    • TTL: Specify a TTL by prefixing it with a + (e.g., +86400).
    • Multi-line Records: Records can span multiple lines.
    • Comments: Use # for comments. In multi-line records, a backslash \ before whitespace allows the record to continue and permits comments mid-record.
    • Pseudo-RR IN: Using IN tells MaraDNS to ignore the current type and look at the next one, making it compatible with BIND-style syntax.
    ## Example csv2 zone file

a.example.net. 10.10.10.10 ~
b.example.net. 10.10.10.11 ~
b.example.net. 10.10.10.12 ~

percent.% a 10.9.8.7 ~

d.example.net. +86400 A 10.11.12.13 ~

c.example.net. # Our C class machine
        +86400  # This record is stored for one day
        A       # A record
        10.1.1.1 
        ~               # End of record

% mx 10 mail.% ~
mail.% +86400 IN A 10.22.23.24 ~

  8. Understand the difference between authoritative and recursive DNS in MaraDNS

    master

    MaraDNS splits DNS responsibilities between two distinct components:

    1. Authoritative DNS: Handled by the maradns daemon. It processes queries for the specific zones it is configured to serve.
    2. Recursive DNS: Handled by the Deadwood daemon. It resolves domain names by contacting other DNS servers (the type of server you typically point to in /etc/resolv.conf).

    Additionally, the zoneserver program can be used to serve zones so that other DNS servers can act as secondaries.

  9. Configure SOA and NS records in csv2

    master

    In csv2 zone files:

    • SOA (Start of Authority): An SOA record is not strictly required. If provided, it must be the first record in the zone. MaraDNS will use it as the SOA record for the zone.
    • NS (Name Server): Authoritative NS records are not required. If they are missing, MaraDNS will automatically synthesize them based on the IP addresses the service is bound to. It intelligently selects public IPs over private IPs for synthesis.

  10. Understand the mararc configuration file format

    master

    MaraDNS uses mararc files for configuration. The syntax is a subset of Python 2.2.3. A properly formatted mararc file can be read by Python 2.2.3 without error.

    Syntax Rules

    • Comments: Start with # and continue to the end of the line.
    • Whitespace: Lines containing only whitespace are ignored.
    • Assignment (=): Used to assign numeric or string values to a variable.
    • Concatenation (+=): Used exclusively with string values to append a new value to the existing string.

    Variable Types

    1. Normal Variables: Single-value variables assigned using name = "value".
    2. Dictionary Variables: Associative arrays (similar to Python dicts or Perl hashes) indexed by strings. They must be initialized with an empty dictionary {} before use. Syntax: name["index"] = "value".
    # Example of assignment and concatenation
ipv4_bind_addresses = "10.2.19.83"
ipv4_bind_addresses += ",10.2.66.74"

# Example of dictionary initialization and usage
csv2 = {}
csv2["example.net."] = "db.example.net"

  11. Use csv2_default_zonefile for trailing star hostnames

    master

    The csv2_default_zonefile is a specialized zone file type that supports stars at the end of hostnames. It has the following constraints:

    • Allowed: Stars at the end of hostnames.
    • Mandatory: A SOA record and NS records.
    • Prohibited: CNAME, FQDN4, FQDN6, and delegation NS records.
    • Restrictions: These files cannot be transferred via zone transfer, and you cannot enable both recursion and default zonefiles simultaneously.

  12. Configure star (wildcard) records in zones

    master

    MaraDNS supports wildcard records at both the beginning and end of names.

    • Prefix wildcards: To map *.example.com. to an IP, add *.example.com. A 10.1.2.3 to your zone file.
    • Suffix wildcards: To support stars at the end of records, you must set csv2_default_zonefile in your configuration.

    Behavior for star records can be further tuned using the bind_star_handling parameter in your mararc file.

    *.example.com. A 10.1.2.3