Zone Model

Table of Contents

ZONE ATTRIBUTES

field type description
status string Active - the zone is connected and ready for use; Syncing - the zone is currently syncing with the DNS backend and is not available until syncing is complete.
updated date-time The last time the zone was changed. Note: this does not include changes to record sets, only the zone entity itself
name string The name of the zone
adminGroupId string The id of the administrators group for the zone
created date-time The time when the zone was first created
account string DEPRECATED The account that created the zone
email string The distribution email for the zone
backendId string Optional. Recommended over connection and transferConnection. The configuration ID of the DNS backend server for the zone. If not provided, default keys will be used unless connection and transfer connection are provided.
connection ZoneConnection Optional. The connection used to issue DDNS updates to the backend zone. If not provided, default keys will be used unless backendId is provided. See the Zone Connection Attributes for more information
transferConnection ZoneConnection Optional. The connection that is used to sync the zone with the DNS backend. This can be different than the update connection. If not provided, default keys will be used unless backendId is provided.
shared boolean An indicator that the zone is shared with anyone. At this time only VinylDNS administrators can set this to true.
acl ZoneACL The access control rules governing the zone. See the Zone ACL Rule Attributes for more information
id string The unique identifier for this zone
latestSync date-time The last date and time the zone was synced
isTest boolean Defaults to false. Used for restricted access during VinylDNS testing, can be ignored by clients
accessLevel string Access level of the user requesting the zone. Current levels are Delete (full access), Read and NoAccess.

ZONE EXAMPLE

{
  "status": "Active",
  "updated": "2016-12-16T15:27:28Z",
  "name": "ok.",
  "adminGroupId": "92b298e8-97db-4f1b-881b-fd08ca0dd311",
  "created": "2016-12-16T15:27:26Z",
  "account": "92b298e8-97db-4f1b-881b-fd08ca0dd311",
  "email": "test@test.com",
  "connection": {
    "primaryServer": "127.0.0.1:5301",
    "keyName": "vinyl.",
    "name": "ok.",
    "key": "OBF:1:W1FXgpOjjrQAABAARrZmyLjFSOuFYTAw81mhvNEmNAc4RnYzPjJQMEjVQWWLRohu7gRAVw=="
  },
  "transferConnection": {
    "primaryServer": "127.0.0.1:5301",
    "keyName": "vinyl.",
    "name": "ok.",
    "key": "OBF:1:W1FXgpOjjrQAABAARrZmyLjFSOuFYTAw81mhvNEmNAc4RnYzPjJQMEjVQWWLRohu7gRAVw=="
  },
  "shared": false,
  "acl": {
    "rules": [
      {
        "accessLevel": "Write",
        "userId": "<uuid>",
        "description": "some_test_rule",
        "recordTypes": []
      },
      {
        "recordMask": ".*",
        "accessLevel": "Write",
        "userId": "<uuid>",
        "description": "some_test_rule",
        "recordTypes": []
      },
      {
        "recordMask": "test.*",
        "accessLevel": "Read",
        "groupId": "<uuid>",
        "description": "some_test_rule",
        "recordTypes": []
      }
    ]
  },
  "id": "9cbdd3ac-9752-4d56-9ca0-6a1a14fc5562",
  "latestSync": "2016-12-16T15:27:26Z",
  "backendId":"func-test-backend",
  "accessLevel": "Delete"
}

ZONE ACL RULE ATTRIBUTES

ACL Rules are used to govern user and group access to record operations on a zone. ACL Rules can be associated with a specific user, or all users in a specified group. If neither a user or a group is attached to an ACL rule, then the rule applies to all users in the system.

Use the Zone Update endpoint to update the acl attribute of the zone

Important! If a user is mentioned on an ACL Rule directly, or is a member of a group that is mentioned on an ACL Rule, that user will be able to see the zone.

Rules made without selecting a group or user will apply to all users in VinylDNS.

field type description
recordMask string (optional) A regular expression that is used to match against record names. If left empty, then all records will be matched for the rule. All records matching the match will be governed by this rule.
recordTypes Array[String] An array of all record types that this rule applies to. If left empty, then all record types will be governed by this rule.
accessLevel string NoAccess - cannot see the data for the record; Read - can read only the record; Write - the user can create and edit records, but cannot delete them; Delete - the user can read, create, update, and delete records
userId string (optional) The unique identifier for the user the rule applies to. Note: this is not the name of the user, but their uuid in VinylDNS
groupId string (optional) The unique identifier for the group the rule applies to. Note: you cannot set both the userId and groupId, only one
description string (optional) A user entered description for the rule

The priority of ACL Rules in descending precedence:

  1. Individual rules placed on a user
  2. Rules placed on groups that a user is in
  3. Rules placed on all users in VinylDNS

Note: Being in the admin group of a zone will grant users full access regardless of ACL Rules

For conflicting rules, the rule that is more specific will take precedence. For example, if the account jdoe201 was given Read access to all records in a zone through the rule:

{
  "userId": "<uuid>",
  "accessLevel": "Read",
}

