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).
9 Furthermore, PowerDNS can be run on the foreground for testing or in
10 other init- systems that supervise processes.
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'.
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.
31 Logging to syslog on systemd-based operating systems
32 ----------------------------------------------------
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.
38 Removing the ``--disable-syslog`` option from the ``ExecStart`` line
39 using ``systemctl edit --full pdns`` enables logging to syslog.
41 .. _logging-to-syslog:
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'.
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.
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.
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.
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::
61 local0.info -/var/log/pdns.info
62 local0.warn -/var/log/pdns.warn
63 local0.err /var/log/pdns.err
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.
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.
72 Be aware that syslog by default logs messages at the configured priority and higher!
73 To log only info messages, use ``local0.=info``
75 Controlling A Running PowerDNS Server
76 -------------------------------------
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.
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`.
92 .. _running-pdnscontrol:
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`.
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.
110 This script supplied with the PowerDNS source accepts the following
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
126 - ``restart``: Restarts PowerDNS if it was running, starts it
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
136 - ``show variable``: Show a single statistic, as present in the output
138 - ``mrtg``: Dump statistics in mrtg format. See the performance
139 :ref:`counters` documentation.
142 Packages provided by Operating System vendors might support
143 different or less commands.
145 Running in the foreground
146 -------------------------
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``
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:
156 .. code-block:: shell
158 pdns_server --no-config --daemon=no --local-port=5300 --launch=gmysql --gmysql-user=my_user --gmysql-password=mypassword
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.