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 creates ``#cpus`` worker threads to take advantage of multiple CPUs. If 115 not specified, ``named`` tries to determine the number of CPUs 116 present and creates one thread per CPU. If it is unable to determine 117 the number of CPUs, a single worker thread is created. 118 119``-p port`` 120 This option listens for queries on ``port``. If not specified, the default is 121 port 53. 122 123``-s`` 124 This option writes memory usage statistics to ``stdout`` on exit. 125 126.. note:: 127 128 This option is mainly of interest to BIND 9 developers and may be 129 removed or changed in a future release. 130 131``-S #max-socks`` 132 This option allows ``named`` to use up to ``#max-socks`` sockets. The default value is 133 21000 on systems built with default configuration options, and 4096 134 on systems built with ``configure --with-tuning=small``. 135 136.. warning:: 137 138 This option should be unnecessary for the vast majority of users. 139 The use of this option could even be harmful, because the specified 140 value may exceed the limitation of the underlying system API. It 141 is therefore set only when the default configuration causes 142 exhaustion of file descriptors and the operational environment is 143 known to support the specified number of sockets. Note also that 144 the actual maximum number is normally slightly fewer than the 145 specified value, because ``named`` reserves some file descriptors 146 for its internal use. 147 148``-t directory`` 149 This option tells ``named`` to chroot to ``directory`` after processing the command-line arguments, but 150 before reading the configuration file. 151 152.. warning:: 153 154 This option should be used in conjunction with the ``-u`` option, 155 as chrooting a process running as root doesn't enhance security on 156 most systems; the way ``chroot`` is defined allows a process 157 with root privileges to escape a chroot jail. 158 159``-U #listeners`` 160 This option tells ``named`` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on 161 each address. If not specified, ``named`` calculates a default 162 value based on the number of detected CPUs: 1 for 1 CPU, and the 163 number of detected CPUs minus one for machines with more than 1 CPU. 164 This cannot be increased to a value higher than the number of CPUs. 165 If ``-n`` has been set to a higher value than the number of detected 166 CPUs, then ``-U`` may be increased as high as that value, but no 167 higher. On Windows, the number of UDP listeners is hardwired to 1 and 168 this option has no effect. 169 170``-u user`` 171 This option sets the setuid to ``user`` after completing privileged operations, such as 172 creating sockets that listen on privileged ports. 173 174.. note:: 175 176 On Linux, ``named`` uses the kernel's capability mechanism to drop 177 all root privileges except the ability to ``bind`` to a 178 privileged port and set process resource limits. Unfortunately, 179 this means that the ``-u`` option only works when ``named`` is run 180 on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or later, since 181 previous kernels did not allow privileges to be retained after 182 ``setuid``. 183 184``-v`` 185 This option reports the version number and exits. 186 187``-V`` 188 This option reports the version number and build options, and exits. 189 190``-X lock-file`` 191 This option acquires a lock on the specified file at runtime; this helps to 192 prevent duplicate ``named`` instances from running simultaneously. 193 Use of this option overrides the ``lock-file`` option in 194 ``named.conf``. If set to ``none``, the lock file check is disabled. 195 196``-x cache-file`` 197 This option loads data from ``cache-file`` into the cache of the default view. 198 199.. warning:: 200 201 This option must not be used in normal operations. It is only of interest to BIND 9 202 developers and may be removed or changed in a future release. 203 204Signals 205~~~~~~~ 206 207In routine operation, signals should not be used to control the 208nameserver; ``rndc`` should be used instead. 209 210SIGHUP 211 This signal forces a reload of the server. 212 213SIGINT, SIGTERM 214 These signals shut down the server. 215 216The result of sending any other signals to the server is undefined. 217 218Configuration 219~~~~~~~~~~~~~ 220 221The ``named`` configuration file is too complex to describe in detail 222here. A complete description is provided in the BIND 9 Administrator 223Reference Manual. 224 225``named`` inherits the ``umask`` (file creation mode mask) from the 226parent process. If files created by ``named``, such as journal files, 227need to have custom permissions, the ``umask`` should be set explicitly 228in the script used to start the ``named`` process. 229 230Files 231~~~~~ 232 233``/etc/named.conf`` 234 The default configuration file. 235 236``/var/run/named/named.pid`` 237 The default process-id file. 238 239See Also 240~~~~~~~~ 241 242: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. 243