and then Write access to only A records through the rule:

{
  "userId": "<uuid>",
  "accessLevel": "Write",
  "recordTypes": ["A"]
}

and then Delete access to only A records that matched the expression *dev* through the rule:

{
  "userId": "<uuid>",
  "accessLevel": "Delete",
  "recordTypes": ["A"],
  "recordMask": "*dev*"
}

then the rule with the recordMask will take precedence and give Delete access to matched A RecordSets, the rule with recordTypes will take precedence and give Write access to all other A records, and the more broad rule will give Read access to all other record types in the zone

ZONE ACL RULE EXAMPLES

Grant read/write/delete access to www.* records of type A, AAAA, CNAME to one user Under this rule, the user specified will be able to view, create, edit, and delete records in the zone that match the expression www.* and are of type A, AAAA, or CNAME.

{
  "recordMask": "www.*",
  "accessLevel": "Delete",
  "userId": "<uuid>",
  "recordTypes": ["A", "AAAA", "CNAME"]
}

Grant read only access to all VinylDNS users to A, AAAA, CNAME records

{
  "accessLevel": "Read",
  "recordTypes": ["A", "AAAA", "CNAME"]
}

Grant read/write/delete access to records of type A, AAAA, CNAME to one group*

{
  "accessLevel": "Delete",
  "groupId": "<uuid>",
  "recordTypes": ["A", "AAAA", "CNAME"]
}

PTR ACL RULES WITH CIDR MASKS

ACL rules can be applied to specific record types and can include record masks to further narrow down which records they apply to. These record masks apply to record names, but because PTR record names are part their reverse zone ip, the use of regular expressions for record masks are not supported.

Instead PTR record masks must be CIDR rules, which will denote a range of IP addresses that the rule will apply to. While more information and useful CIDR rule utility tools can be found online, CIDR rules describe how many bits of an ip address’ binary representation must be the same for a match.

PTR ACL RULES WITH CIDR MASKS EXAMPLE

The ACL Rule

{
    recordTypes: ["PTR"],
    accessLevel: "Read"
}

Will give Read permissions to PTR Record Sets to all users in VinylDNS

The IPv4 ACL Rule

{
    recordTypes: ["PTR"],
    accessLevel: "Read",
    recordMask: "100.100.100.100/16"
}

Will give Read permissions to PTR Record Sets 100.100.000.000 to 100.100.255.255, as 16 bits is half of an IPv4 address

The IPv6 ACL Rule

{
    recordTypes: ["PTR"],
    accessLevel: "Read",
    recordMask: "1000:1000:1000:1000:1000:1000:1000:1000/64"
}

Will give Read permissions to PTR Record Sets 1000:1000:1000:1000:0000:0000:0000:0000 to 1000:1000:1000:1000:FFFF:FFFF:FFFF:FFFF, as 64 bits is half of an IPv6 address.

ZONE CONNECTION ATTRIBUTES

In order for VinylDNS to make updates in DNS, it needs key information for every zone. There are 3 ways to specify that key information; ask your VinylDNS admin which is appropriate for your zone based on the configuration of the service:

  1. Leave connection, transfer connection, and backend ID blank: In this case, the default VinylDNS keys will be used
  2. Specify a backend ID on the zone: if multiple backends are configured for your instance of VinylDNS, you can specify a backend ID on the zone and the keys associated with that backend will be used.
  3. Specify zone connection and transfer connection on the zone itself: see below for details

Note that if both a backend ID and specific connection keys are included on a zone, the specific connection keys will be used.

Zone Connection specifies the connection information to the backend DNS server.

field type description
primaryServer string The IP address or host that is connected to. This can take a port as well 127.0.0.1:5300. If no port is specified, 53 will be assumed.
keyName string The name of the DNS key that has access to the DNS server and zone. Note: For the transfer connection, the key must be given allow-transfer access to the zone. For the primary connection, the key must be given allow-update access to the zone.
name string A user identifier for the connection.
key string The TSIG secret key used to sign requests when communicating with the primary server. Note: After creating the zone, the key value itself is hashed and obfuscated, so it will be unusable from a client perspective.

ZONE CONNECTION EXAMPLE

{
  "primaryServer": "127.0.0.1:5301",
  "keyName": "vinyl.",
  "name": "ok.",
  "key": "OBF:1:W1FXgpOjjrQAABAARrZmyLjFSOuFYTAw81mhvNEmNAc4RnYzPjJQMEjVQWWLRohu7gRAVw=="
}

SHARED ZONES

Shared zones allow for a more open management of records in VinylDNS. Zone administrators can assign ownership of records to groups. Any user in VinylDNS can claim existing unowned records in shared zones, as well as create records in those zones. Once a record is owned, only users in the record owner group, the zone administrators and those with relevant ACL rules can modify or delete the record. The batch change API endpoint and batch change area of the portal are where users can create new records in shared zones, modify records they own, or claim unowned records. If a zone’s shared state changes to false the record ownership access is no longer applicable.