icydns/README.md

IcyDNS HTTP API

HTTP API for managing BIND zone files.

Running

This application is intended to be run behind a proxy. Requires node v14+ for fs/promises. Also requires bind-tools for checking zone files.

• npm install
• npm run build
• npm start

Environment variables

• PORT - server port
• ZONEFILES - path to zone files
• CACHE_TTL - internal zone cache time-to-live
• RNDC_SERVER - RNDC host
• RNDC_PORT - RNDC port
• RNDC_KEYFILE - location of RNDC's key file

Zones are automatically reloaded using rndc after updates. If you do not have rndc configured, you will need to reload the zones manually, but the files still get updated.

API

All requests are prefixed with /api/v1. Authorization is by bearer token, i.e. -H 'Authorization: Bearer <token>'. ? denotes optional parameter.

GET /zone/:domain

Returns all of :domain's DNS records.

Query: None

Response:

{
  ttl: number;
  records: [
    [index]: {
      name: string;
      type: string;
      value: string;
    }
  ]
}

GET /zone/:domain/download

Provides :domain's records as a file.

Query: None

Response: BIND zone file

POST /zone/:domain

Reloads :domain's zone file. Optionally changes the zone file's TTL value.

Body:

{
  ttl?: number;
}

Response:

{
  success: boolean;
  message: string;
  ttl?: number;
}

GET /zone/records/:domain

Returns all of :domain's DNS records or performs a search based on provided query parameters.

Query:

• name?
• type?
• value?

Response:

[
  [index]: {
    name: string;
    type: string;
    value: string;
    index?: number; // when searching only
  }
]

POST /zone/records/:domain

Updates a single or multiple DNS records of :domain at index.

Body:

{
  record: {
    index: number;
    name?: string;
    type?: string;
    value?: string;
  } | {...}[];
}

Response:

{
  success: boolean;
  message: string;
  changed: DNSRecord[];
  errors: {
    message: string;
    record: DNSRecord;
  }[];
}

PUT /zone/records/:domain

Creates a single or multiple new DNS records for :domain.

Body:

{
  record: {
    name: string;
    type: string;
    value: string;
  } | {...}[];
}

Response:

{
  success: boolean;
  message: string;
  created: ({ index: number, ...DNSRecord })[];
  errors: {
    message: string;
    record: DNSRecord;
  }[];
}

DELETE /zone/records/:domain

Deletes a DNS record from :domain at index. Warning: Deleting an index that is not at the end of the record causes following records' indexes to shift back by one.

Body:

{
  index: number;
}

Response:

{
  success: boolean;
  message: string;
  record: DNSRecord;
}

POST /set-ip/:domain

Quickly updates the :domain's IP address (first occurences of A and AAAA records of @ or subdomain). One of the IP addresses is taken from the request, so it's a good idea to use curl with -4 to automatically set the IPv4 address and provide the IPv6 address with a body parameter.

Body:

{
  ipv4?: string;
  ipv6?: string;
  subdomain?: string;
  dualRequest?: boolean;
}

Response:

{
  success: boolean;
  message: string;
  actions: string[]; // detailed descriptions of what was actually done
}