1
0
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:
Paul Dee
2023-03-15 23:43:57 +01:00
committed by GitHub
parent 81054e72c5
commit 731181ffa1
24 changed files with 186 additions and 110 deletions

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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.

View File

@ -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

View File

@ -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.

View File

@ -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).

View File

@ -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)

View File

@ -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.

View File

@ -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