mirror of
https://github.com/StackExchange/dnscontrol.git
synced 2024-05-11 05:55:12 +00:00
DOCS: Mostly styling and links (#2178)
Co-authored-by: Tom Limoncelli <tal@whatexit.org>
This commit is contained in:
@ -14,7 +14,7 @@ parameter_types:
|
||||
`CF_REDIRECT` uses Cloudflare-specific features ("Forwarding URL" Page Rules) to
|
||||
generate a HTTP 301 permanent redirect.
|
||||
|
||||
If _any_ `CF_REDIRECT` or `CF_TEMP_REDIRECT` functions are used then
|
||||
If _any_ `CF_REDIRECT` or [`CF_TEMP_REDIRECT`](CF_TEMP_REDIRECT.md) functions are used then
|
||||
`dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain.
|
||||
Page Rule types other than "Forwarding URL” will be left alone.
|
||||
|
||||
|
@ -14,7 +14,7 @@ parameter_types:
|
||||
`CF_TEMP_REDIRECT` uses Cloudflare-specific features ("Forwarding URL" Page
|
||||
Rules) to generate a HTTP 302 temporary redirect.
|
||||
|
||||
If _any_ `CF_REDIRECT` or `CF_TEMP_REDIRECT` functions are used then
|
||||
If _any_ [`CF_REDIRECT`](CF_REDIRECT.md) or `CF_TEMP_REDIRECT` functions are used then
|
||||
`dnscontrol` will manage _all_ "Forwarding URL" type Page Rules for the domain.
|
||||
Page Rule types other than "Forwarding URL” will be left alone.
|
||||
|
||||
|
@ -14,8 +14,8 @@ For some registrars this will also add NS records to the zone itself.
|
||||
This takes exactly one argument: the name of the nameserver. It must end with
|
||||
a "." if it is a FQDN, just like all targets.
|
||||
|
||||
This is different than the `NS()` function, which inserts NS records
|
||||
in the current zone and accepts a label. `NS()` is useful for downward
|
||||
This is different than the [`NS()`](NS.md) function, which inserts NS records
|
||||
in the current zone and accepts a label. [`NS()`](NS.md) is useful for downward
|
||||
delegations. `NAMESERVER()` is for informing upstream delegations.
|
||||
|
||||
For more information, refer to [this page](../../nameservers.md).
|
||||
@ -43,7 +43,7 @@ D("example2.com", REGISTRAR, .... ,
|
||||
Nameservers are one of the least
|
||||
understood parts of DNS, so a little extra explanation is required.
|
||||
|
||||
* `NS()` lets you add an NS record to a zone, just like A() adds an A
|
||||
* [`NS()`](NS.md) lets you add an NS record to a zone, just like [`A()`](A.md) adds an A
|
||||
record to the zone. This is generally used to delegate a subzone.
|
||||
|
||||
* The `NAMESERVER()` directive speaks to the Registrar about how the parent should delegate the zone.
|
||||
|
@ -2,13 +2,13 @@
|
||||
name: NO_PURGE
|
||||
---
|
||||
|
||||
NO_PURGE indicates that records should not be deleted from a domain.
|
||||
`NO_PURGE` indicates that records should not be deleted from a domain.
|
||||
Records will be added and updated, but not removed.
|
||||
|
||||
NO_PURGE is generally used in very specific situations:
|
||||
`NO_PURGE` is generally used in very specific situations:
|
||||
|
||||
* A domain is managed by some other system and DNSControl is only used to insert a few specific records and/or keep them updated. For example a DNS Zone that is managed by Active Directory, but DNSControl is used to update a few, specific, DNS records. In this case we want to specify the DNS records we are concerned with but not delete all the other records. This is a risky use of NO_PURGE since, if NO_PURGE was removed (or buggy) there is a chance you could delete all the other records in the zone, which could be a disaster. That said, domains with some records updated using Dynamic DNS have no other choice.
|
||||
* To work-around a pseudo record type that is not supported by DNSControl. For example some providers have a fake DNS record type called "URL" which creates a redirect. DNSControl normally deletes these records because it doesn't understand them. NO_PURGE will leave those records alone.
|
||||
* A domain is managed by some other system and DNSControl is only used to insert a few specific records and/or keep them updated. For example a DNS Zone that is managed by Active Directory, but DNSControl is used to update a few, specific, DNS records. In this case we want to specify the DNS records we are concerned with but not delete all the other records. This is a risky use of `NO_PURGE` since, if `NO_PURGE` was removed (or buggy) there is a chance you could delete all the other records in the zone, which could be a disaster. That said, domains with some records updated using Dynamic DNS have no other choice.
|
||||
* To work-around a pseudo record type that is not supported by DNSControl. For example some providers have a fake DNS record type called "URL" which creates a redirect. DNSControl normally deletes these records because it doesn't understand them. `NO_PURGE` will leave those records alone.
|
||||
|
||||
In this example DNSControl will insert "foo.example.com" into the
|
||||
zone, but otherwise leave the zone alone. Changes to "foo"'s IP
|
||||
@ -23,19 +23,19 @@ D("example.com", .... , NO_PURGE,
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
The main caveat of NO_PURGE is that intentionally deleting records
|
||||
becomes more difficult. Suppose a NO_PURGE zone has an record such
|
||||
The main caveat of `NO_PURGE` is that intentionally deleting records
|
||||
becomes more difficult. Suppose a `NO_PURGE` zone has an record such
|
||||
as A("ken", "1.2.3.4"). Removing the record from dnsconfig.js will
|
||||
not delete "ken" from the domain. DNSControl has no way of knowing
|
||||
the record was deleted from the file The DNS record must be removed
|
||||
manually. Users of NO_PURGE are prone to finding themselves with
|
||||
manually. Users of `NO_PURGE` are prone to finding themselves with
|
||||
an accumulation of orphaned DNS records. That's easy to fix for a
|
||||
small zone but can be a big mess for large zones.
|
||||
|
||||
Not all providers support NO_PURGE. For example the BIND provider
|
||||
Not all providers support `NO_PURGE`. For example the BIND provider
|
||||
rewrites zone files from scratch each time, which precludes supporting
|
||||
NO_PURGE. DNSControl will exit with an error if NO_PURGE is used
|
||||
`NO_PURGE`. DNSControl will exit with an error if `NO_PURGE` is used
|
||||
on a driver that does not support it.
|
||||
|
||||
There is also `PURGE` command for completeness. `PURGE` is the
|
||||
There is also [`PURGE`](PURGE.md) command for completeness. [`PURGE`](PURGE.md) is the
|
||||
default, thus this command is a no-op.
|
||||
|
@ -53,7 +53,7 @@ are all equivalent:
|
||||
* `PTR('4.3',` // Assuming the domain is `2.1.in-addr.arpa`
|
||||
|
||||
All magic is RFC2317-aware. We use the first format listed in the
|
||||
RFC for both `REV()` and `PTR()`. The format is
|
||||
RFC for both [`REV()`](../global/REV.md) and `PTR()`. The format is
|
||||
`FIRST/MASK.C.B.A.in-addr.arpa` where `FIRST` is the first IP address
|
||||
of the zone, `MASK` is the netmask of the zone (25-31 inclusive),
|
||||
and A, B, C are the first 3 octets of the IP address. For example
|
||||
@ -91,6 +91,6 @@ D(REV('2001:db8:302::/48'), REGISTRAR, DnsProvider(BIND),
|
||||
```
|
||||
{% endcode %}
|
||||
|
||||
In the future we plan on adding a flag to `A()` which will insert
|
||||
In the future we plan on adding a flag to [`A()`](A.md)which will insert
|
||||
the correct PTR() record if the appropriate `.arpa` domain has been
|
||||
defined.
|
||||
|
@ -2,15 +2,15 @@
|
||||
name: PURGE
|
||||
---
|
||||
|
||||
PURGE is the default setting for all domains. Therefore PURGE is
|
||||
`PURGE` is the default setting for all domains. Therefore `PURGE` is
|
||||
a no-op. It is included for completeness only.
|
||||
|
||||
A domain with a mixture of NO_PURGE and PURGE parameters will abide
|
||||
A domain with a mixture of `NO_PURGE` and `PURGE` parameters will abide
|
||||
by the last one.
|
||||
|
||||
These three examples all are equivalent.
|
||||
|
||||
PURGE is the default:
|
||||
`PURGE` is the default:
|
||||
|
||||
{% code title="dnsconfig.js" %}
|
||||
```javascript
|
||||
|
@ -11,9 +11,9 @@ parameter_types:
|
||||
provider: ROUTE53
|
||||
---
|
||||
|
||||
R53_ALIAS is a Route53 specific virtual record type that points a record at either another record or an AWS entity (like a Cloudfront distribution, an ELB, etc...). It is analogous to a CNAME, but is usually resolved at request-time and served as an A record. Unlike CNAMEs, ALIAS records can be used at the zone apex (`@`)
|
||||
`R53_ALIAS` is a Route53 specific virtual record type that points a record at either another record or an AWS entity (like a Cloudfront distribution, an ELB, etc...). It is analogous to a `CNAME`, but is usually resolved at request-time and served as an `A` record. Unlike `CNAME` records, `ALIAS` records can be used at the zone apex (`@`)
|
||||
|
||||
Unlike the regular ALIAS directive, R53_ALIAS is only supported on Route53. Attempting to use R53_ALIAS on another provider than Route53 will result in an error.
|
||||
Unlike the regular [`ALIAS`](ALIAS.md) directive, `R53_ALIAS` is only supported on Route53. Attempting to use `R53_ALIAS` on another provider than Route53 will result in an error.
|
||||
|
||||
The name should be the relative label for the domain.
|
||||
|
||||
@ -22,7 +22,7 @@ Target should be a string representing the target. If it is a single label we wi
|
||||
The Target can be any of:
|
||||
|
||||
* _CloudFront distribution_: in this case specify the domain name that CloudFront assigned when you created your distribution (note that your CloudFront distribution must include an alternate domain name that matches the record you're adding)
|
||||
* _Elastic Beanstalk environment_: specify the CNAME attribute for the environment. The environment must have a regionalized domain name. To get the CNAME, you can use either the [AWS Console](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/customdomains.html), [AWS Elastic Beanstalk API](http://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_DescribeEnvironments.html), or the [AWS CLI](http://docs.aws.amazon.com/cli/latest/reference/elasticbeanstalk/describe-environments.html).
|
||||
* _Elastic Beanstalk environment_: specify the `CNAME` attribute for the environment. The environment must have a regionalized domain name. To get the `CNAME`, you can use either the [AWS Console](http://docs.aws.amazon.com/elasticbeanstalk/latest/dg/customdomains.html), [AWS Elastic Beanstalk API](http://docs.aws.amazon.com/elasticbeanstalk/latest/api/API_DescribeEnvironments.html), or the [AWS CLI](http://docs.aws.amazon.com/cli/latest/reference/elasticbeanstalk/describe-environments.html).
|
||||
* _ELB load balancer_: specify the DNS name that is associated with the load balancer. To get the DNS name you can use either the AWS Console (on the EC2 page, choose Load Balancers, select the right one, choose the description tab), [ELB API](http://docs.aws.amazon.com/elasticloadbalancing/latest/APIReference/API_DescribeLoadBalancers.html), the [AWS ELB CLI](http://docs.aws.amazon.com/cli/latest/reference/elb/describe-load-balancers.html), or the [AWS ELBv2 CLI](http://docs.aws.amazon.com/cli/latest/reference/elbv2/describe-load-balancers.html).
|
||||
* _S3 bucket_ (configured as website): specify the domain name of the Amazon S3 website endpoint in which you configured the bucket (for instance s3-website-us-east-2.amazonaws.com). For the available values refer to the [Amazon S3 Website Endpoints](http://docs.aws.amazon.com/general/latest/gr/rande.html#s3_region).
|
||||
* _Another Route53 record_: specify the value of the name of another record in the same hosted zone.
|
||||
|
@ -37,4 +37,4 @@ The email address should be specified like a normal RFC822/RFC5322 address (user
|
||||
* The serial number is managed automatically. It isn't even a field in `SOA()`.
|
||||
* Most providers automatically generate SOA records. They will ignore any `SOA()` statements.
|
||||
|
||||
There is more info about SOA in the documentation for the [BIND provider](../../providers/bind.md).
|
||||
There is more info about `SOA` in the documentation for the [BIND provider](../../providers/bind.md).
|
||||
|
@ -14,7 +14,7 @@ parameter_types:
|
||||
"modifiers...": RecordModifier[]
|
||||
---
|
||||
|
||||
SSHFP contains a fingerprint of a SSH server which can be validated before SSH clients are establishing the connection.
|
||||
`SSHFP` contains a fingerprint of a SSH server which can be validated before SSH clients are establishing the connection.
|
||||
|
||||
**Algorithm** (type of the key)
|
||||
|
||||
|
@ -16,7 +16,7 @@ parameter_types:
|
||||
"modifiers...": RecordModifier[]
|
||||
---
|
||||
|
||||
TLSA adds a TLSA record to a domain. The name should be the relative label for the record.
|
||||
`TLSA` adds a `TLSA` record to a domain. The name should be the relative label for the record.
|
||||
|
||||
Usage, selector, and type are ints.
|
||||
|
||||
|
@ -10,7 +10,7 @@ parameter_types:
|
||||
"modifiers...": RecordModifier[]
|
||||
---
|
||||
|
||||
TXT adds an TXT record To a domain. The name should be the relative
|
||||
`TXT` adds an `TXT` record To a domain. The name should be the relative
|
||||
label for the record. Use `@` for the domain apex.
|
||||
|
||||
The contents is either a single or multiple strings. To
|
||||
@ -49,7 +49,7 @@ if it does not handle multiple strings.
|
||||
|
||||
### TXT record edge cases
|
||||
|
||||
Most providers do not support the full possibilities of what a TXT
|
||||
Most providers do not support the full possibilities of what a `TXT`
|
||||
record can store. DNSControl can not handle all the edge cases
|
||||
and incompatibles that providers have introduced. Instead, it
|
||||
stores the string(s) that you provide and passes them to the provider
|
||||
@ -57,14 +57,14 @@ verbatim. The provider may opt to accept the data, fix it, or
|
||||
reject it. This happens early in the processing, long before
|
||||
the DNSControl talks to the provider's API.
|
||||
|
||||
The RFCs specify that a TXT record stores one or more strings,
|
||||
The RFCs specify that a `TXT` record stores one or more strings,
|
||||
each is up to 255 octets (bytes) long. We call these individual
|
||||
strings *chunks*. Each chunk may be zero to 255 octets long.
|
||||
There is no limit to the number of chunks in a TXT record,
|
||||
There is no limit to the number of chunks in a `TXT` record,
|
||||
other than IP packet length restrictions. The contents of each chunk
|
||||
may be octets of value from 0x00 to 0xff.
|
||||
|
||||
In reality DNS Service Providers (DSPs) place many restrictions on TXT
|
||||
In reality DNS Service Providers (DSPs) place many restrictions on `TXT`
|
||||
records.
|
||||
|
||||
Some DSPs only support a single string of 255 octets or fewer.
|
||||
@ -87,7 +87,7 @@ double quotes, back-ticks, or other chars.
|
||||
|
||||
#### How can you tell if a provider will support a particular `TXT()` record?
|
||||
|
||||
Include the `TXT()` record in a `D()` as usual, along
|
||||
Include the `TXT()` record in a [`D()`](../global/D.md) as usual, along
|
||||
with the `DnsProvider()` for that provider. Run `dnscontrol check` to
|
||||
see if any errors are produced. The check command does not talk to
|
||||
the provider's API, thus permitting you to do this without having an
|
||||
|
Reference in New Issue
Block a user