From: Peter van Dijk Date: Fri, 20 Mar 2020 23:25:52 +0000 (+0100) Subject: auth: change installation example from MySQL to SQLite X-Git-Tag: rec-4.5.0-alpha1~25^2~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7a952c877d4782fe49817090ef92a3387753a9ef;p=thirdparty%2Fpdns.git auth: change installation example from MySQL to SQLite --- diff --git a/docs/guides/basic-database.rst b/docs/guides/basic-database.rst index b5e05a1f3d..fcdfbb190d 100644 --- a/docs/guides/basic-database.rst +++ b/docs/guides/basic-database.rst @@ -1,194 +1,106 @@ 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 `_ and `the 4.1 schema `_ 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) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/installation.rst b/docs/installation.rst index 0aaa2c3685..b64d409996 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -14,8 +14,9 @@ Binary Packages Debian-based Systems ~~~~~~~~~~~~~~~~~~~~ -PowerDNS Authoritative Server is available through the -`apt `__ system. +PowerDNS Authoritative Server is available through the `apt `__ system. +Your distribution likely ships a package, but we recommend getting more recent packages from `the PowerDNS repositories `__. +Please see the instructions on the repo site and then come back here! .. code-block:: shell @@ -81,4 +82,4 @@ PowerDNS Authoritative Server is available through Homebrew: After installation ------------------ -Once installed, :doc:`guides/basic-database` using MySQL or start :doc:`migrating ` your data. +Once installed, try :doc:`guides/basic-database` using SQLite 3 or start :doc:`migrating ` your data.