docs/migration.rst

   1 Migrating to PowerDNS
   2 =====================
   3
   4 Before migrating to PowerDNS a few things should be considered.
   5
   6 PowerDNS does not operate as a :ref:`slave-operation` or
   7 :ref:`master-operation` server with all backends. The :doc:`Generic SQL <backends/generic-sql>` and
   8 :doc:`BIND <backends/bind>` backends have the ability to act as master or
   9 slave. See the :doc:`table of backends <backends/index>`
  10 which other backends support these modes.
  11
  12 Using AXFR to a Slave-Capable Backend
  13 -------------------------------------
  14
  15 The easiest way to migrate all your zones from your old infrastructure
  16 to PowerDNS is to add all your domains as a slave domain with your
  17 current master as the master, wait for the zones to be transferred and
  18 change the zones to master. Make sure :ref:`setting-slave` is set to "yes"
  19 in your pdns.conf.
  20
  21 To A Generic SQL Backend
  22 ~~~~~~~~~~~~~~~~~~~~~~~~
  23
  24 .. note::
  25   This assumes the schema provided with PowerDNS is in place
  26
  27 In order to migrate to a Generic SQL backend, add all your domains to
  28 the 'domains' table with the IP of your current master. On your current
  29 master, make sure that this master allows AXFRs to this new slave.
  30
  31 .. code-block:: SQL
  32
  33     INSERT INTO domains (name,type,master) VALUES ('example.net', 'SLAVE', '198.51.100.101');
  34
  35 Then start PowerDNS and wait for all the zones to be transferred. If
  36 this server is the new :ref:`master <master-operation>`, change the type of
  37 domain in the database:
  38
  39 .. code-block:: SQL
  40
  41     UPDATE domains set type='MASTER' where type='SLAVE';
  42
  43 And set :ref:`setting-master` to "yes" in your pdns.conf
  44 and restart PowerDNS.
  45
  46 Or, if you want to use :ref:`native <native-operation>`:
  47
  48 .. code-block:: SQL
  49
  50     UPDATE domains set type='NATIVE' where type='SLAVE';
  51
  52 To the BIND backend
  53 ~~~~~~~~~~~~~~~~~~~
  54
  55 Create a named.conf with all the domains as slave domains, e.g.:
  56
  57 ::
  58
  59     zone "example.net" in {
  60       type slave;
  61       file "/var/lib/powerdns/zones/example.net.zone";
  62       masters {
  63         198.51.100.101;
  64       };
  65     };
  66
  67 Make sure the directory is writable for the ``pdns_server`` process and
  68 that :ref:`setting-bind-config` parameter
  69 references this file. Now start PowerDNS and wait untill all zones are
  70 transferred. Now you can change the zone type to master:
  71
  72 ::
  73
  74     zone "example.net" in {
  75       type master;
  76       file "/var/lib/powerdns/zones/example.net.zone";
  77     };
  78
  79 Don't forget to enable :ref:`setting-master` in your
  80 pdns.conf and restart, or if this setting was already set, use
  81 ``pdns_control rediscover`` to load these zones as master zones.
  82
  83 From zonefiles to PowerDNS
  84 --------------------------
  85
  86 Using the BIND backend
  87 ~~~~~~~~~~~~~~~~~~~~~~
  88
  89 To use the BIND backend, set ``launch=bind`` and
  90 ``bind-config=/path/to/named.conf`` in your ``pdns.conf``. Note that
  91 PowerDNS will not honor any options from named.conf, it will only use
  92 the ``zone`` statements. See the :doc:`BIND backend <backends/bind>`
  93 documentation for more information.
  94
  95 To a Generic SQL backend
  96 ~~~~~~~~~~~~~~~~~~~~~~~~
  97
  98 There are several methods to migrate to a :doc:`Generic SQL <backends/generic-sql>` backend.
  99
 100 .. _migration-zone2sql:
 101
 102 Using ``zone2sql``
 103 ^^^^^^^^^^^^^^^^^^
 104
 105 To migrate, the ``zone2sql`` tool is provided. This tool parses a BIND
 106 ``named.conf`` file and zone files and outputs SQL on standard out,
 107 which can then be fed to your database. It understands the BIND master
 108 file extension ``$GENERATE`` and will also honour ``$ORIGIN`` and
 109 ``$TTL``.
 110
 111 For backends supporting slave operation, there is also an option to keep
 112 slave zones as slaves, and not convert them to native operation.
 113
 114 ``zone2sql`` can generate SQL for nearly all the Generic SQL backends.
 115 See `its manpage <manpages/zone2sql.1>` for more information.
 116
 117 An example call to ``zone2sql`` could be:
 118
 119 .. code-block:: shell
 120
 121     zone2sql --named-conf=/path/to/named.conf --gmysql | mysql -u pdns -p pdns-db
 122
 123 This will generate the SQL statements for the :doc:`Generic MySQL <backends/generic-mysql>` and pipe them into the pdns-db
 124 database in MySQL.
 125
 126 Using ``pdnsutil load-zone``
 127 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 128
 129 The :doc:`pdnsutil <manpages/pdnsutil.1>` tool has a
 130 ``load-zone`` command that ingests a zone file and imports it into the
 131 first backend that is capable of hosting it.
 132
 133 To import, configure the backend and run
 134 ``pdnsutil load-zone example.com /tmp/example.com.zone`` to import
 135 the ``example.com`` domain from the ``/tmp/example.com.zone`` file. The
 136 zone is imported atomically (i.e. it is fully imported, or not) and any
 137 existing records for that zone are overwritten. This include the SOA record too.
 138
 139 .. _b2b-migrate:
 140
 141 Migrating Data from one Backend to Another Backend
 142 --------------------------------------------------
 143
 144 .. note::
 145   This is experimental feature.
 146
 147 Syntax: ``pdnsutil b2b-migrate OLD NEW``
 148
 149 This tool lets you migrate data from one backend to another, it moves
 150 all data, including zones, metadata and crypto keys (if present). Some
 151 example use cases are moving from BIND-style zonefiles to SQL based, or
 152 other way around.
 153
 154 Prerequisites
 155 ~~~~~~~~~~~~~
 156
 157 -  Target backend must support same features as source from set of
 158    domains, zones, metadata, DNSSEC and TSIG. See :doc:`Backend
 159    Capabilities <backends/index>`
 160 -  There must be no data in the target backend, otherwise the migration
 161    will fail. This is checked.
 162
 163 You can perform live upgrade with this tool, provided you follow the
 164 procedure.
 165
 166 Moving from source to target
 167 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 168
 169 -  Take backups of everything.
 170 -  Configure both backends to pdns.conf, if you have source configured,
 171    you can just add target backend. **DO NOT RESTART AUTH SERVER BEFORE
 172    YOU HAVE FINISHED**
 173 -  Then run ``pdnsutil b2b-migrate old new``, the old and new being
 174    configuration prefixes in pdns.conf. If something goes wrong, make
 175    sure you properly clear **ALL** data from target backend before
 176    retrying.
 177 -  Remove (or comment out) old backend from pdns.conf, and run
 178    ``pdnsutil rectify-all-zones`` and ``pdnsutil check-all-zones`` to
 179    make sure everything is OK.
 180 -  If everything is OK, then go ahead to restart your PowerDNS service.
 181    Check logs to make sure everything went ok.