]>
Commit | Line | Data |
---|---|---|
0e2063c3 PL |
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. |