€•mGŒ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é)”}”(hŒ>(*) Implements the dns_resolver key_type to contact userspace.”h]”hŒ>(*) Implements the dns_resolver key_type to contact userspace.”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hè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:”…””}”(hj hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Khh×hžhubj)”}”(hŒ1(*) Dns query support for AFSDB resource record. ”h]”hé)”}”(hŒ0(*) Dns query support for AFSDB resource record.”h]”hŒ0(*) Dns query support for AFSDB resource record.”…””}”(hj2hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K hj.ubah}”(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.”…””}”(hjFhž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:”…””}”(hjmhž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Œ :: 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 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:: [:] where optionally specifies the particular upcall program to invoke, and thus the type of query to do, and specifies the string to be looked up. The default query type is a straight hostname to IP address set lookup. The name parameter is not required to be a NUL-terminated string, and its length should be given by the namelen argument. The options parameter may be NULL or it may be a set of options appropriate to the query type. 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. 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. If _expiry is non-NULL, the expiry time (TTL) of the result will be returned also.”h]”hX: #include :: 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 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:: [:] where optionally specifies the particular upcall program to invoke, and thus the type of query to do, and specifies the string to be looked up. The default query type is a straight hostname to IP address set lookup. The name parameter is not required to be a NUL-terminated string, and its length should be given by the namelen argument. The options parameter may be NULL or it may be a set of options appropriate to the query type. 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. 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. If _expiry is non-NULL, the expiry time (TTL) of the result will be returned also.”…””}”hjsbah}”(h]”h ]”h"]”h$]”h&]”h±h²uh1j{hŸh³h KFhjähž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.”…””}”(hjhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Kjhjähž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 Kpubhé)”}”(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â€.”…””}”(hj8hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h Krhj'hžhubeh}”(h]”Œreading-dns-keys-from-userspace”ah ]”h"]”Œreading dns keys from userspace”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kpubhµ)”}”(hhh]”(hº)”}”(hŒ Mechanism”h]”hŒ Mechanism”…””}”(hjQhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1h¹hjNhžhhŸh³h Kwubhé)”}”(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 KyhjNhž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.”…””}”(hjmhžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K|hjNhž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.”…””}”(hj{hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K€hjNhž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.”…””}”(hj‰hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K„hjNhž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.”…””}”(hj—hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KŠhjNhž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.”…””}”(hj¥hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h KŽhjNhžhubhé)”}”(hŒjSee for further information about request-key function.”h]”(hŒSee <”…””}”(hj³hžhhŸNh NubhŒ reference”“”)”}”(hŒ0file:Documentation/security/keys/request-key.rst”h]”hŒ0file:Documentation/security/keys/request-key.rst”…””}”(hj½hžhhŸNh Nubah}”(h]”h ]”h"]”h$]”h&]”Œrefuri”j¿uh1j»hj³ubhŒ5> for further information about request-key function.”…””}”(hj³hžhhŸNh Nubeh}”(h]”h ]”h"]”h$]”h&]”uh1hèhŸh³h K‘hjNhžhubeh}”(h]”Œ mechanism”ah ]”h"]”Œ mechanism”ah$]”h&]”uh1h´hh¶hžhhŸh³h Kwubhµ)”}”(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”}”(jjjYjVjjjájÞj$j!jKjHjÛjØjj uŒ nametypes”}”(j‰jY‰j‰já‰j$‰jK‰jÛ‰j‰uh}”(jh¶jVh×jj\jÞj“j!jäjHj'jØjNj 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.