1.. Copyright (C) Internet Systems Consortium, Inc. ("ISC") 2.. 3.. SPDX-License-Identifier: MPL-2.0 4.. 5.. This Source Code Form is subject to the terms of the Mozilla Public 6.. License, v. 2.0. If a copy of the MPL was not distributed with this 7.. file, you can obtain one at https://mozilla.org/MPL/2.0/. 8.. 9.. See the COPYRIGHT file distributed with this work for additional 10.. information regarding copyright ownership. 11 12.. highlight: console 13 14.. _man_named: 15 16named - Internet domain name server 17----------------------------------- 18 19Synopsis 20~~~~~~~~ 21 22:program:`named` [ [**-4**] | [**-6**] ] [**-c** config-file] [**-C**] [**-d** debug-level] [**-D** string] [**-E** engine-name] [**-f**] [**-g**] [**-L** logfile] [**-M** option] [**-m** flag] [**-n** #cpus] [**-p** port] [**-s**] [**-S** #max-socks] [**-t** directory] [**-U** #listeners] [**-u** user] [**-v**] [**-V**] [**-X** lock-file] [**-x** cache-file] 23 24Description 25~~~~~~~~~~~ 26 27``named`` is a Domain Name System (DNS) server, part of the BIND 9 28distribution from ISC. For more information on the DNS, see :rfc:`1033`, 29:rfc:`1034`, and :rfc:`1035`. 30 31When invoked without arguments, ``named`` reads the default 32configuration file ``/etc/named.conf``, reads any initial data, and 33listens for queries. 34 35Options 36~~~~~~~ 37 38``-4`` 39 This option tells ``named`` to use only IPv4, even if the host machine is capable of IPv6. ``-4`` and 40 ``-6`` are mutually exclusive. 41 42``-6`` 43 This option tells ``named`` to use only IPv6, even if the host machine is capable of IPv4. ``-4`` and 44 ``-6`` are mutually exclusive. 45 46``-c config-file`` 47 This option tells ``named`` to use ``config-file`` as its configuration file instead of the default, 48 ``/etc/named.conf``. To ensure that the configuration file 49 can be reloaded after the server has changed its working directory 50 due to to a possible ``directory`` option in the configuration file, 51 ``config-file`` should be an absolute pathname. 52 53``-C`` 54 55 This option prints out the default built-in configuration and exits. 56 57 NOTE: This is for debugging purposes only and is not an 58 accurate representation of the actual configuration used by :iscman:`named` 59 at runtime. 60 61``-d debug-level`` 62 This option sets the daemon's debug level to ``debug-level``. Debugging traces from 63 ``named`` become more verbose as the debug level increases. 64 65``-D string`` 66 This option specifies a string that is used to identify a instance of ``named`` 67 in a process listing. The contents of ``string`` are not examined. 68 69``-E engine-name`` 70 When applicable, this option specifies the hardware to use for cryptographic 71 operations, such as a secure key store used for signing. 72 73 When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL 74 engine identifier that drives the cryptographic accelerator or 75 hardware service module (usually ``pkcs11``). When BIND is 76 built with native PKCS#11 cryptography (``--enable-native-pkcs11``), it 77 defaults to the path of the PKCS#11 provider library specified via 78 ``--with-pkcs11``. 79 80``-f`` 81 This option runs the server in the foreground (i.e., do not daemonize). 82 83``-g`` 84 This option runs the server in the foreground and forces all logging to ``stderr``. 85 86``-L logfile`` 87 This option sets the log to the file ``logfile`` by default, instead of the system log. 88 89``-M option`` 90 91 This option sets the default (comma-separated) memory context 92 options. The possible flags are: 93 94 - ``external``: use system-provided memory allocation functions; this 95 is the implicit default. 96 97 - ``internal``: use the internal memory manager. 98 99 - ``fill``: fill blocks of memory with tag values when they are 100 allocated or freed, to assist debugging of memory problems; this is 101 the implicit default if ``named`` has been compiled with 102 ``--enable-developer``. 103 104 - ``nofill``: disable the behavior enabled by ``fill``; this is the 105 implicit default unless ``named`` has been compiled with 106 ``--enable-developer``. 107 108``-m flag`` 109 This option turns on memory usage debugging flags. Possible flags are ``usage``, 110 ``trace``, ``record``, ``size``, and ``mctx``. These correspond to the 111 ``ISC_MEM_DEBUGXXXX`` flags described in ``<isc/mem.h>``. 112 113``-n #cpus`` 114 This option controls the number of CPUs that ``named`` assumes the 115 presence of. If not specified, ``named`` tries to determine the 116 number of CPUs present automatically; if it fails, a single CPU is 117 assumed to be present. 118 119 ``named`` creates two threads per each CPU present (one thread for 120 receiving and sending client traffic and another thread for sending 121 and receiving resolver traffic) and then on top of that a single 122 thread for handling time-based events. 123 124``-p port`` 125 This option listens for queries on ``port``. If not specified, the default is 126 port 53. 127 128``-s`` 129 This option writes memory usage statistics to ``stdout`` on exit. 130 131.. note:: 132 133 This option is mainly of interest to BIND 9 developers and may be 134 removed or changed in a future release. 135 136``-S #max-socks`` 137 This option allows ``named`` to use up to ``#max-socks`` sockets. The default value is 138 21000 on systems built with default configuration options, and 4096 139 on systems built with ``configure --with-tuning=small``. 140 141.. warning:: 142 143 This option should be unnecessary for the vast majority of users. 144 The use of this option could even be harmful, because the specified 145 value may exceed the limitation of the underlying system API. It 146 is therefore set only when the default configuration causes 147 exhaustion of file descriptors and the operational environment is 148 known to support the specified number of sockets. Note also that 149 the actual maximum number is normally slightly fewer than the 150 specified value, because ``named`` reserves some file descriptors 151 for its internal use. 152 153``-t directory`` 154 This option tells ``named`` to chroot to ``directory`` after processing the command-line arguments, but 155 before reading the configuration file. 156 157.. warning:: 158 159 This option should be used in conjunction with the ``-u`` option, 160 as chrooting a process running as root doesn't enhance security on 161 most systems; the way ``chroot`` is defined allows a process 162 with root privileges to escape a chroot jail. 163 164``-U #listeners`` 165 This option tells ``named`` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on 166 each address. If not specified, ``named`` calculates a default 167 value based on the number of detected CPUs: 1 for 1 CPU, and the 168 number of detected CPUs minus one for machines with more than 1 CPU. 169 This cannot be increased to a value higher than the number of CPUs. 170 If ``-n`` has been set to a higher value than the number of detected 171 CPUs, then ``-U`` may be increased as high as that value, but no 172 higher. On Windows, the number of UDP listeners is hardwired to 1 and 173 this option has no effect. 174 175``-u user`` 176 This option sets the setuid to ``user`` after completing privileged operations, such as 177 creating sockets that listen on privileged ports. 178 179.. note:: 180 181 On Linux, ``named`` uses the kernel's capability mechanism to drop 182 all root privileges except the ability to ``bind`` to a 183 privileged port and set process resource limits. Unfortunately, 184 this means that the ``-u`` option only works when ``named`` is run 185 on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or later, since 186 previous kernels did not allow privileges to be retained after 187 ``setuid``. 188 189``-v`` 190 This option reports the version number and exits. 191 192``-V`` 193 This option reports the version number, build options, supported 194 cryptographics algorithms, and exits. 195 196``-X lock-file`` 197 This option acquires a lock on the specified file at runtime; this helps to 198 prevent duplicate ``named`` instances from running simultaneously. 199 Use of this option overrides the ``lock-file`` option in 200 ``named.conf``. If set to ``none``, the lock file check is disabled. 201 202``-x cache-file`` 203 This option loads data from ``cache-file`` into the cache of the default view. 204 205.. warning:: 206 207 This option must not be used in normal operations. It is only of interest to BIND 9 208 developers and may be removed or changed in a future release. 209 210Signals 211~~~~~~~ 212 213In routine operation, signals should not be used to control the 214nameserver; ``rndc`` should be used instead. 215 216SIGHUP 217 This signal forces a reload of the server. 218 219SIGINT, SIGTERM 220 These signals shut down the server. 221 222The result of sending any other signals to the server is undefined. 223 224Configuration 225~~~~~~~~~~~~~ 226 227The ``named`` configuration file is too complex to describe in detail 228here. A complete description is provided in the BIND 9 Administrator 229Reference Manual. 230 231``named`` inherits the ``umask`` (file creation mode mask) from the 232parent process. If files created by ``named``, such as journal files, 233need to have custom permissions, the ``umask`` should be set explicitly 234in the script used to start the ``named`` process. 235 236Files 237~~~~~ 238 239``/etc/named.conf`` 240 The default configuration file. 241 242``/var/run/named/named.pid`` 243 The default process-id file. 244 245See Also 246~~~~~~~~ 247 248:rfc:`1033`, :rfc:`1034`, :rfc:`1035`, :manpage:`named-checkconf(8)`, :manpage:`named-checkzone(8)`, :manpage:`rndc(8)`, :manpage:`named.conf(5)`, BIND 9 Administrator Reference Manual. 249