.\" **************************************************************************
.\" *                                  _   _ ____  _
.\" *  Project                     ___| | | |  _ \| |
.\" *                             / __| | | | |_) | |
.\" *                            | (__| |_| |  _ <| |___
.\" *                             \___|\___/|_| \_\_____|
.\" *
.\" * Copyright (C) Daniel Stenberg, <daniel@haxx.se>, et al.
.\" *
.\" * This software is licensed as described in the file COPYING, which
.\" * you should have received as part of this distribution. The terms
.\" * are also available at https://curl.se/docs/copyright.html.
.\" *
.\" * You may opt to use, copy, modify, merge, publish, distribute and/or sell
.\" * copies of the Software, and permit persons to whom the Software is
.\" * furnished to do so, under the terms of the COPYING file.
.\" *
.\" * This software is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY
.\" * KIND, either express or implied.
.\" *
.\" * SPDX-License-Identifier: curl
.\" *
.\" **************************************************************************
.\"
.TH CURLOPT_DOH_URL 3 "December 04, 2023" "ibcurl 8.5.0" libcurl

.SH NAME
CURLOPT_DOH_URL \- provide the DNS-over-HTTPS URL
.SH SYNOPSIS
.nf
#include <curl/curl.h>

CURLcode curl_easy_setopt(CURL *handle, CURLOPT_DOH_URL, char *URL);
.fi
.SH DESCRIPTION
Pass in a pointer to a \fIURL\fP for the DoH server to use for name
resolving. The parameter should be a char * to a null-terminated string which
must be URL-encoded in the following format: "https://host:port/path". It MUST
specify an HTTPS URL.

libcurl does not validate the syntax or use this variable until the transfer
is issued. Even if you set a crazy value here, \fIcurl_easy_setopt(3)\fP still
returns \fICURLE_OK\fP.

curl sends POST requests to the given DNS-over-HTTPS URL.

To find the DoH server itself, which might be specified using a name, libcurl
uses the default name lookup function. You can bootstrap that by providing the
address for the DoH server with \fICURLOPT_RESOLVE(3)\fP.

Disable DoH use again by setting this option to NULL.
.SH "INHERIT OPTIONS"
DoH lookups use SSL and some SSL settings from your transfer are inherited,
like \fICURLOPT_SSL_CTX_FUNCTION(3)\fP.

The hostname and peer certificate verification settings are not inherited but
can be controlled separately via \fICURLOPT_DOH_SSL_VERIFYHOST(3)\fP and
\fICURLOPT_DOH_SSL_VERIFYPEER(3)\fP.

A set \fICURLOPT_OPENSOCKETFUNCTION(3)\fP callback is not inherited.
.SH "KNOWN BUGS"
Even when DoH is set to be used with this option, there are still some name
resolves that are performed without it, using the default name resolver
mechanism. This includes name resolves done for \fICURLOPT_INTERFACE(3)\fP,
\fICURLOPT_FTPPORT(3)\fP, a proxy type set to \fBCURLPROXY_SOCKS4\fP or
\fBCURLPROXY_SOCKS5\fP and probably some more.
.SH DEFAULT
NULL - there is no default DoH URL. If this option is not set, libcurl uses
the default name resolver.
.SH PROTOCOLS
All
.SH EXAMPLE
.nf
int main(void)
{
  CURL *curl = curl_easy_init();
  if(curl) {
    curl_easy_setopt(curl, CURLOPT_URL, "https://example.com");
    curl_easy_setopt(curl, CURLOPT_DOH_URL, "https://dns.example.com");
    curl_easy_perform(curl);
  }
}
.fi
.SH AVAILABILITY
Added in 7.62.0
.SH RETURN VALUE
Returns CURLE_OK on success or CURLE_OUT_OF_MEMORY if there was insufficient
heap space.

Note that \fIcurl_easy_setopt(3)\fP does immediately parse the given string so
when given a bad DoH URL, libcurl might not detect the problem until it later
tries to resolve a name with it.
.SH "SEE ALSO"
.BR CURLOPT_DNS_CACHE_TIMEOUT (3),
.BR CURLOPT_RESOLVE (3),
.BR CURLOPT_VERBOSE (3)