doc: update DNSSEC BIND to Knot DNS migration

1 files changed, 43 insertions, 21 deletions

diff --git a/doc/migration.rst b/doc/migration.rst
index 332f1776e..ac1eb33d0 100644
--- a/doc/migration.rst
+++ b/doc/migration.rst
@@ -15,39 +15,61 @@ Knot DNS for BIND users
 Automatic DNSSEC signing
 ------------------------
 
-Migrating automatically signed zones from BIND to Knot DNS is very
-easy due to the fact that Knot DNS is able to use DNSSEC keys
-generated by BIND.
+Migrating automatically signed zones from BIND to Knot DNS requires copying
+up-to-date zone files from BIND, importing existing private keys, and updating
+server configuration:
 
 1. To obtain current content of the zone which is being migrated,
    request BIND to flush the zone into the zone file: ``rndc flush
    example.com``.
 
-   *Note:* If dynamic updates (DDNS) are enabled for the given zone, you
-   might need to freeze the zone before flushing it. That can be done
-   similarly: ``rndc freeze example.com``
+   .. NOTE::
+      If dynamic updates (DDNS) are enabled for the given zone, you
+      might need to freeze the zone before flushing it. That can be done
+      similarly: ``rndc freeze example.com``
 
 2. Copy the fresh zone file into the zones storage directory of Knot
    DNS. Its default location is ``/var/lib/knot``.
 
-3. We recommend to store DNSSEC keys for each zone in a separate
-   directory. For this purpose, create a directory
-   ``example.com.keys`` in the zones storage directory. Then copy all
-   DNSSEC keys (``*.key`` and ``*.private``) from BIND key directory
-   (configured as ``key-directory``) into the newly created one.
+3. Initialize DNSSEC KASP database (default location is ``/var/lib/knot/keys``
+   and create a dedicated signing policy for the imported zones with manual
+   key management::
 
-4. Add the zone into the Knot DNS configuration file. Zone
-   configuration should contain at least the specification of the zone
-   file (option ``file``), key directory (option ``kasp-db``),
-   and permission for automatic DNSSEC signing (option ``dnssec-signing``).
+   $ cd /var/lib/knot/keys
+   $ keymgr init
+   $ keymgr policy add bind manual true
 
-   You can follow this example::
+   .. NOTE::
+      The server can be run under a dedicated user account, usually ``knot``.
+      As the server requires read-write access to the KASP database, the
+      permissions must be set correctly. This can be achieved for instance by
+      executing all KASP database management commands under sudo::
+
+      $ sudo -u knot keymgr ...
+
+4. For each imported zone, create an entry in the KASP database and import
+   all existing keys. Make sure that all keys were configured correctly::
+
+   $ keymgr zone add example.com policy bind
+   $ keymgr zone key import example.com path/to/Kexample.com.+013+11111
+   $ keymgr zone key import example.com path/to/Kexample.com.+013+22222
+   $ ...
+   $ keymgr zone key list example.com
+
+4. Add the zone into the Knot DNS configuration file. Zone configuration must
+   include correct path to zone file (option :ref:`file<zone_file>`) and KASP
+   database (option :ref:`kasp-db<zone_kasp_db>`). You can follow this example::
 
     zone:
-      - domain: "example.com."
-        file: "example.com.db"
-        storage: "/var/lib/knot"
+      - domain: example.com
+        storage: /var/lib/knot
+        kasp-db: /var/lib/knot/keys
+        file: example.com.db
         dnssec-signing: on
-        kasp-db: "example.com.keys"
 
-5. Start Knot DNS and check the log files to make sure that everything went right.
+5. Start Knot DNS and check the log files to verify that everything went right.
+
+6. Optionally, review the used KASP policy and enable automatic key management::
+
+   $ keymgr policy set bind manual false
+   $ sudo knotc reload