Adding upstream version 1:9.18.19.upstream/1%9.18.19

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 254 insertions, 0 deletions

diff --git a/bin/named/named.rst b/bin/named/named.rst
new file mode 100644
index 0000000..dc6e46d
--- /dev/null
+++ b/bin/named/named.rst
@@ -0,0 +1,254 @@
+.. Copyright (C) Internet Systems Consortium, Inc. ("ISC")
+..
+.. SPDX-License-Identifier: MPL-2.0
+..
+.. This Source Code Form is subject to the terms of the Mozilla Public
+.. License, v. 2.0.  If a copy of the MPL was not distributed with this
+.. file, you can obtain one at https://mozilla.org/MPL/2.0/.
+..
+.. See the COPYRIGHT file distributed with this work for additional
+.. information regarding copyright ownership.
+
+.. highlight: console
+
+.. iscman:: named
+.. program:: named
+.. _man_named:
+
+named - Internet domain name server
+-----------------------------------
+
+Synopsis
+~~~~~~~~
+
+: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**] [**-t** directory] [**-U** #listeners] [**-u** user] [**-v**] [**-V**] [**-X** lock-file]
+
+Description
+~~~~~~~~~~~
+
+:program:`named` is a Domain Name System (DNS) server, part of the BIND 9
+distribution from ISC. For more information on the DNS, see :rfc:`1033`,
+:rfc:`1034`, and :rfc:`1035`.
+
+When invoked without arguments, :program:`named` reads the default
+configuration file |named_conf|, reads any initial data, and
+listens for queries.
+
+Options
+~~~~~~~
+
+.. option:: -4
+
+   This option tells :program:`named` to use only IPv4, even if the host machine is capable of IPv6. :option:`-4` and
+   :option:`-6` are mutually exclusive.
+
+.. option:: -6
+
+   This option tells :program:`named` to use only IPv6, even if the host machine is capable of IPv4. :option:`-4` and
+   :option:`-6` are mutually exclusive.
+
+.. option:: -c config-file
+
+   This option tells :program:`named` to use ``config-file`` as its configuration file instead of the default,
+   |named_conf|. To ensure that the configuration file
+   can be reloaded after the server has changed its working directory
+   due to to a possible ``directory`` option in the configuration file,
+   ``config-file`` should be an absolute pathname.
+
+.. option:: -C
+
+   This option prints out the default built-in configuration and exits.
+
+   NOTE: This is for debugging purposes only and is not an
+   accurate representation of the actual configuration used by :iscman:`named`
+   at runtime.
+
+.. option:: -d debug-level
+
+   This option sets the daemon's debug level to ``debug-level``. Debugging traces from
+   :program:`named` become more verbose as the debug level increases.
+
+.. option:: -D string
+
+   This option specifies a string that is used to identify a instance of :program:`named`
+   in a process listing. The contents of ``string`` are not examined.
+
+.. option:: -E engine-name
+
+   When applicable, this option specifies the hardware to use for cryptographic
+   operations, such as a secure key store used for signing.
+
+   When BIND 9 is built with OpenSSL, this needs to be set to the OpenSSL
+   engine identifier that drives the cryptographic accelerator or
+   hardware service module (usually ``pkcs11``).
+
+.. option:: -f
+
+   This option runs the server in the foreground (i.e., do not daemonize).
+
+.. option:: -g
+
+   This option runs the server in the foreground and forces all logging to ``stderr``.
+
+.. option:: -L logfile
+
+   This option sets the log to the file ``logfile`` by default, instead of the system log.
+
+.. option:: -M option
+
+   This option sets the default (comma-separated) memory context
+   options. The possible flags are:
+
+   - ``fill``: fill blocks of memory with tag values when they are
+     allocated or freed, to assist debugging of memory problems; this is
+     the implicit default if :program:`named` has been compiled with
+     ``--enable-developer``.
+
+   - ``nofill``: disable the behavior enabled by ``fill``; this is the
+     implicit default unless :program:`named` has been compiled with
+     ``--enable-developer``.
+
+.. option:: -m flag
+
+   This option turns on memory usage debugging flags. Possible flags are ``usage``,
+   ``trace``, ``record``, ``size``, and ``mctx``. These correspond to the
+   ``ISC_MEM_DEBUGXXXX`` flags described in ``<isc/mem.h>``.
+
+.. option:: -n #cpus
+
+   This option creates ``#cpus`` worker threads to take advantage of multiple CPUs. If
+   not specified, :program:`named` tries to determine the number of CPUs
+   present and creates one thread per CPU. If it is unable to determine
+   the number of CPUs, a single worker thread is created.
+
+.. option:: -p value
+
+   This option specifies the port(s) on which the server will listen
+   for queries. If ``value`` is of the form ``<portnum>`` or
+   ``dns=<portnum>``, the server will listen for DNS queries on
+   ``portnum``; if not not specified, the default is port 53. If
+   ``value`` is of the form ``tls=<portnum>``, the server will
+   listen for TLS queries on ``portnum``; the default is 853.
+   If ``value`` is of the form ``https=<portnum>``, the server will
+   listen for HTTPS queries on ``portnum``; the default is 443.
+   If ``value`` is of the form ``http=<portnum>``, the server will
+   listen for HTTP queries on ``portnum``; the default is 80.
+
+.. option:: -s
+
+   This option writes memory usage statistics to ``stdout`` on exit.
+
+.. note::
+
+      This option is mainly of interest to BIND 9 developers and may be
+      removed or changed in a future release.
+
+.. option:: -S #max-socks
+
+   This option is deprecated and no longer has any function.
+
+.. warning::
+
+      This option should be unnecessary for the vast majority of users.
+      The use of this option could even be harmful, because the specified
+      value may exceed the limitation of the underlying system API. It
+      is therefore set only when the default configuration causes
+      exhaustion of file descriptors and the operational environment is
+      known to support the specified number of sockets. Note also that
+      the actual maximum number is normally slightly fewer than the
+      specified value, because :program:`named` reserves some file descriptors
+      for its internal use.
+
+.. option:: -t directory
+
+   This option tells :program:`named` to chroot to ``directory`` after processing the command-line arguments, but
+   before reading the configuration file.
+
+.. warning::
+
+      This option should be used in conjunction with the :option:`-u` option,
+      as chrooting a process running as root doesn't enhance security on
+      most systems; the way ``chroot`` is defined allows a process
+      with root privileges to escape a chroot jail.
+
+.. option:: -U #listeners
+
+   This option tells :program:`named` the number of ``#listeners`` worker threads to listen on, for incoming UDP packets on
+   each address. If not specified, :program:`named` calculates a default
+   value based on the number of detected CPUs: 1 for 1 CPU, and the
+   number of detected CPUs minus one for machines with more than 1 CPU.
+   This cannot be increased to a value higher than the number of CPUs.
+   If :option:`-n` has been set to a higher value than the number of detected
+   CPUs, then :option:`-U` may be increased as high as that value, but no
+   higher.
+
+.. option:: -u user
+
+   This option sets the setuid to ``user`` after completing privileged operations, such as
+   creating sockets that listen on privileged ports.
+
+.. note::
+
+      On Linux, :program:`named` uses the kernel's capability mechanism to drop
+      all root privileges except the ability to ``bind`` to a
+      privileged port and set process resource limits. Unfortunately,
+      this means that the :option:`-u` option only works when :program:`named` is run
+      on kernel 2.2.18 or later, or kernel 2.3.99-pre3 or later, since
+      previous kernels did not allow privileges to be retained after
+      ``setuid``.
+
+.. option:: -v
+
+   This option reports the version number and exits.
+
+.. option:: -V
+
+   This option reports the version number, build options, supported
+   cryptographics algorithms, and exits.
+
+.. option:: -X lock-file
+
+   This option acquires a lock on the specified file at runtime; this helps to
+   prevent duplicate :program:`named` instances from running simultaneously.
+   Use of this option overrides the ``lock-file`` option in
+   :iscman:`named.conf`. If set to ``none``, the lock file check is disabled.
+
+Signals
+~~~~~~~
+
+In routine operation, signals should not be used to control the
+nameserver; :iscman:`rndc` should be used instead.
+
+SIGHUP
+   This signal forces a reload of the server.
+
+SIGINT, SIGTERM
+   These signals shut down the server.
+
+The result of sending any other signals to the server is undefined.
+
+Configuration
+~~~~~~~~~~~~~
+
+The :program:`named` configuration file is too complex to describe in detail
+here. A complete description is provided in the BIND 9 Administrator
+Reference Manual.
+
+:program:`named` inherits the ``umask`` (file creation mode mask) from the
+parent process. If files created by :program:`named`, such as journal files,
+need to have custom permissions, the ``umask`` should be set explicitly
+in the script used to start the :program:`named` process.
+
+Files
+~~~~~
+
+|named_conf|
+   The default configuration file.
+
+|named_pid|
+   The default process-id file.
+
+See Also
+~~~~~~~~
+
+:rfc:`1033`, :rfc:`1034`, :rfc:`1035`, :iscman:`named-checkconf(8) <named-checkconf>`, :iscman:`named-checkzone(8) <named-checkzone>`, :iscman:`rndc(8) <rndc>`, :iscman:`named.conf(5) <named.conf>`, BIND 9 Administrator Reference Manual.