Skip to content

DNS Record Management

Jump to bottom
Sunil Purushottam Thakare edited this page May 9, 2025 · 1 revision

DNS Record Management

This page explains how to manage DNS records with nx9-dns-server.

Database Schema

DNS records are stored in an SQLite database with the following schema:

CREATE TABLE IF NOT EXISTS dns_records (
  domain TEXT NOT NULL,
  record_type TEXT NOT NULL,
  value TEXT NOT NULL,
  ttl INTEGER DEFAULT 3600,
  PRIMARY KEY (domain, record_type, value)
) WITHOUT ROWID;

The schema is designed for simplicity and performance:

  • domain: The DNS domain name (e.g., example.com, www.example.com)
  • record_type: The DNS record type (e.g., A, AAAA, MX, NS, SOA, TXT, CNAME)
  • value: The record's value, format depends on record type
  • ttl: Time to Live in seconds

Supported Record Types

nx9-dns-server supports the following DNS record types:

Record Type Description Example Value
A IPv4 Address 203.0.113.10
AAAA IPv6 Address 2001:db8::1
MX Mail Exchange 10 mail.example.com
NS Name Server ns1.example.com
SOA Start of Authority ns1.example.com hostmaster.example.com 1 10800 3600 604800 86400
TXT Text Record "v=spf1 a mx ~all"
CNAME Canonical Name example.com
PTR Pointer example.com

Managing Records Manually

Adding Records

To add DNS records manually to the database:

INSERT OR REPLACE INTO dns_records VALUES
('example.com', 'A', '203.0.113.10', 3600),
('example.com', 'MX', '10 mail.example.com', 3600),
('example.com', 'NS', 'ns1.example.com', 3600),
('example.com', 'NS', 'ns2.example.com', 3600),
('example.com', 'SOA', 'ns1.example.com hostmaster.example.com 1 10800 3600 604800 86400', 3600),
('example.com', 'TXT', '"v=spf1 a mx ~all"', 3600),
('www.example.com', 'A', '203.0.113.10', 3600);

You can use any SQLite client to manage the database:

sqlite3 /path/to/dns.db

Querying Records

To view existing records:

-- View all records
SELECT * FROM dns_records;

-- View records for a specific domain
SELECT * FROM dns_records WHERE domain = 'example.com';


-- View records of a specific type
SELECT * FROM dns_records WHERE record_type = 'A';

Updating Records

To update an existing record, use the INSERT OR REPLACE statement:

INSERT OR REPLACE INTO dns_records VALUES
('www.example.com', 'A', '203.0.113.11', 3600);

Deleting Records

To delete records:

-- Delete a specific record
DELETE FROM dns_records 
WHERE domain = 'www.example.com' 
AND record_type = 'A' 
AND value = '203.0.113.10';

-- Delete all records for a domain
DELETE FROM dns_records WHERE domain = 'subdomain.example.com';


-- Delete all records of a specific type
DELETE FROM dns_records WHERE record_type = 'TXT';

Special Record Types

SOA Records

Every zone requires an SOA (Start of Authority) record. The format is:

primary_nameserver admin_email serial refresh retry expire minimum_ttl

Example:

INSERT INTO dns_records VALUES
('example.com', 'SOA', 'ns1.example.com hostmaster.example.com 2023051001 10800 3600 604800 86400', 86400);

Components:

  • primary_nameserver: Primary name server for the zone
  • admin_email: Email address of the zone administrator (with @ replaced by .)
  • serial: Version number, typically in format YYYYMMDDNN
  • refresh: Time in seconds that secondary servers should wait before refreshing
  • retry: Time in seconds to wait after a failed refresh
  • expire: Time in seconds that a secondary server should keep serving the zone after refresh failures
  • minimum_ttl: Minimum TTL for negative responses

NS Records

NS records specify the authoritative name servers for a zone:

INSERT INTO dns_records VALUES
('example.com', 'NS', 'ns1.example.com', 86400),
('example.com', 'NS', 'ns2.example.com', 86400);

MX Records

MX records specify mail servers:

INSERT INTO dns_records VALUES
('example.com', 'MX', '10 mail.example.com', 3600),
('example.com', 'MX', '20 backup-mail.example.com', 3600);

The numeric prefix indicates priority (lower values are higher priority).

Updating SOA Serial

When making changes to DNS records, it's important to update the SOA serial number to indicate a zone change. The soa-update.sh script provided with nx9-dns-server can be used for this purpose:

sudo -u dnsuser /var/nx9-dns-server/soa-update.sh

This script automatically increments the SOA serial number in the database.

Web UI Management (Coming Soon)

A web-based interface for DNS record management is under development. This interface will provide:

  • User-friendly record creation and editing
  • Bulk record operations
  • Record validation
  • Automatic SOA serial updates
  • Change history logging

API Management (Coming Soon)

A RESTful API for programmatic record management is also under development. See the API Reference page for more details when available.

Verifying DNS Records

After adding or modifying records, you can verify them using the provided diagnostic script:

bash scripts/dnscheck.sh

Or manually using dig:

# Check A record
dig @localhost example.com A

Check MX records


dig @localhost example.com MX


Check all records


dig @localhost example.com ANY

Best Practices

  1. Always update the SOA serial after making changes
  2. Use consistent TTLs appropriate for your needs:
    • Lower TTLs (300-900s): For records that change frequently
    • Medium TTLs (3600s): For standard records
    • Higher TTLs (86400s): For stable records like NS
  3. Include both forward and reverse records when appropriate
  4. Keep a backup of your DNS database
  5. Test changes in a staging environment before production
