Basic setup: configuring database connectivity
==============================================
-This shows you how to configure the Generic MySQL backend. This backend
-is called 'gmysql', and needs to be configured in ``pdns.conf``. Add the
-following lines, adjusted for your local setup (specifically, you may
-not want to use the 'root' user):
+This shows you how to configure the Generic SQLite3 backend.
-.. code-block:: ini
-
- launch=gmysql
- gmysql-host=127.0.0.1
- gmysql-user=root
- gmysql-dbname=pdns
- gmysql-password=mysecretpassword
+Make sure the SQLite3 backend is installed:
-Remove any earlier :ref:`setting-launch` statements and
-other configuration statements for backends.
+.. code-block:: shell
-.. warning::
- Make sure that you can actually resolve the hostname of
- your database without accessing the database! It is advised to supply an
- IP address here to prevent chicken/egg problems!
+ $ sudo apt-get install pdns-backend-sqlite3
-Now start PowerDNS in the foreground:
+or
-::
+.. code-block:: shell
- # /usr/sbin/pdns_server --daemon=no --guardian=no --loglevel=9
- (...)
- Dec 30 13:40:09 About to create 3 backend threads for UDP
- Dec 30 13:40:09 gmysql Connection failed: Unable to connect to database: Access denied for user 'hubert'@'localhost' to database 'pdns-non-existant'
- Dec 30 13:40:09 Caught an exception instantiating a backend: Unable to launch gmysql connection: Unable to connect to database: Access denied for user 'hubert'@'localhost' to database 'pdns-non-existant'
- Dec 30 13:40:09 Cleaning up
- Dec 30 13:40:10 Done launching threads, ready to distribute questions
+ $ sudo yum install pdns-backend-sqlite
-This is as to be expected - we did not yet add anything to MySQL for
-PowerDNS to read from. At this point you may also see other errors which
-indicate that PowerDNS either could not find your MySQL server or was
-unable to connect to it. Fix these before proceeding.
+This backend is called 'gsqlite3', and needs to be configured in ``pdns.conf``.
+Add the following lines, adjusted for your local setup:
-General MySQL knowledge is assumed in this chapter, please do not
-interpret these commands as DBA advice!
+.. code-block:: ini
-Example: configuring MySQL
---------------------------
+ launch=gsqlite3
+ gsqlite3-database=/var/lib/powerdns/pdns.sqlite3
-Connect to MySQL as a user with sufficient privileges and issue the
-following commands below if you are running the 4.3 or master version of PowerDNS:
+Remove any earlier :ref:`setting-launch` statements and other configuration statements for backends.
-Please find `the 4.2 schema <https://github.com/PowerDNS/pdns/blob/rel/auth-4.2.x/modules/gmysqlbackend/schema.mysql.sql>`_ and `the 4.1 schema <https://github.com/PowerDNS/pdns/blob/rel/auth-4.1.x/modules/gmysqlbackend/schema.mysql.sql>`_ on GitHub.
+Now create the database (on RPM systems, the schema path is ``/usr/share/doc/pdns-backend-sqlite/schema.sqlite3.sql``):
+.. code-block:: shell
-.. literalinclude:: ../../modules/gmysqlbackend/schema.mysql.sql
- :language: SQL
+ $ sudo mkdir /var/lib/powerdns
+ $ sudo sqlite3 /var/lib/powerdns/pdns.sqlite3 < /usr/share/doc/pdns-backend-sqlite3/schema.sqlite3.sql
+ $ sudo chown -R pdns:pdns /var/lib/powerdns
-We recommend you add the following MySQL statements as well. These will add
-foreign key constraints to the tables in order to automate deletion of records, key
-material, and other information upon deletion of a domain from the
-domains table. These will only work on the InnoDB storage engine, but if you
-followed our guide so far, that's exactly the engine we are using.
+And start PowerDNS
-The following SQL does the job:
+.. code-block:: shell
-.. literalinclude:: ../../modules/gmysqlbackend/enable-foreign-keys.mysql.sql
+ $ sudo systemctl start pdns
+or
-Now we have a database and an empty table. PowerDNS should now be able
-to launch in monitor mode and display no errors:
+.. code-block:: shell
-::
+ $ sudo systemctl restart pdns
- # /usr/sbin/pdns_server --daemon=no --guardian=no --loglevel=9
- (...)
- 15:31:30 PowerDNS 1.99.0 (Mar 12 2002, 15:00:28) starting up
- 15:31:30 About to create 3 backend threads
- 15:39:55 [gMySQLbackend] MySQL connection succeeded
- 15:39:55 [gMySQLbackend] MySQL connection succeeded
- 15:39:55 [gMySQLbackend] MySQL connection succeeded
+Make sure no error is reported, and use ``systemctl status pdns`` to make sure PowerDNS was started correctly.
-In a different shell, a sample query sent to the server should now
-return quickly *without* data:
+A sample query sent to the server should now return quickly *without* data:
.. code-block:: shell
- $ dig +short www.example.com @127.0.0.1 # should print nothing
-
-.. warning::
- When debugging DNS problems, don't use ``host``. Please use
- ``dig`` or ``drill``.
-
-And indeed, the output in the first terminal now shows:
+ dig a www.example.com @127.0.0.1
-::
+ ; <<>> DiG 9.10.3-P4-Debian <<>> a www.example.com @127.0.0.1
+ ;; global options: +cmd
+ ;; Got answer:
+ ;; ->>HEADER<<- opcode: QUERY, status: REFUSED, id: 40870
+ ...
- Mar 01 16:04:42 Remote 127.0.0.1 wants 'www.example.com|A', do = 0, bufsize = 1680: packetcache MISS
+.. warning::
+ When debugging DNS problems, don't use ``host``. Please use ``dig`` or ``drill``.
-Now we need to add some records to our database (in a separate shell):
+Note the ``REFUSED`` status - this is the code most name servers use to indicate they do not know about a domain.
-::
+Now, let's add a zone and some records:
- # mysql pdnstest
- mysql> INSERT INTO domains (name, type) values ('example.com', 'NATIVE');
- INSERT INTO records (domain_id, name, content, type,ttl,prio)
- VALUES (1,'example.com','localhost admin.example.com 1 10380 3600 604800 3600','SOA',86400,NULL);
- INSERT INTO records (domain_id, name, content, type,ttl,prio)
- VALUES (1,'example.com','dns-us1.powerdns.net','NS',86400,NULL);
- INSERT INTO records (domain_id, name, content, type,ttl,prio)
- VALUES (1,'example.com','dns-eu1.powerdns.net','NS',86400,NULL);
- INSERT INTO records (domain_id, name, content, type,ttl,prio)
- VALUES (1,'www.example.com','192.0.2.10','A',120,NULL);
- INSERT INTO records (domain_id, name, content, type,ttl,prio)
- VALUES (1,'mail.example.com','192.0.2.12','A',120,NULL);
- INSERT INTO records (domain_id, name, content, type,ttl,prio)
- VALUES (1,'localhost.example.com','127.0.0.1','A',120,NULL);
- INSERT INTO records (domain_id, name, content, type,ttl,prio)
- VALUES (1,'example.com','mail.example.com','MX',120,25);
+.. code-block:: shell
-.. warning::
- Host names and the MNAME of a :ref:`types-soa`
- records are NEVER terminated with a '.' in PowerDNS storage! If a
- trailing '.' is present it will inevitably cause problems, problems that
- may be hard to debug.
+ $ create-zone example.org ns1.example.com
+ Creating empty zone 'example.com'
+ Also adding one NS record
+ $ pdnsutil add-record example.com '' MX '25 mail.example.com'
+ New rrset:
+ example.com. 3005 IN MX 25 mail.example.com
+ $ pdnsutil add-record example.com. www A 192.0.2.1
+ New rrset:
+ www.example.com. 3005 IN A 192.0.2.1
If we now requery our database, ``www.example.com`` should be present:
.. code-block:: shell
$ dig +short www.example.com @127.0.0.1
- 192.0.2.10
+ 192.0.2.1
$ dig +short example.com MX @127.0.0.1
25 mail.example.com
-To confirm what happened, check the statistics:
-
-::
-
- $ /usr/sbin/pdns_control SHOW \*
- corrupt-packets=0,latency=0,packetcache-hit=2,packetcache-miss=5,packetcache-size=0,
- qsize-a=0,qsize-q=0,servfail-packets=0,tcp-answers=0,tcp-queries=0,
- timedout-packets=0,udp-answers=7,udp-queries=7,
- %
-
-The actual numbers will vary somewhat. Now hit CTRL+C in the shell where
-PowerDNS runs, start PowerDNS as a regular daemon, and check launch
-status:
-
-On SysV systems:
-
-::
-
- # /etc/init.d/pdns start
- pdns: started
- # /etc/init.d/pdns status
- pdns: 8239: Child running
- # /etc/init.d/pdns dump
- pdns: corrupt-packets=0,latency=0,packetcache-hit=0,packetcache-miss=0,
- packetcache-size=0,qsize-a=0,qsize-q=0,servfail-packets=0,tcp-answers=0,
- tcp-queries=0,timedout-packets=0,udp-answers=0,udp-queries=0,
-
-On systemd systems:
-
-::
+If this is not the output you get, remove ``+short`` to see the full output so you can find out what went wrong.
- # systemctl start pdns.service
- # systemctl status pdns.service
- * pdns.service - PowerDNS Authoritative Server
- Loaded: loaded (/lib/systemd/system/pdns.service; enabled)
- Active: active (running) since Tue 2017-01-17 15:59:28 UTC; 1 months 12 days ago
- Docs: man:pdns_server(1)
- man:pdns_control(1)
- https://doc.powerdns.com
- Main PID: 24636 (pdns_server)
- CGroup: /system.slice/pdns.service
- `-24636 /usr/sbin/pdns_server --guardian=no --daemon=no --disable-syslog --write-pid=no
+Now, run ``pdnsutil edit-zone example.com`` and try to add a few more records, and query them with dig to make sure they work.
- (...)
- # /usr/sbin/pdns_control SHOW \*
- corrupt-packets=0,latency=0,packetcache-hit=2,packetcache-miss=5,packetcache-size=0,
- qsize-a=0,qsize-q=0,servfail-packets=0,tcp-answers=0,tcp-queries=0,
- timedout-packets=0,udp-answers=7,udp-queries=7,
+You now have a working database driven nameserver!
-You now have a working database driven nameserver! To convert other
-zones already present, see the :doc:`migration guide <../migration>`.
+To convert other zones already present, see the :doc:`migration guide <../migration>`.
Common problems
---------------
-Most problems involve PowerDNS not being able to connect to the
-database.
+Most problems involve PowerDNS not being able to connect to the database.
+This section covers more than just SQLite.
Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
projects / thirdparty / pdns.git / commitdiff
