From: Yorgos Thessalonikefs Date: Tue, 20 May 2025 10:20:20 +0000 (+0200) Subject: RST man pages (#1285) X-Git-Url: http://git.ipfire.org/gitweb/gitweb.cgi?a=commitdiff_plain;h=6662f71732fb2efba5eee5a2e93d1e8da1b2249f;p=thirdparty%2Funbound.git RST man pages (#1285) Introduce restructuredText man pages to sync the online and source code man page documentation. The templated man pages (*.in) are still part of the repo but generated with docutils from their .rst counterpart. Documentation on how to generate those (mainly for core developers) are in README.man. --- diff --git a/doc/README.man b/doc/README.man new file mode 100644 index 000000000..8e7897f47 --- /dev/null +++ b/doc/README.man @@ -0,0 +1,16 @@ +After Unbound 1.23.0, the source of the man pages is in reStructuredText format. + +This helps with the online documentation at https://unbound.docs.nlnetlabs.nl +and makes it easier to maintain and contribute to the documentation. + +The templated man pages (*.in) are still part of the code repository as to not +alter current procedures that could be in place by users/packagers. + +The templated man pages (*.in) are generated by Sphinx (used for the online +documentation). +The online documentation has its own repository at +https://github.com/NLnetLabs/unbound-manual. + +In the README.md there (branch test-auto for now), there are further simple +instructions on how to generate the templated man pages there and update them +in this repository. diff --git a/doc/libunbound.3.in b/doc/libunbound.3.in index 548969142..204cda20c 100644 --- a/doc/libunbound.3.in +++ b/doc/libunbound.3.in @@ -1,335 +1,306 @@ -.TH "libunbound" "3" "@date@" "NLnet Labs" "unbound @version@" -.\" -.\" libunbound.3 -- unbound library functions manual -.\" -.\" Copyright (c) 2007, NLnet Labs. All rights reserved. -.\" -.\" See LICENSE for the license. -.\" -.\" -.SH "NAME" -.B libunbound, -.B unbound.h, -.B ub_ctx, -.B ub_result, -.B ub_callback_type, -.B ub_ctx_create, -.B ub_ctx_delete, -.B ub_ctx_set_option, -.B ub_ctx_get_option, -.B ub_ctx_config, -.B ub_ctx_set_fwd, -.B ub_ctx_set_stub, -.B ub_ctx_set_tls, -.B ub_ctx_resolvconf, -.B ub_ctx_hosts, -.B ub_ctx_add_ta, -.B ub_ctx_add_ta_autr, -.B ub_ctx_add_ta_file, -.B ub_ctx_trustedkeys, -.B ub_ctx_debugout, -.B ub_ctx_debuglevel, -.B ub_ctx_async, -.B ub_poll, -.B ub_wait, -.B ub_fd, -.B ub_process, -.B ub_resolve, -.B ub_resolve_async, -.B ub_cancel, -.B ub_resolve_free, -.B ub_strerror, -.B ub_ctx_print_local_zones, -.B ub_ctx_zone_add, -.B ub_ctx_zone_remove, -.B ub_ctx_data_add, -.B ub_ctx_data_remove -\- Unbound DNS validating resolver @version@ functions. -.SH "SYNOPSIS" -.B #include -.LP -\fIstruct ub_ctx *\fR -\fBub_ctx_create\fR(\fIvoid\fR); -.LP -\fIvoid\fR -\fBub_ctx_delete\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_ctx_set_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar*\fR val); -.LP -\fIint\fR -\fBub_ctx_get_option\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR opt, \fIchar**\fR val); -.LP -\fIint\fR -\fBub_ctx_config\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_set_fwd\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR addr); -.LP -\fIint\fR -\fBub_ctx_set_stub\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone, -\fIchar*\fR addr, -.br - \fIint\fR isprime); -.LP -\fIint\fR -\fBub_ctx_set_tls\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR tls); -.LP -\fIint\fR -\fBub_ctx_resolvconf\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_hosts\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_add_ta\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR ta); -.LP -\fIint\fR -\fBub_ctx_add_ta_autr\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_add_ta_file\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_trustedkeys\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR fname); -.LP -\fIint\fR -\fBub_ctx_debugout\fR(\fIstruct ub_ctx*\fR ctx, \fIFILE*\fR out); -.LP -\fIint\fR -\fBub_ctx_debuglevel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR d); -.LP -\fIint\fR -\fBub_ctx_async\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR dothread); -.LP -\fIint\fR -\fBub_poll\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_wait\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_fd\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_process\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_resolve\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, -.br - \fIint\fR rrtype, \fIint\fR rrclass, \fIstruct ub_result**\fR result); -.LP -\fIint\fR -\fBub_resolve_async\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR name, -.br - \fIint\fR rrtype, \fIint\fR rrclass, \fIvoid*\fR mydata, -.br - \fIub_callback_type\fR callback, \fIint*\fR async_id); -.LP -\fIint\fR -\fBub_cancel\fR(\fIstruct ub_ctx*\fR ctx, \fIint\fR async_id); -.LP -\fIvoid\fR -\fBub_resolve_free\fR(\fIstruct ub_result*\fR result); -.LP -\fIconst char *\fR -\fBub_strerror\fR(\fIint\fR err); -.LP -\fIint\fR -\fBub_ctx_print_local_zones\fR(\fIstruct ub_ctx*\fR ctx); -.LP -\fIint\fR -\fBub_ctx_zone_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name, \fIchar*\fR zone_type); -.LP -\fIint\fR -\fBub_ctx_zone_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR zone_name); -.LP -\fIint\fR -\fBub_ctx_data_add\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); -.LP -\fIint\fR -\fBub_ctx_data_remove\fR(\fIstruct ub_ctx*\fR ctx, \fIchar*\fR data); -.SH "DESCRIPTION" -.B Unbound -is an implementation of a DNS resolver, that does caching and -DNSSEC validation. This is the library API, for using the \-lunbound library. -The server daemon is described in \fIunbound\fR(8). -The library works independent from a running unbound server, and -can be used to convert hostnames to ip addresses, and back, -and obtain other information from the DNS. The library performs public\-key -validation of results with DNSSEC. -.P -The library uses a variable of type \fIstruct ub_ctx\fR to keep context -between calls. The user must maintain it, creating it with -.B ub_ctx_create -and deleting it with -.B ub_ctx_delete\fR. -It can be created and deleted at any time. Creating it anew removes any -previous configuration (such as trusted keys) and clears any cached results. -.P -The functions are thread\-safe, and a context can be used in a threaded (as -well as in a non\-threaded) environment. Also resolution (and validation) -can be performed blocking and non\-blocking (also called asynchronous). -The async method returns from the call immediately, so that processing -can go on, while the results become available later. -.P +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "LIBUNBOUND" "3" "@date@" "@version@" "Unbound" +.SH NAME +libunbound \- Unbound DNS validating resolver @version@ functions. +.SH SYNOPSIS +.sp +\fB#include \fP +.sp +struct ub_ctx * \fBub_ctx_create\fP(void); +.sp +void \fBub_ctx_delete\fP(struct ub_ctx* ctx); +.sp +int \fBub_ctx_set_option\fP(struct ub_ctx* ctx, char* opt, char* val); +.sp +int \fBub_ctx_get_option\fP(struct ub_ctx* ctx, char* opt, char** val); +.sp +int \fBub_ctx_config\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_set_fwd\fP(struct ub_ctx* ctx, char* addr); +.INDENT 0.0 +.TP +int \fBub_ctx_set_stub\fP(struct ub_ctx* ctx, char* zone, char* addr, +int isprime); +.UNINDENT +.sp +int \fBub_ctx_set_tls\fP(struct ub_ctx* ctx, int tls); +.sp +int \fBub_ctx_resolvconf\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_hosts\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_add_ta\fP(struct ub_ctx* ctx, char* ta); +.sp +int \fBub_ctx_add_ta_autr\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_add_ta_file\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_trustedkeys\fP(struct ub_ctx* ctx, char* fname); +.sp +int \fBub_ctx_debugout\fP(struct ub_ctx* ctx, FILE* out); +.sp +int \fBub_ctx_debuglevel\fP(struct ub_ctx* ctx, int d); +.sp +int \fBub_ctx_async\fP(struct ub_ctx* ctx, int dothread); +.sp +int \fBub_poll\fP(struct ub_ctx* ctx); +.sp +int \fBub_wait\fP(struct ub_ctx* ctx); +.sp +int \fBub_fd\fP(struct ub_ctx* ctx); +.sp +int \fBub_process\fP(struct ub_ctx* ctx); +.INDENT 0.0 +.TP +int \fBub_resolve\fP(struct ub_ctx* ctx, char* name, +int rrtype, int rrclass, struct ub_result** result); +.TP +int \fBub_resolve_async\fP(struct ub_ctx* ctx, char* name, +int rrtype, int rrclass, void* mydata, +ub_callback_type* callback, int* async_id); +.UNINDENT +.sp +int \fBub_cancel\fP(struct ub_ctx* ctx, int async_id); +.sp +void \fBub_resolve_free\fP(struct ub_result* result); +.sp +const char * \fBub_strerror\fP(int err); +.sp +int \fBub_ctx_print_local_zones\fP(struct ub_ctx* ctx); +.sp +int \fBub_ctx_zone_add\fP(struct ub_ctx* ctx, char* zone_name, char* zone_type); +.sp +int \fBub_ctx_zone_remove\fP(struct ub_ctx* ctx, char* zone_name); +.sp +int \fBub_ctx_data_add\fP(struct ub_ctx* ctx, char* data); +.sp +int \fBub_ctx_data_remove\fP(struct ub_ctx* ctx, char* data); +.SH DESCRIPTION +.sp +Unbound is an implementation of a DNS resolver, that does caching and DNSSEC +validation. +This is the library API, for using the \fB\-lunbound\fP library. +The server daemon is described in \fI\%unbound(8)\fP\&. +The library works independent from a running unbound server, and can be used to +convert hostnames to ip addresses, and back, and obtain other information from +the DNS. +The library performs public\-key validation of results with DNSSEC. +.sp +The library uses a variable of type \fIstruct ub_ctx\fP to keep context between +calls. +The user must maintain it, creating it with \fBub_ctx_create\fP and deleting it +with \fBub_ctx_delete\fP\&. +It can be created and deleted at any time. +Creating it anew removes any previous configuration (such as trusted keys) and +clears any cached results. +.sp +The functions are thread\-safe, and a context can be used in a threaded (as well +as in a non\-threaded) environment. +Also resolution (and validation) can be performed blocking and non\-blocking +(also called asynchronous). +The async method returns from the call immediately, so that processing can go +on, while the results become available later. +.sp The functions are discussed in turn below. -.SH "FUNCTIONS" -.TP +.SH FUNCTIONS +.INDENT 0.0 +.TP .B ub_ctx_create Create a new context, initialised with defaults. -The information from /etc/resolv.conf and /etc/hosts is not utilised -by default. Use -.B ub_ctx_resolvconf -and -.B ub_ctx_hosts -to read them. -Before you call this, use the openssl functions CRYPTO_set_id_callback and -CRYPTO_set_locking_callback to set up asynchronous operation if you use -lib openssl (the application calls these functions once for initialisation). -Openssl 1.0.0 or later uses the CRYPTO_THREADID_set_callback function. +The information from \fB/etc/resolv.conf\fP and \fB/etc/hosts\fP is +not utilised by default. +Use \fBub_ctx_resolvconf\fP and \fBub_ctx_hosts\fP to read them. +Before you call this, use the openssl functions +\fBCRYPTO_set_id_callback\fP and \fBCRYPTO_set_locking_callback\fP to set +up asynchronous operation if you use lib openssl (the application calls +these functions once for initialisation). +Openssl 1.0.0 or later uses the \fBCRYPTO_THREADID_set_callback\fP +function. .TP .B ub_ctx_delete Delete validation context and free associated resources. -Outstanding async queries are killed and callbacks are not called for them. +Outstanding async queries are killed and callbacks are not called for +them. .TP .B ub_ctx_set_option -A power\-user interface that lets you specify one of the options from the -config file format, see \fIunbound.conf\fR(5). Not all options are -relevant. For some specific options, such as adding trust anchors, special -routines exist. Pass the option name with the trailing ':'. +A power\-user interface that lets you specify one of the options from +the config file format, see \fI\%unbound.conf(5)\fP\&. +Not all options are relevant. +For some specific options, such as adding trust anchors, special +routines exist. +Pass the option name with the trailing \fB\(aq:\(aq\fP\&. .TP .B ub_ctx_get_option -A power\-user interface that gets an option value. Some options cannot be -gotten, and others return a newline separated list. Pass the option name -without trailing ':'. The returned value must be free(2)d by the caller. +A power\-user interface that gets an option value. +Some options cannot be gotten, and others return a newline separated +list. +Pass the option name without trailing \fB\(aq:\(aq\fP\&. +The returned value must be free(2)d by the caller. .TP .B ub_ctx_config -A power\-user interface that lets you specify an unbound config file, see -\fIunbound.conf\fR(5), which is read for configuration. Not all options are -relevant. For some specific options, such as adding trust anchors, special -routines exist. This function is thread\-safe only if a single instance of -ub_ctx* exists in the application. If several instances exist the -application has to ensure that ub_ctx_config is not called in parallel by -the different instances. +A power\-user interface that lets you specify an unbound config file, +see \fI\%unbound.conf(5)\fP, which is read for +configuration. +Not all options are relevant. +For some specific options, such as adding trust anchors, special +routines exist. +This function is thread\-safe only if a single instance of \fBub_ctx\fP* +exists in the application. +If several instances exist the application has to ensure that +\fBub_ctx_config\fP is not called in parallel by the different instances. .TP .B ub_ctx_set_fwd -Set machine to forward DNS queries to, the caching resolver to use. -IP4 or IP6 address. Forwards all DNS requests to that machine, which -is expected to run a recursive resolver. If the proxy is not -DNSSEC capable, validation may fail. Can be called several times, in -that case the addresses are used as backup servers. -At this time it is only possible to set configuration before the -first resolve is done. +Set machine to forward DNS queries to, the caching resolver to use. +IP4 or IP6 address. +Forwards all DNS requests to that machine, which is expected to run a +recursive resolver. +If the proxy is not DNSSEC capable, validation may fail. +Can be called several times, in that case the addresses are used as +backup servers. +At this time it is only possible to set configuration before the first +resolve is done. .TP .B ub_ctx_set_stub -Set a stub zone, authoritative dns servers to use for a particular zone. -IP4 or IP6 address. If the address is NULL the stub entry is removed. -Set isprime true if you configure root hints with it. Otherwise similar to -the stub zone item from unbound's config file. Can be called several times, -for different zones, or to add multiple addresses for a particular zone. -At this time it is only possible to set configuration before the -first resolve is done. +Set a stub zone, authoritative dns servers to use for a particular +zone. +IP4 or IP6 address. +If the address is NULL the stub entry is removed. +Set isprime true if you configure root hints with it. +Otherwise similar to the stub zone item from unbound\(aqs config file. +Can be called several times, for different zones, or to add multiple +addresses for a particular zone. +At this time it is only possible to set configuration before the first +resolve is done. .TP .B ub_ctx_set_tls -Enable DNS over TLS (DoT) for machines set with -.B ub_ctx_set_fwd. -At this time it is only possible to set configuration before the -first resolve is done. +Enable DNS over TLS (DoT) for machines set with \fBub_ctx_set_fwd\fP\&. +At this time it is only possible to set configuration before the first +resolve is done. .TP .B ub_ctx_resolvconf -By default the root servers are queried and full resolver mode is used, but -you can use this call to read the list of nameservers to use from the -filename given. -Usually "/etc/resolv.conf". Uses those nameservers as caching proxies. +By default the root servers are queried and full resolver mode is used, +but you can use this call to read the list of nameservers to use from +the filename given. +Usually \fB\(dq/etc/resolv.conf\(dq\fP\&. +Uses those nameservers as caching proxies. If they do not support DNSSEC, validation may fail. Only nameservers are picked up, the searchdomain, ndots and other -settings from \fIresolv.conf\fR(5) are ignored. -If fname NULL is passed, "/etc/resolv.conf" is used (if on Windows, -the system\-wide configured nameserver is picked instead). -At this time it is only possible to set configuration before the -first resolve is done. +settings from \fIresolv.conf(5)\fP are ignored. +If fname NULL is passed, \fB\(dq/etc/resolv.conf\(dq\fP is used (if on +Windows, the system\-wide configured nameserver is picked instead). +At this time it is only possible to set configuration before the first +resolve is done. .TP .B ub_ctx_hosts Read list of hosts from the filename given. -Usually "/etc/hosts". When queried for, these addresses are not marked -DNSSEC secure. If fname NULL is passed, "/etc/hosts" is used -(if on Windows, etc/hosts from WINDIR is picked instead). -At this time it is only possible to set configuration before the -first resolve is done. -.TP -.B -ub_ctx_add_ta +Usually \fB\(dq/etc/hosts\(dq\fP\&. +When queried for, these addresses are not marked DNSSEC secure. +If fname NULL is passed, \fB\(dq/etc/hosts\(dq\fP is used (if on Windows, +\fBetc/hosts\fP from WINDIR is picked instead). +At this time it is only possible to set configuration before the first +resolve is done. +.TP +.B ub_ctx_add_ta Add a trust anchor to the given context. -At this time it is only possible to add trusted keys before the -first resolve is done. +At this time it is only possible to add trusted keys before the first +resolve is done. The format is a string, similar to the zone\-file format, -[domainname] [type] [rdata contents]. Both DS and DNSKEY records are accepted. +\fB[domainname]\fP \fB[type]\fP \fB[rdata contents]\fP\&. +Both DS and DNSKEY records are accepted. .TP .B ub_ctx_add_ta_autr -Add filename with automatically tracked trust anchor to the given context. -Pass name of a file with the managed trust anchor. You can create this -file with \fIunbound\-anchor\fR(8) for the root anchor. You can also -create it with an initial file with one line with a DNSKEY or DS record. +Add filename with automatically tracked trust anchor to the given +context. +Pass name of a file with the managed trust anchor. +You can create this file with +\fI\%unbound\-anchor(8)\fP for the root anchor. +You can also create it with an initial file with one line with a DNSKEY +or DS record. If the file is writable, it is updated when the trust anchor changes. -At this time it is only possible to add trusted keys before the -first resolve is done. +At this time it is only possible to add trusted keys before the first +resolve is done. .TP .B ub_ctx_add_ta_file Add trust anchors to the given context. Pass name of a file with DS and DNSKEY records in zone file format. -At this time it is only possible to add trusted keys before the -first resolve is done. +At this time it is only possible to add trusted keys before the first +resolve is done. .TP .B ub_ctx_trustedkeys Add trust anchors to the given context. -Pass the name of a bind\-style config file with trusted\-keys{}. -At this time it is only possible to add trusted keys before the -first resolve is done. +Pass the name of a bind\-style config file with \fBtrusted\-keys{}\fP\&. +At this time it is only possible to add trusted keys before the first +resolve is done. .TP .B ub_ctx_debugout -Set debug and error log output to the given stream. Pass NULL to disable -output. Default is stderr. File\-names or using syslog can be enabled -using config options, this routine is for using your own stream. +Set debug and error log output to the given stream. +Pass NULL to disable output. +Default is stderr. +File\-names or using syslog can be enabled using config options, this +routine is for using your own stream. .TP .B ub_ctx_debuglevel -Set debug verbosity for the context. Output is directed to stderr. +Set debug verbosity for the context. +Output is directed to stderr. Higher debug level gives more output. .TP .B ub_ctx_async Set a context behaviour for asynchronous action. -if set to true, enables threading and a call to -.B ub_resolve_async +if set to true, enables threading and a call to \fBub_resolve_async\fP creates a thread to handle work in the background. If false, a process is forked to handle work in the background. -Changes to this setting after -.B ub_resolve_async -calls have been made have no effect (delete and re\-create the context -to change). +Changes to this setting after \fBub_resolve_async\fP calls have been made +have no effect (delete and re\-create the context to change). .TP .B ub_poll Poll a context to see if it has any new results. -Do not poll in a loop, instead extract the fd below to poll for readiness, -and then check, or wait using the wait routine. +Do not poll in a loop, instead extract the \fBfd\fP below to poll for +readiness, and then check, or wait using the wait routine. Returns 0 if nothing to read, or nonzero if a result is available. -If nonzero, call -.B ub_process -to do callbacks. +If nonzero, call \fBub_process\fP to do callbacks. .TP .B ub_wait -Wait for a context to finish with results. Calls -.B ub_process -after the wait for you. After the wait, there are no more outstanding -asynchronous queries. +Wait for a context to finish with results. +Calls \fBub_process\fP after the wait for you. +After the wait, there are no more outstanding asynchronous queries. .TP .B ub_fd -Get file descriptor. Wait for it to become readable, at this point -answers are returned from the asynchronous validating resolver. -Then call the \fBub_process\fR to continue processing. +Get file descriptor. +Wait for it to become readable, at this point answers are returned from +the asynchronous validating resolver. +Then call the \fBub_process\fP to continue processing. .TP .B ub_process Call this routine to continue processing results from the validating -resolver (when the fd becomes readable). +resolver (when the \fBfd\fP becomes readable). Will perform necessary callbacks. .TP .B ub_resolve @@ -340,95 +311,111 @@ The result structure is newly allocated with the resulting data. .TP .B ub_resolve_async Perform asynchronous resolution and validation of the target name. -Arguments mean the same as for \fBub_resolve\fR except no -data is returned immediately, instead a callback is called later. -The callback receives a copy of the mydata pointer, that you can use to pass -information to the callback. The callback type is a function pointer to -a function declared as -.IP -void my_callback_function(void* my_arg, int err, -.br - struct ub_result* result); -.IP -The async_id is returned so you can (at your option) decide to track it -and cancel the request if needed. If you pass a NULL pointer the async_id -is not returned. +Arguments mean the same as for \fBub_resolve\fP except no data is +returned immediately, instead a callback is called later. +The callback receives a copy of the mydata pointer, that you can use to +pass information to the callback. +The callback type is a function pointer to a function declared as: +.INDENT 7.0 +.INDENT 3.5 +.sp +.nf +.ft C +void my_callback_function(void* my_arg, int err, + struct ub_result* result); +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The \fBasync_id\fP is returned so you can (at your option) decide to +track it and cancel the request if needed. +If you pass a NULL pointer the \fBasync_id\fP is not returned. .TP .B ub_cancel -Cancel an async query in progress. This may return an error if the query -does not exist, or the query is already being delivered, in that case you -may still get a callback for the query. +Cancel an async query in progress. +This may return an error if the query does not exist, or the query is +already being delivered, in that case you may still get a callback for +the query. .TP .B ub_resolve_free -Free struct ub_result contents after use. +Free struct \fBub_result\fP contents after use. .TP .B ub_strerror -Convert error value from one of the unbound library functions -to a human readable string. +Convert error value from one of the unbound library functions to a +human readable string. .TP .B ub_ctx_print_local_zones Debug printout the local authority information to debug output. .TP .B ub_ctx_zone_add -Add new zone to local authority info, like local\-zone \fIunbound.conf\fR(5) -statement. +Add new zone to local authority info, like local\-zone +\fI\%unbound.conf(5)\fP statement. .TP .B ub_ctx_zone_remove Delete zone from local authority info. .TP .B ub_ctx_data_add Add resource record data to local authority info, like local\-data -\fIunbound.conf\fR(5) statement. +\fI\%unbound.conf(5)\fP statement. .TP .B ub_ctx_data_remove Delete local authority data from the name given. -.SH "RESULT DATA STRUCTURE" -The result of the DNS resolution and validation is returned as -\fIstruct ub_result\fR. The result structure contains the following entries. -.P +.UNINDENT +.SH RESULT DATA STRUCTURE +.sp +The result of the DNS resolution and validation is returned as \fIstruct +ub_result\fP\&. +The result structure contains the following entries: +.INDENT 0.0 +.INDENT 3.5 +.sp .nf - struct ub_result { - char* qname; /* text string, original question */ - int qtype; /* type code asked for */ - int qclass; /* class code asked for */ - char** data; /* array of rdata items, NULL terminated*/ - int* len; /* array with lengths of rdata items */ - char* canonname; /* canonical name of result */ - int rcode; /* additional error code in case of no data */ - void* answer_packet; /* full network format answer packet */ - int answer_len; /* length of packet in octets */ - int havedata; /* true if there is data */ - int nxdomain; /* true if nodata because name does not exist */ - int secure; /* true if result is secure */ - int bogus; /* true if a security failure happened */ - char* why_bogus; /* string with error if bogus */ - int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */ - int ttl; /* number of seconds the result is valid */ - }; +.ft C +struct ub_result { + char* qname; /* text string, original question */ + int qtype; /* type code asked for */ + int qclass; /* class code asked for */ + char** data; /* array of rdata items, NULL terminated*/ + int* len; /* array with lengths of rdata items */ + char* canonname; /* canonical name of result */ + int rcode; /* additional error code in case of no data */ + void* answer_packet; /* full network format answer packet */ + int answer_len; /* length of packet in octets */ + int havedata; /* true if there is data */ + int nxdomain; /* true if nodata because name does not exist */ + int secure; /* true if result is secure */ + int bogus; /* true if a security failure happened */ + char* why_bogus; /* string with error if bogus */ + int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */ + int ttl; /* number of seconds the result is valid */ +}; +.ft P .fi -.P -If both secure and bogus are false, security was not enabled for the -domain of the query. Else, they are not both true, one of them is true. -.SH "RETURN VALUES" -Many routines return an error code. The value 0 (zero) denotes no error -happened. Other values can be passed to -.B ub_strerror -to obtain a readable error string. -.B ub_strerror -returns a zero terminated string. -.B ub_ctx_create -returns NULL on an error (a malloc failure). -.B ub_poll -returns true if some information may be available, false otherwise. -.B ub_fd -returns a file descriptor or \-1 on error. -.B ub_ctx_config -and -.B ub_ctx_resolvconf -attempt to leave errno informative on a function return with file read failure. -.SH "SEE ALSO" -\fIunbound.conf\fR(5), -\fIunbound\fR(8). -.SH "AUTHORS" -.B Unbound -developers are mentioned in the CREDITS file in the distribution. +.UNINDENT +.UNINDENT +.sp +If both secure and bogus are false, security was not enabled for the domain of +the query. +Else, they are not both true, one of them is true. +.SH RETURN VALUES +.sp +Many routines return an error code. +The value 0 (zero) denotes no error happened. +Other values can be passed to \fBub_strerror\fP to obtain a readable error +string. +\fBub_strerror\fP returns a zero terminated string. +\fBub_ctx_create\fP returns NULL on an error (a malloc failure). +\fBub_poll\fP returns true if some information may be available, false otherwise. +\fBub_fd\fP returns a file descriptor or \-1 on error. +\fBub_ctx_config\fP and \fBub_ctx_resolvconf\fP attempt to leave errno informative +on a function return with file read failure. +.SH SEE ALSO +.sp +\fI\%unbound.conf(5)\fP, \fI\%unbound(8)\fP\&. +.SH AUTHOR +Unbound developers are mentioned in the CREDITS file in the distribution. +.SH COPYRIGHT +1999-2025, NLnet Labs +.\" Generated by docutils manpage writer. +. diff --git a/doc/libunbound.rst b/doc/libunbound.rst new file mode 100644 index 000000000..97883dc55 --- /dev/null +++ b/doc/libunbound.rst @@ -0,0 +1,491 @@ +.. + WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE + +.. + IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE + +.. + IT HELPS PEOPLE DIFFING THE CHANGES + +.. + WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE + +.. + IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE + +.. + IT HELPS PEOPLE DIFFING THE CHANGES + +.. + WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE + +.. + IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE + +.. + IT HELPS PEOPLE DIFFING THE CHANGES + +.. + WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE + +.. + IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE + +.. + IT HELPS PEOPLE DIFFING THE CHANGES + +libunbound(3) +============= + +Synopsis +-------- + +.. only:: html + + .. code-block:: c + + #include + + struct ub_ctx * ub_ctx_create(void); + + void ub_ctx_delete(struct ub_ctx* ctx); + + int ub_ctx_set_option(struct ub_ctx* ctx, char* opt, char* val); + + int ub_ctx_get_option(struct ub_ctx* ctx, char* opt, char** val); + + int ub_ctx_config(struct ub_ctx* ctx, char* fname); + + int ub_ctx_set_fwd(struct ub_ctx* ctx, char* addr); + + int ub_ctx_set_stub(struct ub_ctx* ctx, char* zone, char* addr, + int isprime); + + int ub_ctx_set_tls(struct ub_ctx* ctx, int tls); + + int ub_ctx_resolvconf(struct ub_ctx* ctx, char* fname); + + int ub_ctx_hosts(struct ub_ctx* ctx, char* fname); + + int ub_ctx_add_ta(struct ub_ctx* ctx, char* ta); + + int ub_ctx_add_ta_autr(struct ub_ctx* ctx, char* fname); + + int ub_ctx_add_ta_file(struct ub_ctx* ctx, char* fname); + + int ub_ctx_trustedkeys(struct ub_ctx* ctx, char* fname); + + int ub_ctx_debugout(struct ub_ctx* ctx, FILE* out); + + int ub_ctx_debuglevel(struct ub_ctx* ctx, int d); + + int ub_ctx_async(struct ub_ctx* ctx, int dothread); + + int ub_poll(struct ub_ctx* ctx); + + int ub_wait(struct ub_ctx* ctx); + + int ub_fd(struct ub_ctx* ctx); + + int ub_process(struct ub_ctx* ctx); + + int ub_resolve(struct ub_ctx* ctx, char* name, int rrtype, + int rrclass, struct ub_result** result); + + int ub_resolve_async(struct ub_ctx* ctx, char* name, int rrtype, + int rrclass, void* mydata, ub_callback_type callback, + int* async_id); + + int ub_cancel(struct ub_ctx* ctx, int async_id); + + void ub_resolve_free(struct ub_result* result); + + const char * ub_strerror(int err); + + int ub_ctx_print_local_zones(struct ub_ctx* ctx); + + int ub_ctx_zone_add(struct ub_ctx* ctx, char* zone_name, char* zone_type); + + int ub_ctx_zone_remove(struct ub_ctx* ctx, char* zone_name); + + int ub_ctx_data_add(struct ub_ctx* ctx, char* data); + + int ub_ctx_data_remove(struct ub_ctx* ctx, char* data); + +.. only:: man + + **#include ** + + struct ub_ctx \* **ub_ctx_create**\ (void); + + void **ub_ctx_delete**\ (struct ub_ctx\* ctx); + + int **ub_ctx_set_option**\ (struct ub_ctx\* ctx, char\* opt, char\* val); + + int **ub_ctx_get_option**\ (struct ub_ctx\* ctx, char\* opt, char\*\* val); + + int **ub_ctx_config**\ (struct ub_ctx\* ctx, char* fname); + + int **ub_ctx_set_fwd**\ (struct ub_ctx\* ctx, char\* addr); + + int **ub_ctx_set_stub**\ (struct ub_ctx\* ctx, char\* zone, char\* addr, + int isprime); + + int **ub_ctx_set_tls**\ (struct ub_ctx\* ctx, int tls); + + int **ub_ctx_resolvconf**\ (struct ub_ctx\* ctx, char\* fname); + + int **ub_ctx_hosts**\ (struct ub_ctx\* ctx, char\* fname); + + int **ub_ctx_add_ta**\ (struct ub_ctx\* ctx, char\* ta); + + int **ub_ctx_add_ta_autr**\ (struct ub_ctx\* ctx, char\* fname); + + int **ub_ctx_add_ta_file**\ (struct ub_ctx\* ctx, char\* fname); + + int **ub_ctx_trustedkeys**\ (struct ub_ctx\* ctx, char\* fname); + + int **ub_ctx_debugout**\ (struct ub_ctx\* ctx, FILE\* out); + + int **ub_ctx_debuglevel**\ (struct ub_ctx\* ctx, int d); + + int **ub_ctx_async**\ (struct ub_ctx\* ctx, int dothread); + + int **ub_poll**\ (struct ub_ctx\* ctx); + + int **ub_wait**\ (struct ub_ctx\* ctx); + + int **ub_fd**\ (struct ub_ctx\* ctx); + + int **ub_process**\ (struct ub_ctx\* ctx); + + int **ub_resolve**\ (struct ub_ctx\* ctx, char\* name, + int rrtype, int rrclass, struct ub_result\*\* result); + + int **ub_resolve_async**\ (struct ub_ctx\* ctx, char\* name, + int rrtype, int rrclass, void\* mydata, + ub_callback_type\* callback, int\* async_id); + + int **ub_cancel**\ (struct ub_ctx\* ctx, int async_id); + + void **ub_resolve_free**\ (struct ub_result\* result); + + const char \* **ub_strerror**\ (int err); + + int **ub_ctx_print_local_zones**\ (struct ub_ctx\* ctx); + + int **ub_ctx_zone_add**\ (struct ub_ctx\* ctx, char\* zone_name, char\* zone_type); + + int **ub_ctx_zone_remove**\ (struct ub_ctx\* ctx, char\* zone_name); + + int **ub_ctx_data_add**\ (struct ub_ctx\* ctx, char\* data); + + int **ub_ctx_data_remove**\ (struct ub_ctx\* ctx, char\* data); + +Description +----------- + +Unbound is an implementation of a DNS resolver, that does caching and DNSSEC +validation. +This is the library API, for using the ``-lunbound`` library. +The server daemon is described in :doc:`unbound(8)`. +The library works independent from a running unbound server, and can be used to +convert hostnames to ip addresses, and back, and obtain other information from +the DNS. +The library performs public-key validation of results with DNSSEC. + +The library uses a variable of type *struct ub_ctx* to keep context between +calls. +The user must maintain it, creating it with **ub_ctx_create** and deleting it +with **ub_ctx_delete**. +It can be created and deleted at any time. +Creating it anew removes any previous configuration (such as trusted keys) and +clears any cached results. + +The functions are thread-safe, and a context can be used in a threaded (as well +as in a non-threaded) environment. +Also resolution (and validation) can be performed blocking and non-blocking +(also called asynchronous). +The async method returns from the call immediately, so that processing can go +on, while the results become available later. + +The functions are discussed in turn below. + +Functions +--------- + +.. glossary:: + + ub_ctx_create + Create a new context, initialised with defaults. + The information from :file:`/etc/resolv.conf` and :file:`/etc/hosts` is + not utilised by default. + Use **ub_ctx_resolvconf** and **ub_ctx_hosts** to read them. + Before you call this, use the openssl functions + **CRYPTO_set_id_callback** and **CRYPTO_set_locking_callback** to set + up asynchronous operation if you use lib openssl (the application calls + these functions once for initialisation). + Openssl 1.0.0 or later uses the **CRYPTO_THREADID_set_callback** + function. + + ub_ctx_delete + Delete validation context and free associated resources. + Outstanding async queries are killed and callbacks are not called for + them. + + ub_ctx_set_option + A power-user interface that lets you specify one of the options from + the config file format, see :doc:`unbound.conf(5)`. + Not all options are relevant. + For some specific options, such as adding trust anchors, special + routines exist. + Pass the option name with the trailing ``':'``. + + ub_ctx_get_option + A power-user interface that gets an option value. + Some options cannot be gotten, and others return a newline separated + list. + Pass the option name without trailing ``':'``. + The returned value must be free(2)d by the caller. + + ub_ctx_config + A power-user interface that lets you specify an unbound config file, + see :doc:`unbound.conf(5)`, which is read for + configuration. + Not all options are relevant. + For some specific options, such as adding trust anchors, special + routines exist. + This function is thread-safe only if a single instance of **ub_ctx**\* + exists in the application. + If several instances exist the application has to ensure that + **ub_ctx_config** is not called in parallel by the different instances. + + ub_ctx_set_fwd + Set machine to forward DNS queries to, the caching resolver to use. + IP4 or IP6 address. + Forwards all DNS requests to that machine, which is expected to run a + recursive resolver. + If the proxy is not DNSSEC capable, validation may fail. + Can be called several times, in that case the addresses are used as + backup servers. + At this time it is only possible to set configuration before the first + resolve is done. + + ub_ctx_set_stub + Set a stub zone, authoritative dns servers to use for a particular + zone. + IP4 or IP6 address. + If the address is NULL the stub entry is removed. + Set isprime true if you configure root hints with it. + Otherwise similar to the stub zone item from unbound's config file. + Can be called several times, for different zones, or to add multiple + addresses for a particular zone. + At this time it is only possible to set configuration before the first + resolve is done. + + ub_ctx_set_tls + Enable DNS over TLS (DoT) for machines set with **ub_ctx_set_fwd**. + At this time it is only possible to set configuration before the first + resolve is done. + + ub_ctx_resolvconf + By default the root servers are queried and full resolver mode is used, + but you can use this call to read the list of nameservers to use from + the filename given. + Usually :file:`"/etc/resolv.conf"`. + Uses those nameservers as caching proxies. + If they do not support DNSSEC, validation may fail. + Only nameservers are picked up, the searchdomain, ndots and other + settings from *resolv.conf(5)* are ignored. + If fname NULL is passed, :file:`"/etc/resolv.conf"` is used (if on + Windows, the system-wide configured nameserver is picked instead). + At this time it is only possible to set configuration before the first + resolve is done. + + ub_ctx_hosts + Read list of hosts from the filename given. + Usually :file:`"/etc/hosts"`. + When queried for, these addresses are not marked DNSSEC secure. + If fname NULL is passed, :file:`"/etc/hosts"` is used (if on Windows, + :file:`etc/hosts` from WINDIR is picked instead). + At this time it is only possible to set configuration before the first + resolve is done. + + ub_ctx_add_ta + Add a trust anchor to the given context. + At this time it is only possible to add trusted keys before the first + resolve is done. + The format is a string, similar to the zone-file format, + **[domainname]** **[type]** **[rdata contents]**. + Both DS and DNSKEY records are accepted. + + ub_ctx_add_ta_autr + Add filename with automatically tracked trust anchor to the given + context. + Pass name of a file with the managed trust anchor. + You can create this file with + :doc:`unbound-anchor(8)` for the root anchor. + You can also create it with an initial file with one line with a DNSKEY + or DS record. + If the file is writable, it is updated when the trust anchor changes. + At this time it is only possible to add trusted keys before the first + resolve is done. + + ub_ctx_add_ta_file + Add trust anchors to the given context. + Pass name of a file with DS and DNSKEY records in zone file format. + At this time it is only possible to add trusted keys before the first + resolve is done. + + ub_ctx_trustedkeys + Add trust anchors to the given context. + Pass the name of a bind-style config file with ``trusted-keys{}``. + At this time it is only possible to add trusted keys before the first + resolve is done. + + ub_ctx_debugout + Set debug and error log output to the given stream. + Pass NULL to disable output. + Default is stderr. + File-names or using syslog can be enabled using config options, this + routine is for using your own stream. + + ub_ctx_debuglevel + Set debug verbosity for the context. + Output is directed to stderr. + Higher debug level gives more output. + + ub_ctx_async + Set a context behaviour for asynchronous action. + if set to true, enables threading and a call to **ub_resolve_async** + creates a thread to handle work in the background. + If false, a process is forked to handle work in the background. + Changes to this setting after **ub_resolve_async** calls have been made + have no effect (delete and re-create the context to change). + + ub_poll + Poll a context to see if it has any new results. + Do not poll in a loop, instead extract the **fd** below to poll for + readiness, and then check, or wait using the wait routine. + Returns 0 if nothing to read, or nonzero if a result is available. + If nonzero, call **ub_process** to do callbacks. + + ub_wait + Wait for a context to finish with results. + Calls **ub_process** after the wait for you. + After the wait, there are no more outstanding asynchronous queries. + + ub_fd + Get file descriptor. + Wait for it to become readable, at this point answers are returned from + the asynchronous validating resolver. + Then call the **ub_process** to continue processing. + + ub_process + Call this routine to continue processing results from the validating + resolver (when the **fd** becomes readable). + Will perform necessary callbacks. + + ub_resolve + Perform resolution and validation of the target name. + The name is a domain name in a zero terminated text string. + The rrtype and rrclass are DNS type and class codes. + The result structure is newly allocated with the resulting data. + + ub_resolve_async + Perform asynchronous resolution and validation of the target name. + Arguments mean the same as for **ub_resolve** except no data is + returned immediately, instead a callback is called later. + The callback receives a copy of the mydata pointer, that you can use to + pass information to the callback. + The callback type is a function pointer to a function declared as: + + .. code-block:: c + + void my_callback_function(void* my_arg, int err, + struct ub_result* result); + + The **async_id** is returned so you can (at your option) decide to + track it and cancel the request if needed. + If you pass a NULL pointer the **async_id** is not returned. + + ub_cancel + Cancel an async query in progress. + This may return an error if the query does not exist, or the query is + already being delivered, in that case you may still get a callback for + the query. + + ub_resolve_free + Free struct **ub_result** contents after use. + + ub_strerror + Convert error value from one of the unbound library functions to a + human readable string. + + ub_ctx_print_local_zones + Debug printout the local authority information to debug output. + + ub_ctx_zone_add + Add new zone to local authority info, like local-zone + :doc:`unbound.conf(5)` statement. + + ub_ctx_zone_remove + Delete zone from local authority info. + + ub_ctx_data_add + Add resource record data to local authority info, like local-data + :doc:`unbound.conf(5)` statement. + + ub_ctx_data_remove + Delete local authority data from the name given. + +Result Data structure +--------------------- + +The result of the DNS resolution and validation is returned as *struct +ub_result*. +The result structure contains the following entries: + +.. code-block:: c + + struct ub_result { + char* qname; /* text string, original question */ + int qtype; /* type code asked for */ + int qclass; /* class code asked for */ + char** data; /* array of rdata items, NULL terminated*/ + int* len; /* array with lengths of rdata items */ + char* canonname; /* canonical name of result */ + int rcode; /* additional error code in case of no data */ + void* answer_packet; /* full network format answer packet */ + int answer_len; /* length of packet in octets */ + int havedata; /* true if there is data */ + int nxdomain; /* true if nodata because name does not exist */ + int secure; /* true if result is secure */ + int bogus; /* true if a security failure happened */ + char* why_bogus; /* string with error if bogus */ + int was_ratelimited; /* true if the query was ratelimited (SERVFAIL) by unbound */ + int ttl; /* number of seconds the result is valid */ + }; + +If both secure and bogus are false, security was not enabled for the domain of +the query. +Else, they are not both true, one of them is true. + +Return Values +------------- + +Many routines return an error code. +The value 0 (zero) denotes no error happened. +Other values can be passed to **ub_strerror** to obtain a readable error +string. +**ub_strerror** returns a zero terminated string. +**ub_ctx_create** returns NULL on an error (a malloc failure). +**ub_poll** returns true if some information may be available, false otherwise. +**ub_fd** returns a file descriptor or -1 on error. +**ub_ctx_config** and **ub_ctx_resolvconf** attempt to leave errno informative +on a function return with file read failure. + +See Also +-------- + +:doc:`unbound.conf(5)`, :doc:`unbound(8)`. diff --git a/doc/unbound-anchor.8.in b/doc/unbound-anchor.8.in index 31c4e9113..9c77b4cf7 100644 --- a/doc/unbound-anchor.8.in +++ b/doc/unbound-anchor.8.in @@ -1,189 +1,300 @@ -.TH "unbound-anchor" "8" "@date@" "NLnet Labs" "unbound @version@" -.\" -.\" unbound-anchor.8 -- unbound anchor maintenance utility manual -.\" -.\" Copyright (c) 2008, NLnet Labs. All rights reserved. -.\" -.\" See LICENSE for the license. -.\" -.\" -.SH "NAME" -.B unbound\-anchor -\- Unbound anchor utility. -.SH "SYNOPSIS" -.B unbound\-anchor -.RB [ opts ] -.SH "DESCRIPTION" -.B Unbound\-anchor -performs setup or update of the root trust anchor for DNSSEC validation. -The program fetches the trust anchor with the method from RFC7958 when -regular RFC5011 update fails to bring it up to date. +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "UNBOUND-ANCHOR" "8" "@date@" "@version@" "Unbound" +.SH NAME +unbound-anchor \- Unbound @version@ anchor utility. +.SH SYNOPSIS +.sp +\fBunbound\-anchor\fP [\fBopts\fP] +.SH DESCRIPTION +.sp +\fBunbound\-anchor\fP performs setup or update of the root trust anchor for DNSSEC +validation. +The program fetches the trust anchor with the method from \fI\%RFC 7958\fP when +regular \fI\%RFC 5011\fP update fails to bring it up to date. It can be run (as root) from the commandline, or run as part of startup -scripts. Before you start the \fIunbound\fR(8) DNS server. -.P +scripts. +Before you start the \fI\%unbound(8)\fP DNS server. +.sp Suggested usage: -.P +.INDENT 0.0 +.INDENT 3.5 +.sp .nf - # in the init scripts. - # provide or update the root anchor (if necessary) - unbound-anchor \-a "@UNBOUND_ROOTKEY_FILE@" - # Please note usage of this root anchor is at your own risk - # and under the terms of our LICENSE (see source). - # - # start validating resolver - # the unbound.conf contains: - # auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@" - unbound \-c unbound.conf +.ft C +# in the init scripts. +# provide or update the root anchor (if necessary) +unbound\-anchor \-a \(dq@UNBOUND_ROOTKEY_FILE@\(dq +# Please note usage of this root anchor is at your own risk +# and under the terms of our LICENSE (see source). +# +# start validating resolver +# the unbound.conf contains: +# auto\-trust\-anchor\-file: \(dq@UNBOUND_ROOTKEY_FILE@\(dq +unbound \-c unbound.conf +.ft P .fi -.P -This tool provides builtin default contents for the root anchor and root -update certificate files. -.P +.UNINDENT +.UNINDENT +.sp +This tool provides builtin default contents for the root anchor and root update +certificate files. +.sp It tests if the root anchor file works, and if not, and an update is possible, attempts to update the root anchor using the root update certificate. -It performs a https fetch of root-anchors.xml and checks the results (RFC7958), -if all checks are successful, it updates the root anchor file. Otherwise -the root anchor file is unchanged. It performs RFC5011 tracking if the -DNSSEC information available via the DNS makes that possible. -.P -It does not perform an update if the certificate is expired, if the network -is down or other errors occur. -.P +It performs a https fetch of +\fI\%root\-anchors.xml\fP +and checks the results (\fI\%RFC 7958\fP); if all checks are successful, it updates +the root anchor file. +Otherwise the root anchor file is unchanged. +It performs \fI\%RFC 5011\fP tracking if the DNSSEC information available via the +DNS makes that possible. +.sp +It does not perform an update if the certificate is expired, if the network is +down or other errors occur. +.sp The available options are: +.INDENT 0.0 .TP -.B \-a \fIfile +.B \-a The root anchor key file, that is read in and written out. -Default is @UNBOUND_ROOTKEY_FILE@. -If the file does not exist, or is empty, a builtin root key is written to it. +Default is \fB@UNBOUND_ROOTKEY_FILE@\fP\&. +If the file does not exist, or is empty, a builtin root key is written +to it. +.UNINDENT +.INDENT 0.0 .TP -.B \-c \fIfile +.B \-c The root update certificate file, that is read in. -Default is @UNBOUND_ROOTCERT_FILE@. +Default is \fB@UNBOUND_ROOTCERT_FILE@\fP\&. If the file does not exist, or is empty, a builtin certificate is used. +.UNINDENT +.INDENT 0.0 .TP .B \-l List the builtin root key and builtin root update certificate on stdout. +.UNINDENT +.INDENT 0.0 .TP -.B \-u \fIname -The server name, it connects to https://name. Specify without https:// prefix. -The default is "data.iana.org". It connects to the port specified with \-P. +.B \-u +The server name, it connects to \fBhttps://name\fP\&. +Specify without \fBhttps://\fP prefix. +The default is \fB\(dqdata.iana.org\(dq\fP\&. +It connects to the port specified with \fI\%\-P\fP\&. You can pass an IPv4 address or IPv6 address (no brackets) if you want. +.UNINDENT +.INDENT 0.0 .TP .B \-S -Do not use SNI for the HTTPS connection. Default is to use SNI. +Do not use SNI for the HTTPS connection. +Default is to use SNI. +.UNINDENT +.INDENT 0.0 .TP -.B \-b \fIaddress -The source address to bind to for domain resolution and contacting the server -on https. May be either an IPv4 address or IPv6 address (no brackets). +.B \-b
+The source address to bind to for domain resolution and contacting the +server on https. +May be either an IPv4 address or IPv6 address (no brackets). +.UNINDENT +.INDENT 0.0 .TP -.B \-x \fIpath -The pathname to the root\-anchors.xml file on the server. (forms URL with \-u). -The default is /root\-anchors/root\-anchors.xml. +.B \-x +The pathname to the root\-anchors.xml file on the server. +(forms URL with \fI\%\-u\fP). +The default is \fB/root\-anchors/root\-anchors.xml\fP\&. +.UNINDENT +.INDENT 0.0 .TP -.B \-s \fIpath -The pathname to the root\-anchors.p7s file on the server. (forms URL with \-u). -The default is /root\-anchors/root\-anchors.p7s. This file has to be a PKCS7 -signature over the xml file, using the pem file (\-c) as trust anchor. +.B \-s +The pathname to the root\-anchors.p7s file on the server. +(forms URL with \fI\%\-u\fP). +The default is \fB/root\-anchors/root\-anchors.p7s\fP\&. +This file has to be a PKCS7 signature over the xml file, using the pem +file (\fI\%\-c\fP) as trust anchor. +.UNINDENT +.INDENT 0.0 .TP -.B \-n \fIname -The emailAddress for the Subject of the signer's certificate from the p7s -signature file. Only signatures from this name are allowed. default is -dnssec@iana.org. If you pass "" then the emailAddress is not checked. +.B \-n +The emailAddress for the Subject of the signer\(aqs certificate from the +p7s signature file. +Only signatures from this name are allowed. +The default is \fBdnssec@iana.org\fP\&. +If you pass \fB\(dq\(dq\fP then the emailAddress is not checked. +.UNINDENT +.INDENT 0.0 .TP .B \-4 -Use IPv4 for domain resolution and contacting the server on https. Default is -to use IPv4 and IPv6 where appropriate. +Use IPv4 for domain resolution and contacting the server on +https. +Default is to use IPv4 and IPv6 where appropriate. +.UNINDENT +.INDENT 0.0 .TP .B \-6 -Use IPv6 for domain resolution and contacting the server on https. Default is -to use IPv4 and IPv6 where appropriate. -.TP -.B \-f \fIresolv.conf -Use the given resolv.conf file. Not enabled by default, but you could try to -pass /etc/resolv.conf on some systems. It contains the IP addresses of the -recursive nameservers to use. However, since this tool could be used to -bootstrap that very recursive nameserver, it would not be useful (since -that server is not up yet, since we are bootstrapping it). It could be -useful in a situation where you know an upstream cache is deployed (and -running) and in captive portal situations. -.TP -.B \-r \fIroot.hints -Use the given root.hints file (same syntax as the BIND and Unbound root hints -file) to bootstrap domain resolution. By default a list of builtin root -hints is used. Unbound\-anchor goes to the network itself for these roots, -to resolve the server (\-u option) and to check the root DNSKEY records. +Use IPv6 for domain resolution and contacting the server on https. +Default is to use IPv4 and IPv6 where appropriate. +.UNINDENT +.INDENT 0.0 +.TP +.B \-f +Use the given resolv.conf file. +Not enabled by default, but you could try to pass +\fB/etc/resolv.conf\fP on some systems. +It contains the IP addresses of the recursive nameservers to use. +However, since this tool could be used to bootstrap that very recursive +nameserver, it would not be useful (since that server is not up yet, +since we are bootstrapping it). +It could be useful in a situation where you know an upstream cache is +deployed (and running) and in captive portal situations. +.UNINDENT +.INDENT 0.0 +.TP +.B \-r +Use the given root.hints file (same syntax as the BIND and Unbound root +hints file) to bootstrap domain resolution. +By default a list of builtin root hints is used. +unbound\-anchor goes to the network itself for these roots, to resolve +the server (\fI\%\-u\fP option) and to check the root DNSKEY records. It does so, because the tool when used for bootstrapping the recursive -resolver, cannot use that recursive resolver itself because it is bootstrapping -that server. +resolver, cannot use that recursive resolver itself because it is +bootstrapping that server. +.UNINDENT +.INDENT 0.0 .TP .B \-R -Allow fallback from \-f resolv.conf file to direct root servers query. -It allows you to prefer local resolvers, but fallback automatically -to direct root query if they do not respond or do not support DNSSEC. +Allow fallback from \fI\%\-f\fP \fB\fP file to direct root +servers query. +It allows you to prefer local resolvers, but fallback automatically to +direct root query if they do not respond or do not support DNSSEC. +.UNINDENT +.INDENT 0.0 .TP .B \-v -More verbose. Once prints informational messages, multiple times may enable -large debug amounts (such as full certificates or byte\-dumps of downloaded -files). By default it prints almost nothing. It also prints nothing on -errors by default; in that case the original root anchor file is simply -left undisturbed, so that a recursive server can start right after it. +More verbose. +Once prints informational messages, multiple times may enable large +debug amounts (such as full certificates or byte\-dumps of downloaded +files). +By default it prints almost nothing. +It also prints nothing on errors by default; in that case the original +root anchor file is simply left undisturbed, so that a recursive server +can start right after it. +.UNINDENT +.INDENT 0.0 .TP -.B \-C \fIunbound.conf -Debug option to read unbound.conf into the resolver process used. +.B \-C +Debug option to read \fB\fP into the resolver process +used. +.UNINDENT +.INDENT 0.0 .TP -.B \-P \fIport -Set the port number to use for the https connection. The default is 443. +.B \-P +Set the port number to use for the https connection. +The default is 443. +.UNINDENT +.INDENT 0.0 .TP .B \-F -Debug option to force update of the root anchor through downloading the xml -file and verifying it with the certificate. By default it first tries to -update by contacting the DNS, which uses much less bandwidth, is much -faster (200 msec not 2 sec), and is nicer to the deployed infrastructure. -With this option, it still attempts to do so (and may verbosely tell you), -but then ignores the result and goes on to use the xml fallback method. +Debug option to force update of the root anchor through downloading the +xml file and verifying it with the certificate. +By default it first tries to update by contacting the DNS, which uses +much less bandwidth, is much faster (200 msec not 2 sec), and is nicer +to the deployed infrastructure. +With this option, it still attempts to do so (and may verbosely tell +you), but then ignores the result and goes on to use the xml fallback +method. +.UNINDENT +.INDENT 0.0 .TP .B \-h Show the version and commandline option help. -.SH "EXIT CODE" +.UNINDENT +.SH EXIT CODE +.sp This tool exits with value 1 if the root anchor was updated using the -certificate or if the builtin root-anchor was used. It exits with code -0 if no update was necessary, if the update was possible with RFC5011 -tracking, or if an error occurred. -.P +certificate or if the builtin root\-anchor was used. +It exits with code 0 if no update was necessary, if the update was possible +with \fI\%RFC 5011\fP tracking, or if an error occurred. +.sp You can check the exit value in this manner: +.INDENT 0.0 +.INDENT 3.5 +.sp .nf - unbound-anchor \-a "root.key" || logger "Please check root.key" +.ft C +unbound\-anchor \-a \(dqroot.key\(dq || logger \(dqPlease check root.key\(dq +.ft P .fi +.UNINDENT +.UNINDENT +.sp Or something more suitable for your operational environment. -.SH "TRUST" -The root keys and update certificate included in this tool -are provided for convenience and under the terms of our -license (see the LICENSE file in the source distribution or -https://github.com/NLnetLabs/unbound/blob/master/LICENSE) and might be stale or -not suitable to your purpose. -.P -By running "unbound\-anchor \-l" the keys and certificate that are +.SH TRUST +.sp +The root keys and update certificate included in this tool are provided for +convenience and under the terms of our license (see the LICENSE file in the +source distribution or \fI\%https://github.com/NLnetLabs/unbound/blob/master/LICENSE\fP +and might be stale or not suitable to your purpose. +.sp +By running \fI\%unbound\-anchor \-l\fP the keys and certificate that are configured in the code are printed for your convenience. -.P -The build\-in configuration can be overridden by providing a root\-cert -file and a rootkey file. -.SH "FILES" +.sp +The built\-in configuration can be overridden by providing a root\-cert file and +a rootkey file. +.SH FILES +.INDENT 0.0 .TP -.I @UNBOUND_ROOTKEY_FILE@ -The root anchor file, updated with 5011 tracking, and read and written to. +.B @UNBOUND_ROOTKEY_FILE@ +The root anchor file, updated with 5011 tracking, and read and written +to. The file is created if it does not exist. .TP -.I @UNBOUND_ROOTCERT_FILE@ -The trusted self\-signed certificate that is used to verify the downloaded -DNSSEC root trust anchor. You can update it by fetching it from -https://data.iana.org/root\-anchors/icannbundle.pem (and validate it). +.B @UNBOUND_ROOTCERT_FILE@ +The trusted self\-signed certificate that is used to verify the +downloaded DNSSEC root trust anchor. +You can update it by fetching it from +\fI\%https://data.iana.org/root\-anchors/icannbundle.pem\fP (and validate it). If the file does not exist or is empty, a builtin version is used. .TP -.I https://data.iana.org/root\-anchors/root\-anchors.xml +.B \fI\%https://data.iana.org/root\-anchors/root\-anchors.xml\fP Source for the root key information. .TP -.I https://data.iana.org/root\-anchors/root\-anchors.p7s +.B \fI\%https://data.iana.org/root\-anchors/root\-anchors.p7s\fP Signature on the root key information. -.SH "SEE ALSO" -\fIunbound.conf\fR(5), -\fIunbound\fR(8). +.UNINDENT +.SH SEE ALSO +.sp +\fI\%unbound.conf(5)\fP, +\fI\%unbound(8)\fP\&. +.SH AUTHOR +Unbound developers are mentioned in the CREDITS file in the distribution. +.SH COPYRIGHT +1999-2025, NLnet Labs +.\" Generated by docutils manpage writer. +. diff --git a/doc/unbound-anchor.rst b/doc/unbound-anchor.rst new file mode 100644 index 000000000..480db8eeb --- /dev/null +++ b/doc/unbound-anchor.rst @@ -0,0 +1,281 @@ +.. + WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE + +.. + IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE + +.. + IT HELPS PEOPLE DIFFING THE CHANGES + +.. + WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE + +.. + IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE + +.. + IT HELPS PEOPLE DIFFING THE CHANGES + +.. + WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE + +.. + IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE + +.. + IT HELPS PEOPLE DIFFING THE CHANGES + +.. + WHEN EDITING MAKE SURE EACH SENTENCE STARTS ON A NEW LINE + +.. + IT HELPS RENDERERS TO DO THE RIGHT THING WRT SPACE + +.. + IT HELPS PEOPLE DIFFING THE CHANGES + +.. program:: unbound-anchor + +unbound-anchor(8) +================= + +Synopsis +-------- + +**unbound-anchor** [``opts``] + +Description +----------- + +``unbound-anchor`` performs setup or update of the root trust anchor for DNSSEC +validation. +The program fetches the trust anchor with the method from :rfc:`7958` when +regular :rfc:`5011` update fails to bring it up to date. +It can be run (as root) from the commandline, or run as part of startup +scripts. +Before you start the :doc:`unbound(8)` DNS server. + +Suggested usage: + +.. code-block:: text + + # in the init scripts. + # provide or update the root anchor (if necessary) + unbound-anchor -a "@UNBOUND_ROOTKEY_FILE@" + # Please note usage of this root anchor is at your own risk + # and under the terms of our LICENSE (see source). + # + # start validating resolver + # the unbound.conf contains: + # auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@" + unbound -c unbound.conf + +This tool provides builtin default contents for the root anchor and root update +certificate files. + +It tests if the root anchor file works, and if not, and an update is possible, +attempts to update the root anchor using the root update certificate. +It performs a https fetch of +`root-anchors.xml `__ +and checks the results (:rfc:`7958`); if all checks are successful, it updates +the root anchor file. +Otherwise the root anchor file is unchanged. +It performs :rfc:`5011` tracking if the DNSSEC information available via the +DNS makes that possible. + +It does not perform an update if the certificate is expired, if the network is +down or other errors occur. + +The available options are: + +.. option:: -a + + The root anchor key file, that is read in and written out. + Default is :file:`@UNBOUND_ROOTKEY_FILE@`. + If the file does not exist, or is empty, a builtin root key is written + to it. + +.. option:: -c + + The root update certificate file, that is read in. + Default is :file:`@UNBOUND_ROOTCERT_FILE@`. + If the file does not exist, or is empty, a builtin certificate is used. + +.. option:: -l + + List the builtin root key and builtin root update certificate on stdout. + +.. option:: -u + + The server name, it connects to ``https://name``. + Specify without ``https://`` prefix. + The default is ``"data.iana.org"``. + It connects to the port specified with :option:`-P`. + You can pass an IPv4 address or IPv6 address (no brackets) if you want. + +.. option:: -S + + Do not use SNI for the HTTPS connection. + Default is to use SNI. + +.. option:: -b
+ + The source address to bind to for domain resolution and contacting the + server on https. + May be either an IPv4 address or IPv6 address (no brackets). + +.. option:: -x + + The pathname to the root-anchors.xml file on the server. + (forms URL with :option:`-u`). + The default is :file:`/root-anchors/root-anchors.xml`. + +.. option:: -s + + The pathname to the root-anchors.p7s file on the server. + (forms URL with :option:`-u`). + The default is :file:`/root-anchors/root-anchors.p7s`. + This file has to be a PKCS7 signature over the xml file, using the pem + file (:option:`-c`) as trust anchor. + +.. option:: -n + + The emailAddress for the Subject of the signer's certificate from the + p7s signature file. + Only signatures from this name are allowed. + The default is ``dnssec@iana.org``. + If you pass ``""`` then the emailAddress is not checked. + +.. option:: -4 + + Use IPv4 for domain resolution and contacting the server on + https. + Default is to use IPv4 and IPv6 where appropriate. + +.. option:: -6 + + Use IPv6 for domain resolution and contacting the server on https. + Default is to use IPv4 and IPv6 where appropriate. + +.. option:: -f + + Use the given resolv.conf file. + Not enabled by default, but you could try to pass + :file:`/etc/resolv.conf` on some systems. + It contains the IP addresses of the recursive nameservers to use. + However, since this tool could be used to bootstrap that very recursive + nameserver, it would not be useful (since that server is not up yet, + since we are bootstrapping it). + It could be useful in a situation where you know an upstream cache is + deployed (and running) and in captive portal situations. + +.. option:: -r + + Use the given root.hints file (same syntax as the BIND and Unbound root + hints file) to bootstrap domain resolution. + By default a list of builtin root hints is used. + unbound-anchor goes to the network itself for these roots, to resolve + the server (:option:`-u` option) and to check the root DNSKEY records. + It does so, because the tool when used for bootstrapping the recursive + resolver, cannot use that recursive resolver itself because it is + bootstrapping that server. + +.. option:: -R + + Allow fallback from :option:`-f` ```` file to direct root + servers query. + It allows you to prefer local resolvers, but fallback automatically to + direct root query if they do not respond or do not support DNSSEC. + +.. option:: -v + + More verbose. + Once prints informational messages, multiple times may enable large + debug amounts (such as full certificates or byte-dumps of downloaded + files). + By default it prints almost nothing. + It also prints nothing on errors by default; in that case the original + root anchor file is simply left undisturbed, so that a recursive server + can start right after it. + +.. option:: -C + + Debug option to read :file:`` into the resolver process + used. + +.. option:: -P + + Set the port number to use for the https connection. + The default is 443. + +.. option:: -F + + Debug option to force update of the root anchor through downloading the + xml file and verifying it with the certificate. + By default it first tries to update by contacting the DNS, which uses + much less bandwidth, is much faster (200 msec not 2 sec), and is nicer + to the deployed infrastructure. + With this option, it still attempts to do so (and may verbosely tell + you), but then ignores the result and goes on to use the xml fallback + method. + +.. option:: -h + + Show the version and commandline option help. + +Exit Code +--------- + +This tool exits with value 1 if the root anchor was updated using the +certificate or if the builtin root-anchor was used. +It exits with code 0 if no update was necessary, if the update was possible +with :rfc:`5011` tracking, or if an error occurred. + +You can check the exit value in this manner: + +.. code-block:: text + + unbound-anchor -a "root.key" || logger "Please check root.key" + +Or something more suitable for your operational environment. + +Trust +----- + +The root keys and update certificate included in this tool are provided for +convenience and under the terms of our license (see the LICENSE file in the +source distribution or https://github.com/NLnetLabs/unbound/blob/master/LICENSE +and might be stale or not suitable to your purpose. + +By running :option:`unbound-anchor -l` the keys and certificate that are +configured in the code are printed for your convenience. + +The built-in configuration can be overridden by providing a root-cert file and +a rootkey file. + +Files +----- + +@UNBOUND_ROOTKEY_FILE@ + The root anchor file, updated with 5011 tracking, and read and written + to. + The file is created if it does not exist. + +@UNBOUND_ROOTCERT_FILE@ + The trusted self-signed certificate that is used to verify the + downloaded DNSSEC root trust anchor. + You can update it by fetching it from + https://data.iana.org/root-anchors/icannbundle.pem (and validate it). + If the file does not exist or is empty, a builtin version is used. + +https://data.iana.org/root-anchors/root-anchors.xml + Source for the root key information. + +https://data.iana.org/root-anchors/root-anchors.p7s + Signature on the root key information. + +See Also +-------- + +:doc:`unbound.conf(5)`, +:doc:`unbound(8)`. diff --git a/doc/unbound-checkconf.8.in b/doc/unbound-checkconf.8.in index f4d0f2908..1d17573e9 100644 --- a/doc/unbound-checkconf.8.in +++ b/doc/unbound-checkconf.8.in @@ -1,56 +1,93 @@ -.TH "unbound-checkconf" "8" "@date@" "NLnet Labs" "unbound @version@" -.\" -.\" unbound-checkconf.8 -- unbound configuration checker manual -.\" -.\" Copyright (c) 2007, NLnet Labs. All rights reserved. -.\" -.\" See LICENSE for the license. -.\" -.\" -.SH "NAME" -unbound\-checkconf -\- Check Unbound configuration file for errors. -.SH "SYNOPSIS" -.B unbound\-checkconf -.RB [ \-h ] -.RB [ \-f ] -.RB [ \-q ] -.RB [ \-o -.IR option ] -.RI [ cfgfile ] -.SH "DESCRIPTION" -.B Unbound\-checkconf -checks the configuration file for the -\fIunbound\fR(8) -DNS resolver for syntax and other errors. +.\" Man page generated from reStructuredText. +. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.TH "UNBOUND-CHECKCONF" "8" "@date@" "@version@" "Unbound" +.SH NAME +unbound-checkconf \- Check Unbound @version@ configuration file for errors. +.SH SYNOPSIS +.sp +\fBunbound\-checkconf\fP [\fB\-hf\fP] [\fB\-o option\fP] [cfgfile] +.SH DESCRIPTION +.sp +\fBunbound\-checkconf\fP checks the configuration file for the +\fI\%unbound(8)\fP DNS resolver for syntax and other errors. The config file syntax is described in -\fIunbound.conf\fR(5). -.P +\fI\%unbound.conf(5)\fP\&. +.sp The available options are: +.INDENT 0.0 .TP .B \-h Show the version and commandline option help. +.UNINDENT +.INDENT 0.0 .TP .B \-f -Print full pathname, with chroot applied to it. Use with the \-o option. -.TP -.B \-o\fI option -If given, after checking the config file the value of this option is -printed to stdout. For "" (disabled) options an empty line is printed. +Print full pathname, with chroot applied to it. +Use with the \fI\%\-o\fP option. +.UNINDENT +.INDENT 0.0 .TP .B \-q Make the operation quiet, suppress output on success. +.UNINDENT +.INDENT 0.0 +.TP +.B \-o