[apple/network_cmds.git] / unbound / doc / unbound-anchor.8.in

.TH "unbound-anchor" "8" "Dec  8, 2014" "NLnet Labs" "unbound 1.5.1"
.\"
.\" 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.
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
Suggested usage:
.P
.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
.fi
.P
This tool provides builtin default contents for the root anchor and root
update certificate files.
.P
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, 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
The available options are:
.TP
.B \-a \fIfile
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.
.TP
.B \-c \fIfile
The root update certificate file, that is read in.
Default is @UNBOUND_ROOTCERT_FILE@.
If the file does not exist, or is empty, a builtin certificate is used.
.TP
.B \-l
List the builtin root key and builtin root update certificate on stdout.
.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.
You can pass an IPv4 addres or IPv6 address (no brackets) if you want.
.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.
.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.
.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.
.TP
.B \-4
Use IPv4 for domain resolution and contacting the server on https.  Default is
to use IPv4 and IPv6 where appropriate.
.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.
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.
.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.
.TP
.B \-C \fIunbound.conf
Debug option to read unbound.conf into the resolver process used.
.TP
.B \-P \fIport
Set the port number to use for the https connection.  The default is 443.
.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.
.TP
.B \-h
Show the version and commandline option help.
.SH "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 RFC5011
tracking, or if an error occurred.
.P
You can check the exit value in this manner:
.nf
	unbound-anchor \-a "root.key" || logger "Please check root.key"
.fi
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
http://unbound.nlnetlabs.nl/svn/trunk/LICENSE) and might be stale or
not suitable to your purpose.
.P
By running "unbound\-anchor \-l" 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"
.TP
.I @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).
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
Source for the root key information.
.TP
.I https://data.iana.org/root\-anchors/root\-anchors.p7s
Signature on the root key information.
.SH "SEE ALSO"
\fIunbound.conf\fR(5), 
\fIunbound\fR(8).
Commit	Line	Data
89c4ed63 A	1	.TH "unbound-anchor" "8" "Dec 8, 2014" "NLnet Labs" "unbound 1.5.1"
	2	.\"
	3	.\" unbound-anchor.8 -- unbound anchor maintenance utility manual
	4	.\"
	5	.\" Copyright (c) 2008, NLnet Labs. All rights reserved.
	6	.\"
	7	.\" See LICENSE for the license.
	8	.\"
	9	.\"
	10	.SH "NAME"
	11	.B unbound\-anchor
	12	\- Unbound anchor utility.
	13	.SH "SYNOPSIS"
	14	.B unbound\-anchor
	15	.RB [ opts ]
	16	.SH "DESCRIPTION"
	17	.B Unbound\-anchor
	18	performs setup or update of the root trust anchor for DNSSEC validation.
	19	It can be run (as root) from the commandline, or run as part of startup
	20	scripts. Before you start the \fIunbound\fR(8) DNS server.
	21	.P
	22	Suggested usage:
	23	.P
	24	.nf
	25	# in the init scripts.
	26	# provide or update the root anchor (if necessary)
	27	unbound-anchor \-a "@UNBOUND_ROOTKEY_FILE@"
	28	# Please note usage of this root anchor is at your own risk
	29	# and under the terms of our LICENSE (see source).
	30	#
	31	# start validating resolver
	32	# the unbound.conf contains:
	33	# auto-trust-anchor-file: "@UNBOUND_ROOTKEY_FILE@"
	34	unbound \-c unbound.conf
	35	.fi
	36	.P
	37	This tool provides builtin default contents for the root anchor and root
	38	update certificate files.
	39	.P
	40	It tests if the root anchor file works, and if not, and an update is possible,
	41	attempts to update the root anchor using the root update certificate.
	42	It performs a https fetch of root-anchors.xml and checks the results, if
	43	all checks are successful, it updates the root anchor file. Otherwise
	44	the root anchor file is unchanged. It performs RFC5011 tracking if the
	45	DNSSEC information available via the DNS makes that possible.
	46	.P
	47	It does not perform an update if the certificate is expired, if the network
	48	is down or other errors occur.
	49	.P
	50	The available options are:
	51	.TP
	52	.B \-a \fIfile
	53	The root anchor key file, that is read in and written out.
	54	Default is @UNBOUND_ROOTKEY_FILE@.
	55	If the file does not exist, or is empty, a builtin root key is written to it.
	56	.TP
	57	.B \-c \fIfile
	58	The root update certificate file, that is read in.
	59	Default is @UNBOUND_ROOTCERT_FILE@.
	60	If the file does not exist, or is empty, a builtin certificate is used.
	61	.TP
	62	.B \-l
	63	List the builtin root key and builtin root update certificate on stdout.
	64	.TP
