docs/backends/generic-odbc.rst

   1 Generic ODBC Backend
   2 ====================
   3
   4 * Native: Yes
   5 * Master: Yes
   6 * Slave: Yes
   7 * Superslave: Yes
   8 * Autoserial: Yes
   9 * Case: All lower
  10 * DNSSEC: Yes
  11 * Disabled data: Yes
  12 * Comments: Yes
  13 * Module name: godbc
  14 * Launch name: ``godbc``
  15
  16 The Generic ODBC Backend (godbc) is a child of the Generic SQL (gsql)
  17 backend, similar to the gmysql and gpgsql backends. It uses
  18 `UnixODBC <http://www.unixodbc.org/>`__ and installed drivers to connect
  19 to the databases supported by said drivers.
  20
  21 .. warning::
  22   When there is a more specific generic sql backend (like
  23   goracle or gmysql), it is highly recommended to use that backend
  24   instead!
  25
  26 Enabling the backend
  27 --------------------
  28
  29 When building PowerDNS yourself, append ``godbc`` to ``--with-modules``
  30 or ``--with-dynmodules``. It is expected that most pre-built packages
  31 contain this backend or be separately installable.
  32
  33 Configuration Parameters
  34 ------------------------
  35
  36 This section only details the configuration of PowerDNS for use with
  37 ODBC. For ODBC related configuration, please see UnixODBC
  38 website/documentation and the documentation for the driver you intend to
  39 use.
  40
  41 .. _setting-godbc-datasource:
  42
  43 ``godbc-datasource``
  44 ^^^^^^^^^^^^^^^^^^^^
  45
  46 -  String
  47 -  Default: PowerDNS
  48
  49 The datasource (DSN) to use. This must be configured in the ``odbc.ini``
  50 file, usually found in ``/etc/``, but this depends your local setup.
  51
  52 .. _setting-godbc-username:
  53
  54 ``godbc-username``
  55 ^^^^^^^^^^^^^^^^^^
  56
  57 -  String
  58 -  Default: powerdns
  59
  60 The user to connect to the datasource.
  61
  62 .. _setting-godbc-password:
  63
  64 ``godbc-password``
  65 ^^^^^^^^^^^^^^^^^^
  66
  67 -  String
  68 -  Default is empty
  69
  70 The password to connect with the datasource.
  71
  72 Connecting to Microsoft SQL Server
  73 ----------------------------------
  74
  75 .. note::
  76   In order to connect to Microsoft SQL Server, you will need at
  77   least version 3.2.0 of UnixODBC. FreeDTS has been tested with versions
  78   0.91 and 0.95.
  79
  80 Install the `FreeTDS <http://www.freetds.org/>`__ driver for UnixODBC,
  81 either by compiling or getting it from our distribution's repository and
  82 configure your ``/etc/odbcinst.ini`` with the driver, e.g.:
  83
  84 .. code-block:: ini
  85
  86     [FreeTDS]
  87     Description=v0.95.8 with protocol v7.1
  88     Driver=/usr/local/lib/libtdsodbc.so
  89     UsageCount=1
  90
  91 And add the datasource to your ``/etc/odbc.ini``, e.g:
  92
  93 .. code-block:: ini
  94
  95     [pdns1]
  96     Driver=FreeTDS
  97     Trace=No
  98     Server=server.example.net
  99     Port=1433
 100     Database=pdns-1
 101     TDS_Version=7.1
 102
 103 (For our tests, we add ``ClientCharset=UTF-8`` as well. YMMV.)
 104
 105 You can now test the connection with ``isql pdns1 USERNAME PASSWORD``.
 106
 107 Loading the schema into the database
 108 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 109
 110 For convenience, a schema for MS SQL Server has been created: (Note:
 111 This schema can also be found in the PowerDNS source as
 112 ``modules/godbcbackend/schema.mssql.sql``).
 113
 114 .. literalinclude:: ../../modules/godbcbackend/schema.mssql.sql
 115
 116 Load this into the database as follows:
 117
 118 .. code-block:: bash
 119
 120   cat schema.mssql.sql | tr '\n' ' ' | isql pdns1 USERNAME PASSWORD -b.
 121
 122 Loading records into the database
 123 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 124
 125 Loading records is the same as with any SQL backend, just add them using
 126 SQL-queries. Should you want to use :ref:`zone2sql <migration-zone2sql>`,
 127 use the ``--sqlite`` option for correctly formatted SQL.
 128
 129 Configuring PowerDNS
 130 ^^^^^^^^^^^^^^^^^^^^
 131
 132 Add the options required to your ``pdns.conf``:
 133
 134 ::
 135
 136     launch=godbc
 137     godbc-datasource=pdns1
 138     godbc-username=USERNAME
 139     godbc-password=PASSWORD
 140
 141 Now restart PowerDNS and you're done. Just don't forget to add zones and
 142 records to the database.
 143
 144 Possible issues
 145 ^^^^^^^^^^^^^^^
 146
 147 It might be that you need to compile FreeTDS with the
 148 ``--tds-version=7.1`` to connect to SQL Server.
 149
 150 When connecting to a database hosted with Microsoft Azure, FreeTDS must
 151 be compiled with OpenSSL, use the ``--with-openssl`` configure flag.