docs: networking: convert dns_resolver.txt to ReST

- add SPDX header;
- adjust titles and chapters, adding proper markups;
- comment out text-only TOC from html/pdf output;

- mark code blocks and literals as such;

- adjust identation, whitespaces and blank lines;
- add to networking/index.rst.

Signed-off-by: Mauro Carvalho Chehab <mchehab+huawei@kernel.org>
Signed-off-by: David S. Miller <davem@davemloft.net>
This commit is contained in:
Mauro Carvalho Chehab 2020-04-28 00:01:32 +02:00 committed by David S. Miller
parent 5f32c920c2
commit 9dfe136126
6 changed files with 30 additions and 31 deletions

View File

@ -1,8 +1,10 @@
=================== .. SPDX-License-Identifier: GPL-2.0
DNS Resolver Module
===================
Contents: ===================
DNS Resolver Module
===================
.. Contents:
- Overview. - Overview.
- Compilation. - Compilation.
@ -12,8 +14,7 @@ Contents:
- Debugging. - Debugging.
======== Overview
OVERVIEW
======== ========
The DNS resolver module provides a way for kernel services to make DNS queries The DNS resolver module provides a way for kernel services to make DNS queries
@ -33,50 +34,50 @@ It does not yet support the following AFS features:
This code is extracted from the CIFS filesystem. This code is extracted from the CIFS filesystem.
=========== Compilation
COMPILATION
=========== ===========
The module should be enabled by turning on the kernel configuration options: The module should be enabled by turning on the kernel configuration options::
CONFIG_DNS_RESOLVER - tristate "DNS Resolver support" CONFIG_DNS_RESOLVER - tristate "DNS Resolver support"
========== Setting up
SETTING UP
========== ==========
To set up this facility, the /etc/request-key.conf file must be altered so that To set up this facility, the /etc/request-key.conf file must be altered so that
/sbin/request-key can appropriately direct the upcalls. For example, to handle /sbin/request-key can appropriately direct the upcalls. For example, to handle
basic dname to IPv4/IPv6 address resolution, the following line should be basic dname to IPv4/IPv6 address resolution, the following line should be
added: added::
#OP TYPE DESC CO-INFO PROGRAM ARG1 ARG2 ARG3 ... #OP TYPE DESC CO-INFO PROGRAM ARG1 ARG2 ARG3 ...
#====== ============ ======= ======= ========================== #====== ============ ======= ======= ==========================
create dns_resolver * * /usr/sbin/cifs.upcall %k create dns_resolver * * /usr/sbin/cifs.upcall %k
To direct a query for query type 'foo', a line of the following should be added To direct a query for query type 'foo', a line of the following should be added
before the more general line given above as the first match is the one taken. before the more general line given above as the first match is the one taken::
create dns_resolver foo:* * /usr/sbin/dns.foo %k create dns_resolver foo:* * /usr/sbin/dns.foo %k
===== Usage
USAGE
===== =====
To make use of this facility, one of the following functions that are To make use of this facility, one of the following functions that are
implemented in the module can be called after doing: implemented in the module can be called after doing::
#include <linux/dns_resolver.h> #include <linux/dns_resolver.h>
(1) int dns_query(const char *type, const char *name, size_t namelen, ::
const char *options, char **_result, time_t *_expiry);
int dns_query(const char *type, const char *name, size_t namelen,
const char *options, char **_result, time_t *_expiry);
This is the basic access function. It looks for a cached DNS query and if This is the basic access function. It looks for a cached DNS query and if
it doesn't find it, it upcalls to userspace to make a new DNS query, which it doesn't find it, it upcalls to userspace to make a new DNS query, which
may then be cached. The key description is constructed as a string of the may then be cached. The key description is constructed as a string of the
form: form::
[<type>:]<name> [<type>:]<name>
@ -107,16 +108,14 @@ This can be cleared by any process that has the CAP_SYS_ADMIN capability by
the use of KEYCTL_KEYRING_CLEAR on the keyring ID. the use of KEYCTL_KEYRING_CLEAR on the keyring ID.
=============================== Reading DNS Keys from Userspace
READING DNS KEYS FROM USERSPACE
=============================== ===============================
Keys of dns_resolver type can be read from userspace using keyctl_read() or Keys of dns_resolver type can be read from userspace using keyctl_read() or
"keyctl read/print/pipe". "keyctl read/print/pipe".
========= Mechanism
MECHANISM
========= =========
The dnsresolver module registers a key type called "dns_resolver". Keys of The dnsresolver module registers a key type called "dns_resolver". Keys of
@ -147,11 +146,10 @@ See <file:Documentation/security/keys/request-key.rst> for further
information about request-key function. information about request-key function.
========= Debugging
DEBUGGING
========= =========
Debugging messages can be turned on dynamically by writing a 1 into the Debugging messages can be turned on dynamically by writing a 1 into the
following file: following file::
/sys/module/dnsresolver/parameters/debug /sys/module/dnsresolver/parameters/debug

View File

@ -52,6 +52,7 @@ Contents:
dctcp dctcp
decnet decnet
defza defza
dns_resolver
.. only:: subproject and html .. only:: subproject and html

View File

@ -39,6 +39,6 @@ config CEPH_LIB_USE_DNS_RESOLVER
be resolved using the CONFIG_DNS_RESOLVER facility. be resolved using the CONFIG_DNS_RESOLVER facility.
For information on how to use CONFIG_DNS_RESOLVER consult For information on how to use CONFIG_DNS_RESOLVER consult
Documentation/networking/dns_resolver.txt Documentation/networking/dns_resolver.rst
If unsure, say N. If unsure, say N.

View File

@ -19,7 +19,7 @@ config DNS_RESOLVER
SMB2 later. DNS Resolver is supported by the userspace upcall SMB2 later. DNS Resolver is supported by the userspace upcall
helper "/sbin/dns.resolver" via /etc/request-key.conf. helper "/sbin/dns.resolver" via /etc/request-key.conf.
See <file:Documentation/networking/dns_resolver.txt> for further See <file:Documentation/networking/dns_resolver.rst> for further
information. information.
To compile this as a module, choose M here: the module will be called To compile this as a module, choose M here: the module will be called

View File

@ -1,6 +1,6 @@
/* Key type used to cache DNS lookups made by the kernel /* Key type used to cache DNS lookups made by the kernel
* *
* See Documentation/networking/dns_resolver.txt * See Documentation/networking/dns_resolver.rst
* *
* Copyright (c) 2007 Igor Mammedov * Copyright (c) 2007 Igor Mammedov
* Author(s): Igor Mammedov (niallain@gmail.com) * Author(s): Igor Mammedov (niallain@gmail.com)

View File

@ -1,7 +1,7 @@
/* Upcall routine, designed to work as a key type and working through /* Upcall routine, designed to work as a key type and working through
* /sbin/request-key to contact userspace when handling DNS queries. * /sbin/request-key to contact userspace when handling DNS queries.
* *
* See Documentation/networking/dns_resolver.txt * See Documentation/networking/dns_resolver.rst
* *
* Copyright (c) 2007 Igor Mammedov * Copyright (c) 2007 Igor Mammedov
* Author(s): Igor Mammedov (niallain@gmail.com) * Author(s): Igor Mammedov (niallain@gmail.com)