docs/running.rst

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