From 355fce1f4ea0f95277a63e8e8808ef574e57b88a Mon Sep 17 00:00:00 2001 From: Pieter Lexis Date: Thu, 7 Jan 2016 20:07:41 +0100 Subject: [PATCH] Remove internals.md, move content to better places --- docs/manpages/pdns_control.1.md | 22 +-- docs/markdown/authoritative/backend-remote.md | 2 +- docs/markdown/authoritative/howtos.md | 50 +++++- docs/markdown/authoritative/index.md | 1 - docs/markdown/authoritative/internals.md | 152 ------------------ .../authoritative/modes-of-operation.md | 4 +- docs/markdown/authoritative/performance.md | 2 +- docs/markdown/authoritative/running.md | 92 ++++++++++- docs/markdown/authoritative/settings.md | 47 ++++-- docs/markdown/changelog.raw.md | 10 +- docs/mkdocs.yml | 1 - 11 files changed, 190 insertions(+), 193 deletions(-) delete mode 100644 docs/markdown/authoritative/internals.md diff --git a/docs/manpages/pdns_control.1.md b/docs/manpages/pdns_control.1.md index a785fcfbf..0cc96206e 100644 --- a/docs/manpages/pdns_control.1.md +++ b/docs/manpages/pdns_control.1.md @@ -42,7 +42,9 @@ ccounts : Show the content of the cache. current-config -: Show the currently running configuration. +: Show the currently running configuration. The output has the same format as + `pdns_server --config`. You'll notice that all the are uncommented. This is + because PowerDNS simply has values, and the default isn't known at runtime. cycle : Restart the nameserver so it reloads its configuration. Only works when the @@ -56,12 +58,12 @@ list-zones [master,slave,native] : Show a list of zones, optionally filter on the type of zones to show. notify *DOMAIN* -: Adds *DOMAIN* to the notification list, causing PDNS to send out +: Adds *DOMAIN* to the notification list, causing PowerDNS to send out notifications to the nameservers of a domain. Can be used if a slave missed previous notifications or is generally hard of hearing. -notify-host *DOMAIN* *HOST* -: Same as above but with operator specified IP address as destination, to be +notify-host *DOMAIN* *ADDRESS* +: Same as above but with operator specified IP *ADDRESS* as destination, to be used if you know better than PowerDNS. ping, rping @@ -70,12 +72,12 @@ ping, rping running without a guardian. purge [*RECORD*] -: Purge entries from the packet cache. If *RECORD* ends with a dollar ($) +: Purge entries from the cache. If *RECORD* ends with a dollar ($) all entries that end with that name are removed. If no record is specified the entire cache is purged. qtypes -: Get a count of queries per qtype. +: Get a count of queries per qtype on standard out. quit : Tell a running pdns_server to quit. @@ -85,10 +87,10 @@ rediscover in the case of the Bind backend, in named.conf. reload -: Instruct the server to reload all its zones. +: Instruct the server to reload all its zones, this will not add new zones. remotes -: Get the top number of remote addresses. +: Get the top number of remote addresses (clients). respsizes : Get a histogram of the response sizes. @@ -108,7 +110,9 @@ status mode. token-login *MODULE* *SLOT* *PIN* -: Log on to a PKCS#11 slot. +: Log on to a PKCS#11 slot. You only need to login once per slot, even if you + have multiple keys on single slot. Only available if PowerDNS was compiled + with PKCS#11 support. uptime : Show the uptime of the running server. diff --git a/docs/markdown/authoritative/backend-remote.md b/docs/markdown/authoritative/backend-remote.md index 7f898131d..ec25ad782 100644 --- a/docs/markdown/authoritative/backend-remote.md +++ b/docs/markdown/authoritative/backend-remote.md @@ -312,7 +312,7 @@ Content-Type: text/javascript; charset=utf-8 ``` ### `getDomainKeys` -Retrieves any keys of kind. The id, flags are unsigned integers, and active is boolean. Content must be valid key record in format that PowerDNS understands. You are encouraged to implement [the section called "addDomainKey"](#adddomainkey), as you can use [`pdnsutil`](internals.md#pdnsutil) to provision keys. +Retrieves any keys of kind. The id, flags are unsigned integers, and active is boolean. Content must be valid key record in format that PowerDNS understands. You are encouraged to implement [the section called "addDomainKey"](#adddomainkey), as you can use [`pdnsutil`](../manpages/pdnsutil.1.md) to provision keys. * Mandatory: for DNSSEC * Parameters: name, kind diff --git a/docs/markdown/authoritative/howtos.md b/docs/markdown/authoritative/howtos.md index 7b4d98f8b..fb9af359d 100644 --- a/docs/markdown/authoritative/howtos.md +++ b/docs/markdown/authoritative/howtos.md @@ -100,7 +100,7 @@ $ dig +short example.com MX @127.0.0.1 25 mail.example.com ``` -To confirm what happened, issue the command [`SHOW *`](internals.md#show-variable) to the control console: +To confirm what happened, issue the command `SHOW *` to the control console: ``` % show * @@ -205,3 +205,51 @@ show only the DS records for the new KSK, you may disable sending out the CDS responses: `pdnsutil unset-pushish-cds example.com`. Done! + +# Adding new DNS record types +Here are the full descriptions on how we added the TLSA record type to all +PowerDNS products, with links to the actual source code. + +First, define the TLSARecordContent class in [dnsrecords.hh](https://github.com/PowerDNS/pdns/blob/5a3409cbb4314b84f1171a69c7337386568fa886/pdns/dnsrecords.hh#L396): + +``` +class TLSARecordContent : public DNSRecordContent +{ +public: + includeboilerplate(TLSA) + +private: + uint8_t d_certusage, d_selector, d_matchtype; + string d_cert; +}; +``` + +The `includeboilerplate(TLSA)` macro generates the four methods that do everything +PowerDNS would ever want to do with a record: + +- read TLSA records from zonefile format +- write out a TLSA record in zonefile format +- read a TLSA record from a packet +- write a TLSA record to a packet + +The [actual parsing code](https://github.com/PowerDNS/pdns/blob/5a3409cbb4314b84f1171a69c7337386568fa886/pdns/dnsrecords.cc#L304): + +``` +boilerplate_conv(TLSA, 52, + conv.xfr8BitInt(d_certusage); + conv.xfr8BitInt(d_selector); + conv.xfr8BitInt(d_matchtype); + conv.xfrHexBlob(d_cert, true); + ) +``` + +This code defines the TLSA rrtype number as 52. Secondly, it says there are 3 +eight bit fields for Certificate Usage, Selector and Match type. Next, it defines +that the rest of the record is the actual certificate (hash). +['conv'](https://github.com/PowerDNS/pdns/blob/5a3409cbb4314b84f1171a69c7337386568fa886/pdns/dnsparser.hh#L68) +methods are supplied for all DNS data types in use. + +Now add `TLSARecordContent::report()` to [`reportOtherTypes()`](https://github.com/PowerDNS/pdns/blob/5a3409cbb4314b84f1171a69c7337386568fa886/pdns/dnsrecords.cc#L594). + +And that's it. For completeness, add TLSA and 52 to the QType enum in [`qtype.hh`](https://github.com/PowerDNS/pdns/blob/5a3409cbb4314b84f1171a69c7337386568fa886/pdns/qtype.hh#L116), +which makes it easier to refer to the TLSA record in code if so required. diff --git a/docs/markdown/authoritative/index.md b/docs/markdown/authoritative/index.md index 9e7729d7b..d57c4fe22 100644 --- a/docs/markdown/authoritative/index.md +++ b/docs/markdown/authoritative/index.md @@ -6,7 +6,6 @@ Examples of backends include relational databases, other DNS data formats and co # Backends PowerDNS has the concepts of 'backends'. A backend is a datastore that the server will consult that contains DNS records (and some meta-data). The backends range from database backends (Mysql, PostgreSQL, Oracle) and Bind-zonefiles to co-processes and JSON API's. -For more in-depth information, see [Modules & Backends](internals.md#modules-backends) in the documentation on internals. Multiple backends can be enabled in the configuration by using the [`launch`](settings.md#launch) option. Each backend can be configured separetly. diff --git a/docs/markdown/authoritative/internals.md b/docs/markdown/authoritative/internals.md deleted file mode 100644 index d638cd25d..000000000 --- a/docs/markdown/authoritative/internals.md +++ /dev/null @@ -1,152 +0,0 @@ -# PowerDNS Internals -PowerDNS is normally launched by the init.d script but is actually a binary called `pdns_server`. This file is started by the **start** and **monitor** commands to the init.d script. Other commands are implemented using the controlsocket. - -# Controlsocket -The controlsocket is the means to contact a running PDNS daemon, or as we now know, a running `pdns_server`. Over this sockets, instructions can be sent using the `pdns_control` program. Like the `pdns_server`, this program is normally accessed via the init.d script. - -# `pdns_control` -To communicate with PowerDNS Authoritative Server over the controlsocket, the `pdns_control` command is used. The init.d script also calls pdns\_control. The syntax is simple: `pdns_control command arguments`. Currently this is most useful for telling backends to rediscover domains or to force the transmission of notifications. See [Master](../authoritative/modes-of-operation.md#master). - -Besides the commands implemented by the init.d script, for which see [Running The Authoritative Server](../authoritative/installation.md), the following `pdns_control` commands are available: - -## `ccounts` -Returns counts on the contents of the cache. - -## `current-config` -Retrieves the current configuration settings from the Authoritative Server instance. This can be useful to generate a from a running instance. - -The output has the same format as `pdns_server --config`. You'll notice that all the are uncommented. This is because PowerDNS simply has values, and the default isn't known at runtime. - -## `cycle` -Restart a PowerDNS instance. Only available when running in guardian mode. - -## `notify DOMAIN` -Adds a domain to the notification list, causing PowerDNS to send out notifications to the nameservers of a domain. Can be used if a slave missed previous notifications or is generally hard of hearing. Use * to send notifications for all (type=MASTER) zones to all slaves. - -## `notify-host DOMAIN HOST` -Same as above but with operator specified IP address as destination, to be used if you know better than PowerDNS. - -## `ping` -'PING' the powerdns-guardian. Will return 'PONG' when it is available. (Only works when you are running in guardian mode) - -## `purge` -Purges the entire Packet Cache - see [Authoritative Server Performance](../authoritative/performance.md). - -## `purge RECORD` -Purges all entries for this exact record name - see [Authoritative Server Performance](../authoritative/performance.md). - -## `purge RECORD` -Purges all cache entries ending on this name, effectively purging an entire domain - see [Authoritative Server Performance](../authoritative/performance.md). - -## `purge` -Purges the entire Packet Cache - see [Authoritative Server Performance](../authoritative/performance.md). - -## `rping` -'PING' the powerdns-instance. Will return 'PONG' when it is available. - -## `rediscover` -Instructs backends that new domains may have appeared in the database, or, in the case of the Bind backend, in named.conf. - -## `reload` -Instructs backends that the contents of domains may have changed. Many backends ignore this, the Bind backend will check timestamps for all zones (once queries come in for it) and reload if needed. - -## `retrieve DOMAIN` -Retrieve a slave domain from its master. Done nearly immediately. - -## `set VARIABLE VALUE` -Set a configuration parameter. Currently only the 'query-logging' parameter can be set. - -## `token-login MODULE SLOT PIN` -Logs on to a PKCS#11 slot. You only need to login once per slot, even if you have multiple keys on single slot. - -## `uptime` -Reports the uptime of the daemon in human readable form. - -## `show VARIABLE` -Show a specific statistic. Use * for all. (You may need to quote as '\*' or \\\*). - -## `version` -Returns the version of a running pdns daemon. - -## `status` -Retrieves the status of PowerDNS. Only available when running with guardian. - -# Guardian -When launched by the init.d script, `pdns_server` wraps itself inside a 'guardian'. This guardian monitors the performance of the inner `pdns_server` instance which shows up in the process list of your OS as `pdns_server-instance`. It is also this guardian that `pdns_control` talks to. A **STOP** is interpreted by the guardian, which causes the guardian to sever the connection to the inner process and terminate it, after which it terminates itself. The init.d script **DUMP** and **SHOW** commands need to access the inner process, because the guardian itself does not run a nameserver. For this purpose, the guardian passes controlsocket requests to the control console of the inner process. This is the same console as seen with init.d **MONITOR**. - -# Modules & Backends -PowerDNS Authoritative Server has the concept of backends and modules. Non-static PowerDNS distributions have the ability to load new modules at runtime, while the static versions come with a number of modules built in, but cannot load more. - -## Related Parameters -### `--help` -Outputs all known parameters, including those of launched backends, see below. - -### `--launch=backend,backend1,backend1:name` -Launches backends. In its most simple form, supply all backends that need to be launched. If you find that you need to launch single backends multiple times, you can specify a name for later instantiations. In this case, there are 2 instances of backend1, and the second one is called 'name'. This means that `--backend1-setting` is available to configure the first or main instance, and `--backend1-name-setting` for the second one. - -### `--load-modules=/directory/libyourbackend.so` -If backends are available in nonstandard directories, specify their location here. Multiple files can be loaded if separated by commas. Only available in non-static distributions. - -### `--list-modules` -Will list all available modules, both compiled in and in dynamically loadable modules. - -To run on the command line, use the `pdns_server` binary. For example, to see options for the gpgsql backend, use the following: - -``` - $ /usr/sbin/pdns_server --launch=gpgsql --help=gpgsql -``` - -# How PowerDNS translates DNS queries into backend queries -A DNS query is not a straightforward lookup. Many DNS queries need to check the backend for additional data, for example to determine if an unfound record should lead to an NXDOMAIN ('we know about this domain, but that record does not exist') or an unauthoritative response. - -Simplified, without CNAME processing, wildcards, referrals and DNSSEC, the algorithm is like this: - -When a query for a `qname`/`qtype` tuple comes in, PowerDNS queries backends to find the closest matching SOA, thus figuring out what backend owns this zone. When the right backend has been found, PowerDNS issues a `qname`/`ANY` query to the backend. If the response is empty, NXDOMAIN is concluded. If the response is not empty, any contents matching the original qtype are added to the list of records to return, and NOERROR is set. - -Each of these records is now investigated to see if it needs 'additional processing'. This holds for example for MX records which may point to hosts for which the PowerDNS backends also contain data. This involves further lookups for A or AAAA records. - -After all additional processing has been performed, PowerDNS sieves out all double records which may well have appeared. The resulting set of records is added to the answer packet, and sent out. - -A zone transfer works by looking up the `domain_id` of the SOA record of the name and then listing all records of that `domain_id`. This is why all records in a domain need to have the same domain\_id. - -If no SOA was found, an unauthoritative no-error is returned. - -PowerDNS (before 3.0) broke strict RFC compatibility by not always checking for the presence of a SOA record first. This was unlikely to lead to problems though. - -# Adding new DNS record types -Here are the full descriptions on how we added the TLSA record type to all PowerDNS products, with links to the actual source code. - -First, define the TLSARecordContent class in [dnsrecords.hh](http://wiki.powerdns.com/trac/browser/trunk/pdns/pdns/dnsrecords.hh?rev=2338#L307): - -``` -class TLSARecordContent : public DNSRecordContent -{ -public: - includeboilerplate(TLSA) - uint8_t d_certusage, d_selector, d_matchtype; - string d_cert; -}; -``` - -The 'includeboilerplate(TLSA)' generates the four methods that do everything PowerDNS would ever want to do with a record: -- read TLSA records from zonefile format -- write out a TLSA record in zonefile format -- read a TLSA record from a packet -- write a TLSA record to a packet - -The [actual parsing code](http://wiki.powerdns.com/trac/browser/trunk/pdns/pdns/dnsrecords.cc?rev=2638#L226): - -``` -boilerplate_conv(TLSA, 52, - conv.xfr8BitInt(d_certusage); - conv.xfr8BitInt(d_selector); - conv.xfr8BitInt(d_matchtype); - conv.xfrHexBlob(d_cert, true); - ) -``` - -This code defines the TLSA rrtype number as 52. Secondly, it says there are 3 eight bit fields for Certificate Usage, Selector and Match type. Next, it defines that the rest of the record is the actual certificate (hash). ['conv'](http://wiki.powerdns.com/trac/browser/trunk/pdns/pdns/dnsparser.hh?rev=2338#L70) methods are supplied for all DNS data types in use. - -Now add TLSRecordContent::report() to [reportOtherTypes()](http://wiki.powerdns.com/trac/browser/trunk/pdns/pdns/dnsrecords.cc?rev=2338#L364). - -And that's it. For completeness, add TLSA and 52 to the QType enum in qtype.hh, which makes it easier to refer to the TLSA record in code if so required. diff --git a/docs/markdown/authoritative/modes-of-operation.md b/docs/markdown/authoritative/modes-of-operation.md index 83b788c78..c4a450c27 100644 --- a/docs/markdown/authoritative/modes-of-operation.md +++ b/docs/markdown/authoritative/modes-of-operation.md @@ -46,7 +46,7 @@ documentation for your backend to see how it processes changes in zones. To help deal with slaves that may have missed notifications, or have failed to respond to them, several override commands are available via the -[`pdns_control`](../authoritative/internals.md#pdnscontrol) tool: +[`pdns_control`](../authoritative/running.md#pdnscontrol) tool: * `pdns_control notify ` This instructs PDNS to notify all IP addresses it considers to be slaves of this domain. @@ -77,7 +77,7 @@ with either BerkeleyDB or InnoDB meets this requirement, as do PostgreSQL and Oracle. The Bindbackend implements transaction semantics by renaming files if and only if they have been retrieved completely and parsed correctly. -Slave operation can also be programmed using several [`pdns_control`](internals.md#pdnscontrol) +Slave operation can also be programmed using several [`pdns_control`](running.md#pdnscontrol) commands. The `retrieve` command is especially useful as it triggers an immediate retrieval of the zone from the configured master. diff --git a/docs/markdown/authoritative/performance.md b/docs/markdown/authoritative/performance.md index 16a8720b6..bdc5b2ffd 100644 --- a/docs/markdown/authoritative/performance.md +++ b/docs/markdown/authoritative/performance.md @@ -14,7 +14,7 @@ This is done with the [`distributor-threads`](settings.md#distributor-threads) s Another very important setting is [`cache-ttl`](settings.md#cache-ttl). PDNS caches entire packets it sends out so as to save the time to query backends to assemble all data. The default setting of 20 seconds may be low for high traffic sites, a value of 60 seconds rarely leads to problems. -Some PDNS operators set cache-ttl to many hours or even days, and use [`pdns_control`](internals.md#pdns_control)` purge` to selectively or globally notify PDNS of changes made in the backend. Also look at the [Query Cache](#query-cache) described in this chapter. It may materially improve your performance. +Some PDNS operators set cache-ttl to many hours or even days, and use [`pdns_control`](running.md#pdns_control)` purge` to selectively or globally notify PDNS of changes made in the backend. Also look at the [Query Cache](#query-cache) described in this chapter. It may materially improve your performance. To determine if PDNS is unable to keep up with packets, determine the value of the [`qsize-q`](../common/logging.md#counters) variable. This represents the number of packets waiting for database attention. During normal operations the queue should be small. diff --git a/docs/markdown/authoritative/running.md b/docs/markdown/authoritative/running.md index 2349bf6be..3536fb141 100644 --- a/docs/markdown/authoritative/running.md +++ b/docs/markdown/authoritative/running.md @@ -1,4 +1,4 @@ -# Running PowerDNS +# Running and Operating PowerDNS PDNS is normally controlled via a SysV-style init.d script, often located in `/etc/init.d` or `/etc/rc.d/init.d`. For Linux distributions with systemd, a service file is provided (either in the package or in the contrib directory of @@ -7,10 +7,42 @@ the tarball). Furthermore, PowerDNS can be run on the foreground for testing or in other init- systems that supervise processes. -# SysV init +## Guardian +When the init-system of the Operating System does not properly supervises processes, +like SysV init, it is recommended to run PowerDNS with the [`guardian`](settings.md#guardian) +option set to 'yes'. + +When launched with `guardian=yes`, `pdns_server` wraps itself inside a 'guardian'. +This guardian monitors the performance of the inner `pdns_server` instance which +shows up in the process list of your OS as `pdns_server-instance`. It is also +this guardian that [`pdns_control`](#pdns_control) talks to. A **STOP** is +interpreted by the guardian, which causes the guardian to sever the connection +to the inner process and terminate it, after which it terminates itself. Requests +that require data from the actual nameserver are passed to the inner process as well. + +# Controlling A Running PowerDNS Server +As a DNS server is critical infrastructure, downtimes should be avoided as much +as possible. Even though PowerDNS (re)starts very fast, it offers a way to +control it while running. + +## Control Socket +The controlsocket is the means to contact a running PowerDNS process. Over this +socket, instructions can be sent using the `pdns_control` program. The control +socket is called `pdns.controlsocket` and is created inside the [`socket-dir`](settings.md#socket-dir). + +## `pdns_control` +To communicate with PowerDNS Authoritative Server over the controlsocket, the +`pdns_control` command is used. The syntax is simple: `pdns_control command arguments`. +Currently this is most useful for telling backends to rediscover domains or to +force the transmission of notifications. See [Master Operation](../authoritative/modes-of-operation.md#master-operation). + +For all supported `pdns_control` commands and options, see [the manpage](../manpages/pdns_control.1) +and the output of `pdns_control --help` on your system. + +# The SysV init This script supplied with the PowerDNS source accepts the following commands: -* `monitor`: Monitor is a special way to view the daemon. It executes PDNS in the foreground with a lot of logging turned on, which helps in determining startup problems. Besides running in the foreground, the raw PDNS control socket is made available. All external communication with the daemon is normally sent over this socket. While useful, the control console is not an officially supported feature. Commands which work are: `QUIT`, [`SHOW *`](internals.md#show-variable), `SHOW varname`, [`RPING`](internals.md#rping). +* `monitor`: Monitor is a special way to view the daemon. It executes PDNS in the foreground with a lot of logging turned on, which helps in determining startup problems. Besides running in the foreground, the raw PDNS control socket is made available. All external communication with the daemon is normally sent over this socket. While useful, the control console is not an officially supported feature. Commands which work are: `QUIT`, `SHOW *`, `SHOW varname`, `RPING`. * `start`: Start PDNS in the background. Launches the daemon but makes no special effort to determine success, as making database connections may take a while. Use `status` to query success. You can safely run `start` many times, it will not start additional PDNS instances. * `restart`: Restarts PDNS if it was running, starts it otherwise. * `status`: Query PDNS for status. This can be used to figure out if a launch was successful. The status found is prefixed by the PID of the main PDNS process. @@ -37,3 +69,57 @@ pdns_server --no-config --daemon=no --local-port=5300 --launch=gmysql --gmysql-u This starts PowerDNS without loading on-disk config, in the foreground, on all network interfaces on port 5300 and starting the [gmysql](backend-generic-mysql.md) backend. + +## Commandline Parameters +There are several important command-line switches for `pdns_server`. All [settings](settings.md) +can also be added as a commandline option (e.g. `pdns_server --daemon=no`) and +will overwrite any options set in pdns.conf. + +### `--help` +Outputs all known parameters, including those of launched backends, see below. + +To run on the command line, use the `pdns_server` binary. For example, to see +options for the gpgsql backend, use the following: + +``` + $ /usr/sbin/pdns_server --launch=gpgsql --help=gpgsql +``` + +### `--list-modules` +Will list all available modules, both compiled in and in dynamically loadable modules. + +### `--config` +This will dump the config to standard out. Should you combine this with e.g. a +[`launch`](settings.md#launch) statement (`pdns_server --launch=gpgsql --config`), +all settings related to that backend (and their defaults) are included in the dump. + +# Internals +## How PowerDNS translates DNS queries into backend queries +A DNS query is not a straightforward lookup. Many DNS queries need to check the +backend for additional data, for example to determine if an unfound record should +lead to an NXDOMAIN ('we know about this domain, but that record does not exist') +or an unauthoritative response. + +Simplified, without CNAME processing, wildcards, referrals and DNSSEC, the +algorithm is like this: + +When a query for a `qname`/`qtype` tuple comes in, PowerDNS queries backends to +find the closest matching SOA, thus figuring out what backend owns this zone. +When the right backend has been found, PowerDNS issues a `qname`/`ANY` query to +the backend. If the response is empty, NXDOMAIN is concluded. If the response is +not empty, any contents matching the original qtype are added to the list of +records to return, and NOERROR is set. + +Each of these records is now investigated to see if it needs 'additional processing'. +This holds for example for MX records which may point to hosts for which the PowerDNS +backends also contain data. This involves further lookups for A or AAAA records. + +After all additional processing has been performed, PowerDNS sieves out all +double records which may well have appeared. The resulting set of records is +added to the answer packet, and sent out. + +A zone transfer works by looking up the `domain_id` of the SOA record of the +name and then listing all records of that `domain_id`. This is why all records +in a domain need to have the same domain\_id. + +If no SOA was found, a REFUSED is returned. diff --git a/docs/markdown/authoritative/settings.md b/docs/markdown/authoritative/settings.md index ad9918979..cc9b02162 100644 --- a/docs/markdown/authoritative/settings.md +++ b/docs/markdown/authoritative/settings.md @@ -161,7 +161,7 @@ Operate as a daemon. * Default: rsasha256 The algorithm that should be used for the KSK when running -[`pdnsutil secure-zone`](internals.md#pdnsutil). +[`pdnsutil secure-zone`](../manpages/pdnsutil.1.md). Must be one of: * rsamd5 * dh @@ -180,7 +180,7 @@ Must be one of: * Default: whichever is default for `default-ksk-algorithms` The default keysize for the KSK generated with -[`pdnsutil secure-zone`](internals.md#pdnsutil). +[`pdnsutil secure-zone`](../manpages/pdnsutil.1.md). ## `default-soa-name` * String @@ -218,7 +218,7 @@ TTL to use when none is provided. * Default: rsasha256 The algorithm that should be used for the ZSK when running -[`pdnsutil secure-zone`](internals.md#pdnsutil). +[`pdnsutil secure-zone`](../manpages/pdnsutil.1.md). Must be one of: * rsamd5 * dh @@ -237,7 +237,7 @@ Must be one of: * Default: whichever is default for `default-zsk-algorithms` The default keysize for the ZSK generated with -[`pdnsutil secure-zone`](internals.md#pdnsutil). +[`pdnsutil secure-zone`](../manpages/pdnsutil.1.md). ## `direct-dnskey` * Boolean @@ -321,10 +321,7 @@ Forward DNS updates sent to a slave to the master. * Boolean * Default: no -Run within a guardian process. See ["Guardian"](internals.md#guardian). - -## `help` -Provide a helpful message +Run within a guardian process. See ["Guardian"](running.md#guardian). ## `include-dir` * Path @@ -335,8 +332,24 @@ loaded in order using `POSIX` as locale. ## `launch` * Backend names, separated by commas -Which backends to launch and order to query them in. See -["Modules & Backends"](internals.md#modules-backends). +Which backends to launch and order to query them in. Launches backends. In its +most simple form, supply all backends that need to be launched. e.g. + +``` +launch=bind,gmysql,remote +``` + +If you find that you need to a backend multiple times with different configuration, +you can specify a name for later instantiations. e.g.: + +``` +launch=gmysql,gmysql:server2 +``` + +In this case, there are 2 instances of the gmysql backend, one by the normal name +and the second one is called 'server2'. The backend configuration item names +change: e.g. `gmysql-host` is available to configure the `host` setting of the +first or main instance, and `gmysql-server2-host` for the second one. ## `lazy-recursion` * Boolean @@ -346,10 +359,11 @@ Which backends to launch and order to query them in. See Check local data first before recursing. See ["Recursion"](recursion.md). ## `load-modules` -* Path +* Paths, seperated by commas -Load this module - supply absolute or relative path. See -["Modules & Backends"](internals.md#modules-backends). +If backends are available in nonstandard directories, specify their location here. +Multiple files can be loaded if separated by commas. Only available in non-static +distributions. ## `local-address` * IPv4 Addresses, separated by commas or whitespace @@ -479,8 +493,7 @@ Allow this many incoming TCP DNS connections simultaneously. ## `module-dir` * Path -Directory for modules. See ["Modules and Backends"](internals.md#modules-backends). -Default depends on `PKGLIBDIR` during compile-time. +Directory for modules. Default depends on `PKGLIBDIR` during compile-time. ## `negquery-cache-ttl` * Integer @@ -620,7 +633,7 @@ Number of receiver (listening) threads to start. See * Default: 10 Seconds to store recursive packets in the PacketCache. See -["Packet Cache"](internals.md#packet-cache). +["Packet Cache"](performance.md#packet-cache). ## `recursor` * IP Address @@ -722,7 +735,7 @@ under that offset. Where the controlsocket will live. The default depends on `LOCALSTATEDIR` during compile-time (usually `/var/run` or `/run`). See -["Controlsocket"](internals.md#controlsocket). +["Controlsocket"](running.md#controlsocket). This path will also contain the pidfile for this instance of PowerDNS called `pdns.pid` by default. See [`config-name`](#config-name) and diff --git a/docs/markdown/changelog.raw.md b/docs/markdown/changelog.raw.md index 6129bfd6a..b02564061 100644 --- a/docs/markdown/changelog.raw.md +++ b/docs/markdown/changelog.raw.md @@ -2737,7 +2737,7 @@ pdns[17495]: AXFR done for 'forfun.net', zone committed Also, you can force PowerDNS to reload a zone from disk immediately with **pdns\_control bind-reload-now**. All this happens 'live', per your instructions. Without instructions, the right things also happen, but the operator is in charge. -For more about all this coolness, see [“pdns\_control”](authoritative/internals.md#pdnscontrol "pdns_control") and [“pdns\_control commands”](authoritative/backend-bind.md#bind-control-commands "pdns_control commands"). +For more about all this coolness, see [“pdns\_control”](authoritative/running.md#pdnscontrol "pdns_control") and [“pdns\_control commands”](authoritative/backend-bind.md#bind-control-commands "pdns_control commands"). **Warning**: Again some changes in compilation instructions. The hybrid pgmysql backend has been split up into 'gmysql' and 'gpgsql', sharing a common base within the PowerDNS server itself. This means that you can no longer compile **--with-modules="pgmysql" --enable-mysql --enable-pgsql** but that you should now use: **--with-modules="gmysql gpgsql"**. The old launch-names remain available. @@ -3006,7 +3006,7 @@ For operators of PowerDNS Express trying to host .DE domains, the very special * ## New features - Wildcard CNAMEs now work as expected! -- **pdns\_control purge** can now also purge based on suffix, allowing operators to purge an entire domain from the packet cache instead of only specific records. See also [pdns\_control](authoritative/internals.md#pdnscontrol "pdns_control") Thanks to Mike Benoit for this suggestion. +- **pdns\_control purge** can now also purge based on suffix, allowing operators to purge an entire domain from the packet cache instead of only specific records. See also [pdns\_control](authoritative/running.md#pdnscontrol "pdns_control") Thanks to Mike Benoit for this suggestion. - **soa-serial-offset** for installations with small SOA serial numbers wishing to register .DE domains with DENIC which demands six-figure SOA serial numbers. See also [Chapter 21, *Index of all Authoritative Server settings*](authoritative/settings.md "Index of all Authoritative Server settings"). # Version 2.1 @@ -3030,7 +3030,7 @@ To run the dynamic version of PDNS, which is needed for backend drivers which ar ## Features - Oracle support has been tuned, leading to the first public release of the Oracle backend. Zone2sql now outputs better SQL and the backend is now fully documented. Furthermore, the queries are compatible with the PowerDNS XML-RPC product, allowing PowerDNS express to run off Oracle. See [Oracle backend](authoritative/backend-oracle.md "Oracle backend"). - Zone2sql now accepts --transactions to wrap zones in a transaction for PostgreSQL and Oracle output. This is a major speedup and also makes for better isolation of inserts. See [Zone2sql](authoritative/migration.md#zone2sql "Zone2sql"). -- **pdns\_control** now has the ability to purge the PowerDNS cache or parts of it. This enables operators to raise the TTL of the Packet Cache to huge values and only to invalidate the cache when changes are made. See also [Authoritative Server Performance](authoritative/performance.md "Authoritative Server Performance") and [pdns\_control](authoritative/internals.md#pdnscontrol "pdns_control"). +- **pdns\_control** now has the ability to purge the PowerDNS cache or parts of it. This enables operators to raise the TTL of the Packet Cache to huge values and only to invalidate the cache when changes are made. See also [Authoritative Server Performance](authoritative/performance.md "Authoritative Server Performance") and [pdns\_control](authoritative/running.md#pdnscontrol "pdns_control"). # Version 2.0.1 Maintenance release, fixing three small issues. @@ -3124,8 +3124,8 @@ Developers: this version is compatible with 1.99.11 backends. - Documentation bug - postgresql create/index statements created a duplicate index. If you've previously copy pasted the commands and not noticed the error, execute **CREATE INDEX rec\_name\_index ON records(name)** to remedy. Thanks to Jeff Miller for reporting this. This also lead to depressingly slow 'ANY' lookups for those of you doing benchmarks. ## Features -- pdns\_control (see [pdns\_control](authoritative/internals.md#pdnscontrol "pdns_control")) now opens the local end of its socket in `/tmp` instead of next to the remote socket (by default `/var/run`). This eases the way for allowing non-root access to pdns\_control. When running chrooted (see [Chapter 7, *Security settings & considerations*](common/security.md "Security settings & considerations")), the local socket again moves back to `/var/run`. -- pdns\_control now has a 'version' command. See [Section 1.1, “pdns\_control”](authoritative/internals.md#pdnscontrol "1.1. pdns_control"). +- pdns\_control (see [pdns\_control](authoritative/running.md#pdnscontrol "pdns_control")) now opens the local end of its socket in `/tmp` instead of next to the remote socket (by default `/var/run`). This eases the way for allowing non-root access to pdns\_control. When running chrooted (see [Chapter 7, *Security settings & considerations*](common/security.md "Security settings & considerations")), the local socket again moves back to `/var/run`. +- pdns\_control now has a 'version' command. See [Section 1.1, “pdns\_control”](authoritative/running.md#pdnscontrol "1.1. pdns_control"). # Version 1.99.11 Prerelease This release is important because it is the first release which is accompanied by an Open Source Backend Development Kit, allowing external developers to write backends for PDNS. Furthermore, a few bugs have been fixed diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index 28024731d..294dadf1b 100644 --- a/docs/mkdocs.yml +++ b/docs/mkdocs.yml @@ -26,7 +26,6 @@ pages: - Dynamic DNS Update: authoritative/dnsupdate.md - Using TSIG for AXFR: authoritative/tsig.md - Various How To's: authoritative/howtos.md - - Internals: authoritative/internals.md - Virtual Hosting: authoritative/virtual.md - Performance Tuning and Monitoring: authoritative/performance.md - Migrating to PowerDNS: authoritative/migration.md -- 2.40.0