€•LŒsphinx.addnodes”Œdocument”“”)”}”(Œ rawsource”Œ”Œchildren”]”(Œ translations”Œ LanguagesNode”“”)”}”(hhh]”(hŒ pending_xref”“”)”}”(hhh]”Œdocutils.nodes”ŒText”“”ŒChinese (Simplified)”…””}”Œparent”hsbaŒ attributes”}”(Œids”]”Œclasses”]”Œnames”]”Œdupnames”]”Œbackrefs”]”Œ refdomain”Œstd”Œreftype”Œdoc”Œ reftarget”Œ+/translations/zh_CN/networking/dns_resolver”Œmodname”NŒ classname”NŒ refexplicit”ˆuŒtagname”hhh ubh)”}”(hhh]”hŒChinese (Traditional)”…””}”hh2sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/zh_TW/networking/dns_resolver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒItalian”…””}”hhFsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/it_IT/networking/dns_resolver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒJapanese”…””}”hhZsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/ja_JP/networking/dns_resolver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒKorean”…””}”hhnsbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/ko_KR/networking/dns_resolver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubh)”}”(hhh]”hŒSpanish”…””}”hh‚sbah}”(h]”h ]”h"]”h$]”h&]”Œ refdomain”h)Œreftype”h+Œ reftarget”Œ+/translations/sp_SP/networking/dns_resolver”Œmodname”NŒ classname”NŒ refexplicit”ˆuh1hhh ubeh}”(h]”h ]”h"]”h$]”h&]”Œcurrent_language”ŒEnglish”uh1h hhŒ _document”hŒsource”NŒline”NubhŒcomment”“”)”}”(hŒ SPDX-License-Identifier: GPL-2.0”h]”hŒ SPDX-License-Identifier: GPL-2.0”…””}”hh£sbah}”(h]”h ]”h"]”h$]”h&]”Œ xml:space”Œpreserve”uh1h¡hhhžhhŸŒE/var/lib/git/docbuild/linux/Documentation/networking/dns_resolver.rst”h KubhŒsection”“”)”}”(hhh]”(hŒtitle”“”)”}”(hŒDNS Resolver Module”h]”hŒDNS Resolver Module”…””}”(hh»hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh¶hžhhŸh³h Kubh¢)”}”(hŒVContents: - Overview. - Compilation. - Setting up. - Usage. - Mechanism. - Debugging.”h]”hŒVContents: - Overview. - Compilation. - Setting up. - Usage. - Mechanism. - Debugging.”…””}”hhÉsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1h¡hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒOverview”h]”hŒOverview”…””}”(hhÚhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hh×hžhhŸh³h KubhŒ paragraph”“”)”}”(hŒÇThe DNS resolver module provides a way for kernel services to make DNS queries by way of requesting a key of key type dns_resolver. These queries are upcalled to userspace through /sbin/request-key.”h]”hŒÇThe DNS resolver module provides a way for kernel services to make DNS queries by way of requesting a key of key type dns_resolver. These queries are upcalled to userspace through /sbin/request-key.”…””}”(hhêhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubhé)”}”(hŒËThese routines must be supported by userspace tools dns.upcall, cifs.upcall and request-key. It is under development and does not yet provide the full feature set. The features it does support include:”h]”hŒËThese routines must be supported by userspace tools dns.upcall, cifs.upcall and request-key. It is under development and does not yet provide the full feature set. The features it does support include:”…””}”(hhøhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubhŒ block_quote”“”)”}”(hŒ=* Implements the dns_resolver key_type to contact userspace. ”h]”hŒ bullet_list”“”)”}”(hhh]”hŒ list_item”“”)”}”(hŒ;Implements the dns_resolver key_type to contact userspace. ”h]”hé)”}”(hŒ:Implements the dns_resolver key_type to contact userspace.”h]”hŒ:Implements the dns_resolver key_type to contact userspace.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khjubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjubah}”(h]”h ]”h"]”h$]”h&]”Œbullet”Œ*”uh1j hŸh³h Khjubah}”(h]”h ]”h"]”h$]”h&]”uh1jhŸh³h Khh×hžhubhé)”}”(hŒ3It does not yet support the following AFS features:”h]”hŒ3It does not yet support the following AFS features:”…””}”(hj9hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubj)”}”(hŒ/* DNS query support for AFSDB resource record. ”h]”j )”}”(hhh]”j)”}”(hŒ-DNS query support for AFSDB resource record. ”h]”hé)”}”(hŒ,DNS query support for AFSDB resource record.”h]”hŒ,DNS query support for AFSDB resource record.”…””}”(hjRhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K hjNubah}”(h]”h ]”h"]”h$]”h&]”uh1jhjKubah}”(h]”h ]”h"]”h$]”h&]”j1j2uh1j hŸh³h K hjGubah}”(h]”h ]”h"]”h$]”h&]”uh1jhŸh³h K hh×hžhubhé)”}”(hŒ0This code is extracted from the CIFS filesystem.”h]”hŒ0This code is extracted from the CIFS filesystem.”…””}”(hjrhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K"hh×hžhubeh}”(h]”Œoverview”ah ]”h"]”Œoverview”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kubhµ)”}”(hhh]”(hº)”}”(hŒ Compilation”h]”hŒ Compilation”…””}”(hj‹hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjˆhžhhŸh³h K&ubhé)”}”(hŒMThe module should be enabled by turning on the kernel configuration options::”h]”hŒLThe module should be enabled by turning on the kernel configuration options:”…””}”(hj™hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K(hjˆhžhubhŒ literal_block”“”)”}”(hŒ9CONFIG_DNS_RESOLVER - tristate "DNS Resolver support"”h]”hŒ9CONFIG_DNS_RESOLVER - tristate "DNS Resolver support"”…””}”hj©sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j§hŸh³h K*hjˆhžhubeh}”(h]”Œ compilation”ah ]”h"]”Œ compilation”ah$]”h&]”uh1h´hh¶hžhhŸh³h K&ubhµ)”}”(hhh]”(hº)”}”(hŒ Setting up”h]”hŒ Setting up”…””}”(hjÂhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj¿hžhhŸh³h K.ubhé)”}”(hŒñ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 basic dname to IPv4/IPv6 address resolution, the following line should be added::”h]”hŒð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 basic dname to IPv4/IPv6 address resolution, the following line should be added:”…””}”(hjÐhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K0hj¿hžhubj¨)”}”(hŒÆ#OP TYPE DESC CO-INFO PROGRAM ARG1 ARG2 ARG3 ... #====== ============ ======= ======= ========================== create dns_resolver * * /usr/sbin/cifs.upcall %k”h]”hŒÆ#OP TYPE DESC CO-INFO PROGRAM ARG1 ARG2 ARG3 ... #====== ============ ======= ======= ========================== create dns_resolver * * /usr/sbin/cifs.upcall %k”…””}”hjÞsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j§hŸh³h K6hj¿hžhubhé)”}”(hŒž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::”h]”hŒ¡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:”…””}”(hjìhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K:hj¿hžhubj¨)”}”(hŒ”h]”hŒ#include ”…””}”hjCsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j§hŸh³h KEhjhžhubhé)”}”(hŒ%Then queries may be made by calling::”h]”hŒ$Then queries may be made by calling:”…””}”(hjQhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KGhjhžhubj¨)”}”(hŒ…int dns_query(const char *type, const char *name, size_t namelen, const char *options, char **_result, time_t *_expiry);”h]”hŒ…int dns_query(const char *type, const char *name, size_t namelen, const char *options, char **_result, time_t *_expiry);”…””}”hj_sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j§hŸh³h KIhjhžhubhé)”}”(hŒç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 may then be cached. The key description is constructed as a string of the form::”h]”hŒè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 may then be cached. The key description is constructed as a string of the form:”…””}”(hjmhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KLhjhžhubj¨)”}”(hŒ[:]”h]”hŒ[:]”…””}”hj{sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j§hŸh³h KQhjhžhubhé)”}”(hŒßwhere optionally specifies the particular upcall program to invoke, and thus the type of query, and specifies the string to be looked up. The default query type is a straight hostname to IP address set lookup.”h]”hŒßwhere optionally specifies the particular upcall program to invoke, and thus the type of query, and specifies the string to be looked up. The default query type is a straight hostname to IP address set lookup.”…””}”(hj‰hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KShjhžhubhé)”}”(hŒyThe name parameter is not required to be a NUL-terminated string, and its length should be given by the namelen argument.”h]”hŒyThe name parameter is not required to be a NUL-terminated string, and its length should be given by the namelen argument.”…””}”(hj—hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KWhjhžhubhé)”}”(hŒ^The options parameter may be NULL or it may be a set of options appropriate to the query type.”h]”hŒ^The options parameter may be NULL or it may be a set of options appropriate to the query type.”…””}”(hj¥hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KZhjhžhubhé)”}”(hŒÅThe return value is a string appropriate to the query type. For instance, for the default query type it is just a list of comma-separated IPv4 and IPv6 addresses. The caller must free the result.”h]”hŒÅThe return value is a string appropriate to the query type. For instance, for the default query type it is just a list of comma-separated IPv4 and IPv6 addresses. The caller must free the result.”…””}”(hj³hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K]hjhžhubhé)”}”(hŒ¢The length of the result string is returned on success, and a negative error code is returned otherwise. -EKEYREJECTED will be returned if the DNS lookup failed.”h]”hŒ¢The length of the result string is returned on success, and a negative error code is returned otherwise. -EKEYREJECTED will be returned if the DNS lookup failed.”…””}”(hjÁhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kahjhžhubhé)”}”(hŒRIf _expiry is non-NULL, the expiry time (TTL) of the result will be returned also.”h]”hŒRIf _expiry is non-NULL, the expiry time (TTL) of the result will be returned also.”…””}”(hjÏhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kehjhžhubhé)”}”(hŒÊThe kernel maintains an internal keyring in which it caches looked up keys. 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.”h]”hŒÊThe kernel maintains an internal keyring in which it caches looked up keys. 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.”…””}”(hjÝhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khhjhžhubeh}”(h]”Œusage”ah ]”h"]”Œusage”ah$]”h&]”uh1h´hh¶hžhhŸh³h KAubhµ)”}”(hhh]”(hº)”}”(hŒReading DNS Keys from Userspace”h]”hŒReading DNS Keys from Userspace”…””}”(hjöhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjóhžhhŸh³h Knubhé)”}”(hŒeKeys of dns_resolver type can be read from userspace using keyctl_read() or "keyctl read/print/pipe".”h]”hŒiKeys of dns_resolver type can be read from userspace using keyctl_read() or “keyctl read/print/pipeâ€.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kphjóhžhubeh}”(h]”Œreading-dns-keys-from-userspace”ah ]”h"]”Œreading dns keys from userspace”ah$]”h&]”uh1h´hh¶hžhhŸh³h Knubhµ)”}”(hhh]”(hº)”}”(hŒ Mechanism”h]”hŒ Mechanism”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjhžhhŸh³h Kuubhé)”}”(hŒ™The dns_resolver module registers a key type called "dns_resolver". Keys of this type are used to transport and cache DNS lookup results from userspace.”h]”hŒThe dns_resolver module registers a key type called “dns_resolverâ€. Keys of this type are used to transport and cache DNS lookup results from userspace.”…””}”(hj+hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kwhjhžhubhé)”}”(hŒ²When dns_query() is invoked, it calls request_key() to search the local keyrings for a cached DNS result. If that fails to find one, it upcalls to userspace to get a new result.”h]”hŒ²When dns_query() is invoked, it calls request_key() to search the local keyrings for a cached DNS result. If that fails to find one, it upcalls to userspace to get a new result.”…””}”(hj9hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kzhjhžhubhé)”}”(hŒØUpcalls to userspace are made through the request_key() upcall vector, and are directed by means of configuration lines in /etc/request-key.conf that tell /sbin/request-key what program to run to instantiate the key.”h]”hŒØUpcalls to userspace are made through the request_key() upcall vector, and are directed by means of configuration lines in /etc/request-key.conf that tell /sbin/request-key what program to run to instantiate the key.”…””}”(hjGhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K~hjhžhubhé)”}”(hXbThe upcall handler program is responsible for querying the DNS, processing the result into a form suitable for passing to the keyctl_instantiate_key() routine. This then passes the data to dns_resolver_instantiate() which strips off and processes any options included in the data, and then attaches the remainder of the string to the key as its payload.”h]”hXbThe upcall handler program is responsible for querying the DNS, processing the result into a form suitable for passing to the keyctl_instantiate_key() routine. This then passes the data to dns_resolver_instantiate() which strips off and processes any options included in the data, and then attaches the remainder of the string to the key as its payload.”…””}”(hjUhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K‚hjhžhubhé)”}”(hŒêThe upcall handler program should set the expiry time on the key to that of the lowest TTL of all the records it has extracted a result from. This means that the key will be discarded and recreated when the data it holds has expired.”h]”hŒêThe upcall handler program should set the expiry time on the key to that of the lowest TTL of all the records it has extracted a result from. This means that the key will be discarded and recreated when the data it holds has expired.”…””}”(hjchžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kˆhjhžhubhé)”}”(hŒfdns_query() returns a copy of the value attached to the key, or an error if that is indicated instead.”h]”hŒfdns_query() returns a copy of the value attached to the key, or an error if that is indicated instead.”…””}”(hjqhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KŒhjhžhubhé)”}”(hŒcSee Documentation/security/keys/request-key.rst for further information about request-key function.”h]”hŒcSee Documentation/security/keys/request-key.rst for further information about request-key function.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khjhžhubeh}”(h]”Œ mechanism”ah ]”h"]”Œ mechanism”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kuubhµ)”}”(hhh]”(hº)”}”(hŒ Debugging”h]”hŒ Debugging”…””}”(hj˜hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hj•hžhhŸh³h K”ubhé)”}”(hŒXDebugging messages can be turned on dynamically by writing a 1 into the following file::”h]”hŒWDebugging messages can be turned on dynamically by writing a 1 into the following file:”…””}”(hj¦hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K–hj•hžhubj¨)”}”(hŒ)/sys/module/dns_resolver/parameters/debug”h]”hŒ)/sys/module/dns_resolver/parameters/debug”…””}”hj´sbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j§hŸh³h K™hj•hžhubeh}”(h]”Œ debugging”ah ]”h"]”Œ debugging”ah$]”h&]”uh1h´hh¶hžhhŸh³h K”ubeh}”(h]”Œdns-resolver-module”ah ]”h"]”Œdns resolver module”ah$]”h&]”uh1h´hhhžhhŸh³h Kubeh}”(h]”h ]”h"]”h$]”h&]”Œsource”h³uh1hŒcurrent_source”NŒ current_line”NŒsettings”Œdocutils.frontend”ŒValues”“”)”}”(h¹NŒ generator”NŒ datestamp”NŒ source_link”NŒ source_url”NŒ toc_backlinks”Œentry”Œfootnote_backlinks”KŒ sectnum_xform”KŒstrip_comments”NŒstrip_elements_with_classes”NŒ strip_classes”NŒ report_level”KŒ halt_level”KŒexit_status_level”KŒdebug”NŒwarning_stream”NŒ traceback”ˆŒinput_encoding”Œ utf-8-sig”Œinput_encoding_error_handler”Œstrict”Œoutput_encoding”Œutf-8”Œoutput_encoding_error_handler”jõŒerror_encoding”Œutf-8”Œerror_encoding_error_handler”Œbackslashreplace”Œ language_code”Œen”Œrecord_dependencies”NŒconfig”NŒ id_prefix”hŒauto_id_prefix”Œid”Œ dump_settings”NŒdump_internals”NŒdump_transforms”NŒdump_pseudo_xml”NŒexpose_internals”NŒstrict_visitor”NŒ_disable_config”NŒ_source”h³Œ _destination”NŒ _config_files”]”Œ7/var/lib/git/docbuild/linux/Documentation/docutils.conf”aŒfile_insertion_enabled”ˆŒ raw_enabled”KŒline_length_limit”M'Œpep_references”NŒ pep_base_url”Œhttps://peps.python.org/”Œpep_file_url_template”Œpep-%04d”Œrfc_references”NŒ rfc_base_url”Œ&https://datatracker.ietf.org/doc/html/”Œ tab_width”KŒtrim_footnote_reference_space”‰Œsyntax_highlight”Œlong”Œ smart_quotes”ˆŒsmartquotes_locales”]”Œcharacter_level_inline_markup”‰Œdoctitle_xform”‰Œ docinfo_xform”KŒsectsubtitle_xform”‰Œ image_loading”Œlink”Œembed_stylesheet”‰Œcloak_email_addresses”ˆŒsection_self_link”‰Œenv”NubŒreporter”NŒindirect_targets”]”Œsubstitution_defs”}”Œsubstitution_names”}”Œrefnames”}”Œrefids”}”Œnameids”}”(jÏjÌj…j‚j¼j¹j j jðjíjjj’jjÇjÄuŒ nametypes”}”(jωj…‰j¼‰j ‰jð‰j‰j’‰jljuh}”(jÌh¶j‚h×j¹jˆj j¿jíjjjójjjÄj•uŒ footnote_refs”}”Œ citation_refs”}”Œ autofootnotes”]”Œautofootnote_refs”]”Œsymbol_footnotes”]”Œsymbol_footnote_refs”]”Œ footnotes”]”Œ citations”]”Œautofootnote_start”KŒsymbol_footnote_start”KŒ id_counter”Œ collections”ŒCounter”“”}”…”R”Œparse_messages”]”Œtransform_messages”]”Œ transformer”NŒ include_log”]”Œ decoration”Nhžhub.