GetZone
get
/20180115/zones/{zone_name_or_id}
Gets information about the specified zone, including its creation date, zone type, and serial. When the zone name is provided as a path parameter and PRIVATE is used for the scope query parameter then the viewId query parameter is required.
Request
Supported Media Types
- application/json
Path Parameters
-
zoneNameOrId(required): string
The name or OCID of the target zone.
Query Parameters
-
compartmentId: string
Minimum Length:
1
Maximum Length:255
The OCID of the compartment the zone belongs to. Deprecated. Do not use. -
scope: string
Specifies to operate only on resources that have a matching DNS scope.Allowed Values:
[ "GLOBAL", "PRIVATE" ]
-
viewId: string
Minimum Length:
1
Maximum Length:255
The OCID of the view the resource is associated with.
Header Parameters
-
If-Modified-Since: string
The If-Modified-Since header field makes a GET or HEAD request method conditional on the selected representation's modification date being more recent than the date provided in the field-value. Transfer of the selected representation's data is avoided if that data has not changed.
-
if-none-match: string
The system returns the requested resource, with a 200 status, only if the resource has no etag matching the one specified. If the condition fails for the GET and HEAD methods, then the system returns the HTTP status code 304 (Not Modified). Example: example-etagDefault Value:
-
opc-request-id: string
Minimum Length:
1
Maximum Length:98
Unique Oracle-assigned identifier for the request. Provide this request OCID if you need to contact Oracle about this request.
Response
Supported Media Types
- application/json
200 Response
A response containing a single zone object.
Headers
-
ETag: string
The current version of the resource, ending with a representation-specific suffix. This value may be used in If-Match and If-None-Match headers for later requests of the same resource.
-
opc-request-id: string
Unique Oracle-assigned identifier for the request. Provide this request OCID if you need to contact Oracle about this request.
Root Schema : Zone
Type:
object
A DNS zone. Avoid entering confidential information when you supply string values using the API.
Show Source
-
compartmentId(required):
string
Minimum Length:
1
Maximum Length:255
The OCID of the compartment containing the zone. -
definedTags(required):
object definedTags
Additional Properties Allowed: additionalPropertiesDefined tags for this resource. Each key is predefined and scoped to a namespace. Example: {"Operations": {"CostCenter": "42"}}
-
dnssecConfig:
object DnssecConfig
DNSSEC configuration data. A zone may have a maximum total of 10 DnssecKeyVersions, regardless of signing key type.
-
dnssecState(required):
string
Default Value:
DISABLED
Allowed Values:[ "ENABLED", "DISABLED" ]
The state of DNSSEC on the zone. In order to benefit from utilizing DNSSEC, every parent zone in the DNS tree, up to the TLD or an independent trust anchor, must also have DNSSEC correctly set up. After enabling DNSSEC, a DS record must be added to this zone's parent zone containing data corresponding to the KskDnssecKeyVersion that gets created, and then the KskDnssecKeyVersion must be promoted via the PromoteZoneDnssecKeyVersion operation. New KskDnssecKeyVersions are generated annually, a week before the existing KskDnssecKeyVersion's expiration. KskDnssecKeyVersion rollover requires replacing the parent zone's DS record, corresponding to the current KskDnssecKeyVersion, using the data from its successor KskDnssecKeyVersion. To prevent service disruption from resolver caches including signatures using only the old KSK version, that DS record should not be replaced until the new version has been active for at least the DNSKEY TTL. After the DS replacement has been completed then the PromoteZoneDnssecKeyVersion operation must be called. Metrics are emitted in the oci_dns namespace daily for each KskDnssecKeyVersion indicating how many days are left until expiration. Alarms and notifications should be set up in order to be notified of the KskDnssecKeyVersion expiration so that the necessary parent zone updates can be made and the PromoteZoneDnssecKeyVersion operation can be called. Zones with DNSSEC enabled are subject to a maximum allowed TTL on records of 1 day (86400 seconds). Enabling DNSSEC will result in additional records in DNS responses which will increase their size and can cause higher response latency. Re-enabling DNSSEC on a zone shortly after it being disabled will restore the previous DnssecKeyVersions. TODO: Add link to DNSSEC docs covering: how to set up alarms/notifications, warnings about enabling/disabling, warnings about timing and impacts, how to handle automatic rollover, how to handle manual rollover, and how to handle emergency rollover. -
externalDownstreams(required):
array externalDownstreams
External secondary servers for the zone. This field is currently not supported when zoneType is SECONDARY or scope is PRIVATE.
-
externalMasters(required):
array externalMasters
External master servers for the zone. externalMasters becomes a required parameter when the zoneType value is SECONDARY.
-
freeformTags(required):
object freeformTags
Additional Properties Allowed: additionalPropertiesFree-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {"Department": "Finance"}
-
id(required):
string
Minimum Length:
1
Maximum Length:255
The OCID of the zone. -
isProtected(required):
boolean
A Boolean flag indicating whether or not parts of the resource are unable to be explicitly managed.
-
lifecycleState(required):
string
Allowed Values:
[ "ACTIVE", "CREATING", "DELETED", "DELETING", "FAILED", "UPDATING" ]
The current state of the zone resource. -
name(required):
string
Minimum Length:
1
Maximum Length:254
The name of the zone. -
nameservers(required):
array nameservers
The authoritative nameservers for the zone.
-
scope(required):
string
Allowed Values:
[ "GLOBAL", "PRIVATE" ]
The scope of the zone. -
self(required):
string(url)
The canonical absolute URL of the resource.
-
serial(required):
integer(int64)
The current serial of the zone. As seen in the zone's SOA record.
-
timeCreated(required):
string(date-time)
The date and time the resource was created in "YYYY-MM-ddThh:mm:ssZ" format with a Z offset, as defined by RFC 3339. Example: 2016-07-22T17:23:59:60Z
-
version(required):
string
Version is the never-repeating, totally-orderable, version of the zone, from which the serial field of the zone's SOA record is derived.
-
viewId:
string
Minimum Length:
1
Maximum Length:255
The OCID of the private view containing the zone. This value will be null for zones in the global DNS, which are publicly resolvable and not part of a private view. -
zoneTransferServers:
array zoneTransferServers
The OCI nameservers that transfer the zone data with external nameservers.
-
zoneType(required):
string
Allowed Values:
[ "PRIMARY", "SECONDARY" ]
The type of the zone. Must be either PRIMARY or SECONDARY. SECONDARY is only supported for GLOBAL zones.
Nested Schema : definedTags
Type:
object
Additional Properties Allowed
Show Source
-
object additionalProperties
Additional Properties Allowed: additionalPropertiesKey-value pair representing a defined tag key and value, scoped to a namespace. Example: {"CostCenter": "42"}
Defined tags for this resource. Each key is predefined and scoped to a namespace. Example: {"Operations": {"CostCenter": "42"}}
Nested Schema : DnssecConfig
Type:
object
DNSSEC configuration data. A zone may have a maximum total of 10 DnssecKeyVersions, regardless of signing key type.
Show Source
-
kskDnssecKeyVersions:
array kskDnssecKeyVersions
A read only array of KSK DnssecKeyVersions.
-
zskDnssecKeyVersions:
array zskDnssecKeyVersions
A read only array of ZSK DnssecKeyVersions.
Nested Schema : externalDownstreams
Type:
array
External secondary servers for the zone. This field is currently not supported when zoneType is SECONDARY or scope is PRIVATE.
Show Source
-
Array of:
object ExternalDownstream
External downstream nameserver for the zone. This field is currently not supported when zoneType is SECONDARY or scope is PRIVATE.
Nested Schema : externalMasters
Type:
array
External master servers for the zone. externalMasters becomes a required parameter when the zoneType value is SECONDARY.
Show Source
-
Array of:
object ExternalMaster
An external master name server used as the source of zone data.
Nested Schema : freeformTags
Type:
object
Additional Properties Allowed
Show Source
Free-form tags for this resource. Each tag is a simple key-value pair with no predefined name, type, or namespace. Example: {"Department": "Finance"}
Nested Schema : nameservers
Type:
array
The authoritative nameservers for the zone.
Show Source
-
Array of:
object Nameserver
A server that has been set up to answer DNS queries for a zone.
Nested Schema : zoneTransferServers
Type:
array
The OCI nameservers that transfer the zone data with external nameservers.
Show Source
-
Array of:
object ZoneTransferServer
An OCI nameserver that transfers zone data with external nameservers.
Nested Schema : additionalProperties
Type:
object
Additional Properties Allowed
Show Source
-
object additionalProperties
The value of the tag. Only string, integer, and boolean types are supported.
Key-value pair representing a defined tag key and value, scoped to a namespace. Example: {"CostCenter": "42"}
Nested Schema : additionalProperties
Type:
object
The value of the tag. Only string, integer, and boolean types are supported.
Nested Schema : kskDnssecKeyVersions
Type:
array
A read only array of KSK DnssecKeyVersions.
Show Source
-
Array of:
object KskDnssecKeyVersion
A KSK DnssecKeyVersion. This contains timing and configuration data corresponding to the KSK that is used to apply DNSSEC on the zone.
Nested Schema : zskDnssecKeyVersions
Type:
array
A read only array of ZSK DnssecKeyVersions.
Show Source
-
Array of:
object ZskDnssecKeyVersion
A ZSK DnssecKeyVersion. This contains timing and configuration data corresponding to the ZSK that is used to apply DNSSEC on the zone.
Nested Schema : KskDnssecKeyVersion
Type:
object
A KSK DnssecKeyVersion. This contains timing and configuration data corresponding to the KSK that is used to apply DNSSEC on the zone.
Show Source
-
algorithm:
string
Allowed Values:
[ "RSASHA256" ]
The signing algorithm that will be utilized. -
dsData:
array dsData
An array of data for DS records corresponding with this key version. An entry will exist for each supported DS digest algorithm.
-
keyTag:
integer
Minimum Value:
0
Maximum Value:65535
The key tag associated with the DnssecKeyVersion. This key tag will be present in the RRSIG and DS records associated with the key material for this DnssecKeyVersion. For more information about key tags, see [RFC 4034](https://tools.ietf.org/html/rfc4034). -
lengthInBytes:
integer(int32)
The length of the corresponding private key in bytes, expressed as an integer.
-
predecessorDnssecKeyVersionUuid:
string
Minimum Length:
36
Maximum Length:36
When populated, this is the UUID of the DnssecKeyVersion that this DnssecKeyVersion will replace or has replaced. -
successorDnssecKeyVersionUuid:
string
Minimum Length:
36
Maximum Length:36
When populated, this is the UUID of the DnssecKeyVersion that will replace, or has replaced, this DnssecKeyVersion. -
timeActivated:
string(date-time)
The date and time the key version went, or will go, active, expressed in RFC 3339 timestamp format. This is when the key material will be used to generate RRSIGs. Example: 2016-07-22T17:23:59:00Z
-
timeCreated:
string(date-time)
The date and time the key version was created, expressed in RFC 3339 timestamp format. Example: 2016-07-22T17:23:59:00Z
-
timeExpired:
string(date-time)
The date and time at which the recommended key version publication/activation lifetime ends, expressed in RFC 3339 timestamp format. This is when the corresponding DNSKEY should no longer exist in zone contents and no longer be used to generate RRSIGs. For KSK, if PromoteZoneDnssecKeyVersion has not been called on this DnssecKeyVersion's successor then it will remain active for arbitrarily long past its recommended lifetime (preventing service disruption at the potential increased risk of key compromise). Example: 2016-07-22T17:23:59:00Z
-
timeInactivated:
string(date-time)
The date and time the key version went, or will go, inactive, expressed in RFC 3339 timestamp format. This is when the key material will no longer be used to generate RRSIGs. Example: 2016-07-22T17:23:59:00Z
-
timePromoted:
string(date-time)
The date and time the key version was promoted expressed in RFC 3339 timestamp format. Example: 2016-07-22T17:23:59:00Z
-
timePublished:
string(date-time)
The date and time the key version was, or will be, published, expressed in RFC 3339 timestamp format. This is when the zone contents will include a DNSKEY record corresponding to the key material. Example: 2016-07-22T17:23:59:00Z
-
timeUnpublished:
string(date-time)
The date and time the key version was, or will be, unpublished, expressed in RFC 3339 timestamp format. This is when the corresponding DNSKEY will be removed from zone contents. For a KSK DnssecKeyVersion this will be populated after PromoteZoneDnssecKeyVersion has been called on its successor DnssecKeyVersion. Example: 2016-07-22T17:23:59:00Z
-
uuid:
string
Minimum Length:
36
Maximum Length:36
The UUID of the DnssecKeyVersion.
Nested Schema : dsData
Type:
array
Minimum Length:
1
An array of data for DS records corresponding with this key version. An entry will exist for each supported DS digest algorithm.
Show Source
-
Array of:
object DnssecKeyVersionDsData
Data for a parent-zone DS record corresponding to this key-signing key.
Nested Schema : DnssecKeyVersionDsData
Type:
object
Data for a parent-zone DS record corresponding to this key-signing key.
Show Source
-
digestType:
string
Allowed Values:
[ "SHA_256" ]
The type of the digest associated with the rdata. -
rdata:
string
Presentation-format DS record data that must be added to the parent zone.Example:
60485 5 1 2BB183AF5F22588179A53B0A98631FAD1A292118
Nested Schema : ZskDnssecKeyVersion
Type:
object
A ZSK DnssecKeyVersion. This contains timing and configuration data corresponding to the ZSK that is used to apply DNSSEC on the zone.
Show Source
-
algorithm:
string
Allowed Values:
[ "RSASHA256" ]
The signing algorithm that will be utilized. -
keyTag:
integer
Minimum Value:
0
Maximum Value:65535
The key tag associated with the DnssecKeyVersion. This key tag will be present in the RRSIG and DS records associated with the key material for this DnssecKeyVersion. For more information about key tags, see [RFC 4034](https://tools.ietf.org/html/rfc4034). -
lengthInBytes:
integer(int32)
The length of the corresponding private key in bytes, expressed as an integer.
-
predecessorDnssecKeyVersionUuid:
string
Minimum Length:
36
Maximum Length:36
When populated, this is the UUID of the DnssecKeyVersion that this DnssecKeyVersion will replace or has replaced. -
successorDnssecKeyVersionUuid:
string
Minimum Length:
36
Maximum Length:36
When populated, this is the UUID of the DnssecKeyVersion that will replace, or has replaced, this DnssecKeyVersion. -
timeActivated:
string(date-time)
The date and time the key version went, or will go, active, expressed in RFC 3339 timestamp format. This is when the key material will be used to generate RRSIGs. Example: 2016-07-22T17:23:59:00Z
-
timeCreated:
string(date-time)
The date and time the key version was created, expressed in RFC 3339 timestamp format. Example: 2016-07-22T17:23:59:00Z
-
timeExpired:
string(date-time)
The date and time at which the recommended key version publication/activation lifetime ends, expressed in RFC 3339 timestamp format. This is when the corresponding DNSKEY should no longer exist in zone contents and no longer be used to generate RRSIGs. For KSK, if PromoteZoneDnssecKeyVersion has not been called on this DnssecKeyVersion's successor then it will remain active for arbitrarily long past its recommended lifetime (preventing service disruption at the potential increased risk of key compromise). Example: 2016-07-22T17:23:59:00Z
-
timeInactivated:
string(date-time)
The date and time the key version went, or will go, inactive, expressed in RFC 3339 timestamp format. This is when the key material will no longer be used to generate RRSIGs. Example: 2016-07-22T17:23:59:00Z
-
timePromoted:
string(date-time)
The date and time the key version was promoted expressed in RFC 3339 timestamp format. Example: 2016-07-22T17:23:59:00Z
-
timePublished:
string(date-time)
The date and time the key version was, or will be, published, expressed in RFC 3339 timestamp format. This is when the zone contents will include a DNSKEY record corresponding to the key material. Example: 2016-07-22T17:23:59:00Z
-
timeUnpublished:
string(date-time)
The date and time the key version was, or will be, unpublished, expressed in RFC 3339 timestamp format. This is when the corresponding DNSKEY will be removed from zone contents. For a KSK DnssecKeyVersion this will be populated after PromoteZoneDnssecKeyVersion has been called on its successor DnssecKeyVersion. Example: 2016-07-22T17:23:59:00Z
-
uuid:
string
Minimum Length:
36
Maximum Length:36
The UUID of the DnssecKeyVersion.
Nested Schema : ExternalDownstream
Type:
object
External downstream nameserver for the zone. This field is currently not supported when zoneType is SECONDARY or scope is PRIVATE.
Show Source
-
address(required):
string
The server's IP address (IPv4 or IPv6).
-
port:
integer
Default Value:
53
The server's port. Port value must be a value of 53, otherwise omit the port value. -
tsigKeyId:
string
Minimum Length:
1
Maximum Length:255
The OCID of the TSIG key. A TSIG key is used to secure DNS messages (in this case, zone transfers) between two systems that both have the (shared) secret.
Nested Schema : ExternalMaster
Type:
object
An external master name server used as the source of zone data.
Show Source
-
address(required):
string
The server's IP address (IPv4 or IPv6).
-
port:
integer
Default Value:
53
The server's port. Port value must be a value of 53, otherwise omit the port value. -
tsigKeyId:
string
Minimum Length:
1
Maximum Length:255
The OCID of the TSIG key.
Nested Schema : Nameserver
Type:
object
A server that has been set up to answer DNS queries for a zone.
Show Source
-
hostname(required):
string
The hostname of the nameserver.
Nested Schema : ZoneTransferServer
Type:
object
An OCI nameserver that transfers zone data with external nameservers.
Show Source
-
address(required):
string
The server's IP address (IPv4 or IPv6).
-
isTransferDestination:
boolean
A Boolean flag indicating whether or not the server is a zone data transfer destination.
-
isTransferSource:
boolean
A Boolean flag indicating whether or not the server is a zone data transfer source.
-
port:
integer
Default Value:
53
The server's port.
400 Response
Bad Request
Headers
-
opc-request-id: string
Unique Oracle-assigned identifier for the request. Provide this request OCID if you need to contact Oracle about this request.
Root Schema : Error
Type:
object
The properties that define an error.
Show Source
-
code(required):
string
A short error code that defines the error, meant for programmatic parsing..Example:
UnknownError
-
message(required):
string
A human-readable error string.Example:
error validating payload
401 Response
Unauthorized
Headers
-
opc-request-id: string
Unique Oracle-assigned identifier for the request. Provide this request OCID if you need to contact Oracle about this request.
Root Schema : Error
Type:
object
The properties that define an error.
Show Source
-
code(required):
string
A short error code that defines the error, meant for programmatic parsing..Example:
UnknownError
-
message(required):
string
A human-readable error string.Example:
error validating payload
404 Response
Not Found
Headers
-
opc-request-id: string
Unique Oracle-assigned identifier for the request. Provide this request OCID if you need to contact Oracle about this request.
Root Schema : Error
Type:
object
The properties that define an error.
Show Source
-
code(required):
string
A short error code that defines the error, meant for programmatic parsing..Example:
UnknownError
-
message(required):
string
A human-readable error string.Example:
error validating payload
412 Response
Precondition Failed
Headers
-
opc-request-id: string
Unique Oracle-assigned identifier for the request. Provide this request OCID if you need to contact Oracle about this request.
Root Schema : Error
Type:
object
The properties that define an error.
Show Source
-
code(required):
string
A short error code that defines the error, meant for programmatic parsing..Example:
UnknownError
-
message(required):
string
A human-readable error string.Example:
error validating payload
429 Response
Too Many Requests
Headers
-
opc-request-id: string
Unique Oracle-assigned identifier for the request. Provide this request OCID if you need to contact Oracle about this request.
Root Schema : Error
Type:
object
The properties that define an error.
Show Source
-
code(required):
string
A short error code that defines the error, meant for programmatic parsing..Example:
UnknownError
-
message(required):
string
A human-readable error string.Example:
error validating payload
500 Response
Internal Server Error
Headers
-
opc-request-id: string
Unique Oracle-assigned identifier for the request. Provide this request OCID if you need to contact Oracle about this request.
Root Schema : Error
Type:
object
The properties that define an error.
Show Source
-
code(required):
string
A short error code that defines the error, meant for programmatic parsing..Example:
UnknownError
-
message(required):
string
A human-readable error string.Example:
error validating payload
Default Response
An error has occurred.
Headers
-
opc-request-id: string
Unique Oracle-assigned identifier for the request. Provide this request OCID if you need to contact Oracle about this request.
Root Schema : Error
Type:
object
The properties that define an error.
Show Source
-
code(required):
string
A short error code that defines the error, meant for programmatic parsing..Example:
UnknownError
-
message(required):
string
A human-readable error string.Example:
error validating payload