# DNS Record Management

This page explains how to manage DNS records with nx9-dns-server.

Database Schema

DNS records are stored in an SQLite database with the following schema:

CREATE TABLE IF NOT EXISTS dns_records (
  domain TEXT NOT NULL,
  record_type TEXT NOT NULL,
  value TEXT NOT NULL,
  ttl INTEGER DEFAULT 3600,
  PRIMARY KEY (domain, record_type, value)
) WITHOUT ROWID;

The schema is designed for simplicity and performance:

  • domain: The DNS domain name (e.g., example.com, www.example.com)
  • record_type: The DNS record type (e.g., A, AAAA, MX, NS, SOA, TXT, CNAME)
  • value: The record's value, format depends on record type
  • ttl: Time to Live in seconds

Supported Record Types

nx9-dns-server supports the following DNS record types:

Record Type Description Example Value
A IPv4 Address 203.0.113.10
AAAA IPv6 Address 2001:db8::1
MX Mail Exchange 10 mail.example.com
NS Name Server ns1.example.com
SOA Start of Authority ns1.example.com hostmaster.example.com 1 10800 3600 604800 86400
TXT Text Record "v=spf1 a mx ~all"
CNAME Canonical Name example.com
PTR Pointer example.com

Managing Records Manually

Adding Records

To add DNS records manually to the database:

INSERT OR REPLACE INTO dns_records VALUES
('example.com', 'A', '203.0.113.10', 3600),
('example.com', 'MX', '10 mail.example.com', 3600),
('example.com', 'NS', 'ns1.example.com', 3600),
('example.com', 'NS', 'ns2.example.com', 3600),
('example.com', 'SOA', 'ns1.example.com hostmaster.example.com 1 10800 3600 604800 86400', 3600),
('example.com', 'TXT', '"v=spf1 a mx ~all"', 3600),
('www.example.com', 'A', '203.0.113.10', 3600);

You can use any SQLite client to manage the database:

sqlite3 /path/to/dns.db

Querying Records

To view existing records:

-- View all records
SELECT * FROM dns_records;

-- View records for a specific domain
SELECT * FROM dns_records WHERE domain = 'example.com';

-- View records of a specific type
SELECT * FROM dns_records WHERE record_type = 'A';

Updating Records

To update an existing record, use the INSERT OR REPLACE statement:

INSERT OR REPLACE INTO dns_records VALUES
('www.example.com', 'A', '203.0.113.11', 3600);

Deleting Records

To delete records:

-- Delete a specific record
DELETE FROM dns_records 
WHERE domain = 'www.example.com' 
AND record_type = 'A' 
AND value = '203.0.113.10';

-- Delete all records for a domain
DELETE FROM dns_records WHERE domain = 'subdomain.example.com';

-- Delete all records of a specific type
DELETE FROM dns_records WHERE record_type = 'TXT';

Special Record Types

SOA Records

Every zone requires an SOA (Start of Authority) record. The format is:

primary_nameserver admin_email serial refresh retry expire minimum_ttl

Example:

INSERT INTO dns_records VALUES
('example.com', 'SOA', 'ns1.example.com hostmaster.example.com 2023051001 10800 3600 604800 86400', 86400);

Components:

  • primary_nameserver: Primary name server for the zone
  • admin_email: Email address of the zone administrator (with @ replaced by .)
  • serial: Version number, typically in format YYYYMMDDNN
  • refresh: Time in seconds that secondary servers should wait before refreshing
  • retry: Time in seconds to wait after a failed refresh
  • expire: Time in seconds that a secondary server should keep serving the zone after refresh failures
  • minimum_ttl: Minimum TTL for negative responses

NS Records

NS records specify the authoritative name servers for a zone:

INSERT INTO dns_records VALUES
('example.com', 'NS', 'ns1.example.com', 86400),
('example.com', 'NS', 'ns2.example.com', 86400);

MX Records

MX records specify mail servers:

INSERT INTO dns_records VALUES
('example.com', 'MX', '10 mail.example.com', 3600),
('example.com', 'MX', '20 backup-mail.example.com', 3600);

The numeric prefix indicates priority (lower values are higher priority).

Updating SOA Serial

When making changes to DNS records, it's important to update the SOA serial number to indicate a zone change. The soa-update.sh script provided with nx9-dns-server can be used for this purpose:

sudo -u dnsuser /var/nx9-dns-server/soa-update.sh

This script automatically increments the SOA serial number in the database.

Web UI Management (Coming Soon)

A web-based interface for DNS record management is under development. This interface will provide:

  • User-friendly record creation and editing
  • Bulk record operations
  • Record validation
  • Automatic SOA serial updates
  • Change history logging

API Management (Coming Soon)

A RESTful API for programmatic record management is also under development. See the [API Reference] page for more details when available.

Verifying DNS Records

After adding or modifying records, you can verify them using the provided diagnostic script:

bash scripts/dnscheck.sh

Or manually using dig:

# Check A record
dig @localhost example.com A

# Check MX records
dig @localhost example.com MX

# Check all records
dig @localhost example.com ANY

Best Practices

  1. Always update the SOA serial after making changes
  2. Use consistent TTLs appropriate for your needs:
    • Lower TTLs (300-900s): For records that change frequently
    • Medium TTLs (3600s): For standard records
    • Higher TTLs (86400s): For stable records like NS
  3. Include both forward and reverse records when appropriate
  4. Keep a backup of your DNS database
  5. Test changes in a staging environment before production

Clone this wiki locally