gomiabdns

README

Go-MIABDNS

Mail-In-A-Box custom DNS API client for go.

CLI tool

go install github.com/luv2code/go-miabdns/cmd/miabdns@latest

# get a list of all domains defined:
miabdns -email $MIAB_USER -password $MIAB_PASS -url "https://your-box/admin" -command list -totp $TOTP_SECRET

The totp secret has to be provided if you've enabled multi factor authentication

# update CNAME with the IP of current machine (will add if it doesn't exist):
miabdns \
    -email $MIAB_USER \
    -password $MIAB_PASS \
    -url "https://your-box/admin" 
    -command update \
    -rname "dyndns.your-box" \
    -rtype "A" \
    -rvalue "$(wget -qO- ipinfo.io/ip)" # also with curl: $(curl -s ipinfo.io/ip)

# add a new record to CNAME to the dyndns record set above
miabdns \
    -email $MIAB_USER \
    -password $MIAB_PASS \
    -url "https://your-box/admin" 
    -command add \
    -rname "some-other-name.your-box" \
    -rtype "CNAME" \
    -rvalue "dyndns.your-box"

# delete a record.
miabdns \
    -email $MIAB_USER \
    -password $MIAB_PASS \
    -url "https://your-box/admin" 
    -command delete \
    -rname "some-other-name.your-box" \
    -rtype "CNAME"

TOTP Secret

The TOTP Secret can be obtained from the Mail-in-a-Box users database like so:

$ sqlite3 /home/user-data/mail/users.sqlite
sqlite> select id,secret from mfa;

This will output the user id, together with the TOTP secret: 1|<TOTP_SECRET> To obtain the id, you can look at the users table:

sqlite> select id,email from users;

Using as a Library

This project was created for use in github.com/libdns in order to create a dns provider for caddy server.

You can find the libdns project here, and the caddy dns provider here

Documentation

Overview

Package gomiabdns provides a interface for the Mail-In-A-Box dns API

Index

• type APIStatus
• type Client
  • func New(apiUrl, email, password string, totp_secret string) *Client
  • func (c *Client) AddHost(ctx context.Context, name string, recordType RecordType, value string) error
  • func (c *Client) DeleteHost(ctx context.Context, name string, recordType RecordType, value string) error
  • func (c *Client) GetHosts(ctx context.Context, name string, recordType RecordType) ([]DNSRecord, error)
  • func (c *Client) GetZonefile(ctx context.Context, zone string) (string, error)
  • func (c *Client) GetZones(ctx context.Context) ([]DNSZone, error)
  • func (c *Client) UpdateHost(ctx context.Context, name string, recordType RecordType, value string) error
• type DNSRecord
• type DNSZone
• type RecordType

Types

type APIStatus

type APIStatus struct {
	Status string `json:"status"`
	Reason string `json:"reason"`
}

Represents status returned from the API

type Client

type Client struct {
	ApiUrl *url.URL
	// contains filtered or unexported fields
}

Client provides a target for methods interacting with the DNS API.

func New

func New(apiUrl, email, password string, totp_secret string) *Client

New returns a new client ready to call the provided endpoint.

func (*Client) AddHost

func (c *Client) AddHost(ctx context.Context, name string, recordType RecordType, value string) error

AddHost adds a record. name, recordType, and value are all required. If a record exists with the same value, no new record is created. Use this method for creating multple A records for dns loadbalancing. Or use it to create multiple different TXT records.

func (*Client) DeleteHost

func (c *Client) DeleteHost(ctx context.Context, name string, recordType RecordType, value string) error

DeleteHost will delete records that match the passed paramters.

func (*Client) GetHosts

func (c *Client) GetHosts(ctx context.Context, name string, recordType RecordType) ([]DNSRecord, error)

GetHosts returns all defined records if name and recordType are both empty string. If values are provided for both name and recordType, only the records that match both are returned. If one or the other of name and recordType are empty string, no records are returned.

func (*Client) GetZonefile

func (c *Client) GetZonefile(ctx context.Context, zone string) (string, error)

GetZonefile returns the zonefile for the indicate zone

func (*Client) GetZones

func (c *Client) GetZones(ctx context.Context) ([]DNSZone, error)

GetZones returns all zones that the MiaB box is responsible for.

func (*Client) UpdateHost

func (c *Client) UpdateHost(ctx context.Context, name string, recordType RecordType, value string) error

UpdateHost will create or update a record that corresponds with the name and recordType. If multiple records with the same name and type exists, they will all be removed and replaced with a single one that matches the parameters passed to this method. name, recordType, and value are all required.

type DNSRecord

type DNSRecord struct {
	QualifiedName string     `json:"qname"`
	RecordType    RecordType `json:"rtype"`
	SortOrder     struct {
		ByCreated int `json:"created"`
		ByName    int `json:"qname"`
	} `json:"sort-order"`
	Value string `json:"value"`
	Zone  string `json:"zone"`
}

DNSRecord represents the host data returned from the API

type DNSZone

type DNSZone string

DNSZone represents the zone data returned from the API

type RecordType

type RecordType string

RecordType is the type of DNS Record. For ex. CNAME.

const (
	// A record type.
	A RecordType = "A"
	// AAAA record type.
	AAAA RecordType = "AAAA"
	// CAA record type.
	CAA RecordType = "CAA"
	// CNAME record type.
	CNAME RecordType = "CNAME"
	// MX record type.
	MX RecordType = "MX"
	// NS record type.
	NS RecordType = "NS"
	// TXT record type.
	TXT RecordType = "TXT"
	// SRV record type.
	SRV RecordType = "SRV"
	// SSHFP record type.
	SSHFP RecordType = "SSHFP"
)