65	.B \-u \fIname
66	The server name, it connects to https://name. Specify without https:// prefix.
67	The default is "data.iana.org". It connects to the port specified with \-P.
68	You can pass an IPv4 addres or IPv6 address (no brackets) if you want.
69	.TP
70	.B \-x \fIpath
71	The pathname to the root\-anchors.xml file on the server. (forms URL with \-u).
72	The default is /root\-anchors/root\-anchors.xml.
73	.TP
74	.B \-s \fIpath
75	The pathname to the root\-anchors.p7s file on the server. (forms URL with \-u).
76	The default is /root\-anchors/root\-anchors.p7s. This file has to be a PKCS7
77	signature over the xml file, using the pem file (\-c) as trust anchor.
78	.TP
79	.B \-n \fIname
80	The emailAddress for the Subject of the signer's certificate from the p7s
81	signature file. Only signatures from this name are allowed. default is
82	dnssec@iana.org. If you pass "" then the emailAddress is not checked.
83	.TP
84	.B \-4
85	Use IPv4 for domain resolution and contacting the server on https. Default is
86	to use IPv4 and IPv6 where appropriate.
87	.TP
88	.B \-6
89	Use IPv6 for domain resolution and contacting the server on https. Default is
90	to use IPv4 and IPv6 where appropriate.
91	.TP
92	.B \-f \fIresolv.conf
93	Use the given resolv.conf file. Not enabled by default, but you could try to
94	pass /etc/resolv.conf on some systems. It contains the IP addresses of the
95	recursive nameservers to use. However, since this tool could be used to
96	bootstrap that very recursive nameserver, it would not be useful (since
97	that server is not up yet, since we are bootstrapping it). It could be
98	useful in a situation where you know an upstream cache is deployed (and
99	running) and in captive portal situations.
100	.TP
101	.B \-r \fIroot.hints
102	Use the given root.hints file (same syntax as the BIND and Unbound root hints
103	file) to bootstrap domain resolution. By default a list of builtin root
104	hints is used. Unbound\-anchor goes to the network itself for these roots,
105	to resolve the server (\-u option) and to check the root DNSKEY records.
106	It does so, because the tool when used for bootstrapping the recursive
107	resolver, cannot use that recursive resolver itself because it is bootstrapping
108	that server.
109	.TP
110	.B \-v
111	More verbose. Once prints informational messages, multiple times may enable
112	large debug amounts (such as full certificates or byte\-dumps of downloaded
113	files). By default it prints almost nothing. It also prints nothing on
114	errors by default; in that case the original root anchor file is simply
115	left undisturbed, so that a recursive server can start right after it.
116	.TP
117	.B \-C \fIunbound.conf
118	Debug option to read unbound.conf into the resolver process used.
119	.TP
120	.B \-P \fIport
121	Set the port number to use for the https connection. The default is 443.
122	.TP
123	.B \-F
124	Debug option to force update of the root anchor through downloading the xml
125	file and verifying it with the certificate. By default it first tries to
126	update by contacting the DNS, which uses much less bandwidth, is much
127	faster (200 msec not 2 sec), and is nicer to the deployed infrastructure.
128	With this option, it still attempts to do so (and may verbosely tell you),
129	but then ignores the result and goes on to use the xml fallback method.
130	.TP
131	.B \-h
132	Show the version and commandline option help.
133	.SH "EXIT CODE"
134	This tool exits with value 1 if the root anchor was updated using the
135	certificate or if the builtin root-anchor was used. It exits with code
136	0 if no update was necessary, if the update was possible with RFC5011
137	tracking, or if an error occurred.
138	.P
139	You can check the exit value in this manner:
140	.nf
141	unbound-anchor \-a "root.key" \|\| logger "Please check root.key"
142	.fi
143	Or something more suitable for your operational environment.
144	.SH "TRUST"
145	The root keys and update certificate included in this tool
146	are provided for convenience and under the terms of our
147	license (see the LICENSE file in the source distribution or
148	http://unbound.nlnetlabs.nl/svn/trunk/LICENSE) and might be stale or
149	not suitable to your purpose.
150	.P
151	By running "unbound\-anchor \-l" the keys and certificate that are
152	configured in the code are printed for your convenience.
153	.P
154	The build\-in configuration can be overridden by providing a root\-cert
155	file and a rootkey file.
156	.SH "FILES"
157	.TP
158	.I @UNBOUND_ROOTKEY_FILE@
159	The root anchor file, updated with 5011 tracking, and read and written to.
160	The file is created if it does not exist.
161	.TP
162	.I @UNBOUND_ROOTCERT_FILE@
163	The trusted self\-signed certificate that is used to verify the downloaded
164	DNSSEC root trust anchor. You can update it by fetching it from
165	https://data.iana.org/root\-anchors/icannbundle.pem (and validate it).
166	If the file does not exist or is empty, a builtin version is used.
167	.TP
168	.I https://data.iana.org/root\-anchors/root\-anchors.xml
169	Source for the root key information.
170	.TP
171	.I https://data.iana.org/root\-anchors/root\-anchors.p7s
172	Signature on the root key information.
173	.SH "SEE ALSO"
174	\fIunbound.conf\fR(5),
175	\fIunbound\fR(8).