Class: PDNS::Zone

Inherits:
API
  • Object
show all
Defined in:
lib/pdns_api/zone.rb

Overview

Zone on a server.

Instance Attribute Summary collapse

Attributes inherited from API

#class, #url

Instance Method Summary collapse

Methods inherited from API

#change, #create, #delete, #ensure_array, #get, #info

Constructor Details

#initialize(http, parent, id, info = {}) ⇒ Zone

Creates a Zone object.

Parameters:

  • http (HTTP) —

    An HTTP object for interaction with the PowerDNS server.

  • parent (API) —

    This object’s parent.

  • id (String) —

    ID of the zone.

  • info (Hash) (defaults to: {}) —

    Optional information of the zone.



39
40
41
42
43
44
45
46
 
# File 'lib/pdns_api/zone.rb', line 39

def initialize(http, parent, id, info = {})
  @class  = :zones
  @http   = http
  @parent = parent
  @id     = id
  @info   = info
  @url    = "#{parent.url}/#{@class}/#{id}"
end

Instance Attribute Details

#id ⇒ String (readonly)

Returns the ID of the zone.

Returns:

  • (String) —

    the ID of the zone.



29
30
31
 
# File 'lib/pdns_api/zone.rb', line 29

def id
  @id
end

Instance Method Details

#add(*rrsets) ⇒ Hash

Adds records to the ones already existing in the zone.

The existing records are retrieved and merged with the ones given in rrsets.

Elements of rrsets can contain :records, which can be:

  • A String containing a single record value.

  • An Array containing record values.

  • An Array containing hashes as specified in the PowerDNS API.

Examples:

zone.add({
  name: 'www0.example.com.',
  type: 'A',
  ttl:  86_400,
  records: '127.0.1.1',
}, {
  name: 'www1.example.com.',
  type: 'A',
  ttl:  86_400,
  records: ['127.0.1.1', '127.0.0.1'],
}, {
  name: 'www2.example.com.',
  type: 'A',
  ttl:  86_400,
  records: [{content: '127.0.1.1'},{content: '127.0.0.1', disabled: true}],
})

Parameters:

  • rrsets (Array<Object>) —

    Array of Hashes containing records to replace.

Returns:

  • (Hash) —

    Hash containing result of the operation.



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
 
# File 'lib/pdns_api/zone.rb', line 136

def add(*rrsets)
  # Get current zone data
  data = get

  # Return any errors
  return data if data.key?(:error)

  # Add these records to the rrset
  rrsets.map! do |rrset|
    # Get current data from rrset
    current = current_records(rrset, data)

    # Merge data
    rrset[:records]    = current + ensure_array(rrset[:records])
    rrset[:changetype] = 'REPLACE'
    rrset
  end
  modify(rrsets)
end

#axfr_retrieve ⇒ Hash

Retrieves the data for a zone. Only works for domains for which the server is a slave.

Returns:

  • (Hash) —

    the result of the retrieval.



84
85
86
 
# File 'lib/pdns_api/zone.rb', line 84

def axfr_retrieve
  @http.put "#{@url}/axfr-retrieve"
end

#check ⇒ Hash

Checks the zone for errors.

Returns:

  • (Hash) —

    the result of the check.



100
101
102
 
# File 'lib/pdns_api/zone.rb', line 100

def check
  @http.get "#{@url}/check"
end

#cryptokeys(id = nil) ⇒ Hash, CryptoKey

Returns existing or creates a CryptoKey object.

Examples:

ckeys = zone.cryptokeys
ckey  = zone.cryptokey(12)

Parameters:

  • id (Integer, nil) (defaults to: nil) —

    ID of a CryptoKey.

Returns:

  • (Hash, CryptoKey) —

    Hash of CryptoKeys or a single CryptoKey.

    • If id is not set the current servers are returned in a hash containing CryptoKey objects.

    • If id is set a CryptoKey object with the provided ID is returned.



275
276
277
278
279
280
281
282
283
 
# File 'lib/pdns_api/zone.rb', line 275

def cryptokeys(id = nil)
  return CryptoKey.new(@http, self, id) unless id.nil?

  # Get all current metadata
  cryptokeys = @http.get("#{@url}/cryptokeys")

  # Convert cryptokeys to hash
  cryptokeys.map { |c| [c[:id], CryptoKey.new(@http, self, c[:id], c)] }.to_h
end

#export ⇒ Hash

Exports the zone as a bind zone file.

Returns:

  • (Hash) —

    containing the Bind formatted zone in :result.



91
92
93
94
95
 
# File 'lib/pdns_api/zone.rb', line 91

