docs/running.rst

   1 Running and Operating
   2 =====================
   3
   4 On Linux, PowerDNS is controlled by a systemd service called ``pdns.service``.
   5 The service definition file should be installed by the binary package, and can also be found in the tarball (``pdns.service.in`` template file).
   6
   7 On non-Linux systems, a SysV-style init script can be used, and should be supplied by the operating system packages.
   8
   9 Furthermore, PowerDNS can be run on the foreground for testing or for use with other init-systems that supervise processes.
  10
  11 Also see :doc:`guides/virtual-instances`.
  12
  13 .. _running-guardian:
  14
  15 Guardian
  16 --------
  17
  18 When the init-system of the Operating System does not properly
  19 supervises processes, like SysV init, it is recommended to run PowerDNS
  20 with the :ref:`setting-guardian` option set to 'yes'.
  21
  22 When launched with ``guardian=yes``, ``pdns_server`` wraps itself inside
  23 a 'guardian'. This guardian monitors the performance of the inner
  24 ``pdns_server`` instance which shows up in the process list of your OS
  25 as ``pdns_server-instance``. It is also this guardian that
  26 :ref:`running-pdnscontrol` talks to. A **STOP** is interpreted
  27 by the guardian, which causes the guardian to sever the connection to
  28 the inner process and terminate it, after which it terminates itself.
  29 Requests that require data from the actual nameserver are passed to the
  30 inner process as well.
  31
  32 Logging to syslog on systemd-based operating systems
  33 ----------------------------------------------------
  34
  35 By default, logging to syslog is disabled in the systemd unit file
  36 to prevent the service logging twice, as the systemd journal picks up
  37 the output from the process itself.
  38
  39 Removing the ``--disable-syslog`` option from the ``ExecStart`` line
  40 using ``systemctl edit --full pdns`` enables logging to syslog.
  41
  42 .. _logging-to-syslog:
  43
  44 Logging to syslog
  45 -----------------
  46 This chapter assumes familiarity with syslog, the unix logging device.
  47 PowerDNS logs messages with different levels.
  48 The more urgent the message, the lower the 'priority'.
  49
  50 By default, PowerDNS will only log messages with an urgency of 3 or lower, but this can be changed using the :ref:`setting-loglevel` setting in the configuration file.
  51 Setting it to 0 will eliminate all logging, 9 will log everything.
  52
  53 By default, logging is performed under the 'DAEMON' facility which is shared with lots of other programs.
  54 If you regard nameserving as important, you may want to have it under a dedicated facility so PowerDNS can log to its own files, and not clutter generic files.
  55
  56 For this purpose, syslog knows about 'local' facilities, numbered from LOCAL0 to LOCAL7.
  57 To move PowerDNS logging to LOCAL0, add :ref:`logging-facility=0 <setting-logging-facility>` to your configuration.
  58
  59 Furthermore, you may want to have separate files for the differing priorities - preventing lower priority messages from obscuring important ones.
  60 A sample ``syslog.conf`` might be::
  61
  62   local0.info                       -/var/log/pdns.info
  63   local0.warn                       -/var/log/pdns.warn
  64   local0.err                        /var/log/pdns.err
  65
  66 Where local0.err would store the really important messages.
  67 For performance and disk space reasons, it is advised to audit your ``syslog.conf`` for statements also logging PowerDNS activities.
  68 Many ``syslog.conf``\ s have a ``*.*`` statement to ``/var/log/syslog``, which you may want to remove.
  69
  70 For performance reasons, be especially certain that no large amounts of synchronous logging take place.
  71 Under Linux, this is indicated by file names not starting with a ``-`` - indicating a synchronous log, which hurts performance.
  72
  73 Be aware that syslog by default logs messages at the configured priority and higher!
  74 To log only info messages, use ``local0.=info``
  75
  76 Controlling A Running PowerDNS Server
  77 -------------------------------------
  78
  79 As a DNS server is critical infrastructure, downtimes should be avoided
  80 as much as possible. Even though PowerDNS (re)starts very fast, it
  81 offers a way to control it while running.
  82
  83 .. _control-socket:
  84
  85 Control Socket
  86 ~~~~~~~~~~~~~~
  87
  88 The controlsocket is the means to contact a running PowerDNS process.
  89 Over this socket, instructions can be sent using the ``pdns_control``
  90 program. The control socket is called ``pdns.controlsocket`` and is
  91 created inside the :ref:`setting-socket-dir`.
  92
  93 .. _running-pdnscontrol:
  94
  95 ``pdns_control``
  96 ~~~~~~~~~~~~~~~~
  97
  98 To communicate with PowerDNS Authoritative Server over the
  99 controlsocket, the ``pdns_control`` command is used. The syntax is
 100 simple: ``pdns_control command arguments``. Currently this is most
 101 useful for telling backends to rediscover domains or to force the
 102 transmission of notifications. See :ref:`master-operation`.
 103
 104 For all supported ``pdns_control`` commands and options, see :doc:`the
 105 manpage <../manpages/pdns_control.1>` and the output of
 106 ``pdns_control --help`` on your system.
 107
 108 Backend manipulation
 109 ~~~~~~~~~~~~~~~~~~~~
 110
 111 ``pdnsutil``
 112 ~~~~~~~~~~~~
 113
 114 To perform zone and record changes using inbuilt tools, the ``pdnsutil`` command can be used. All available options are described in the online :doc:`manual page <../manpages/pdnsutil.1>` as well as in ``man pdnsutil``.
 115
 116 The SysV init script
 117 --------------------
 118
 119 This script supplied with the PowerDNS source accepts the following
 120 commands:
 121
 122 -  ``monitor``: Monitor is a special way to view the daemon. It executes
 123    PowerDNS in the foreground with a lot of logging turned on, which
 124    helps in determining startup problems. Besides running in the
 125    foreground, the raw PowerDNS control socket is made available. All
 126    external communication with the daemon is normally sent over this
 127    socket. While useful, the control console is not an officially
 128    supported feature. Commands which work are: ``QUIT``, ``SHOW *``,
 129    ``SHOW varname``, ``RPING``.
 130 -  ``start``: Start PowerDNS in the background. Launches the daemon but
 131    makes no special effort to determine success, as making database
 132    connections may take a while. Use ``status`` to query success. You
 133    can safely run ``start`` many times, it will not start additional
 134    PowerDNS instances.
 135 -  ``restart``: Restarts PowerDNS if it was running, starts it
 136    otherwise.
 137 -  ``status``: Query PowerDNS for status. This can be used to figure out
 138    if a launch was successful. The status found is prefixed by the PID
 139    of the main PowerDNS process.
 140 -  ``stop``: Requests that PowerDNS stop. Again, does not confirm
 141    success. Success can be ascertained with the ``status`` command.
 142 -  ``dump``: Dumps a lot of statistics of a running PowerDNS daemon. It
 143    is also possible to single out specific variable by using the
 144    ``show`` command.
 145 -  ``show variable``: Show a single statistic, as present in the output
 146    of the ``dump``.
 147 -  ``mrtg``: Dump statistics in mrtg format. See the performance
 148    :ref:`counters` documentation.
 149
 150 .. note::
 151   Packages provided by Operating System vendors might support
 152   different or less commands.
 153
 154 Running in the foreground
 155 -------------------------
 156
 157 One can run PowerDNS in the foreground by invoking the ``pdns_server``
 158 executable. Without any options, it will load the ``pdns.conf`` and run.
 159 To make sure PowerDNS starts in the foreground, add the ``--daemon=no``
 160 option.
 161
 162 All :doc:`settings <settings>` can be added on the commandline. e.g. to
 163 test a new database config, you could start PowerDNS like this:
 164
 165 .. code-block:: shell
 166
 167     pdns_server --no-config --daemon=no --local-port=5300 --launch=gmysql --gmysql-user=my_user --gmysql-password=mypassword
 168
 169 This starts PowerDNS without loading on-disk config, in the foreground,
 170 on all network interfaces on port 5300 and starting the
 171 :doc:`gmysql <backends/generic-mysql>` backend.