]>
Commit | Line | Data |
---|---|---|
0e2063c3 PL |
1 | Running and Operating |
2 | ===================== | |
3 | ||
33b958b8 CH |
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). | |
0e2063c3 | 6 | |
33b958b8 CH |
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`. | |
0e2063c3 PL |
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 | ||
6a1e987d | 35 | By default, logging to syslog is disabled in the systemd unit file |
0e2063c3 PL |
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 | ||
fc63af1b | 108 | Backend manipulation |
eb422b4d | 109 | ~~~~~~~~~~~~~~~~~~~~ |
fc63af1b | 110 | |
111 | ``pdnsutil`` | |
eb422b4d | 112 | ~~~~~~~~~~~~ |
fc63af1b | 113 | |
67e9cc23 | 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``. |
fc63af1b | 115 | |
0e2063c3 PL |
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 | ||
f404c4c6 | 150 | .. note:: |
0e2063c3 PL |
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. |