def export
  data = @http.get "#{@url}/export"
  data.delete(:error) if data[:error] == 'Non-JSON response'
  data
end

#metadata(kind = nil, value = nil) ⇒ Metadata, Hash

Returns existing metadata or creates a Metadata object.

Examples:

# Retrieve all metadata in a hash
zone.metadata
# Create a metadata object
meta = zone.metadata('ALLOW-AXFR-FROM')
puts meta.get
# Create a metadata object with a value
meta = zone.metadata('ALLOW-AXFR-FROM','AUTO-NS')
meta.change

Parameters:

  • kind (String, nil) (defaults to: nil) —

    The kind of metadata.

  • value (String, nil) (defaults to: nil) —

    The value of the metadata.

Returns:

  • (Metadata, Hash) —

    Hash containing all metadata, or single Metadata object.

    • If kind is not set the current metadata is returned in a Hash.

    • If kind is set a Metadata object is returned using the provided kind.

    • If value is set as well, a complete Metadata object is returned.



243
244
245
246
247
248
249
250
251
252
253
254
255
 
# File 'lib/pdns_api/zone.rb', line 243

def metadata(kind = nil, value = nil)
  return Metadata.new(@http, self, kind, value) unless kind.nil? || value.nil?
  return Metadata.new(@http, self, kind) unless kind.nil?

  # Get all current metadata
  metadata = @http.get("#{@url}/metadata")

  # Check for errors
  return metadata if metadata.is_a?(Hash) && metadata.key?(:error)

  # Convert metadata to hash
  metadata.map { |c| [c[:kind], c[:metadata]] }.to_h
end

#modify(rrsets) ⇒ Hash

Modifies information (records) of a zone. Also formats records to match the API requirements.

Examples:

zone.modify([
   changetype: 'DELETE',
   name: 'www.example.com.',
   type: 'A'
])

Parameters:

  • rrsets (Array) —

    Changeset to send to the PowerDNS API.

Returns:

  • (Hash) —

    result of the changeset.



63
64
65
66
67
68
69
70
 
# File 'lib/pdns_api/zone.rb', line 63

def modify(rrsets)
  rrsets.map! do |rrset|
    rrset = format_records(rrset) if rrset.key?(:records)
    rrset
  end

  @http.patch(@url, rrsets: rrsets)
end

#notify ⇒ Hash

Notifies slaves for a zone. Only works for domains for which the server is a master.

Returns:

  • (Hash) —

    the result of the notification.



76
77
78
 
# File 'lib/pdns_api/zone.rb', line 76

def notify
  @http.put "#{@url}/notify"
end

#remove(*rrsets) ⇒ Hash

Removes all records for a name/type combination from the zone.

Examples:

zone.remove({
  name: 'www0.example.com.',
  type: 'A'
}, {
  name: 'www1.example.com.',
  type: 'A'
})

Parameters:

  • rrsets (Array<Object>) —

    Array of Hashes to delete. The Hash(es) in the Array should contain :name and :type.

Returns:

  • (Hash) —

    Hash containing result of the operation.



213
214
215
216
217
218
219
220
 
# File 'lib/pdns_api/zone.rb', line 213

def remove(*rrsets)
  # Set type and format records
  rrsets.map! do |rrset|
    rrset[:changetype] = 'DELETE'
    rrset
  end
  modify(rrsets)
end

#update(*rrsets) ⇒ Hash

Updates (replaces) records for a name/type combination in the zone.

Elements of rrsets can contain :records, which can be:

  • A String containing a single record value.

  • An Array containing record values.

  • An Array containing hashes as specified in the PowerDNS API.

Examples:

zone.update({
  name: 'www0.example.com.',
  type: 'A',
  ttl:  86_400,
  records: '127.0.1.1'
}, {
  name: 'www1.example.com.',
  type: 'A',
  ttl:  86_400,
  records: ['127.0.1.1', '127.0.0.1']
}, {
  name: 'www2.example.com.',
  type: 'A',
  ttl:  86_400,
  records: [{content: '127.0.1.1'},{content: '127.0.0.1', disabled: true}]
})

Parameters:

  • rrsets (Array<Object>) —

    Array of Hashes containing records to replace.

Returns:

  • (Hash) —

    Hash containing result of the operation.



186
187
188
189
190
191
192
193
194
 
# File 'lib/pdns_api/zone.rb', line 186

def update(*rrsets)
  # Set type and format records
  rrsets.map! do |rrset|
    rrset[:changetype] = 'REPLACE'
    rrset[:records] = ensure_array(rrset[:records])
    rrset
  end
  modify(rrsets)
end